semctl()" -- General Function (libc)" "
Control semaphore operations
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
iinntt sseemmccttll((_i_d,, _n_u_m_b_e_r,, _c_o_m_m_a_n_d,, _a_r_g))
iinntt _i_d,, _c_o_m_m_a_n_d,, _n_u_m_b_e_r;;
uunniioonn sseemmuunn {{
iinntt _v_a_l_u_e;;
ssttrruucctt sseemmiidd__ddss **_b_u_f_f_e_r;;
uunnssiiggnneedd sshhoorrtt _a_r_r_a_y[[]];;
}} _a_r_g;;
The function semctl() controls the COHERENT
system's semaphore facility.
A set of semaphores consists of a copy of structure
semid_ds, which is defined in header file
<sys/sem.h>. This structure points to
the set of semaphores, notes how many semaphores are in the
set, and gives information on who can manipulate it, and
how. The semaphores themselves consist of an array of
structures of type sem, which is also defined
in sem.h. When the function
semget() creates a set of semaphores, it
assigns to that set an identification number and returns
that number to the calling process. For details on this
process, see the Lexicon entry for semget()
id identifies the set of semaphores to be
manipulated. This value must have been returned by a call
to semget(). number gives the offset
within the set identified by id of the semaphore
that interests you. arg gives information to be
passed to, or received from, the semaphore in question.
command names the operation that you want
semctl() to perform.
The following commands manipulate semaphore
number within the set identified by
id:
- GGEETTVVAALL
- Return the value of sseemmvvaall, which is the field in
structure sem that gives the address of the
semaphore's text map.
- SSEETTVVAALL
- Set sseemmvvaall to _a_r_g_._v_a_l_u_e. If an ``adjust value'' had
been created for this semaphore (by changing or setting a
semaphore through semop() with the flag
SEM_UNDO set), it is erased.
- GGEETTPPIIDD
- Return the value of sseemmppiidd, which is the field in
sem that identifies the last process to
have manipulated this semaphore.
- GGEETTNNCCNNTT
- Return the value of sseemmnnccnntt, which gives the number of
processes that await an increase in field
sem.semval.
- GGEETTZZCCNNTT
- Return the value of sseemmzzccnntt, which gives the number of
processes that are waiting for the value of
sem.semval to become zero.
The following commands return or set field
semval within every semaphore in the set
identified by id:
- GGEETTAALLLL
- Write every semval into _a_r_g_._a_r_r_a_y.
- SSEETTAALLLL
- Initialize every semval to the
corresponding value within _a_r_g_._a_r_r_a_y. All ``adjust values''
for this semaphores are erased.
semctl() also recognizes the following
commands:
- IIPPCC__SSTTAATT
- Copy the value of each semaphore in the set identified
by id into the structure pointed to by _a_r_g_._b_u_f_f_e_r.
- IIPPCC__SSEETT
- Copy fields sem_perm.uid,
sem_perm.gid, and
sem_perm.mode (low nine bits only) from the
ipc_perm associated with id into
that pointed to arg.buffer. Only the superuser
root or the user whose effective user ID
matches the value of field uid in the data
structure identified by id can invoke this command.
- IIPPCC__RRMMIIDD
- Destroy the semid_ds structure
identified by id, plus its array of
semaphores. Only the superuser root or the
user whose effective user ID matches the value of field
uid can invoke this command.
semctl() fails if one or more of the
following is true:
- +o
- id is not a valid semaphore identifier.
semctl() sets the global variable
errno to EINVAL.
- +o
- number is less than zero or greater than field
sem_nsems in structure
semid_ds, which gives the number of semaphores
in the set identified by id (EEIINNVVAALL).
- +o
- command is not a valid command (EEIINNVVAALL).
- +o
- The calling process is denied operation permission
(EEAACCCCEESS).
- +o
- command is SETVAL or
SETALL, but the value of
semval exceeds the system-imposed maximum
(EERRAANNGGEE).
- +o
- command is IPC_RMID or
IPC_SET, but the calling process is owned
neither by root nor by the user who created
the set of semaphores being manipulated (EEPPEERRMM).
- +o
- arg.buffer points to an illegal address
(EEFFAAUULLTT).
semctl() returns the following values upon
successful completion of their following commands:
_C_o_m_m_a_n_d _R_e_t_u_r_n _V_a_l_u_e
GGEETTVVAALL Value of sseemmvvaall
GGEETTPPIIDD Value of sseemmppiidd
GGEETTNNCCNNTT Value of sseemmnnccnntt
GGEETTZZCCNNTT Value of sseemmzzccnntt
For all other commands, semctl() returns
zero to indicate successful completion.
If it could not execute a command successfully,
semctl() returns -1 and sets eerrrrnnoo to an
appropriate value.
Files
/usr/include/sys/ipc.h
/usr/include/sys/sem.h
See Also
Notes
For information on other methods of interprocess
communication, see the Lexicon entries for
msgctl() and shmctl().