semop - semaphore operations

Syntax

#include <sys/sem.h>

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

Description

semop() permits the automatic execution of a user-defined list of semaphore operations on the semaphore set with the semaphore ID specified in the argument semid.

sops points to a user-defined array of semaphore operation structures.

nsops specifies the number of structures in the array.

Each sembuf structure contains the following members:

Data type	Member name	Description
short	sem_num	Semaphore number
short	sem_op	Semaphore operation
short	sem_flg	Operation flags

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

sem_op defines one of the following three semaphore operations:

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

   • If semval is greater than or equal to the absolute value of sem_op, the absolute value of sem_op is subtracted from semval.

   • 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 (see exit()).

   • 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() increments the semncnt value of the specified semaphore and suspends execution of the calling process 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 semncnt value of the specified semaphore is decremented by 1, 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 process is awaiting action is removed from the system. In this case, errno is set equal to EIDRM and the value -1 is returned.

     • The calling process receives a signal that is to be caught. When this occurs, the semncnt value of the specified semaphore is decremented by 1, and the calling process resumes execution as described under the sigaction() function.

2. If sem_op is a positive integer and the calling process has write 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 semadj value of the calling process 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 and (sem_flg & IPC_NOWAIT) are both non-zero, semop() will return immediately.

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

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

     • The identifier semid of the semaphore for which the calling process is awaiting action is removed from the system. When this occurs, errno is set to EIDRM and the value -1 is returned.

     • The calling process receives a signal that is to be caught. When this occurs, the semzcnt value of the specified semaphore is decremented by 1, and the calling process resumes execution as described under 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.

When threads are used, the functionality of semop changes in the following aspects:

Execution of semaphore operations:

Regarding 1. If semval is smaller than the absolute value of sem_op and ( sem_flg & IPC_NOWAIT) is equal to 0, semop() increments the value of semncnt of the specified semaphore by 1 and the calling thread is stopped until one of the following conditions is met:

• The value of semval is greater than or equal to the absolute value of sem_op. When this occurs, the value of semncnt of the specified semaphore is decremented by 1, the absolute value of sem_op is subtracted from semval and if (sem_flg & SEM_UNDO) is not equal to 0, the absolute value of sem_op is added to the semadj value of the calling process for the specified semaphore.

• The semid identifier for which the calling thread is waiting for an operation is deleted from the system. In this case errno is set to EIDRM and -1 is returned.

• The calling thread receives a signal that must be trapped. In this case the value of semncnt of the specified semaphore is decremented by 1 and the calling thread continues execution in the manner described for the sigaction() function.

Regarding 3. If semval is not equal to 0 and (sem_flg & IPC_NOWAIT) is equal to 0, semop() increments the value of semzcnt of the specified semaphore by 1 and the calling thread is stopped until one of the following events occur:

• semval assumes the value 0. After that the value of semzcnt of the specified semaphore is decremented by 1.

• The semid identifier for which the calling thread is waiting for an operation is deleted from the system. In this case errno is set to EIDRM and -1 is returned.

The calling thread receives a signal that must be trapped. In this case the value of semzcnt of the specified semaphore is decremented by 1 and the calling thread continues execution in the manner described for the sigaction() function.

Return val.

0

-1

if successful.

if unsuccessful. errno is set to indicate the error.

Errors

semop() will fail if:

 

 

E2BIG

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

 

EACCES

The process does not have the required access permission for the command to be executed (see section “Error handling” ).

 

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 was removed from the system.

EINTR

semop() 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 system-specific limit on the maximum number of individual processes requesting a SEM_UNDO would be exceeded.

ERANGE

An operation would cause a semval or a semadj to exceed the maximum value for the system.

See also

exec, exit(), fork(), semctl(), semget(), sys/sem.h, section “Interprocesscommunication” .