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.