semctl(2)semctl(2)NAMEsemctl - Perform semaphore control operations
SYNOPSIS
#include <sys/sem.h>
int semctl(
int semid,
int semnum,
int cmd,
... );
Application developers might want to specify #include statements for
<sys/types.h> and <sys/ipc.h> before the one for <sys/sem.h> if pro‐
grams are being developed for multiple platforms. The additional
#include statements are not required on Tru64 UNIX systems or by ISO or
XSH specifications, but may be required on other vendors' systems that
conform to these standards.
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
semctl(): XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the ID of the semaphore set. Specifies the number of the
semaphore to be processed. Specifies the type of command. See
DESCRIPTION for a list of available commands.
The fourth argument is optional and depends on the operation requested.
If required, it is of the type union semun, which the application pro‐
gram must explicitly declare as follows:
union semun {
int val;
struct semid_ds *buf;
u_short *array;
} arg );
The members of this structure are described as follows:
Contains the semaphore value to which semval is set when the SETVAL
command is performed. Points to a structure of type semid_ds. For
information about this structure, see semid_ds(4). When you specify the
IPC_STAT command, semctl() copies the contents of the semid_ds struc‐
ture identified by semid into arg.buf. When you specify the IPC_SET
command, semctl() copies the contents of the arg.buf parameter into the
semid_ds structure identified by the semid parameter. Points to an
array of semval values. These semval values are returned by the GETALL
command and set by the SETALL command.
DESCRIPTION
The semctl() function allows a process to perform various operations on
an individual semaphore within a semaphore set, on all semaphores
within a semaphore set, and on the semid_ds structure associated with
the semaphore set. It also allows a process to remove the semaphore
set's ID and its associated semid_ds structure.
The cmd value determines which operation is performed. The following
commands operate on the specified semaphore (that is, the one specified
by the semnum parameter) within the semaphore set identified by semid:
Returns the value of semval. This command requires read permission.
Sets the value of semval to arg.val. When this command successfully
executes, the kernel clears the semaphore's adjust-on-exit value in all
processes. This command requires modify permission. Returns the value
of sempid. This command requires read permission. Returns the value of
semncnt. This command requires read permission. Returns the value of
semzcnt. This command requires read permission.
The following commands operate on all the semaphores in the semaphore
set:
Returns all the semval values and places them in the array pointed to
by arg.array. This command requires read permission. Sets all the
semval values according to the array pointed to by arg.array. When this
command successfully executes, the kernel clears the semaphore's
adjust-on-exit value in all processes. This command requires modify
permission.
You can also use the following IPC commands:
Queries the semaphore ID by copying the contents of its associated
semid_ds structure into the structure pointed to by arg.buf. This com‐
mand requires read permission. Sets the semaphore set by copying the
values in the arg.buf structure into corresponding fields in the
semid_ds structure associated with the semaphore ID. This operation is
restricted. The effective user ID of the calling process must have
superuser privilege or must be equal to the value of sem_perm.cuid or
sem_perm.uid in the structure associated with the semaphore ID. The
fields are set as follows: The sem_perm.uid field is set to the owner's
user ID. The sem_perm.gid field is set to the owner's group ID. The
sem_perm.mode field is set to the access modes for the semaphore set.
Only the low-order nine bits are set. The sem_ctime field is set to
the time of the last IPC_SET operation. Removes the semaphore ID and
destroys the set of semaphores and the semid_ds data structure associ‐
ated with it. This operation is restricted. The effective user ID of
the calling process must have superuser privilege or be equal to the
value of sem_perm.cuid or sem_perm.uid in the associated semid_ds
structure.
NOTES
The librt library contains alternative interfaces for interprocess com‐
munication. The names of these routines adhere to the format sem_* and
their reference pages are listed in SEE ALSO.
RETURN VALUES
Upon successful completion, the value returned depends on the cmd
parameter as follows: Returns the value of semval. Returns the value
of sempid. Returns the value of semncnt. Returns the value of
semzcnt.
All other commands return a value of 0 (zero).
If the semctl() function fails, it returns a value of -1 and sets errno
to indicate the error.
ERRORS
The semctl() function sets errno to the specified values for the fol‐
lowing conditions: The calling process does not have the required per‐
mission. [Tru64 UNIX] The cmd parameter is IPC_STAT or IPC_SET and an
error occurred in accessing the arg structure. The semid parameter is
not a valid semaphore ID; the value of semnum is less than 0 (zero) or
greater than sem_nsems; or cmd is not a valid command. [Tru64
UNIX] The system does not have enough memory to complete the function.
Either the cmd parameter is equal to IPC_RMID and the effective user ID
of the calling process does not have appropriate privilege, or the cmd
parameter is equal to IPC_SET and the effective user ID of the calling
process is not equal to the value of sem_perm.cuid or sem_perm.uid in
the semid_ds structure associated with the semaphore ID. The cmd
parameter is SETVAL or SETALL and the value to which semval is to be
set is greater than the system-defined maximum.
SEE ALSO
Functions: semget(2), semop(2), sem_close(3), sem_destroy(3), sem_get‐
value(3), sem_init(3), sem_open(3), sem_post(3), sem_unlink(3),
sem_wait(3)
Data structures: semid_ds(4)
Standards: standards(5)semctl(2)