semctl() - semaphore control operations
#include <sys/sem.h>
int semctl(int semid, int semnum, int cmd, ...)
The semctl(2) function provides control operations over semaphores in the semaphore set identified by semid. The control operation is defined by the cmd argument. (Values for cmd are defined in <sys/sem.h>.) Some control operations act on a single semaphore in the set, others act on the entire set identified by semid.
Semaphore identifiers are obtained with the semget(2) call; semaphore operations are performed with the semop(2) call.
The following values for cmd act on the semaphore identified by both semid and semnum.
| cmd | Command |
|---|---|
GETPID
|
Returns value of sempid. Requires read permission. |
| GETNCNT | Returns value of semncnt. Requires read permission. |
| GETZCNT | Returns value of semzcnt. Requires read permission. |
| GETVAL | Returns value of semval member. Requires read permission. |
| SETVAL | Sets value of semval member. Requires alter permission. |
| IPC_RMID | Removes semid from the system and destroy all associated structures and semaphores. Requires permission to be same as the value of sem_perm.cuid or sem_perm.uid in the semid_ds structure associated with semid. |
See the semget(2) reference page for a description of the structure members. The IPC_RMID macro is defined in <sys/ipc.h>, which is included by <sys/sem.h>.
These values of cmd operate on each semaphore in the set. They require a fourth argument to the semctl(2) function. The fourth argument contains an array which is used to hold values for the semaphores; it's described in more detail under The Fourth Argument.
| cmd | Command |
|---|---|
| GETALL | For each semaphore in the set, place the value of semval in the array pointed to by arg.array. Requires read permission. |
| SETALL | For each semaphore in the set, set the value of semval to the corresponding value in the array pointed to by arg.array. When successful, this operation clears the semadj values corresponding to each semaphore. Requires alter permission. |
The following values of cmd deal with stat setting, and removing semaphores:
| cmd | Command |
|---|---|
| IPC_STAT | Copy current value of each member in the data structure associated with semid into the data structure pointed at by arg.buf, where arg is the fourth argument to semctl(). Requires read permission. |
| IPC_SET | Set the value of UID, GID, and mode permission members in the semid_ds data structure associated with semid to the corresponding value in the data structure point at by arg.buf, where arg is the fourth argument to semctl(). The calling process needs an effective UID that matches the semaphore's sem_perm.cuid or sem_perm.uid values. |
| IPC_RMID | Remove the semaphore specified by semid from the system and destroy the set of semaphores and datastructure associated. The calling process needs an effective UID that matches the semaphore's sem_perm.cuid or sem_perm.uid values. |
For these values of cmd, a fourth argument is required:
SETVAL, GETALL, SETALL, IPC_STAT, IPC_SET, IPC_RMID
This argument is of type union semun and the application
program must explicitly declare it:
union semun {
|
||
int
|
val;
|
|
struct semid_ds *
|
buf;
|
|
unsigned short *
|
array;
|
|
};
|
||
The return value for a successful call to semctl(2) depends upon the cmd:
On failure, semctl(2) returns -1 and sets errno to indicate the error.
The semctl(2) function can fail for the following reasons:
semget(2)
semop(2)