semop and semtimedop Subroutines

Purpose

Performs semaphore operations.

Library

Standard C Library (libc.a)

Syntax

#include <sys/sem.h>

int semop (SemaphoreID, SemaphoreOperations, NumberOfSemaphoreOperations)
int  SemaphoreID;
struct sembuf * SemaphoreOperations;
size_t  NumberOfSemaphoreOperations;

#include <sys/sem.h>

int semtimedop (SemaphoreID, SemaphoreOperations,
NumberOfSemaphoreOperations, Timeout)
int  SemaphoreID;
struct sembuf * SemaphoreOperations;
size_t  NumberOfSemaphoreOperations;
struct timespec * timeout;

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:

Item Description
tv_sec Seconds on timer
tv_nsec Nanoseconds on timer

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.

Note: The semtimedop subroutine is available beginning with AIX® Version 6.1.

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:

Item Description
sem_num Semaphore number
sem_op Semaphore operation
sem_flg Operation flags

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 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.
Note: Calling the semtimedop subroutine with an invalid Timeout parameter will prevent the calling process from being suspended if necessary. If the Timeout parameter specified to the semtimedop subroutine is not valid and the calling process needs to be suspended, then the errno global variable will be set to indicate the error and a value of -1 will be returned.

The following limits apply to semaphores:

Parameters

Item Description
SemaphoreID Specifies the semaphore identifier.
NumberOfSemaphoreOperations Specifies the number of structures in the array.
SemaphoreOperations Points to an array of structures, each of which specifies a semaphore operation.
Timeout Points to a structure specifying an interval of time beyond which the operation should not sleep.

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.

Item Description
EINVAL The SemaphoreID parameter is not a valid semaphore identifier.
EINVAL The number of individual semaphores for which the calling process requests a SEM_UNDO flag would exceed the limit.
EINVAL The Timeout parameter specified a tv_sec or tv_nsec value less than 0, or a tv_nsec value greater than 1000 million.
EFBIG The sem_num value is less than 0 or it is greater than or equal to the number of semaphores in the set associated with the SemaphoreID parameter.
E2BIG The NumberOfSemaphoreOperations parameter is greater than the system-imposed maximum.
EACCES The calling process is denied permission for the specified operation.
EAGAIN The operation would result in suspension of the calling process, but the IPC_NOWAIT value is set in the sem_flg field.
ENOSPC The limit on the number of individual processes requesting a SEM_UNDO flag would be exceeded.
EINVAL The number of individual semaphores for which the calling process requests a SEM_UNDO flag would exceed the limit.
ERANGE An operation would cause a semval value to overflow the system-imposed limit.
ERANGE An operation would cause a semadj value to overflow the system-imposed limit.
EFAULT The SemaphoreOperations parameter points outside of the address space of the process.
EINTR A signal interrupted the semop subroutine.
EIDRM The semaphore identifier SemaphoreID parameter has been removed from the system.
EFAULT The Timeout parameter points to an invalid address.
ETIMEDOUT The time specified by the Timeout parameter expired before the requested operations could be completed.