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

NAME
       semctl - semaphore control operations

SYNOPSIS
       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/sem.h>

       #if defined(__GNU_LIBRARY__) && !defined(_SEM_SEMUN_UNDEFINED)
       /* union semun is defined by including <sys/sem.h> */
       #else
       /* according to X/OPEN we have to define it ourselves */
       union semun {
               int val;                    /* value for SETVAL */
               struct semid_ds *buf;       /* buffer for IPC_STAT, IPC_SET */
               unsigned short int *array;  /* array for GETALL, SETALL */
               struct seminfo *__buf;      /* buffer for IPC_INFO */
       };
       #endif

       int  semctl  (int  semid, int semnum, int cmd, union semun
       arg)

DESCRIPTION
       The function performs the control operation  specified  by
       cmd on the semaphore set (or on the semnum-th semaphore of
       the set) identified by semid.  The first semaphore of  the
       set is indicated by a value 0 for semnum.

       Legal values for cmd are

       IPC_STAT    Copy  info  from the semaphore set data struc-
                   ture into the structure pointed to by arg.buf.
                   The  argument  semnum is ignored.  The calling
                   process must have read  access  privileges  on
                   the semaphore set.

       IPC_SET     Write  the  values  of  some  members  of  the
                   semid_ds structure pointed to  by  arg.buf  to
                   the  semaphore  set  data  structure, updating
                   also its sem_ctime member.  Considered members
                   from the user supplied struct semid_ds pointed
                   to by arg.buf are

                        sem_perm.uid
                        sem_perm.gid
                        sem_perm.mode  /* only lowest 9-bits */

                   The calling process effective user-ID must  be
                   one  among super-user, creator or owner of the
                   semaphore  set.   The   argument   semnum   is
                   ignored.

       IPC_RMID    Remove  immediately  the semaphore set and its
                   data structures  awakening  all  waiting  pro-
                   cesses  (with an error return and errno set to
                   EIDRM).  The calling process effective user-ID
                   must be one among super-user, creator or owner
                   of the semaphore set.  The argument semnum  is
                   ignored.

       GETALL      Return  semval  for  all semaphores of the set
                   into  arg.array.   The  argument   semnum   is
                   ignored.   The  calling process must have read
                   access privileges on the semaphore set.

       GETNCNT     The system call returns the value  of  semncnt
                   for  the  semnum-th semaphore of the set (i.e.
                   the  number  of  processes  waiting   for   an
                   increase of semval for the semnum-th semaphore
                   of the set).  The calling  process  must  have
                   read access privileges on the semaphore set.

       GETPID      The  system  call  returns the value of sempid
                   for the semnum-th semaphore of the  set  (i.e.
                   the  pid of the process that executed the last
                   semop call for the semnum-th semaphore of  the
                   set).   The  calling  process  must  have read
                   access privileges on the semaphore set.

       GETVAL      The system call returns the  value  of  semval
                   for  the  semnum-th semaphore of the set.  The
                   calling process must have read  access  privi-
                   leges on the semaphore set.

       GETZCNT     The  system  call returns the value of semzcnt
                   for the semnum-th semaphore of the  set  (i.e.
                   the  number of processes waiting for semval of
                   the semnum-th semaphore of the set  to  become
                   0).  The calling process must have read access
                   privileges on the semaphore set.

       SETALL      Set semval for all semaphores of the set using
                   arg.array,  updating also the sem_ctime member
                   of the semid_ds structure  associated  to  the
                   set.   Undo  entries  are  cleared for altered
                   semaphores in all processes.  Processes sleep-
                   ing  on  the  wait  queue are awakened if some
                   semval becomes 0 or increases.   The  argument
                   semnum  is  ignored.  The calling process must
                   have alter access privileges on the  semaphore
                   set.

       SETVAL      Set  the  value  of  semval to arg.val for the
                   semnum-th semaphore of the set, updating  also
                   the sem_ctime member of the semid_ds structure
                   associated to the set.  Undo entry is  cleared
                   for  altered semaphore in all processes.  Pro-
                   cesses sleeping on the wait queue are awakened
                   if semval becomes 0 or increases.  The calling
                   process must have alter access  privileges  on
                   the semaphore set.

RETURN VALUE
       On  fail  the system call returns -1 with errno indicating
       the error.  Otherwise the system call returns  a  nonnega-
       tive value depending on cmd as follows:

       GETNCNT    the value of semncnt.

       GETPID     the value of sempid.

       GETVAL     the value of semval.

       GETZCNT    the value of semzcnt.

ERRORS
       For  a  failing return, errno will be set to one among the
       following values:

       EACCES     The calling process has no  access  permissions
                  needed to execute cmd.

       EFAULT     The  address pointed to by arg.buf or arg.array
                  isn't accessible.

       EIDRM      The semaphore set was removed.

       EINVAL     Invalid value for cmd or semid.

       EPERM      The argument cmd has value IPC_SET or  IPC_RMID
                  but  the  calling process effective user-ID has
                  insufficient privileges to execute the command.

       ERANGE     The argument cmd has value SETALL or SETVAL and
                  the value to which semval has to  be  set  (for
                  some  semaphore  of  the set) is less than 0 or
                  greater than the implementation value SEMVMX.

NOTES
       The IPC_INFO, SEM_STAT and SEM_INFO control calls are used
       by the ipcs(8) program to provide information on allocated
       resources.  In the future these can be modified as  needed
       or moved to a proc file system interface.

       The  following  system  limit  on semaphore sets affects a
       semctl call:

       SEMVMX     Maximum value for semval: implementation depen-
                  dent (32767).

CONFORMING TO
       SVr4,  SVID.   SVr4 documents more error conditions EINVAL
       and EOVERFLOW.

SEE ALSO
       ipc(5), shmget(2), shmat(2), shmdt(2).

Linux 0.99.13            November 1, 1993                       1