semctl (2)
NAME
semctl - semaphore control operations
SYNOPSIS
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int semctl(int semid, int semnum, int cmd, ...);
DESCRIPTION
The function semctl performs the control operation specified by cmd on
the semaphore set identified by semid, or on the semnum-th semaphore of
that set. (Semaphores are numbered starting at 0.)
This function has three or four arguments. When there are four, the
call is semctl(semid,semnum,cmd,arg); where the fourth argument arg has
a type union semun defined as follows:
#if defined(__GNU_LIBRARY__) && !defined(_SEM_SEMUN_UNDEFINED)
/* union semun is defined by including <sys/sem.h> */
#else
/* according to X/OPEN we have to define it ourselves */
union semun {
int val; /* value for SETVAL */
struct semid_ds *buf; /* buffer for IPC_STAT, IPC_SET */
unsigned short *array; /* array for GETALL, SETALL */
/* Linux specific part: */
struct seminfo *__buf; /* buffer for IPC_INFO */
};
#endif
Legal values for cmd are:
IPC_STAT Copy info from the semaphore set data structure into the
structure pointed to by arg.buf. The argument semnum is
ignored. The calling process must have read access privi-
leges on the semaphore set.
IPC_SET Write the values of some members of the semid_ds structure
pointed to by arg.buf to the semaphore set data structure,
updating also its sem_ctime member. Considered members
from the user supplied struct semid_ds pointed to by
arg.buf are
sem_perm.uid
sem_perm.gid
sem_perm.mode /* only lowest 9-bits */
The effective user-ID of the calling process must be that
of the super-user, or match the creator or owner of the
semaphore set. The argument semnum is ignored.
IPC_RMID Immediately remove the semaphore set and its data struc-
tures awakening all waiting processes (with an error return
GETNCNT The system call returns the value of semncnt for the sem-
num-th semaphore of the set (i.e. the number of processes
waiting for an increase of semval for the semnum-th
semaphore of the set). The calling process must have read
access privileges on the semaphore set.
GETPID The system call returns the value of sempid for the sem-
num-th semaphore of the set (i.e. the pid of the process
that executed the last semop call for the semnum-th
semaphore of the set). The calling process must have read
access privileges on the semaphore set.
GETVAL The system call returns the value of semval for the sem-
num-th semaphore of the set. The calling process must have
read access privileges on the semaphore set.
GETZCNT The system call returns the value of semzcnt for the sem-
num-th semaphore of the set (i.e. the number of processes
waiting for semval of the semnum-th semaphore of the set to
become 0). The calling process must have read access priv-
ileges on the semaphore set.
SETALL Set semval for all semaphores of the set using arg.array,
updating also the sem_ctime member of the semid_ds struc-
ture associated to the set. Undo entries are cleared for
altered semaphores in all processes. Processes sleeping on
the wait queue are awakened if some semval becomes 0 or
increases. The argument semnum is ignored. The calling
process must have alter access privileges on the semaphore
set.
SETVAL Set the value of semval to arg.val for the semnum-th
semaphore of the set, updating also the sem_ctime member of
the semid_ds structure associated to the set. Undo entries
are cleared for altered semaphores in all processes. Pro-
cesses sleeping on the wait queue are awakened if semval
becomes 0 or increases. The calling process must have
alter access privileges on the semaphore set.
RETURN VALUE
On failure semctl returns -1 with errno indicating the error. Other-
wise the system call returns a nonnegative value depending on cmd as
follows:
GETNCNT the value of semncnt.
GETPID the value of sempid.
GETVAL the value of semval.
GETZCNT the value of semzcnt.
All other cmd values return 0 on success.
ERRORS
On failure, errno will be set to one of the following:
EPERM The argument cmd has value IPC_SET or IPC_RMID but the call-
ing process has insufficient privileges to execute the com-
mand.
ERANGE The argument cmd has value SETALL or SETVAL and the value to
which semval has to be set (for some semaphore of the set)
is less than 0 or greater than the implementation value
SEMVMX.
NOTES
The IPC_INFO, SEM_STAT and SEM_INFO control calls are used by the
ipcs(8) program to provide information on allocated resources. In the
future these can be modified as needed or moved to a proc file system
interface.
Various fields in a struct semid_ds were shorts under Linux 2.2 and
have become longs under Linux 2.4. To take advantage of this, a recom-
pilation under glibc-2.1.91 or later should suffice. (The kernel dis-
tinguishes old and new calls by a IPC_64 flag in cmd.)
The following system limit on semaphore sets affects a semctl call:
SEMVMX Maximum value for semval: implementation dependent (32767).
For greater portability it is best to always call semctl with four
arguments.
Under Linux, the function semctl is not a system call, but is imple-
mented via the system call ipc(2).
CONFORMING TO
SVr4, SVID. SVr4 documents more error conditions EINVAL and EOVERFLOW.
SEE ALSO
ipc(2), shmget(2), shmat(2), shmdt(2), ipc(5)
Linux 2.4.1 2001-12-21 semctl(2)