shmget()-Get ID of Shared Memory Segment with Key

#include <sys/shm.h>
#include <sys/stat.h>

int shmget(key_t key,size_t size, int shmflg);

The shmget() function returns the shared memory ID associated with the specified shared memory key.

Parameters

key

(Input) The key associated with the shared memory ID. Specifying a key of IPC_PRIVATE guarantees that a unique shared memory ID and shared memory segment are created. A key may also be generated by the caller or by calling the ftok() function.

size

(Input) The size of the shared memory segment being created. The size of the segment may be changed using the shmctl() API if it is nonteraspace shared memory segment or if it was created by specifying SHM_RESIZE_NP on the shmflg parameter of shmget(). If an existing shared memory ID is being accessed, the size may be zero.

shmflg

(Input) Operation and permission flags

The value of the shmflg parameter is either zero or is obtained by performing an OR operation on one or more of the constants listed below. If an existing shared memory ID is being accessed, then the permissions specified must be a subset of the existing permissions of the shared memory segment. If an existing shared memory ID is being accessed, then the SHM_TS_NP and SHM_MAP_FIXED_NP flags must match the existing attributes of the shared memory segment.

'0x0100' or S_IRUSR

Permits the creator of the shared memory ID to attach to it in read mode.

'0x0080' or S_IWUSR

Permits the creator of the shared memory ID to attach to it in write mode.

'0x0020' or S_IRGRP

Permits the group associated with the shared memory ID to attach to it in read mode

'0x0010' or S_IWGRP

Permits the group associated with the shared memory ID to attach to it in write mode

'0x0004' or S_IROTH

Permits others to attach to the shared memory ID in read mode.

'0x0002' or S_IWOTH

Permits others to attach to the shared memory ID in write mode.

'0x0200' or IPC_CREAT

Creates the shared memory segment ID if it does not exist already.

'0x0400' or IPC_EXCL

Causes shmget() to fail if IPC_CREAT is also set and the shared memory ID already exists.

'0x10000' or SHM_TS_NP

If shmget() creates a new shared memory segment, then the new shared memory segment will be created as a teraspace shared memory segment. When a process attaches to this shared memory segment, the shared memory segment will be added to the process's teraspace. Some compilers permit the user to indicate that the teraspace versions of storage functions should be used. For example, if a C module is compiled using CRTCMOD TERASPACE(*YES *TSIFC), this flag will be set automatically.

'0x40000' or SHM_RESIZE_NP

If shmget() creates a new teraspace shared memory segment, then the size of the shared memory segment may be changed using the shmctl() API. The maximum size of this teraspace shared memory segment is 268 435 456 bytes (256 MB). This flag is ignored for nonteraspace shared memory segments. A nonteraspace shared memory segment may always be resized up to 16 773 120 bytes (16 MB - 4096 bytes).

'0x100000' or SHM_MAP_FIXED_NP

If shmget() creates a new teraspace shared memory segment, then all processes that successfully attach to the shared memory segment will attach to the shared memory segment at the same address. The shared memory segment may not be attached in read-only mode. This flag is ignored for nonteraspace shared memory segments.

Authorities

Figure 1-17. Authorization Required for shmget()

Object Referred to	Authority Required	errno
Shared memory segment to be created	None	None
Existing shared memory segment to be accessed	See Note	EACCES
Note: If the thread is accessing a shared memory segment that already exists, the mode specified in the last 9 bits of shmflg must be a subset of the mode of the existing shared memory segment.

Return Value

value

shmget()was successful. The value returned is the shared memory ID associated with the key parameter.

-1

shmget() was not successful. The errno variable is set to indicate the error.

Error Conditions

If shmget() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

A shared memory identifier exists for the parameter key, but operation permission as specified by the low-order 9 bits of shmflg would not be granted.

[EDAMAGE]

A damaged object was encountered.

The value of key corresponds to shared memory that has been marked as damaged by a previous shared memory operation.

[EEXIST]

File exists.

The file specified already exists and the specified operation requires that it not exist.

The named file, directory, or path already exists.

A shared memory identifier exists for the parameter key, but ((shmflg & IPC_CREAT) && (shmflg & IPC_EXCL)) is not zero. (& is a bitwise AND; && is a logical AND.)

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

One of the following has occurred:

• The value of the parameter size is less than the system-imposed minimum or greater than the system-imposed maximum.

• A shared memory identifier exists for the parameter key, but the size of the segment associated with it is less than size and size is not zero.

• A shared memory identifier exists for the parameter key, but the SHM_MAP_FIXED_NP or SHM_TS_NP attributes of the shared memory segment do not match the attributes specified by the parameter shmflg.

[ENOENT]

No such path or directory.

The directory or a component of the path name specified does not exist.

A named file or directory does not exist or is an empty string.

A shared memory identifier does not exist for the parameter key, and (shmflg & IPC_CREAT) is zero.

[ENOMEM]

Storage allocation request failed.

A function needed to allocate storage, but no storage is available.

A shared memory identifier and associated shared memory segment are to be created, but the amount of available physical memory is not sufficient to fulfill the request.

[ENOSPC]

No space available.

The requested operations required additional space on the device and there is no space left. This could also be caused by exceeding the user profile storage limit when creating or transferring ownership of an object.

Insufficient space remains to hold the intended file, directory, or link.

A shared memory identifier is to be created, but the system-imposed limit on the maximum number of allowed shared memory identifiers system-wide would be exceeded.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Error Messages

None.

Usage Notes

1. shmget() creates a shared memory ID, its associated shmid_ds data structure, and a shared memory segment of at least size bytes if one of the following is true:

   • The shared memory key is IPC_PRIVATE

   • There is no shared memory ID already associated with the shared memory key and the IPC_CREAT flag is set.

2. When the shared memory ID is created, the shmid_ds structure (defined in the <sys/shm.h> header file) that is associated with the shared memory ID is initialized as follows:

   • The shm_perm.cuid and shm_perm.uid values are set equal to the effective user ID (uid) of the calling thread.

   • The shm_perm.cgid and shm_perm.gid values are set equal to the effective group ID (gid) of the calling thread.

   • The low-order 9 bits of shm_perm.mode are set equal to the low-order 9 bits of shmflg.

   • shm_segsz is set to the value specified in size.

   • shm_lpid, shm_nattch, shm_atime, and shm_dtime are set to zero.

   • shm_ctime is set to the current time.

3. shmat() should be used to set or gain pointer addressability to the shared memory segment associated with the shared memory ID after the shared memory ID is obtained.

4. The maximum size of a teraspace shared memory segment is 4 294 967 295 bytes (4GB - 1). The maximum size of a resizeable teraspace shared memory segment is 268 435 456 bytes (256 MB). The maximum shared memory segment size for nonteraspace shared memory segments is 16 776 960 bytes (16 MB - 256 bytes).

5. The storage for a shared memory segment is not allocated until it is attached to a process. A process will not be able to attach to a shared memory segment that is larger than the amount of storage available on the system.

6. Processes cannot attach a nonteraspace shared memory segment in read-only or write-only mode. Consequently, permissions that specify read-only or write-only will always result in shmat() failure. Processes are permitted to attach a teraspace shared memory segment in read-only mode.

7. Shared memory segments larger than 16 773 120 bytes (16 MB minus 4096 bytes) should be created as teraspace shared memory segments. When the operating system accesses a nonteraspace shared memory segment that has a size in the range 16 773 120 bytes (16 MB minus 4096 bytes) to 16 776 960 bytes (16 MB minus 256 bytes), a performance degradation may be observed.

Related Information

• The <sys/shm.h> file (see Header Files for UNIX-Type Functions)

• ftok()--Generate IPC Key from File Name

• shmat()-Attach Shared Memory Segment to Current Process

• shmctl()-Perform Shared Memory Control Operations

• shmdt()-Detach Shared Memory Segment from Calling Process

Example

For an example of using this function, see Using Semaphores and Shared Memory in Appendix A, Examples.