NAME
semctl() — semaphore control operations
SYNOPSIS
#include <sys/sem.h>
int semctl(int semid,
int semnum,
int cmd,
...
);
union semun {
int val;
struct semid_ds *buf;
ushort *array;
} arg;
DESCRIPTION
The
semctl()
system call provides a variety of semaphore control operations as specified by
cmd.
The fourth argument is optional and depends on the operation
requested.
If present, it must be of type
union semun,
which the
application program must explicitly declare.
For the meaning of unspecified variables, see
semaphore identifier
in
glossary(9).
The following values for
cmd
are executed with respect to the semaphore specified by
semid
and
semnum:
- GETVAL
Returns the semaphore value.
Requires semaphore Read permission.
- SETVAL
Sets the value of the semaphore
to
arg.val,
where
arg
is the fourth argument of
semctl()
taken as a
union semun.
When this
cmd
is successfully executed,
the
semadj
value corresponding to the specified semaphore
in all processes is cleared.
Requires semaphore Alter permission.
- GETPID
Returns the pid of the last process that performed a
semaphore operation on this semaphore.
Requires semaphore Read permission.
- GETNCNT
Returns count of the number of processes that are
currently suspended awaiting this semaphore's
value to become greater than its current value.
Requires semaphore Read permission.
- GETZCNT
Returns count of the number of processes that are
currently suspended awaiting this semaphore's
value to become zero.
Requires semaphore Read permission.
The following values for
cmd
return and set, respectively, every
semaphore in the set of semaphores.
- GETALL
Place semaphore value into array pointed to by
arg.array,
where
arg
is the fourth argument of
semctl()
taken as a
union semun.
Requires semaphore Read permission.
- SETALL
Set semaphore value
according to the array pointed to by
arg.array,
where
arg
is the fourth argument of
semctl()
taken as a
union semun.
When this
cmd
is successfully executed,
the
semadj
values corresponding to each specified semaphore
in all processes are cleared.
Requires semaphore Alter permission.
The following values for
cmd
are also available:
- IPC_STAT
Place the current value of each member
of the data structure associated with
semid
into the structure pointed to by
arg.buf,
where
arg
is the fourth argument of
semctl()
taken as a
union semun.
The contents of this structure are defined in
glossary(9).
Requires semaphore Read permission.
- IPC_SET
Set the value of the following members of the data structure associated with
semid
to the corresponding value found in the structure pointed to by
arg.buf,
where
arg
is the fourth argument of
semctl()
taken as a
union semun:
sem_perm.uid
sem_perm.gid
sem_perm.mode /* only low 9 bits */
This
cmd
can only be executed by a process that
has an effective user
ID
equal to either that of a user with the
OWNER
privilege or to the value of either
sem_perm.uid
or
sem_perm.cuid
in the data structure associated with
semid.
- IPC_RMID
Remove the semaphore identifier specified by
semid
from the system and destroy the set of semaphores and data structure
associated with it.
This
cmd
can only be executed by a process that
has an effective user
ID
equal to either that of a user with the
OWNER
privilege or to
the value of either
sem_perm.uid
or
sem_perm.cuid
in the data structure associated with
semid.
Security Restrictions
Some or all of the actions associated with this system call are subject to
compartmental restrictions. See
compartments(5)
for more information about compartmentalization on systems that support
that feature.
Compartmental restrictions can be overridden if the process possesses the
COMMALLOWED
privilege (PRIV_COMMALLOWED).
Processes owned by the superuser may not have this privilege.
Processes owned by any user may have this privilege, depending on system
configuration.
Some or all of the actions associated with this system call require one
or more privileges.
Processes owned by the superuser have many, though not all, privileges.
Processes owned by other users may have privilege(s), depending on system
configuration. See
privileges(5)
for more information about privileged access on
systems that support fine-grained privileges.
RETURN VALUE
Upon successful completion,
semctl()
returns a value based on
cmd.
All others return
0.
If it fails, it returns
-1
and sets
errno
to indicate the error.
ERRORS
If
semctl()
fails, it sets
errno
to one of the following values:
- EACCES
Operation permission is denied to the calling process (see
semaphore operation permissions
in
glossary(9).
- EFAULT
cmd
is
SETVAL,
GETALL,
SETALL,
IPC_SET,
or
IPC_STAT,
and
arg
is an invalid pointer.
- EINVAL
semid
is not a valid semaphore identifier.
- EINVAL
semnum
is less than zero or greater than or equal
sem_nsems.
- EINVAL
cmd
is not a valid command, or the command contains invalid parameters.
- EPERM
cmd
is equal to
IPC_RMID
or
IPC_SET
and the process does not
have an effective user
ID
equal to either that of a user with the
OWNER
privilege or to
the value of either
sem_perm.uid
or
sem_perm.cuid
in the data structure associated with
semid.
- ERANGE
cmd
is
SETVAL
or
SETALL
and the value to which
semaphore value is to be set
is greater than the system imposed maximum.
EXAMPLES
The following call to
semctl()
initializes the set of 4 semaphores to the values 0,
1, 0, and 1 respectively.
This example assumes the process has a valid
semid
representing a set of 4 semaphores as shown in the
semget(2)
manual entry.
For an example of performing "P" and "V" operations
on the semaphores below, refer to
semop(2).
union semun {
int val;
struct semid_ds *buf;
ushort *array;
} arg;
ushort semarray[4];
semarray[0] = 0;
semarray[1] = 1;
semarray[2] = 0;
semarray[3] = 1;
arg.array = &semarray[0];
semctl (mysemid, 0, SETALL, arg);
STANDARDS CONFORMANCE
semctl(): SVID2, SVID3, XPG2, XPG3, XPG4
Printable version
