semop Subroutine

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;

Description

The semop subroutine performs operations on the set of semaphores associated with the semaphore identifier specified by the SemaphoreID parameter. 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. 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 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 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 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 subroutine.

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 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 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 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 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 following limits apply to semaphores:

• Maximum number of semaphore IDs is 4096 for AIX releases before 4.3.2 and 131072 for AIX 4.3.2 and following.

• 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 subroutine returns 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 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 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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The exec subroutine, exit subroutine, fork subroutine, semctl subroutine, semget subroutine, sigaction subroutine.