.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "IPC::Shareable::SharedMem 3" .TH IPC::Shareable::SharedMem 3 2026-07-07 "perl v5.42.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME IPC::Shareable::SharedMem \- Allows access to a shared memory segment via an object oriented interface. .SH DESCRIPTION .IX Header "DESCRIPTION" This module provides object oriented access to a shared memory segment. Although it can be used standalone, it was designed for use specifically within the IPC::Shareable library. .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use IPC::Shareable::SharedMem; \& \& my $seg = IPC::Shareable::SharedMem\->new( \& key => 1234, \& size => 65536, \& ); \& \& $seg\->shmwrite($data); \& \& my $data = $seg\->data; .Ve .SH METHODS .IX Header "METHODS" .SS new(%params) .IX Subsection "new(%params)" Instantiates and returns an object that represents a shared memory segment. .PP If for any reason we can\*(Aqt create the shared memory segment, we\*(Aqll return \&\f(CW\*(C`undef\*(C'\fR. .PP Parameters (must be in key => value pairs): .PP \fIkey\fR .IX Subsection "key" .PP \&\fIMandatory, Integer\fR: An integer that references the shared memory segment. .PP \fIsize\fR .IX Subsection "size" .PP \&\fIOptional, Integer\fR: An integer representing the size in bytes of the shared memory segment. The maximum is Operating System independent. .PP \&\fIDefault\fR: 1024 .PP \fIflags\fR .IX Subsection "flags" .PP \&\fIOptional, Bitwise Mask\fR: A bitwise mask of options logically OR\*(Aqd together with any or all of \f(CW\*(C`IPC_CREAT\*(C'\fR (create segment if it doesn\*(Aqt exist), \&\f(CW\*(C`IPC_EXCL\*(C'\fR (exclusive access; if the segment already exists, we\*(Aqll \f(CW\*(C`croak\*(C'\fR) and \f(CW\*(C`IPC_RDONLY\*(C'\fR (create a read only segment). .PP See IPC::SysV for further details. .PP \&\fIDefault\fR: \f(CW0\fR (ie. no flags). .PP \fImode\fR .IX Subsection "mode" .PP \&\fIOptional, Octal Integer\fR: An octal number representing the access permissions for the shared memory segment. Exactly the same as a Unix file system permissions. .PP \&\fIDefault\fR: 0666 (User RW, Group RW, World RW). .PP \fItype\fR .IX Subsection "type" .PP \&\fIOptional, String\fR: The type of data that will be stored in the shared memory segment. IPC::Shareable uses \f(CW\*(C`SCALAR\*(C'\fR, \f(CW\*(C`ARRAY\*(C'\fR or \f(CW\*(C`HASH\*(C'\fR. .SS id .IX Subsection "id" Sets/gets the identification number that references the shared memory segment. .PP A warning will be thrown if you try to set the ID after the object is already instantiated, and no change will occur. .SS key .IX Subsection "key" Sets/gets the key used to identify the shared memory segment. .PP Setting this attribute should only be done internally. If it is sent in after the object is already associated with a shared memory segment, we will \f(CW\*(C`croak\*(C'\fR. .PP See "key" for further details. .SS key_hex($key) .IX Subsection "key_hex($key)" Returns the hex formatted key which appears in \f(CW\*(C`ipcs\*(C'\fR calls. .PP Parameters: .PP \fR\f(CI$key\fR\fI\fR .IX Subsection "$key" .PP \&\fIOptional, String\fR: This is always sent in during initialization. .SS size .IX Subsection "size" Sets/gets the size of the shared memory segment in bytes. See "size" for further details. .PP A warning will be thrown if you try to set the size after the object is already instantiated, and no change will occur. .SS flags .IX Subsection "flags" Sets/gets the flags that the segment will be created with. See "flags" for details. .PP A warning will be thrown if you try to set the flags after the object is already instantiated, and no change will occur. .SS mode .IX Subsection "mode" Sets/gets the access permissions. See "mode" for further details. .PP A warning will be thrown if you try to set the mode after the object is already instantiated, and no change will occur. .SS type .IX Subsection "type" Sets/gets the type of data that will be contained in the shared memory segment. See "type" for details. .PP A warning will be thrown if you try to set the type after the object is already instantiated, and no change will occur. .SS data .IX Subsection "data" Returns the data in the shared memory segment, with all NULL pad bytes removed. .PP Use this method for text data. For binary data where you need all blocks within the segment, use the "shmread" method. .SS stat .IX Subsection "stat" This method has sub methods that display various system\-level information about the memory segment. These sub methods are: .PP .Vb 12 \& uid \& gid \& cuid \& cgid \& mode \& segsz \& lpid \& cpid \& nattch \& atime \& dtime \& ctime .Ve .PP Example call: .PP .Vb 1 \& my $ctime = $seg\->stat\->ctime; .Ve .SS stats .IX Subsection "stats" Returns an href of the various system\-level stat information: .PP .Vb 10 \& { \& uid => 501, \& gid => 20, \& cuid => 501, \& cgid => 20, \& mode => 0666, \& segsz => 65536, \& lpid => 61270, \& cpid => 61270, \& nattch => 0, \& atime => 1778791348, \& dtime => 1778791348, \& ctime => 1778791348, \& } .Ve .SS stat_list .IX Subsection "stat_list" Returns an array of all the segment\*(Aqs system stat entries. These are what make up the method names of the \f(CW\*(C`$seg\->stat\*(C'\fR object. .SS shmread .IX Subsection "shmread" Returns the data (and NULL pad bytes) stored in the shared memory segment. .PP By default, when data is retrieved from the shared memory segment, the data is padded to the right by NULL bytes to fill up the entire size of the segment. This can cause issues when using the space for non serialized data (ie. if you stored "hello" in a 1024 byte segment, the ASCII text wouldn\*(Aqt match). .PP Typically this method is used when you want all blocks of the segment, such as if you\*(Aqve stored binary data. .PP For text/ASCII data, use the "data" method which automatically strips NULL pad bytes. .PP \&\fIReturn\fR: The data if any is stored, empty string if no data has been stored yet, and \f(CW\*(C`undef\*(C'\fR if a failure to read occurs. .SS shmwrite($data) .IX Subsection "shmwrite($data)" Stores the serialized data to the shared memory segment. .PP Parameters: .PP .Vb 1 \& $data .Ve .PP \&\fIMandatory, String\fR: Typically, the a serialized data structure. .PP \&\fIReturn\fR: True on success, false on failure. .SS remove .IX Subsection "remove" Removes the shared memory segment and returns the resources to the system. .PP \&\fIReturn\fR: True (\f(CW1\fR) on success, false (\f(CW0\fR) on failure. .SH AUTHOR .IX Header "AUTHOR" Ben Sugars (bsugars@canoe.ca) .SH "MAINTAINED BY" .IX Header "MAINTAINED BY" Steve Bertrand .SH "SEE ALSO" .IX Header "SEE ALSO" IPC::Shareable, IPC::Shareable::SharedMem, IPC::ShareLite