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 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 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 */
               time_t shm_dtime;          /* last detach time */
               time_t shm_ctime;          /* last change time */
               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 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 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 access
                   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, creator, or the

       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, creator, or the super-

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

       In  addition,  the super-user can prevent or allow swapping of a shared
       memory segment with the following cmds: (Linux only)

       SHM_LOCK    prevents swapping of a shared memory segment. The user must
                   fault  in  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.  In the
       future, these may be modified as needed or moved to a proc file  system

       0 is returned on success, -1 on error.

       On error, errno will be set to one of the following:

       EACCES      is  returned  if  IPC_STAT  is requested and shm_perm.modes
                   does not allow read access for shmid.

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

       EINVAL      is  returned  if shmid is not a valid identifier, or cmd is
                   not a valid command.

       EIDRM       is returned if shmid points to a removed identifier.

       EPERM       is returned if IPC_SET or IPC_RMID is  attempted,  and  the
                   effective user ID of the calling process is not the creator
                   (as  found  in  shm_perm.cuid),  the  owner  (as  found  in
                   shm_perm.uid), or the super-user.

       EOVERFLOW   is  returned  if  IPC_STAT is attempted, and the gid or uid
                   value is too large to be stored in the structure pointed to
                   by buf.

       Various  fields  in  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 a IPC_64 flag in cmd.)

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

       shmget(2), shmop(2)

Linux 2.4.1                       2002-01-05                         SHMCTL(2)