semctl(2) semctl(2)
NAME [Toc] [Back]
semctl - semaphore control operations
SYNOPSIS [Toc] [Back]
#include <sys/sem.h>
int semctl(int semid,
int semnum,
int cmd,
...
);
union semun {
int val;
struct semid_ds *buf;
ushort *array;
} arg;
DESCRIPTION [Toc] [Back]
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 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 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 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.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
semctl(2) semctl(2)
GETALL Place semvals 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 semvals 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
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 [Toc] [Back]
Upon successful completion, semctl() returns a value based on cmd as
follows:
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
semctl(2) semctl(2)
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 [Toc] [Back]
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 [Toc] [Back]
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;
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
semctl(2) semctl(2)
ushort semarray[4];
semarray[0] = 0;
semarray[1] = 1;
semarray[2] = 0;
semarray[3] = 1;
arg.array = &semarray[0];
semctl (mysemid, 0, SETALL, arg);
SEE ALSO [Toc] [Back]
ipcrm(1), ipcs(1), semget(2), semop(2), glossary(9).
STANDARDS CONFORMANCE [Toc] [Back]
semctl(): SVID2, SVID3, XPG2, XPG3, XPG4
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003 [ Back ] |
