Semaphore control operations
This function is supported on OpenVMS Integrity servers and
Alpha only.
Format
#include <sem.h>
int semctl (int semid, int semnum, int cmd, . . . );
1 – Argument
semid
A semaphore set identifier, a positive integer. It is created
by the semget function and used to identify the semaphore set on
which to perform the control operation.
semnum
Semaphore number, a non-negative integer. It identifies a
semaphore within the semaphore set on which to perform the
control operation.
cmd
The control operation to perform on the semaphore.
. . .
Optional fourth argument of type union semun, which depends on
the control operation requested in cmd.
2 – Description
The semctl function provides a variety of semaphore control
operations as specified by cmd. The fourth argument is optional
and depends upon the operation requested. If required, it is of
type union semun, which is explicitly declared as:
union semun {
int val;
struct semid_ds *buf;
unsigned short *array;
} arg;
The following semaphore control operations as specified by cmd
are executed with respect to the semaphore specified by semid and
semnum. The level of permission required for each operation is
shown with each command. The symbolic names for the values of cmd
are defined in the <sem.h> header:
o GETVAL
Returns the value of semval. Requires read permission.
o 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. Requires
alter permission.
o GETPID
Returns the value of sempid; requires read permission.
o GETNCNT
Returns the value of semncnt; requires read permission.
o GETZCNT
Returns the value of semzcnt; requires read permission.
The following values of cmd operate on each semval in the set of
semaphores:
o GETALL
Returns the value of semval for each semaphore in the
semaphore set and places it into the array pointed to by
arg.array, where arg is the fourth argument to semctl;
requires read permission.
o SETALL
Sets the value of semval for each semaphore in the semaphore
set according to the array pointed to by arg.array, where
arg is the fourth argument to semctl. When this command is
successfully executed, the semadj values corresponding to each
specified semaphore in all processes are cleared. Requires
alter permission.
The following values of cmd are also available:
o IPC_STAT
Places the current value of each member of the semid_ds data
structure associated with semid into the structure pointed to
by arg.buf, where arg is the fourth argument to semctl. The
contents of this structure are defined in <sem.h>. Requires
read permission.
o IPC_SET
Sets the value of the following members of the semid_ds data
structure associated with semid to the corresponding value
found in the structure pointed to by arg.buf, where arg is the
fourth argument to semctl:
sem_perm.uid
sem_perm.gid
sem_perm.mode
The mode bits specified in The Open Group Base Specifications
IPC General Description section are copied into the
corresponding bits of the sem_perm.mode associated with semid.
The stored values of any other bits are unspecified.
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 data structure associated with
semid.
o IPC_RMID
Removes the semaphore identifier specified by semid from
the system and destroys the set of semaphores and semid_ds
data structure associated with it. 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 data
structure associated with semid.
3 – Return Values
n or 0 Upon successful completion, the value returned
by the function depends on cmd as follows:
o GETVAL - The value of semval
o GETPID - The value of sempid
o GETNCNT - The value of semncnt
o GETZCNT - The value of semzcnt
o All others - 0
-1 Indicates an error. The function sets errno to
one of the following values:
o EACCES - Operation permission is denied to
the calling process.
o EFAULT - The arguments passed to the
function are not accessible.
o EINVAL - The value of semid is not a valid
semaphore identifier, or the value of
semnum is less than zero or greater than
or equal to sem_nsems, or the value of cmd
is not a valid command.
o EPERM - The argument cmd is equal to IPC_
RMID or IPC_SET and the effective user ID
of the calling process is not equal to that
of a process with appropriate privileges
and it is not equal to the value of sem_
perm.cuid or sem_perm.uid in the data
structure associated with semid.
o EVMSERR - OpenVMS specific nontranslatable
error code.