semop (BPX1SOP, BPX4SOP) — Perform semaphore serialization operations

Function

The semop service performs a group of semaphore operations atomically.

Requirements

Parameters

Semaphore_ID

Supplied parameter

Type:

Integer

Length:

Halfword

Specifies the semaphore identifier.

Semaphore_Operations

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

A fullword (doubleword) that points to an array of data structures mapped by SEM_BUF_ELE in BPXYSEM — Map interprocess communication semaphores. The SEM_OP operations modify the semval for a specific semaphore in the semaphore set specified by SEM_NUM. All updates to the semaphores' semval are made atomically when this callable service returns successfully. Partial updates to semval are not performed. Each SEM_BUF_ELE element contains the following:

• SEM_NUM is a halfword semaphore number in the Semaphore_ID set. References to semval, sempid, semncnt, semzcnt are to this element in the semaphore set. SEM_NUM ranges from 0 to Number_of_Semaphore_Operations - 1.
• SEM_OP is a signed halfword with three different operations, described as follows:
  • SEM_OP < 0, evaluate semval + SEM_OP (remember that SEM_OP is negative). If the operation yields a negative number, the operation either returns to the caller (EAGAIN) or suspends execution of the calling thread until the operation yields a non-negative number. Semncnt is incremented for each thread that is waiting, and decremented when waiting is complete. When waiting is complete, semval = semval + SEM_OP.
  • SEM_OP > 0, set semval = semval + SEM_OP.
  • SEM_OP = 0, test semval. If not zero, the operation either returns to the caller (EAGAIN) or suspends execution of the calling thread until semval=0. Semzcnt is incremented for each thread that is waiting, and decremented when waiting is complete.
• SEM_FLGS – contains the Ipc_NOWAIT and Sem_UNDO bits. Ipc_NOWAIT causes SEM_OP=0 and SEM_OP<0 to return immediately with a return code of EAGAIN if the condition cannot be met. Otherwise, processing is suspended. Sem_UNDO instructs the process to maintain an adjustment value for SEM_OP ^= 0. For the data structure, see BPXYSEM — Map interprocess communication semaphores.

Number_of_Semaphore_Operations

Supplied parameter

Type:

Integer

Length:

Fullword

Contains the number of operations in Semaphore_Operations. A value of zero up to the maximum allowed by the system may be specified.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the semop service returns 0 (all SEM_OP operations were performed) or -1 (none of the SEM_OP operations were performed).

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the semop service stores the return code. The semop service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The semop service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	Permission is denied. The following reason code can accompany the return code: JRIpcDenied.
EAGAIN	The operation would result in suspension of the calling process, but NOWAIT (see SEM_FLGS) was specified. The following reason code can accompany the return code: JRIpcRetry.
EDEADLK	The combination of operations can never be satisfied. This condition is detected by analysis of the operations that were requested and the system maximums, and does not include interactions with other threads. For example, an operation could add 1 to a semaphore, and a later operation in the same SEM_BUF could test it for zero. The following reason code can accompany the return code: JRDeadlock.
EFAULT	The Semaphore_Operations parameter specified an address that caused the service to program check. The following reason code can accompany the return code: JRBadAddress.
EFBIG	SEM_NUM is less than zero or is greater than or equal to the number of semaphores in the set specified by the Number_of_Semaphores parameter of the semget() call. The following reason code can accompany the return code: JRSema4BadSemN.
EIDRM	Semaphore_ID was removed from the system while the caller was waiting. The following reason code can accompany the return code: JRIpcRemoved.
EINTR	semop() was interrupted by a signal. The following reason code can accompany the return code: JRIpcSignaled.
EINVAL	The Semaphore_ID does not represent a semaphore set. The following reason code can accompany the return code: JRIpcBadID.
ENOSPC	The space that is allotted for all semaphore data would be exceeded by the addition of the UNDO structure for this request. The following reason code can accompany the return code: JRSemStorageLimit.
ERANGE	An operation would cause sem_val or sem_adj to overflow the system-imposed limit. These system limits are defined in BPXYSEM fields SEM#MAX_VAL and SEM#MAX_ADJ. The following reason codes can accompany the return code: JRSema4BadValue and JRSema4BadAdj.
E2BIG	Number_of_Semaphore_Operations exceeds the maximum allowed by the system. This system limit is set with the IPCSEMNOPS parameter in a BPXPRMxx parmlib member. You can use the ipcs -x shell command to view this value. The following reason code can accompany the return code: JRSema4BadNOps.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the semop service stores the reason code. The semop service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

1. Each semaphore in the semaphore set is represented by an anonymous data structure, which is defined as follows:

   semval

   Unsigned halfword semaphore value

   sempid

   Process ID of last operation

   semncnt

   Unsigned halfword number of processes waiting for semval to become greater than current value

   semzcnt

   Unsigned halfword number of processes waiting for semval to become zero

2. A nonzero SEM_OP value requires write permission (else EACCES).
3. A zero SEM_OP value requires read permission (else EACCES).
4. Upon successful completion, sempid equals the process ID of the calling process.
5. Wait queue service is unpredictable.
6. Waiting is done on a thread basis. Multiple threads (even within a single process) could be waiting on the same semaphore.
7. Adjustments are maintained on a process basis, and can be changed by threads outside or within the process.
8. Within an array of semaphore operations, either all operations or none of the operations are performed.
9. Incorrect usage of semaphores may cause the application to become deadlocked and wait forever. Designing the semaphore hierarchy so that the semaphores are obtained in a specific order will avoid deadlocks.
10. If the Number_of_Semaphore_Operations is zero, the callable service returns successfully with no semaphore operation being performed.

Related services

• mvsprocclp (BPX1MPC, BPX4MPC) — Clean up kernel resources
• semctl (BPX1SCT, BPX4SCT) — Perform semaphore control operations
• semget (BPX1SGT, BPX4SGT) — Create or find a set of semaphores

Characteristics and restrictions

The invoker is restricted by ownership, read, and read-write permissions that are defined by semget and semctl Ipc_SET.