Seth Woolley's Man Viewer

shmctl(2) - shmctl, shmctl - shared memory control - man 2 shmctl

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

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

       shmctl - shared memory control

       #include <sys/ipc.h>

       #include <sys/shm.h>

       int shmctl(int shmid, int cmd, struct shmid_ds *buf);

       shmctl() allows the user to receive information on a shared memory seg-
       ment, set(7,n,1 builtins) the owner, group, and permissions of a shared memory segment,
       or  destroy  a segment. The information about the segment identified by
       shmid is returned in(1,8) a shmid_ds structure:

           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 */

       The highlighted fields in(1,8) the member shm_perm can be set:

           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 access(2,5) modes */
               ushort seq;   /* sequence number */

       The following cmds are available:

       IPC_STAT    is used to copy the information  about  the  shared  memory
                   segment into the buffer buf. The user must have read(2,n,1 builtins) access(2,5)
                   to the shared memory segment.

       IPC_SET     is used to apply the changes the user has made to the  uid,
                   gid, or mode members of the shm_perms field.  Only the low-
                   est 9 bits of mode are used.  The shm_ctime member is  also
                   updated.   The  user  must  be  the owner or creator, or be

       IPC_RMID    is used to mark the segment as destroyed. It will  actually
                   be  destroyed  after  the  last  detach.   (I.e.,  when the
                   shm_nattch member of the associated structure  shmid_ds  is
                   zero.)  The user must be the owner or creator, or be privi-

       The user must ensure that a segment is eventually destroyed;  otherwise
       its pages that were faulted in(1,8) will remain in(1,8) memory or swap.

   Linux additions
       A privileged user can prevent or allow swapping of a shared memory seg-
       ment with the following cmds:

       SHM_LOCK    prevents swapping of a shared memory segment. The user must
                   fault  in(1,8)  any  pages that are required to be present after
                   locking is enabled.

       SHM_UNLOCK  allows the shared memory segment to be swapped out.

       The IPC_INFO, SHM_STAT and SHM_INFO  control  calls  are  used  by  the
       ipcs(8) program to provide information on allocated resources.

       On  success,  zero is returned.  On error(8,n), -1 is returned, and errno is
       set(7,n,1 builtins) appropriately.

       EACCES     IPC_STAT or SHM_STAT is requested  and  shm_perm.modes  does
                  not  allow  read(2,n,1 builtins)  access(2,5)  for shmid, and the calling process
                  does not have the CAP_IPC_OWNER capability.

       EFAULT     The argument cmd has  value  IPC_SET  or  IPC_STAT  but  the
                  address pointed to by buf isn't accessible.

       EIDRM      shmid points to a removed identifier.

       EINVAL     shmid  is not a valid identifier, or cmd is not a valid com-

       EOVERFLOW  IPC_STAT is attempted, and the gid or uid value is too large
                  to be stored in(1,8) the structure pointed to by buf.

       EPERM      IPC_SET  or IPC_RMID is attempted, and the effective user ID
                  of the calling process is not that of the creator (found  in(1,8)
                  shm_perm.cuid),  or  the  owner (found in(1,8) shm_perm.uid), and
                  the process was not privileged  (Linux:  did  not  have  the
                  CAP_SYS_ADMIN capability).

                  Or,  SHM_LOCK  or  SHM_UNLOCK was specified, but the process
                  was not privileged (Linux: did  not  have  the  CAP_IPC_LOCK

       Various  fields  in(1,8)  a  struct shmid_ds were shorts under Linux 2.2 and
       have become longs under Linux 2.4. To take advantage of this, a  recom-
       pilation  under glibc-2.1.91 or later should suffice.  (The kernel dis-
       tinguishes old and new calls by an IPC_64 flag in(1,8) cmd.)

       SVr4, SVID.  SVr4 documents additional error(8,n) conditions EINVAL, ENOENT,
       ENOSPC, ENOMEM, EEXIST.  Neither SVr4 nor SVID documents an EIDRM error(8,n)

       shmget(2), shmop(2), capabilities(7)

Linux 2.6.7                       2004-06-17                         SHMCTL(2)

References for this manual (incoming links)