semop()-Perform Semaphore Operations on Semaphore Set

#include <sys/sem.h>

int semop(int semid, struct sembuf *sops,
          size_t nsops);

The semop() function performs operations on semaphores in a semaphore set. These operations are supplied in a user-defined array of operations.

Parameters

semid

(Input) Semaphore set identifier.

sops

(Input) Pointer to array of semaphore operation (sembuf) structures.

nsops

(Input) Number of sembuf structures in sops array.

Following is an example of what one of the sembuf structures should look like:

struct sembuf {            /* semaphore operation structure */
  unsigned short sem_num;  /* semaphore number */
           short sem_op;   /* semaphore operation */
           short sem_flg;  /* operation flags SEM_UNDO and IPC_NOWAIT */
}

Authorities

Figure 1-13. Authorization Required for semop()

Object Referred to	Authority Required	errno
Semaphore, sem_op is negative	Write	EACCES
Semaphore, sem_op is positive	Write	EACCES
Semaphore, sem_op is zero	Read	EACCES

Return Value

0

semop() was successful.

-1

semop() was not successful. The errno variable is set to indicate the error.

Error Conditions

If semop() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems.

Operation permission is denied to the calling thread.

[EAGAIN]

Operation would have caused the process to be suspended.

The operation would result in suspension of the calling thread but (sem_flg & IPC_NOWAIT) is not zero. (& is a bitwise AND.)

[EDAMAGE]

A damaged object was encountered.

A referenced object is damaged. The object cannot be used.

The value of semid corresponds to a semaphore set that has been marked as damaged by a previous semaphore operation.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EFBIG]

Object is too large.

The size of the object would exceed the system allowed maximum size.

The value of sem_num is less than 0 or greater than or equal to the number of semaphores in the set associated with semid.

[EIDRM]

ID has been removed.

The semaphore identifier semid has been removed from the system.

[EINTR]

Interrupted function call.

The semop() function was interrupted by a signal while the thread was in a wait state.

[ERROR_INVALID_PARAMETER]

An invalid parameter was found.

A parameter passed to this function is not valid.

The value of semid is not a valid semaphore identifier.

[ENOSPC]

No space available.

The requested operations required additional space on the device and there is no space left. This could also be caused by exceeding the user profile storage limit when creating or transferring ownership of an object.

Insufficient space remains to hold the intended file, directory, or link.

The limit on the number of individual threads requesting a SEM_UNDO would be exceeded.

[ERANGE]

A range error occurred.

The value of an argument is too small, or a result too large.

An operation would cause a semval to overflow the system-imposed limit, or an operation would cause a semaphore adjustment value to overflow the system-imposed limit.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Error Messages

None.

Usage Notes

1. Each semaphore operation specified by the sops array is performed on the semaphore set specified by semid. The entire array of operations is performed atomically; no other thread will operate on the semaphore set until all of the operations are done or it is determined that they cannot be done. If the entire set of operations cannot be performed, none of the operations are done, and the thread waits until all of the operations can be done.

2. semop() changes each semaphore specified by sem_num according to the value of sem_op:

   • If sem_op is positive, semop() increments the value of the semaphore and awakens any threads waiting for the semaphore to increase. This corresponds to releasing resources controlled by the semaphore.

   • If sem_op is negative, semop() attempts to decrement the value of the semaphore. If the result would be negative, it waits for the semaphore value to increase. If the result would be positive, it decrements the semaphore. If the result would be zero, it decrements the semaphore and awakens any threads waiting for the semaphore to be zero. This corresponds to the allocation of resources.

   • If sem_op is zero, the thread waits for the semaphore's value to be zero.

3. If IPC_NOWAIT is set and the operation cannot be completed, semop() returns an [EAGAIN] error instead of causing the thread to wait.

4. If SEM_UNDO is set, semop() causes IPC to reverse the effect of this semaphore operation when the thread ends, effectively releasing the resources or request for resources controlled by the semaphore. This value is known as the semaphore adjustment value.

5. A semop() is interruptible by an asynchronous signal when the thread is waiting for a semaphore to reach a value.

Related Information

• The <sys/sem.h> file (see Header Files for UNIX-Type Functions)

• semget()-Get Semaphore Set with Key

• semctl()-Perform Semaphore Control Operations

Example

For an example of using this function, see Using Semaphores and Shared Memory in Appendix A, Examples.