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

NAME
       semop - semaphore operations

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

       int semop ( int semid, struct sembuf *sops, unsigned nsops
       )

DESCRIPTION
       The function performs operations on  selected  members  of
       the  semaphore  set indicated by semid.  Each of the nsops
       elements in the array pointed to by sops specify an opera-
       tion  to  be  performed  on a semaphore by a struct sembuf
       including the following members:

            short sem_num;  /* semaphore number: 0 = first */
            short sem_op;   /* semaphore operation */
            short sem_flg;  /* operation flags */

       Flags recognized in sem_flg are IPC_NOWAIT  and  SEM_UNDO.
       If  an  operation asserts SEM_UNDO, it will be undone when
       the process exits.

       The system call semantic assures that the operations  will
       be  performed  if  and  only  if all of them will succeed.
       Each operation is performed on the sem_num-th semaphore of
       the  semaphore  set - where the first semaphore of the set
       is semaphore 0 - and is one among the following three.

       If sem_op is a positive integer, the operation  adds  this
       value to semval.  Furthermore, if SEM_UNDO is asserted for
       this operation, the system updates the process undo  count
       for this semaphore.  The operation always goes through, so
       no process sleeping can happen.  The calling process  must
       have alter permissions on the semaphore set.

       If  sem_op is zero, the process must have read access per-
       missions on the semaphore set.  If  semval  is  zero,  the
       operation  goes  through.   Otherwise,  if  IPC_NOWAIT  is
       asserted in sem_flg, the system call  fails  (undoing  all
       previous  actions  performed)  with  errno  set to EAGAIN.
       Otherwise semzcnt is incremented by one  and  the  process
       sleeps until one of the following occurs:

              o      semval becomes 0, at which time the value of
                     semzcnt is decremented.

              o      The semaphore set  is  removed:  the  system
                     call fails with errno set to EIDRM.

              o      The  calling  process receives a signal that
                     has to be caught: the value  of  semzcnt  is
                     decremented  and  the system call fails with
                     errno set to EINTR.

       If sem_op is less than zero, the process must  have  alter
       permissions  on  the  semaphore set.  If semval is greater
       than or equal to the absolute value of sem_op,  the  abso-
       lute  value  of  sem_op is subtracted by semval.  Further-
       more, if SEM_UNDO is asserted for this operation, the sys-
       tem  updates  the  process  undo count for this semaphore.
       Then the operation goes through.  Otherwise, if IPC_NOWAIT
       is asserted in sem_flg, the system call fails (undoing all
       previous actions performed)  with  errno  set  to  EAGAIN.
       Otherwise  semncnt  is  incremented by one and the process
       sleeps until one of the following occurs:

              o      semval becomes greater or equal to the abso-
                     lute  value  of  sem_op,  at  which time the
                     value of semncnt is decremented,  the  abso-
                     lute value of sem_op is subtracted from sem-
                     val and, if SEM_UNDO is  asserted  for  this
                     operation,  the  system  updates the process
                     undo count for this semaphore.

              o      The semaphore set is removed from  the  sys-
                     tem: the system call fails with errno set to
                     EIDRM.

              o      The calling process receives a  signal  that
                     has  to  be  caught: the value of semncnt is
                     decremented and the system call  fails  with
                     errno set to EINTR.

       In case of success, the sempid member of the structure sem
       for each semaphore specified in the array  pointed  to  by
       sops  is  set  to  the  process-ID of the calling process.
       Furthermore both sem_otime and sem_ctime are  set  to  the
       current time.

RETURN VALUE
       If  successful  the  system  call  returns 0, otherwise it
       returns -1 with errno indicating the error.

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

       E2BIG      The  argument nsops is greater than SEMOPM, the
                  maximum number of operations allowed per system
                  call.

       EACCES     The  calling  process has no access permissions
                  on the semaphore set as required by one of  the
                  specified operations.

       EAGAIN     An   operation   could   not   go  through  and
                  IPC_NOWAIT was asserted in its sem_flg.

       EFAULT     The address pointed to by sops  isn't  accessi-
                  ble.

       EFBIG      For some operation the value of sem_num is less
                  than 0 or greater than or equal to  the  number
                  of semaphores in the set.

       EIDRM      The semaphore set was removed.

       EINTR      Sleeping  on a wait queue, the process received
                  a signal that had to be caught.

       EINVAL     The semaphore set doesn't exist,  or  semid  is
                  less  than  zero,  or  nsops has a non-positive
                  value.

       ENOMEM     The sem_flg of some operation asserted SEM_UNDO
                  and  the  system has not enough memory to allo-
                  cate the undo structure.

       ERANGE     For some operation semop+semval is greater than
                  SEMVMX,  the  implementation  dependent maximum
                  value for semval.

NOTES
       The sem_undo structures of a process aren't  inherited  by
       its child on execution of a fork(2) system call.  They are
       instead inherited by the substituting process resulting by
       the execution of the execve(2) system call.

       The  followings  are  limits  on  semaphore  set resources
       affecting a semop call:

       SEMOPM     Maximum number of operations  allowed  for  one
                  semop call: policy dependent.

       SEMVMX     Maximum allowable value for semval: implementa-
                  tion dependent (32767).

       The implementation has no intrinsic limits for the  adjust
       on  exit  maximum  value (SEMAEM), the system wide maximum
       number of undo structures (SEMMNU)  and  the  per  process
       maximum number of undo entries system parameters.

BUGS
       The  system maintains a per process sem_undo structure for
       each semaphore altered by the process with undo  requests.
       Those  structures  are  free  at  process exit.  One major
       cause for unhappiness with the undo mechanism is  that  it
       does not fit in with the notion of having an atomic set of
       operations an array of semaphores.  The undo requests  for
       an  array and each semaphore therein may have been accumu-
       lated over many semopt calls.  Should  the  process  sleep
       when  exiting,  or  should  all undo operations be applied
       with the IPC_NOWAIT flag in effect?  Currently those  undo
       operations  which  go through immediately are applied, and
       those that require a  wait  are  ignored  silently.   Thus
       harmless  undo usage is guaranteed with private semaphores
       only.

CONFORMING TO
       SVr4, SVID.  SVr4 documents  additional  error  conditions
       EINVAL, EFBIG, ENOSPC.

SEE ALSO
       ipc(5), semctl(2), semget(2).

Linux 0.99.13            November 1, 1993                       1