--- name: "IPC::Shareable::SharedMem" section: "3pm" platform: "linux" package: "perl-ipc-shareable" version: "1.19-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/IPC::Shareable::SharedMem" --- # IPC::Shareable::SharedMem(3pm) Allows access to a shared memory segment via an object oriented interface. ## NAME IPC::Shareable::SharedMem - Allows access to a shared memory segment via an object oriented interface. ## 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. ## SYNOPSIS ``` use IPC::Shareable::SharedMem; my $seg = IPC::Shareable::SharedMem->new( key => 1234, size => 65536, ); $seg->shmwrite($data); my $data = $seg->data; ``` ## METHODS ### new(%params) Instantiates and returns an object that represents a shared memory segment. If for any reason we can't create the shared memory segment, we'll return `"undef"`. Parameters (must be in key =\> value pairs): *key* *Mandatory, Integer*: An integer that references the shared memory segment. *size* *Optional, Integer*: An integer representing the size in bytes of the shared memory segment. The maximum is Operating System independent. *Default*: 1024 *flags* *Optional, Bitwise Mask*: A bitwise mask of options logically OR'd together with any or all of `"IPC_CREAT"` (create segment if it doesn't exist), `"IPC_EXCL"` (exclusive access; if the segment already exists, we'll `"croak"`) and `"IPC_RDONLY"` (create a read only segment). See IPC::SysV for further details. *Default*: `0` (ie. no flags). *mode* *Optional, Octal Integer*: An octal number representing the access permissions for the shared memory segment. Exactly the same as a Unix file system permissions. *Default*: 0666 (User RW, Group RW, World RW). *type* *Optional, String*: The type of data that will be stored in the shared memory segment. IPC::Shareable uses `"SCALAR"`, `"ARRAY"` or `"HASH"`. ### id Sets/gets the identification number that references the shared memory segment. A warning will be thrown if you try to set the ID after the object is already instantiated, and no change will occur. ### key Sets/gets the key used to identify the shared memory segment. 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 `"croak"`. See "key" for further details. ### key\_hex($key) Returns the hex formatted key which appears in `"ipcs"` calls. Parameters: *$key* *Optional, String*: This is always sent in during initialization. ### size Sets/gets the size of the shared memory segment in bytes. See "size" for further details. A warning will be thrown if you try to set the size after the object is already instantiated, and no change will occur. ### flags Sets/gets the flags that the segment will be created with. See "flags" for details. A warning will be thrown if you try to set the flags after the object is already instantiated, and no change will occur. ### mode Sets/gets the access permissions. See "mode" for further details. A warning will be thrown if you try to set the mode after the object is already instantiated, and no change will occur. ### type Sets/gets the type of data that will be contained in the shared memory segment. See "type" for details. A warning will be thrown if you try to set the type after the object is already instantiated, and no change will occur. ### data Returns the data in the shared memory segment, with all NULL pad bytes removed. Use this method for text data. For binary data where you need all blocks within the segment, use the "shmread" method. ### stat This method has sub methods that display various system-level information about the memory segment. These sub methods are: ``` uid gid cuid cgid mode segsz lpid cpid nattch atime dtime ctime ``` Example call: ``` my $ctime = $seg->stat->ctime; ``` ### stats Returns an href of the various system-level stat information: ``` { uid => 501, gid => 20, cuid => 501, cgid => 20, mode => 0666, segsz => 65536, lpid => 61270, cpid => 61270, nattch => 0, atime => 1778791348, dtime => 1778791348, ctime => 1778791348, } ``` ### stat\_list Returns an array of all the segment's system stat entries. These are what make up the method names of the `"$seg->stat"` object. ### shmread Returns the data (and NULL pad bytes) stored in the shared memory segment. 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't match). Typically this method is used when you want all blocks of the segment, such as if you've stored binary data. For text/ASCII data, use the "data" method which automatically strips NULL pad bytes. *Return*: The data if any is stored, empty string if no data has been stored yet, and `"undef"` if a failure to read occurs. ### shmwrite($data) Stores the serialized data to the shared memory segment. Parameters: ``` $data ``` *Mandatory, String*: Typically, the a serialized data structure. *Return*: True on success, false on failure. ### remove Removes the shared memory segment and returns the resources to the system. *Return*: True (`1`) on success, false (`0`) on failure. ## AUTHOR Ben Sugars (bsugars@canoe.ca) ## MAINTAINED BY Steve Bertrand \ ## SEE ALSO IPC::Shareable, IPC::Shareable::SharedMem, IPC::ShareLite