NAME
semctl — semaphore control operations
SYNOPSIS
#include <sys/sem.h>
int semctl(int semid,
int semnum,
int cmd,
union arg
);
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.
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
Return the value of
semval.
Requires semaphore Read permission.
- SETVAL
Set the value of
semval
to
arg.val,
where
arg
is the fourth argument of
semctl()
taken as an
int.
When this
cmd
is successfully executed,
the
semadj
value corresponding to the specified semaphore
in all processes is cleared.
Requires semaphore Alter permission.
- GETPID
Return the value of
sempid.
Requires semaphore Read permission.
- GETNCNT
Return the value of
semncnt.
Requires semaphore Read permission.
- GETZCNT
Return the value of
semzcnt.
Requires semaphore Read permission.
The following values for
cmd
return and set, respectively, every
semval
in the set of semaphores.
- GETALL
Place
semvals
into array pointed to by
arg.array,
where
arg
is the fourth argument of
semctl()
taken as a pointer to
unsigned short int.
Requires semaphore Read permission.
- SETALL
Set
semvals
according to the array pointed to by
arg.array,
where
arg
is the fourth argument of
semctl()
taken as a pointer to
unsigned short int.
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 pointer to
struct semid_ds.
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 pointer to
struct semid_ds:
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 superuser 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 superuser or to
the value of either
sem_perm.uid
or
sem_perm.cuid
in the data structure associated with
semid.
RETURN VALUE
Upon successful completion,
semctl()
returns a value based on
cmd
as follows:
- GETVAL
The value of
semval.
- GETNCNT
The value of
semncnt.
- GETZCNT
The value of
semzcnt.
- GETPID
The value of
sempid.
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 superuser 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
semval
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
