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

       A semaphore is represented by an anonymous structure including the fol-
       lowing members:

           unsigned short  semval;   /* semaphore value */
           unsigned short  semzcnt;  /* # waiting for zero */
           unsigned short  semncnt;  /* # waiting for increase */
           pid_t           sempid;   /* process that did last op */

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

           unsigned short sem_num;  /* semaphore number */
           short sem_op;            /* semaphore operation */
           short sem_flg;           /* operation flags */

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

       The set of operations contained in sops is performed  atomically,  that
       is, the operations are performed at the same time, and only if they can
       all be simultaneously performed.  The behaviour of the system  call  if
       not all operations can be performed immediately depends on the presence
       of the IPC_NOWAIT flag in  the  individual  sem_flg  fields,  as  noted
       below.

       Each  operation  is  performed  on  the  sem_num-th  semaphore  of  the
       semaphore set, where the first semaphore of the  set  is  semaphore  0.
       There  are  three  types  of  operation,  distinguished by the value of
       sem_op.

       If sem_op is a positive integer, the operation adds this value  to  the
       semaphore  value  (semval).   Furthermore,  if SEM_UNDO is asserted for
       this operation, the system updates the process undo count (semadj)  for
       this  semaphore.  This operation can always proceed - it never forces a
       process to wait.  The calling process must have alter permission on the
       semaphore set.

       If  sem_op is zero, the process must have read access permission on the
       semaphore set.  This is a "wait-for-zero" operation: if semval is zero,
       the  operation  can  immediately  proceed.  Otherwise, if IPC_NOWAIT is
       asserted in sem_flg, the system call fails with  errno  set  to  EAGAIN
       (and  none  of the operations in sops is performed).  Otherwise semzcnt

             The calling process catches a signal: 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 permission  on
       the  semaphore set.  If semval is greater than or equal to the absolute
       value of sem_op, the operation can proceed  immediately:  the  absolute
       value of sem_op is subtracted from semval, and, if SEM_UNDO is asserted
       for this operation, the system updates the process undo count  (semadj)
       for  this  semaphore.   If the absolute value of sem_op is greater than
       semval, and IPC_NOWAIT is asserted in sem_flg, the system  call  fails,
       with  errno  set  to EAGAIN (and none of the operations in sops is per-
       formed).  Otherwise semncnt (the counter of processes waiting for  this
       semaphore's  value  to  increase) is incremented by one and the process
       sleeps until one of the following occurs:

             semval becomes greater than or equal to the  absolute  value  of
              sem_op,  at  which time the value of semncnt is decremented, the
              absolute value of sem_op  is  subtracted  from  semval  and,  if
              SEM_UNDO  is asserted for this operation, the system updates the
              process undo count (semadj) for this semaphore.

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

             The  calling  process  catches a signal: the value of semncnt is
              decremented and the system call fails with errno set to EINTR.

       On successful completion, the sempid value for each semaphore specified
       in the array pointed to by sops is set to the process ID of the calling
       process.  In addition, the sem_otime is set to the current time.


RETURN VALUE

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


ERRORS

       On failure, errno is set to one of the following:

       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 proceed immediately and IPC_NOWAIT was
              asserted in its sem_flg.

       EFAULT The address pointed to by sops isn't accessible.

       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  While  blocked in this system call, the process caught a signal.


NOTES

       The  sem_undo structures of a process aren't inherited across a fork(2)
       system call, but they are inherited across a execve(2) system call.

       semop is never automatically restarted after  being  interrupted  by  a
       signal  handler, regardless of the setting of the SA_RESTART flags when
       establishing a signal handler.

       semadj is a per-process integer which is simply the (negative) count of
       all  semaphore operations performed specifying the SEM_UNDO flag.  When
       a semaphore's value is directly set using the SETVAL or SETALL  request
       to  semctl(2),  the  corresponding  semadj  values in all processes are
       cleared.

       The semval, sempid, semzcnt, and semnct values for a semaphore can  all
       be retrieved using appropriate semctl(2) calls.

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

       SEMOPM Maximum number of operations allowed for one semop call (32).

       SEMVMX Maximum allowable value  for  semval:  implementation  dependent
              (32767).

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


BUGS

       When a process terminates, its set of associated semadj  structures  is
       used to undo the effect of all of the semaphore operations it performed
       with the SEM_UNDO flag.  This raises a difficulty: if one (or more)  of
       these  semaphore  adjustments  would result in an attempt to decrease a
       semaphore's value below zero, what should an  implementation  do?   One
       possible approach would be to block until all the semaphore adjustments
       could be performed.  This is however undesirable since it  could  force
       process  termination  to  block  for arbitrarily long periods.  Another
       possibility is that such semaphore adjustments could be  ignored  alto-
       gether  (somewhat  analogously  to failing when IPC_NOWAIT is specified
       for a semaphore operation).  Linux adopts a third approach:  decreasing
       the  semaphore  value  as  far as possible (i.e., to zero) and allowing
       process termination to proceed immediately.


CONFORMING TO

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


SEE ALSO

       ipc(5), semctl(2), semget(2), sigaction(2)

Linux 2.4                         2002-01-08                          semop(2)