NAME

semop - semaphore operations

 SYNOPSIS

#include <sys/sem.h>

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

 DESCRIPTION

The semop() function is used to perform atomically a user-defined array of semaphore operations on the set of semaphores associated with the semaphore identifier specified by the argument semid.

The argument sops is a pointer to a user-defined array of semaphore operation structures. The implementation will not modify elements of this array unless the application uses implementation-dependent extensions.

The argument nsops is the number of such structures in the array.

Each structure, sembuf, includes the following members:

Member Type	Member Name	Description
short	sem_num	semaphore number
short	sem_op	semaphore operation
short	sem_flg	operation flags

Each semaphore operation specified by sem_op is performed on the corresponding semaphore specified by semid and sem_num.

The variable sem_op specifies one of three semaphore operations:

1. If sem_op is a negative integer and the calling process has alter permission, one of the following will occur:

   • If semval, see <sys/sem.h>, is greater than or equal to the absolute value of sem_op, the absolute value of sem_op is subtracted from semval. Also, if (sem_flg&SEM_UNDO) is non-zero, the absolute value of sem_op is added to the calling process' semadj value for the specified semaphore.

   • If semval is less than the absolute value of sem_op and (sem_flg&IPC_NOWAIT) is non-zero, semop() will return immediately.
     

   • If semval is less than the absolute value of sem_op and (sem_flg&IPC_NOWAIT) is 0, semop() will increment the semncnt associated with the specified semaphore and suspend execution of the calling thread until one of the following conditions occurs:

     • The value of semval becomes greater than or equal to the absolute value of sem_op. When this occurs, the value of semncnt associated with the specified semaphore is decremented, the absolute value of sem_op is subtracted from semval and, if (sem_flg&SEM_UNDO) is non-zero, the absolute value of sem_op is added to the calling process' semadj value for the specified semaphore.
       

     • The semid for which the calling thread is awaiting action is removed from the system. When this occurs, errno is set equal to [EIDRM] and -1 is returned.
       

     • The calling thread receives a signal that is to be caught. When this occurs, the value of semncnt associated with the specified semaphore is decremented, and the calling thread resumes execution in the manner prescribed in sigaction().

2. If sem_op is a positive integer and the calling process has alter permission, the value of sem_op is added to semval and, if (sem_flg&SEM_UNDO) is non-zero, the value of sem_op is subtracted from the calling process' semadj value for the specified semaphore.

3. If sem_op is 0 and the calling process has read permission, one of the following will occur:

   • If semval is 0, semop() will return immediately.

   • If semval is non-zero and (sem_flg&IPC_NOWAIT) is non-zero, semop() will return immediately.

   • If semval is non-zero and (sem_flg&IPC_NOWAIT) is 0, semop() will increment the semzcnt associated with the specified semaphore and suspend execution of the calling thread until one of the following occurs:

     • The value of semval becomes 0, at which time the value of semzcnt associated with the specified semaphore is decremented.

     • The semid for which the calling thread is awaiting action is removed from the system. When this occurs, errno is set equal to [EIDRM] and -1 is returned.

     • The calling thread receives a signal that is to be caught. When this occurs, the value of semzcnt associated with the specified semaphore is decremented, and the calling thread resumes execution in the manner prescribed in sigaction().

Upon successful completion, the value of sempid for each semaphore specified in the array pointed to by sops is set equal to the process ID of the calling process.

 RETURN VALUE

Upon successful completion, semop() returns 0. Otherwise, it returns -1 and errno will be set to indicate the error.

 ERRORS

The semop() function will fail if:

[E2BIG]

The value of nsops is greater than the system-imposed maximum.

[EACCES]

Operation permission is denied to the calling process, see IPC.

[EAGAIN]

The operation would result in suspension of the calling process but (sem_flg&IPC_NOWAIT) is non-zero.

[EFBIG]

The value of sem_num is less than 0 or greater than or equal to the number of semaphores in the set associated with semid.

[EIDRM]

The semaphore identifier semid is removed from the system.

[EINTR]

The semop() function was interrupted by a signal.

[EINVAL]

The value of semid is not a valid semaphore identifier, or the number of individual semaphores for which the calling process requests a SEM_UNDO would exceed the system-imposed limit.

[ENOSPC]

The limit on the number of individual processes requesting a SEM_UNDO would be exceeded.

[ERANGE]

An operation would cause a semval to overflow the system-imposed limit, or an operation would cause a semadj value to overflow the system-imposed limit.

 EXAMPLES

None.

 APPLICATION USAGE

The POSIX Realtime Extension defines alternative interfaces for interprocess communication. Application developers who need to use IPC should design their applications so that modules using the IPC routines described in IPC can be easily modified to use the alternative interfaces.

 FUTURE DIRECTIONS

None.

 SEE ALSO

exec, exit(), fork(), semctl(), semget(), sem_close(), sem_destroy(), sem_getvalue(), sem_init(), sem_open(), sem_post(), sem_unlink(), sem_wait(), <sys/ipc.h>, <sys/sem.h>, <sys/types.h>, IPC.

DERIVATION

Derived from Issue 2 of the SVID.