semctl
Purpose
Controls semaphore operations.
Syntax
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int semctl (semid, semnum, cmd, val)
-- or --
int semctl (semid, semnum, cmd, buf)
-- or --
int semctl (semid, semnum, cmd, array)
int semid;
unsigned int semnum;
int cmd;
int val;
struct semid_ds *buf;
unsigned short array[ ];
Description
The semctl system call performs a variety of semaphore
control operations as specified by the cmd parameter.
The data type of the last parameter depends on the value
of the cmd parameter. It is referred to as val, buf, or
array to indicate one of the definitions given in the
preceding Syntax section.
The first seven cmds get and set the values of a sem
structure, which is defined in the sys/sem.h header file
and contains the following members:
ushort semval; /* Operation permission structure */
short sempid; /* ID of last process that did a semop */
ushort semncnt; /* No. of processes awaiting semval > cval */
ushort semzcnt; /* No. of processes awaiting semval = 0 */
The following cmds are executed with respect to the
semaphore specified by the semid and semnum parameters.
GETVAL Returns the value of semval, if the current
process has read permission.
SETVAL Sets the value of semval to the value speci-
fied by val, if the current process has write
permission. When this cmd is successfully
executed, the semadj value corresponding to
the specified semaphore is cleared in all
processes.
GETPID Returns the value of sempid, if the current
process has read permission.
GETNCNT Returns the value of semncnt, if the current
process has read permission.
GETZCNT Returns the value of semzcnt, if the current
process has read permission.
The following cmds return and set every semval in the set
of semaphores.
GETALL Stores semvals into the array pointed to by
array, if the current process has read per-
mission.
SETALL Sets semvals according to the array pointed
to by array, if the current process has write
permission. When this cmd is successfully
executed, the semadj value corresponding to
each specified semaphore is cleared in all
processes.
The following cmds are also available:
IPC_STAT Stores the current value of each member of
the data structure associated with the semid
parameter into the structure pointed to by
buf, if the current process has read permis-
sion. This structure is defined in sys/sem.h
and contains the following members:
struct ipc_perm sem_perm; /* Operation permission structure */
struct sem *sem_base; /* Pointer to first semaphore in set */
ushort sem_nsems; /* Number of semaphores in the set */
ushort semlcnt; /* Processes waiting on locked semaphore */
time_t sem_otime; /* Time of last semop call */
time_t sem_ctime; /* Time of the last change to this */
/* structure with a semctl call */
IPC_SET Sets the value of the following members of
the data structure associated with the semid
parameter to the corresponding value found in
the structure pointed to by buf:
sem_perm.uid
sem_perm.gid
sem_perm.mode /* Only the low-order nine bits */
This cmd can only be executed by a process
that has an effective user ID equal to either
that of superuser or to the value of
sem_perm.uid in the data structure associated
with the semid parameter.
IPC_RMID Removes the semaphore identifier specified by
the semid parameter from the system and
destroys the set of semaphores and data
structures associated with it. This cmd can
only be executed by a process that has an
effective user ID equal to either that of
superuser or to the value of sem_perm.uid in
the data structure associated with the semid
parameter.
Return Value
Upon successful completion, the value returned depends on
the cmd parameter as follows:
cmd Return Value
GETVAL Returns the value of semval.
GETPID Returns the value of sempid.
GETNCNT Returns the value of semncnt.
GETZCNT Returns the value of semzcnt.
All others Return a value of 0.
If semctl fails, a value of -1 is returned and errno is
set to indicate the error.
Diagnostics
The semctl system call fails if one or more of the fol-
lowing are true:
EINVAL The semid parameter is not a valid semaphore
identifier.
EINVAL The semnum parameter is less than 0 or greater
than sem_nsems.
EINVAL The cmd parameter is not a valid command.
EACCES Operation permission is denied to the calling
process.
ERANGE The cmd parameter is SETVAL or SETALL and the
value to which semval is to be set is greater
than the system-imposed maximum.
EPERM The cmd parameter is equal to IPC_RMID or
IPC_SET and the effective user ID of the
calling process is not equal either to that of
superuser or to the value of sem_perm.uid in
the data structure associated with the semid
parameter.
EFAULT The buf or array parameter &pointsout..
Related Information
In this book: "semget" and "semop."