semctl() — Semaphore control operations
Standards
| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
XPG4 |
both |
Format
#define _XOPEN_SOURCE
#include <sys/sem.h>
int semctl(int semid, int semnum, int cmd, ...);General description
The semctl() function performs control operations in semaphore set semid as specified by the argument cmd.
Depending on the value of argument cmd, argument semnum may be ignored or identify one specific semaphore number.
The fourth
argument is optional and depends upon the operation requested. If
required, it is of type union semun, which
the application program must explicitly declare:
union semun {
int val;
struct semid_ds *buf;
unsigned short *array;
} arg;Each semaphore in the semaphore set is represented by the following anonymous data structure:
| unsigned short int | semval | Semaphore value |
| pid_t | sempid | Process ID of last operation |
| unsigned sort int | semcnt | Number of processes waiting for semval to become greater than current value |
| unsigned short int | semzcnt | Number of processes waiting for semval to become zero |
When semctl() is used to identify one specific semaphore number for commands GETVAL, SETVAL, GETPID, GETNCNT, and GETZCNT, then references are made to this anonymous data structure for the semaphore semnum.
The following semaphore
control operations as specified by argument cmd may
be specified. The level of permission required for each operation
is shown with each command. These symbolic constants are defined
by the <sys/sem.h> header:
- GETVAL
- Returns the value of semval, if the current process has read permission.
- SETVAL
- Sets the value of semval to arg.val, where arg is the value of the fourth argument to semctl(). When this command is successfully executed, the semadj value corresponding to the specified semaphore in all processes is cleared. This command requires alter permission. For an __IPC_BINSEM semaphore set the only values that may be set are zero and one.
- GETPID
- Returns the most recent process to update the semaphore (sempid), if the current process has read permission.
- GETNCNT
- Returns the number of threads waiting on the semaphore to become greater than the current value, if the current process has read permission.
- GETZCNT
- Returns the number of threads waiting on the semaphore to become zero, if the current process has read permission. For an __IPC_BINSEM semaphore set this operation will always return a zero; threads are not allowed to wait for the semaphore to become zero in this type of semaphore set.
- GETALL
- Stores semvals for each semaphore in the semaphore set and place into the array pointed to by arg.array, where arg. is the fourth argument to semctl(). GETALL requires read permission. It is the caller's responsibility to ensure that the storage allocated is large enough to hold the number of semaphore elements. The number of semaphore values stored is sem_nsems, which may be obtained using the IPC_STAT command.
- SETALL
- Sets semval values for each semaphore in the semaphore set according to the array pointed to by arg.array, where arg is the fourth argument to semctl(). SETALL requires alter permission. Each semval value must be zero or positive. When this command is successfully executed, the semadj values corresponding to each specified semaphore in all processes are cleared. It is the caller's responsibility to ensure that the storage allocated is large enough to hold the number of semaphore elements. The number of semaphore values set is sem_nsems, which may be obtained using the IPC_STAT command. If __IPC_BINSEM was specified on the semget, this option should not be used while there is the possibility of other threads performing semaphore operations on this semaphore, as there may be no serialization while updating the semaphore values; therefore a SETALL will not be allowed after a semop has been done to the __IPC_BINSEM semaphore set. Also, for the __IPC_BINSEM semaphore set, the only values that may be set are zero and one.
- IPC_STAT
- This command obtains status information for the semaphore identifier specified by semid. This requires read permission. This information is stored in the address specified by the fourth argument defined by data structure semid_ds.
- IPC_SET
- Set the value
of the sem_perm.uid, sem_perm.gid,
and sem_perm.mode in semid_ds data
structure for the semaphore identifier specified by semid.
These values are set to the values found in semid_ds structure
pointed to by the fourth argument.
Any value for sem_perm.uid and semperm.gid may be set.
Only mode bits defined under semget() function argument semflg may be set in sem_perm.mode.
This command can only be executed by a process that has an effective user ID equal to either that of a process with appropriate privileges or to the value of sem_perm.cuid or sem_perm.uid in the semid_ds structure associated with semid.
- IPC_RMID
- Remove the semaphore
identifier specified by argument semid from
the system and free the storage for the set of semaphores in the semid_ds structure.
This command can only be executed by a process that has an effective user ID equal to either that of a process with appropriate privileges or to the value of sem_perm.cuid or sem_perm.uid in the semid_ds structure associated with semid. For an __IPC_BINSEM semaphore set, it is recommended that all use of semop should be completed before removing the semaphore ID.
Returned value
If successful, the value
returned by semctl() depends on the value of the argument cmd as
follows:
- GETVAL
- value of semval is returned
- GETPID
- value of sempid is returned
- GETNCNT
- value of semncnt is returned
- GETZCNT
- value of semzcnt is returned
- All others
- value of zero is returned
If unsuccessful, semctl() returns -1 and sets
errno to one of the following values:
- Error Code
- Description
- EACCES
- Operation permission (read or write) is denied to the calling process.
- EINVAL
- The value of argument semid is not a valid semaphore identifier, or the value of semnum is less than zero or greater than or equal to the number of semaphores in the set, or the argument cmd is not a valid command, or the bits specified for sem_perm.mode are undefined. Note that the valid range of semnum is 0 to (number of semaphores in the set minus 1).
- EPERM
- The argument cmd has a value of IPC_RMID or IPC_SET and the effective user ID of the caller is not that of a process with appropriate privileges and is not the value of sem_perm.cuid or sem_perm.uid in the semid_ds data structure associated with semid.
- ERANGE
- The argument cmd has a value of SETVAL or SETALL and the semval value to be set exceeds the system limit as defined in <sys/sem.h>.