sem.h File

Purpose

Describes the structures that are used by subroutines that perform semaphore operations.

Description

The /usr/include/sys/sem.h file defines the structures that are used by the semop subroutine and the semctl subroutine to perform various semaphore operations.

The sem structure stores the values that the Commands parameter of the semctl subroutine gets and sets. This structure contains the following fields:

The sembuf structure stores semaphore information used by the semop subroutine. This structure contains the following fields:

sem_num

Specifies a semaphore on which to perform some semaphore operation. The data type of this field is unsigned short.

sem_op

Specifies a semaphore operation to be performed on the semaphore specified by the sem_num field and the SemaphoreID parameter of the semop subroutine. This value can be a positive integer, a negative integer, or 0:

i

If the current process has write permission, the positive integer value of this field is added to the value of the semval field of the semaphore.

- i

If the current process has write permission, a negative integer value in this field causes one of the following actions:

If the semval field 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 value of the semval field.

If the semval field is less than the absolute value of the sem_op field and the IPC_NOWAIT flag is set, the semop subroutine returns a value of -1 and sets the errno global variable to EAGAIN.

If the value of the semval field is less than the absolute value of the sem_op field and the IPC_NOWAIT flag is not set, the semop subroutine increments the semncnt field associated with the specified semaphore and suspends execution of the calling process until one of the following conditions is met:

• The value of the semval field becomes greater than or equal to the absolute value of the sem_op field. When this occurs, the value of the semncnt vield associated with the specified semaphore is decremented, the absolute value of the sem_op field is subtracted from semval value and, 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 semaphore specified by the SemaphoreID parameter for which the calling process is awaiting action is removed from the system (see the semctl subroutine). When this occurs, the errno global variable is set equal to EIDRM, and a value of -1 is returned.
• The calling process receives a signal that is to be caught. When this occurs, the value of the semncnt field associated with the specified semaphore is decremented, and the calling process resumes execution in the manner prescribed in the sigaction subroutine.

0

If the current process has read permission, a value of 0 in this field causes one of the following actions:

• If the semval field is 0, the semop subroutine returns a value of 0.
• If the semval field is not equal to 0 and the IPC_NOWAIT flag is set, the semop subroutine returns a value of -1 and sets the errno global variable to EAGAIN.
• If semval is not equal to 0 and the IPC_NOWAIT flag is not set, the semop subroutine increments the semzcnt field associated with the specified semaphore and suspends execution of the calling process until one of the following conditions is met:
  • The value of the semval field becomes 0, at which time the value of the semzcnt field associated with the specified semaphore is decremented.
  • The semaphore specified by 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 equal to EIDRM, and a value of -1 is returned.
  • The calling process receives a signal that is to be caught. When this occurs, the value of the semzcnt field associated with the specified semaphore is decremented, and the calling process resumes execution in the manner prescribed in the sigaction subroutine.

The data type of the sem_op field is short.

sem_flg

If the value of this field is not 0 for an operation, the value is constructed by logically ORing one or more of the following values:

SEM_UNDO

Specifies whether to modify the Semadj values of the calling process.

If this value is set for an operation and the value of the sem_op field is a positive integer, the value of the sem_op field is subtracted from the Semadj value of the calling process.

If this value is set for an operation and the value of the sem_op field is a negative integer, the absolute value of the sem_op field is added to the Semadj value of the calling process. The exit subroutine adds the Semadj value to the value of the semval field of the semaphore when the process terminates.

SEM_ORDER

Specifies whether to perform atomically or individually the operations specified by the SemaphoreOperations array of the semop subroutine. (This flag is valid only when included in the SemaphoreOperations[0].sem_flg parameter, the first operation in the SemaphoreOperations array.)

If the SEM_ORDER flag is not set (the default), the specified operations are performed atomically. That is, none of the semval values in the array are modified until all of the semaphore operations are completed. If the calling process must wait until some semval requirement is met, the semop subroutine does so before performing any of the operations. If any semaphore operation would cause an error to occur, none of the operations are performed.

If the SEM_ORDER flag is set, the operations are performed individually in the order that they appear in the array, regardless of whether any of the operations require the process to wait. If an operation encounters an error condition, the semop subroutine sets the SEM_ERR flag in the sem_flg field of the failing operation; neither the failing operation nor the following operations in the array are performed.

IPC_NOWAIT

Specifies whether to wait or to return immediately when the semval of a semaphore is not a certain value.

The data type of the sem_flg field is short.

The semid_ds structure stores semaphore status information used by the semctl subroutine and pointed to by the Buffer parameter. This structure contains the following fields: