semctl - Perform semaphore control operations
#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 programs 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.
Interfaces documented on this reference page conform to
industry standards 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.
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 program 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 structure 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.
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 adjuston-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 command 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 associated 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.
The librt library contains alternative interfaces for
interprocess communication. The names of these routines
adhere to the format sem_* and their reference pages are
listed in SEE ALSO.
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.
The semctl() function sets errno to the specified values
for the following conditions: The calling process does not
have the required permission. [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.
Functions: semget(2), semop(2), sem_close(3),
sem_destroy(3), sem_getvalue(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)
[ Back ] | 