shmget() — Get a shared memory segment

Standards

Standards / Extensions C or C++ Dependencies

XPG4
XPG4.2
Single UNIX Specification, Version 3

 both  

Format

#define _XOPEN_SOURCE
#include <sys/shm.h>

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

General description

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

A shared memory identifier, associated data structure and shared memory segment of at least size bytes, see <sys/shm.h>, are created for key if one of the following is true:
  1. Argument key has a value of IPC_PRIVATE
  2. Argument key does not already have a shared memory identifier associated with it and the flag IPC_CREAT was specified

Specify __IPC_MEGA to request segment level sharing. The resulting shared memory segment will be allocated in units of segments instead of units of pages. The shared memory size parameter still reflects the number of bytes required but must be in megabyte multiples. A shared memory size parameter of 0 or one which is not a megabyte multiple will result in the request failing.

The first shmget to define the shared memory segment determines whether the segment has the __IPC_MEGA attribute or not. Subsequent shmgets, those that use existing shared memory segments, will use the __IPC_MEGA attribute defined by that segment. The __IPC_MEGA option will have no effect for these shmgets and will be ignored.

Specification of the __IPC_MEGA option for large segments will result in significant real storage savings and reduced ESQA usage, especially as the number of shares increases.

Valid values for the argument shmflg include any combination of the following constants defined in <sys/ipc.h> and <sys/modes.h>:
__IPC_SHAREAS
This flag enables the sharing of the same storage area from multiple processes in the same address space. When specified by an AMODE 31 application, this flag is only honored when __IPC_MEGA is also specified, otherwise it is ignored. When specified by an AMODE 64 application, this flag is honored for any type of shared memory segment that is obtained above the bar.
__IPC_BELOWBAR
Forces the memory object to be allocated from below the 2 gigabyte address range. This can be used to allow AMODE 64 applications to share objects with non-AMODE 64 applications. This option is mutually exclusive with the __IPC_GIGA option. If a 31-bit application specifies this option, then the request will be failed with EINVAL.
IPC_CREAT
Create a shared memory segment if the key specified does not already have an associated ID. IPC_CREAT is ignored when IPC_PRIVATE is specified.
IPC_EXCL
Causes the shmget() function to fail if the key specified has an associated ID. IPC_EXCL is ignored when IPC_CREAT is not specified or IPC_PRIVATE is specified.
__IPC_GIGA
Requests a shared memory segment with a size in gigabyte multiples. Use of this option requires that the size parameter be specified as a gigabyte multiple. Failure to use a gigabyte multiple will result in a failure. [EINVAL] This option is mutually exclusive with the __IPC_BELOWBAR and __IPC_MEGA options.
__IPC_MEGA
Requests a shared memory segment with the size in megabyte multiples. Use of this option requires that the size parameter, size_t, be in a megabyte multiple. The __IPC_MEGA option is required to create the shared memory segment but the __IPC_MEGA option is not required to acquire access to a previously defined/created shared memory segment that has the __IPC_MEGA attribute. When specified by an AMODE 64 application, option __IPC_BELOWBAR is implied and megaroo sharing will be in effect. This option is mutually exclusive with the __IPC_GIGA option.
S_IRGRP
Permits read access when the effective group ID of the caller matches either shm_perm.cgid or shm_perm.gid.
S_IROTH
Permits other read access.
S_IRUSR
Permits read access when the effective user ID of the caller matches either shm_perm.cuid or shm_perm.uid.
S_IWGRP
Permits write access when the effective group ID of the caller matches either shm_perm.cgid or shm_perm.gid.
S_IWOTH
Permits other write access.
S_IWUSR
Permits write access when the effective user ID of the caller matches either shm_perm.cuid or shm_perm.uid.

When a shared memory segment associated with argument key already exists, setting IPC_EXCL and IPC_CREAT in argument shmflg will force shmget() to fail.

The following fields are initialized when a shmid_ds data structure is created:
  • The fields shm_perm.cuid and shm_perm.uid are set equal to the effective user ID of the calling process
  • The fields shm_perm.cgid and sem_perm.gid are set equal to the effective group ID of the calling process
  • The low-order 9 bits of shm_perm.mode are set to the value in the low-order 9 bits of shmflg
  • The field shm_segsz is set equal to the value of the argument size
  • The field shm_lpid, shm_nattach, shm_atime, and shm_dtime are set equal to zero
  • The value of shm_ctime is set equal to the current time

Usage notes

  • Shared memory segments created with __IPC_MEGA will show this bit in S_MODE byte returned with w_getipc.

Special behavior for AMODE 64: Applications will not be allowed to change the address to which a shared memory segment allocated is attached, when it resides above the 2 gigabyte address range. The size parameter is rounded up to a megabyte multiple for AMODE 64 users.

Returned value

If successful, shmget() returns a nonnegative integer, namely a shared memory identifier.

If unsuccessful, shmget() returns -1 and sets errno to one of the following values:
Error Code
Description
EACCES
A shared memory identifier exists for the argument key, but operation permission as specified by the low-order 9 bits of shmflg could not be granted
EEXIST
A shared memory identifier exists for the argument key and both IPC_CREAT and IPC_EXCL are specified in shmflg
EINVAL
A shared memory identifier does not exist for the argument key specified and the value of argument size is less than the system-imposed minimum or greater than the system-imposed maximum.

OR a shared memory identifier exists for the argument key, but the size of the segment associated with it is less that specified by argument size.

OR __IPC_MEGA is specified and the segment size, size_t, is not in megabyte multiples.

ENOENT
A shared memory identifier does not exist for the argument, key, and IPC_CREAT is not specified.
ENOMEM
A shared memory identifier and associated shared memory segment are to be created but the amount of available system storage was insufficient to fill the request.
ENOSPC
A shared memory identifier is to be created but the system-imposed limit on the maximum number of allocated shared memory identifiers, system-wide, would be exceeded.
When shmflg equals 0, the following applies:
  • If a shared memory identifier has already been created with key earlier, and the calling process of this shmget() has read and/or write permissions to it, then shmget() returns the associated shared memory identifier.
  • If a shared memory identifier has already been created with key earlier, and the calling process of this shmget() does not have read and/or write permissions to it, then shmget() returns-1 and sets errno to EACCES.
  • If a shared memory identifier has not been created with key earlier, then shmget() returns -1 and sets errno to ENOENT.

Related information

Parent topic: Library functions