NAME
semctl —
control operations on a semaphore
set
LIBRARY
library “libc”
SYNOPSIS
#include
<sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int
semctl(int
semid, int semnum,
int cmd,
...);
DESCRIPTION
Semctl()
performs the operation indicated by cmd on the semaphore
set indicated by semid. A fourth argument, a
union semun arg, is required for certain values of
cmd. For the commands that use the
arg parameter, union semun is
defined as follows:
union semun {
int val; /* value for SETVAL */
struct semid_ds *buf; /* buffer for IPC_STAT & IPC_SET */
u_short *array; /* array for GETALL & SETALL */
};
Commands are performed as follows:
IPC_STAT- Fetch the semaphore set's struct semid_ds, storing it in the memory pointed to by arg.buf.
IPC_SET- Changes the sem_perm.uid, sem_perm.gid, and sem_perm.mode members of the semaphore set's struct semid_ds to match those of the struct pointed to by arg.buf. The calling process's effective uid must match either sem_perm.uid or sem_perm.cuid, or it must have superuser privileges.
IPC_RMID- Immediately removes the semaphore set from the system. The calling process's effective uid must equal the semaphore set's sem_perm.uid or sem_perm.cuid, or the process must have superuser privileges.
GETVAL- Return the value of semaphore number semnum.
SETVAL- Set the value of semaphore number semnum to arg.val.
GETPID- Return the pid of the last process to perform an operation on semaphore number semnum.
GETNCNT- Return the number of processes waiting for semaphore number semnum's value to become greater than its current value.
GETZCNT- Return the number of processes waiting for semaphore number semnum's value to become 0.
GETALL- Fetch the value of all of the semaphores in the set into the array pointed to by arg.array.
SETALL- Set the values of all of the semaphores in the set to the values in the array pointed to by arg.array.
The struct semid_ds is defined as follows:
struct semid_ds {
struct ipc_perm sem_perm; /* operation permission struct */
struct sem *sem_base; /* pointer to first semaphore in set */
u_short sem_nsems; /* number of sems in set */
time_t sem_otime; /* last operation time */
long sem_pad1; /* SVABI/386 says I need this here */
time_t sem_ctime; /* last change time */
/* Times measured in secs since */
/* 00:00:00 GMT, Jan. 1, 1970 */
long sem_pad2; /* SVABI/386 says I need this here */
long sem_pad3[4]; /* SVABI/386 says I need this here */
};
RETURN VALUES
On success, when cmd is one of
GETVAL, GETPID,
GETNCNT or GETZCNT,
semctl() returns the corresponding value; otherwise,
0 is returned. On failure, -1 is returned, and errno
is set to indicate the error.
ENVIRONMENT
The XSI Interprocess Communication family of functions is also available as an implementation in userspace. To use it, the sysvipcd(8) daemon has to be running.
If the USR_SYSVIPC variable is set in a
process' environment, the process and its children will use the userspace
implementation.
ERRORS
Semctl() will fail if:
- [
EINVAL] - No semaphore set corresponds to semid.
- [
EINVAL] - semnum is not in the range of valid semaphores for given semaphore set.
- [
EPERM] - The calling process's effective uid does not match the uid of the semaphore set's owner or creator.
- [
EACCES] - Permission denied due to mismatch between operation and mode of semaphore set.
SEE ALSO
AUTHORS
The DragonFly specific userspace implementation (see ENVIRONMENT) was written by Larisa Grigore.