Seth Woolley's Man Viewer

shmget(2) - shmget, shmget - allocates a shared memory segment - man 2 shmget

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

SHMGET(2)                  Linux Programmer's Manual                 SHMGET(2)



NAME
       shmget - allocates a shared memory segment

SYNOPSIS
       #include <sys/ipc.h>

       #include <sys/shm.h>

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

DESCRIPTION
       shmget() returns the identifier of the shared memory segment associated
       with the value of the argument key.  A new shared memory segment,  with
       size  equal to the value of size rounded up to a multiple of PAGE_SIZE,
       is created if(3,n) key has the value IPC_PRIVATE or key  isn't  IPC_PRIVATE,
       no  shared memory segment corresponding to key exists, and IPC_CREAT is
       asserted in(1,8) shmflg (i.e.  shmflg&IPC_CREAT isn't zero).

       The value shmflg is composed of:

       IPC_CREAT   to create a new segment. If this flag  is  not  used,  then
                   shmget()  will  find  the  segment  associated with key and
                   check to see if(3,n) the user has permission to access(2,5) the  seg-
                   ment.

       IPC_EXCL    used  with  IPC_CREAT  to  ensure  failure  if(3,n)  the segment
                   already exists.

       mode_flags (lowest 9 bits)
                   specifying the permissions granted to the owner, group, and
                   world.   Presently, the execute permissions are not used by
                   the system.

       If a new segment is created, the access(2,5)  permissions  from  shmflg  are
       copied  into the shm_perm member of the shmid_ds structure that defines
       the segment.  The shmid_ds structure has the following form:

            struct shmid_ds {
                struct ipc_perm shm_perm;    /* operation perms */
                int             shm_segsz;   /* size of segment (bytes) */
                time_t          shm_atime;   /* last attach time(1,2,n) */
                time_t          shm_dtime;   /* last detach time(1,2,n) */
                time_t          shm_ctime;   /* last change time(1,2,n) */
                unsigned short  shm_cpid;    /* pid of creator */
                unsigned short  shm_lpid;    /* pid of last operator */
                short           shm_nattch;  /* no. of current attaches */
            };

            struct ipc_perm {
                key_t  key;
                ushort uid;   /* owner euid and egid */
                ushort gid;
                ushort cuid;  /* creator euid and egid */
                ushort cgid;
                ushort mode;  /* lower 9 bits of shmflg */
                ushort seq;   /* sequence number */
            };

       When creating a new shared memory segment, the system call  initializes
       the shmid_ds data structure shmid_ds as follows:

              shm_perm.cuid  and shm_perm.uid are set(7,n,1 builtins) to the effective user-ID
              of the calling process.

              shm_perm.cgid and shm_perm.gid are set(7,n,1 builtins) to the effective group-ID
              of the calling process.

              The  lowest  order 9 bits of shm_perm.mode are set(7,n,1 builtins) to the lowest
              order 9 bit of shmflg.

              shm_segsz is set(7,n,1 builtins) to the value of size.

              shm_lpid, shm_nattch, shm_atime and shm_dtime are set(7,n,1 builtins) to 0.

              shm_ctime is set(7,n,1 builtins) to the current time.

       If the shared memory segment already exists, the access(2,5) permissions are
       verified, and a check is made to see if(3,n) it is marked for destruction.


SYSTEM CALLS
       fork() After  a  fork()  the  child inherits the attached shared memory
              segments.

       exec(3,n,1 builtins)() After an exec(3,n,1 builtins)() all attached shared memory segments are detached
              (not destroyed).

       exit(3,n,1 builtins)() Upon  exit(3,n,1 builtins)()  all  attached  shared memory segments are detached
              (not destroyed).


RETURN VALUE
       A valid segment identifier, shmid, is returned on success, -1 on error.

ERRORS
       On failure, errno is set(7,n,1 builtins) to one of the following:

       EACCES      The user does not have permission to access(2,5) the shared mem-
                   ory segment, and does not have the  CAP_IPC_OWNER  capabil-
                   ity.

       EEXIST      IPC_CREAT  | IPC_EXCL was specified and the segment exists.

       EINVAL      A new segment was to be created and size < SHMMIN or size >
                   SHMMAX, or no new segment was to be created, a segment with
                   given key existed, but size is greater  than  the  size  of
                   that segment.

       ENFILE      The system limit on the total number of open(2,3,n) files has been
                   reached.

       ENOENT      No segment exists for the given key, and IPC_CREAT was  not
                   specified.

       ENOMEM      No memory could be allocated for segment overhead.

       ENOSPC      All  possible  shared memory id's have been taken (SHMMNI),
                   or allocating a segment of the requested size  would  cause
                   the system to exceed the system-wide limit on shared memory
                   (SHMALL).

NOTES
       IPC_PRIVATE isn't a flag field but a key_t type.  If this special value
       is  used  for  key,  the  system call ignores everything but the lowest
       order 9 bits of shmflg and creates a new shared memory segment (on suc-
       cess).

       The  followings are limits on shared memory segment resources affecting
       a shmget call:

       SHMALL     System wide maximum of shared memory  pages:  policy  depen-
                  dent.

       SHMMAX     Maximum size in(1,8) bytes for a shared memory segment: implemen-
                  tation dependent (currently 4M).

       SHMMIN     Minimum size in(1,8) bytes for a shared memory segment: implemen-
                  tation  dependent (currently 1 byte, though PAGE_SIZE is the
                  effective minimum size).

       SHMMNI     System wide maximum number of shared memory segments: imple-
                  mentation  dependent  (currently  4096, was 128 before Linux
                  2.3.99).

       The implementation has no specific limits for the per  process  maximum
       number of shared memory segments (SHMSEG).

BUGS
       The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW would more
       clearly show its function.

CONFORMING TO
       SVr4, SVID.  SVr4  documents  an  additional  error(8,n)  condition  EEXIST.
       Until  version(1,3,5) 2.3.30 Linux would return EIDRM for a shmget on a shared
       memory segment scheduled for deletion.

SEE ALSO
       shmat(2), shmctl(2), shmdt(2), ftok(3), ipc(2,5)(5), capabilities(7)



Linux 2.6.7                       2004-06-17                         SHMGET(2)

References for this manual (incoming links)