NAME

     shmctl - shared memory control

SYNOPSIS

     #include <sys/ipc.h>

     #include <sys/shm.h>

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

DESCRIPTION

     shmctl() allows the user to receive information on a  shared
     memory  segment,  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 following are private */
               unsigned short   shm_npages;  /* size of segment (pages) */
               unsigned long   *shm_pages;
               struct shm_desc *attaches;    /* descriptors for attaches */
          };

     The 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  seg-
                 ment.

     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 lowest 9 bits of mode
                 are used.  The shm_ctime member is also updated.
                 The user must be  the  owner,  creator,  or  the
                 super-user.

     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-
                 user.

     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 man be modified  as  needed
     or moved to a proc file system interface.

SYSTEM CALLS

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

     exec()
          After an exec() all attached shared memory segments are
          detached (not destroyed).

     exit()
          Upon exit() all attached  shared  memory  segments  are
          detached (not destroyed).

RETURN VALUE

     0 is returned on success, -1 on error.

ERRORS

     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
                 msqid.

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

     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  iden-
                 tifier.

     EPERM       is returned if IPC_SET or IPC_RMID is attempted,
                 and  the  user is not the creator, the owner, or
                 the super-user, and the user does not have  per-
                 mission granted to their group or to the world.

CONFORMING TO

     SVr4, SVID.  SVr4 documents additional error conditions EIN-
     VAL,  ENOENT, ENOSPC, ENOMEM, EEXIST.  Neither SVr4 nor SVID
     documents an EIDRM error condition.

SEE ALSO

     shmget(2), shmop(2)