SEMOP(2)                    BSD System Calls Manual                   SEMOP(2)

NAME
     semop -- atomic array of operations on a semaphore set

SYNOPSIS
     #include <sys/sem.h>

     int
     semop(int semid, struct sembuf *sops, size_t nsops);

DESCRIPTION
     The semop() system call atomically performs the array of operations indi-
     cated by sops on the semaphore set indicated by semid.  The length of
     sops is indicated by nsops.  Each operation is encoded in a struct
     sembuf, which is defined as follows:

     struct sembuf {
             u_short sem_num;        /* semaphore # */
             short   sem_op;         /* semaphore operation */
             short   sem_flg;        /* operation flags */
     };

     For each element in sops, sem_op and sem_flg determine an operation to be
     performed on semaphore number sem_num in the set.  The values SEM_UNDO
     and IPC_NOWAIT may be OR'ed into the sem_flg member in order to modify
     the behavior of the given operation.

     The operation performed depends as follows on the value of sem_op:

     o   When sem_op is positive and the process has alter permission, the
         semaphore's value is incremented by sem_op's value.  If SEM_UNDO is
         specified, the semaphore's adjust on exit value is decremented by
         sem_op's value.  A positive value for sem_op generally corresponds to
         a process releasing a resource associated with the semaphore.

     o   The behavior when sem_op is negative and the process has alter per-
         mission, depends on the current value of the semaphore:

         o   If the current value of the semaphore is greater than or equal to
             the absolute value of sem_op, then the value is decremented by
             the absolute value of sem_op.  If SEM_UNDO is specified, the sem-
             aphore's adjust on exit value is incremented by the absolute
             value of sem_op.

         o   If the current value of the semaphore is less than the absolute
             value of sem_op, one of the following happens:

             o   If IPC_NOWAIT was specified, then semop() returns immediately
                 with a return value of EAGAIN.

             o   Otherwise, the calling process is put to sleep until one of
                 the following conditions is satisfied:

                 o   Some other process removes the semaphore with the
                     IPC_RMID option of semctl(2).  In this case, semop()
                     returns immediately with a return value of EIDRM.

                 o   The process receives a signal that is to be caught.  In
                     this case, the process will resume execution as defined
                     by sigaction(2).

                 o   The semaphore's value is greater than or equal to the
                     absolute value of sem_op.  When this condition becomes
                     true, the semaphore's value is decremented by the abso-
                     lute value of sem_op, the semaphore's adjust on exit
                     value is incremented by the absolute value of sem_op.

         A negative value for sem_op generally means that a process is waiting
         for a resource to become available.

     o   When sem_op is zero and the process has read permission, one of the
         following will occur:

         o   If the current value of the semaphore is equal to zero then
             semop() can return immediately.

         o   If IPC_NOWAIT was specified, then semop() returns immediately
             with a return value of EAGAIN.

         o   Otherwise, the calling process is put to sleep until one of the
             following conditions is satisfied:

             o   Some other process removes the semaphore with the IPC_RMID
                 option of semctl(2).  In this case, semop() returns immedi-
                 ately with a return value of EIDRM.

             o   The process receives a signal that is to be caught.  In this
                 case, the process will resume execution as defined by
                 sigaction(2).

             o   The semaphore's value becomes zero.

     For each semaphore a process has in use, the kernel maintains an ``adjust
     on exit'' value, as alluded to earlier.  When a process exits, either
     voluntarily or involuntarily, the adjust on exit value for each semaphore
     is added to the semaphore's value.  This can be used to insure that a
     resource is released if a process terminates unexpectedly.

RETURN VALUES
     The semop() function returns the value 0 if successful; otherwise the
     value -1 is returned and the global variable errno is set to indicate the
     error.

ERRORS
     The semop() system call will fail if:

     [E2BIG]            Too many operations are specified.  [SEMOPM]

     [EACCES]           Permission is denied, due to a mismatch between the
                        operation and the mode of the semaphore set.

     [EAGAIN]           The semaphore's value would result in the process
                        being put to sleep and IPC_NOWAIT is specified.

     [EFBIG]            sem_num is not in the range of valid semaphores for
                        the set.

     [EIDRM]            The semaphore set is removed from the system.

     [EINTR]            The semop() system call is interrupted by a signal.

     [EINVAL]           No semaphore set corresponds to semid, or the process
                        would exceed the system-defined limit for the number
                        of per-process SEM_UNDO structures.

     [ENOSPC]           The system SEM_UNDO pool [SEMMNU] is full.

     [ERANGE]           The requested operation would cause either the sema-
                        phore's current value [SEMVMX] or its adjust-on-exit
                        value [SEMAEM] to exceed the system-imposed limits.

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

     The include files <sys/types.h> and <sys/ipc.h> are necessary.

SEE ALSO
     semctl(2), semget(2), sigaction(2), compat(5)

BUGS
     The semop() system call may block waiting for memory even if IPC_NOWAIT
     was specified.

BSD                           September 22, 1995                           BSD