Standards
Standards / Extensions |
C or C++ |
Dependencies |
XPG4
XPG4.2
Single UNIX Specification, Version 3
|
both |
|
Format
#define _XOPEN_SOURCE
#include <sys/sem.h>
int semctl(int semid, int semnum, int cmd, ...);
General description
The semctl()
function performs control operations in semaphore set semid as
specified by the argument cmd.
Depending
on the value of argument cmd, argument semnum may
be ignored or identify one specific semaphore number.
The fourth
argument is optional and depends upon the operation requested. If
required, it is of type
union semun, which
the application program must explicitly declare:
union semun {
int val;
struct semid_ds *buf;
unsigned short *array;
} arg;
Each semaphore in the semaphore set is represented
by the following anonymous data structure:
unsigned short
int |
semval |
Semaphore value |
pid_t |
sempid |
Process ID of last
operation |
unsigned sort int |
semcnt |
Number of processes
waiting for semval to become greater than current
value |
unsigned short int |
semzcnt |
Number of processes
waiting for semval to become zero |
When semctl() is used to identify one specific semaphore
number for commands GETVAL, SETVAL, GETPID, GETNCNT, and GETZCNT,
then references are made to this anonymous data structure for the
semaphore semnum.
The following semaphore
control operations as specified by argument
cmd may
be specified. The level of permission required for each operation
is shown with each command. These symbolic constants are defined
by the <sys/sem.h> header:
- GETVAL
- Returns the value
of semval, if the current process has read permission.
- SETVAL
- Sets
the value of semval to arg.val,
where arg is the value of the fourth argument to
semctl(). When this command is successfully executed, the semadj value
corresponding to the specified semaphore in all processes is cleared.
This command requires alter permission. For an __IPC_BINSEM semaphore
set the only values that may be set are zero and one.
- GETPID
- Returns the most
recent process to update the semaphore (sempid), if the current process
has read permission.
- GETNCNT
- Returns the number
of threads waiting on the semaphore to become greater than the current
value, if the current process has read permission.
- GETZCNT
- Returns the number
of threads waiting on the semaphore to become zero, if the current
process has read permission. For an __IPC_BINSEM semaphore set this
operation will always return a zero; threads are not allowed to wait
for the semaphore to become zero in this type of semaphore set.
- GETALL
- Stores semvals for
each semaphore in the semaphore set and place into the array pointed
to by arg.array, where arg. is the
fourth argument to semctl(). GETALL requires read permission. It
is the caller's responsibility to ensure that the storage allocated
is large enough to hold the number of semaphore elements. The number
of semaphore values stored is sem_nsems, which may
be obtained using the IPC_STAT command.
- SETALL
- Sets semval values
for each semaphore in the semaphore set according to the array pointed
to by arg.array, where arg is the fourth argument
to semctl(). SETALL requires alter permission. Each semval value
must be zero or positive. When this command is successfully executed,
the semadj values corresponding to each specified
semaphore in all processes are cleared. It is the caller's responsibility
to ensure that the storage allocated is large enough to hold the number
of semaphore elements. The number of semaphore values set is sem_nsems,
which may be obtained using the IPC_STAT command. If __IPC_BINSEM
was specified on the semget, this option should not be used while
there is the possibility of other threads performing semaphore operations
on this semaphore, as there may be no serialization while updating
the semaphore values; therefore a SETALL will not be allowed after
a semop has been done to the __IPC_BINSEM semaphore set. Also,
for the __IPC_BINSEM semaphore set, the only values that may be set
are zero and one.
- IPC_STAT
- This command
obtains status information for the semaphore identifier specified
by semid. This requires read permission.
This information is stored in the address specified by the fourth
argument defined by data structure semid_ds.
- IPC_SET
- Set the value
of the sem_perm.uid, sem_perm.gid,
and sem_perm.mode in semid_ds data
structure for the semaphore identifier specified by semid.
These values are set to the values found in semid_ds structure
pointed to by the fourth argument.
Any value for sem_perm.uid and semperm.gid may
be set.
Only mode bits defined under semget() function argument semflg may
be set in sem_perm.mode.
This command can
only be executed by a process that has an effective user ID equal
to either that of a process with appropriate privileges or to the
value of sem_perm.cuid or sem_perm.uid in
the semid_ds structure associated with semid.
- IPC_RMID
- Remove the semaphore
identifier specified by argument semid from
the system and free the storage for the set of semaphores in the semid_ds structure.
This command can only be executed by a process that has an effective
user ID equal to either that of a process with appropriate privileges
or to the value of sem_perm.cuid or sem_perm.uid in
the semid_ds structure associated with semid.
For an __IPC_BINSEM semaphore set, it is recommended that all use
of semop should be completed before removing the semaphore ID.
Returned value
If successful, the value
returned by semctl() depends on the value of the argument
cmd as
follows:
- GETVAL
- value of semval is returned
- GETPID
- value of sempid is returned
- GETNCNT
- value of semncnt is returned
- GETZCNT
- value of semzcnt is returned
- All others
- value of zero is returned
If unsuccessful, semctl() returns -1 and sets
errno to one of the following values:
- Error Code
- Description
- EACCES
- Operation permission (read or write) is denied to the calling
process.
- EINVAL
- The value of argument semid is not a
valid semaphore identifier, or the value of semnum is
less than zero or greater than or equal to the number of semaphores
in the set, or the argument cmd is not a
valid command, or the bits specified for sem_perm.mode are
undefined. Note that the valid range of semnum is
0 to (number of semaphores in the set minus 1).
- EPERM
- The argument cmd has a value of IPC_RMID or IPC_SET and
the effective user ID of the caller is not that of a process with
appropriate privileges and is not the value of sem_perm.cuid or sem_perm.uid in
the semid_ds data structure associated with semid.
- ERANGE
- The argument cmd has a value of SETVAL or SETALL and
the semval value to be set exceeds the system limit
as defined in <sys/sem.h>.