A shared memory segment is an area of memory that a process can attach to its own virtual address space. Attaching a memory area in this manner enables the process to treat the area as if it is local. Shared memory is often used as a fast way to share information among processes; however, access must be properly synchronized.

When a shared memory segment is created, the segment is not attached to the process' address space. Use one of the attach() family of functions to attach the segment to the process' address space. To detach a process from its shared memory region, send detach() to the segment or terminate the process.

Once created, a shared memory segment persists in the system even if no processes are attached to it. To remove a shared memory segment, send remove() , which schedules the shared memory segment for removal when the last process detaches from the segment.

A process with superuser privileges can use lock() to lock a shared memory segment into main memory. Using lock() to lock a memory segment protects the segment from the paging system. Similarly, a superuser can use unlock() to unlock a segment.

Conversions permit interchangeable use of os_shared_memory and os_vid_t (the System V IPC ID).

Legal open control:	`O_OPEN, O_CREAT, O_EXCL`
Legal I/O control:	`O_RDONLY, O_RDWR`
Default I/O control:	`O_RDWR`

Interface

Constructor

os_shared_memory()

Constructs object with no associated shared memory segment.

Constructor

os_shared_memory( os_vid_t id )

Constructs object to reference the existing shared memory segment with ID id .

Constructor

os_shared_memory( const os_key& key )

Constructs an object to reference the existing shared memory segment with key key . Does not attach to the new segment. Use one of the attach...() family of functions to attach to the new segment.

Throws: os_unix_toolkit_error

Constructor

os_shared_memory( int size , os_mode_t mode )

Constructs an object to reference a new memory segment of size bytes that has a private key and mode mode . Does not attach to the new segment. Use one of the attach...() family of functions to attach to the new segment.

Throws: os_unix_toolkit_error

Constructor

os_shared_memory( const os_key& key , os_open_t open , int size , os_mode_t mode )

Constructs an object to reference a new memory segment of size bytes with key key and mode mode . If a memory segment with key key already exists, the object references the existing memory segment and ignores the mode and size parameters. Does not attach to the new segment. Use one of the attach...() family of functions to attach to the new segment.

Throws: os_unix_toolkit_error

bool operator<( const os_shared_memory& shared_memory ) const

Returns true if the object's ID is less than shared_memory .

bool operator==( const os_shared_memory& shared_memory ) const

Returns true if the object's ID is the same as shared_memory .

(os_vid_t)

operator os_vid_t() const

Returns the object's ID.

address

char* address() const

Returns the memory address where the object is currently attached within the object process' address space. If the object is not currently attached, returns OS_UNDEFINED_SEGMENT .

attach_aligned_at

char* attach_aligned_at( char* address , os_ioctl_t control )

Attaches the object to the current process' address space at location address with control control (default O_RDWR ). Before attaching, rounds down address to the next legal address boundary. Returns the address of attachment if successful; otherwise, returns OS_UNDEFINED_SEGMENT . Address boundaries are machine dependent, but usually are every 32 bits. On machines where data alignment is a concern, this method of attachment is more desirable than attach_at() .

Throws: os_unix_toolkit_error

attach_at

char* attach_at( char* address , os_ioctl_t control )

Attaches the object to the current process' address space at address with control control (default O_RDWR ). Returns the address of attachment if successful; otherwise, returns OS_UNDEFINED_SEGMENT . Due to the variance in the memory management policies of different platforms, this method of attachment should be avoided when creating portable code.

Throws: os_unix_toolkit_error

attach_at_first_available

char* attach_at_first_available( os_ioctl_t control )

Attaches the object to the current process' address space at the first available address assigned by the operating system with control control (default O_RDWR ). For portability, this is the best way to attach a segment. Returns the address of attachment if successful; otherwise, returns OS_UNDEFINED_SEGMENT .

Throws: os_unix_toolkit_error

creator_group

os_gid_t creator_group() const

Returns the object creator's group.

Throws: os_unix_toolkit_error

creator_process

os_pid_t creator_process() const

Returns the process that created the object's shared memory segment.

Throws: os_unix_toolkit_error

creator_user

os_uid_t creator_user() const

Returns the object creator's user.

Throws: os_unix_toolkit_error

defined

bool defined() const

Returns true if the object ID is not OS_UNDEFINED .

detach

void detach()

Detaches from the operating system IPC structure. After detachment, the current process can no longer access the previous shared memory space. The object address is set to OS_UNDEFINED_SEGMENT .

Throws: os_unix_toolkit_error

void id( os_vid_t id )

Sets the object ID to id .

os_vid_t id() const

Returns the object ID.

key

os_key key() const

Returns the object key.

Throws: os_unix_toolkit_error

last_attach_time

os_time_and_date last_attach_time() const

Returns the time a process last attached to the object's shared memory segment.

Throws: os_unix_toolkit_error

last_change_time

os_time_and_date last_change_time() const

Returns the time of the last change to the object's shared memory segment.

Throws: os_unix_toolkit_error

last_detach_time

os_time_and_date last_detach_time() const

Returns the time a process last detached from the object's shared memory segment.

Throws: os_unix_toolkit_error

last_op_process

os_pid_t last_op_process() const

Returns the process ID of the last process that operated on the object's shared memory segment.

Throws: os_unix_toolkit_error

lock

void lock()

Locks a shared memory segment into memory. This function can only be executed by a superuser.

Throws: os_unix_toolkit_error

mode

os_mode_t mode() const

Returns the object's mode.

Throws: os_unix_toolkit_error

mode

void mode( os_mode_t mode )

Sets the object's mode to mode .

Throws: os_unix_toolkit_error

number_attached

int number_attached() const

Returns the number of processes attached to the object's shared memory segment.

Throws: os_unix_toolkit_error

owner_group

void owner_group( os_gid_t group )

Sets the object owner's group to group .

Throws: os_unix_toolkit_error

owner_group

os_gid_t owner_group() const

Returns the object owner's group.

Throws: os_unix_toolkit_error

owner_user

void owner_user( os_uid_t user )

Sets the object owner's user to user .

Throws: os_unix_toolkit_error

owner_user

os_uid_t owner_user() const

Returns the object owner's user.

Throws: os_unix_toolkit_error

print

void print( ostream& stream ) const

Prints the object's ID to stream .

Throws: os_unix_toolkit_error

remove

void remove()

Schedules the object's memory segment for removal from the system and prevents any processes from using the object's key. The memory segment is automatically removed when no processes are attached to it. Any processes already attached to the segment are unaffected by this operation.

Throws: os_unix_toolkit_error

size

int size() const

Returns the size of the object's shared memory segment in bytes.

Throws: os_unix_toolkit_error

slot_sequence_number

int slot_sequence_number() const

Returns the object's slot usage sequence number.

Throws: os_unix_toolkit_error

unlock

void unlock()

Unlocks a shared memory segment from memory. This function can only be executed by a superuser.

Throws: os_unix_toolkit_error

shared_memory

Library

Declaration

Options

Interface

Non-Member Functions