semop and semtimedop Subroutines

Purpose

Performs semaphore operations.

Library

Standard C Library (libc.a)

Syntax

#include <sys/sem.h>

#include <sys/sem.h>

Description

The semop and semtimedop subroutines perform operations on the set of semaphores associated with the semaphore identifier specified by the SemaphoreID parameter.

The semtimedop subroutine limits the time the caller will sleep while waiting for the semaphore operation(s) to complete. The timespec structure is defined in the /usr/include/sys/time.h file and includes the following fields:

If the caller sleeps for the time allotted by the timespec structure before the operation(s) can be completed, the current operation is aborted and the semtimedop subroutine will return an error.

The sembuf structure is defined in the usr/include/sys/sem.h file. Each sembuf structure specified by the SemaphoreOperations parameter includes the following fields:

Each semaphore operation specified by the sem_op field is performed on the semaphore specified by the SemaphoreID parameter and the sem_num field. Semaphore operations are performed in the order they are received in the sembuf array. The sem_op field specifies one of three semaphore operations.

1. If the sem_op field is a negative integer and the calling process has permission to alter, one of the following conditions occurs:
   • If the semval variable (see the /usr/include/sys/sem.h file) is greater than or equal to the absolute value of the sem_op field, the absolute value of the sem_op field is subtracted from the semval variable. In addition, if the SEM_UNDO flag is set in the sem_flg field, the absolute value of the sem_op field is added to the semadj value of the calling process for the specified semaphore.
   • If the semval variable is less than the absolute value of the sem_op field and the IPC_NOWAIT value is set in the sem_flg field, the semop or semtimedop subroutine returns immediately.
   • If the semval variable is less than the absolute value of the sem_op field and the IPC_NOWAIT value is not set in the sem_flg field, the semop and semtimedop subroutine increments the semncnt field associated with the specified semaphore and suspends the calling process until one of the following conditions occurs:
     • The value of the semval variable becomes greater than or equal to the absolute value of the sem_op field. The value of the semncnt field associated with the specified semaphore is then decremented, and the absolute value of the sem_op field is subtracted from the semval variable. In addition, if the SEM_UNDO flag is set in the sem_flg field, the absolute value of the sem_op field is added to the semadj value of the calling process for the specified semaphore.
     • The SemaphoreID parameter for which the calling process is awaiting action is removed from the system. When this occurs, the errno global variable is set to the EIDRM flag and a value of -1 is returned.
     • The calling process received a signal that is to be caught. When this occurs, the semop and semtimedop subroutine decrements the value of the semncnt field associated with the specified semaphore. When the semzcnt field is decremented, the calling process resumes as prescribed by the sigaction (sigaction, sigvec, or signal Subroutine) subroutine.
     • The calling process sleeps for the time allotted by the timespec structure. When this occurs, the errno global variable is set to the ETIMEDOUT flag and a value of -1 is returned.
2. If the sem_op field is a positive integer and the calling process has alter permission, the value of the sem_op field is added to the semval variable. In addition, if the SEM_UNDO flag is set in the sem_flg field, the value of the sem_op field is subtracted from the calling process's semadj value for the specified semaphore.
3. If the value of the sem_op field is 0 and the calling process has read permission, one of the following occurs:
   • If the semval variable is 0, the semop or semtimedop subroutine returns immediately.
   • If the semval variable is not equal to 0 and IPC_NOWAIT value is set in the sem_flg field, the semop or semtimedop subroutine returns immediately.
   • If the semval variable is not equal to 0 and the IPC_NOWAIT value is not set in the sem_flg field, the semop or semtimedop subroutine increments the semzcnt field associated with the specified semaphore and suspends execution of the calling process until one of the following occurs:
     • The value of the semval variable becomes 0. When this occurs, the value of the semzcnt field associated with the specified semaphore is decremented.
     • The SemaphoreID parameter for which the calling process is awaiting action is removed from the system. If this occurs, the errno global variable is set to the EIDRM error code and a value of -1 is returned.
     • The calling process received a signal that is to be caught. When this occurs, the semop or semtimedop subroutine decrements the value of the semzcnt field associated with the specified semaphore. When the semzcnt field is decremented, the calling process resumes execution as prescribed by the sigaction subroutine.
     • The calling process sleeps for the time allotted by the timespec structure. When this occurs, the errno global variable is set to the ETIMEDOUT flag and a value of -1 is returned.

The following limits apply to semaphores:

• Maximum number of semaphore IDs is 131072.
• Maximum number of semaphores per ID is 65,535.
• Maximum number of operations per call by the semop subroutine is 1024.
• Maximum number of undo entries per procedure is 1024.
• Maximum capacity of a semaphore value is 32,767 bytes.
• Maximum adjust-on-exit value is 16,384 bytes.

Parameters

Return Values

Upon successful completion, the semop and semtimedop subroutines return a value of 0. Also, the SemaphoreID parameter value for each semaphore that is operated upon is set to the process ID of the calling process.

If the semop or semtimedop subroutine is unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the error. If the SEM_ORDER flag was set in the sem_flg field for the first semaphore operation in the SemaphoreOperations array, the SEM_ERR value is set in the sem_flg field for the unsuccessful operation.

If the SemaphoreID parameter for which the calling process is awaiting action is removed from the system, the errno global variable is set to the EIDRM error code and a value of -1 is returned.

Error Codes

The semop or semtimedop subroutine is unsuccessful if one or more of the following are true for any of the semaphore operations specified by the SemaphoreOperations parameter. If the operations were performed individually, the discussion of the SEM_ORDER flag provides more information about error situations.