SEMCTL(3,L) AIX Technical Reference SEMCTL(3,L)
-------------------------------------------------------------------------------
semctl
PURPOSE
Controls semaphore operations.
LIBRARY
Standard C Library (libc.a)
SYNTAX
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int semctl (semid, semnum, cmd, val)
- or -
int semctl (semid, semnum, cmd, buf)
- or -
int semctl (semid, semnum, cmd, array)
int semid;
unsigned int semnum;
int cmd;
int val;
struct semid_ds *buf;
unsigned short array [ ];
DESCRIPTION
The semctl system call performs a variety of semaphore control operations as
specified by the cmd parameter. The data type of the last parameter depends on
the value of the cmd parameter. It is referred to as val, buf, or array to
indicate one of the definitions given in the preceding Syntax section.
The first seven cmds get and set the values of a sem structure, which is
defined in the sys/sem.h header file and contains the following members:
ushort semval; /* Operation permission structure */
pid_t sempid; /* ID of last process that did a semop */
ushort semncnt; /* No. of processes awaiting semval > cval */
ushort semzcnt; /* No. of processes awaiting semval = 0 */
The following cmds are executed with respect to the semaphore specified by the
semid and semnum parameters.
Processed November 7, 1990 SEMCTL(3,L) 1
SEMCTL(3,L) AIX Technical Reference SEMCTL(3,L)
GETVAL Returns the value of semval, if the current process has read
permission.
SETVAL Sets the value of semval to the value specified by val, if the
current process has write permission. When this cmd is
successfully executed, the semadj value corresponding to the
specified semaphore is cleared in all processes.
GETPID Returns the value of sempid, if the current process has read
permission.
GETNCNT Returns the value of semncnt, if the current process has read
permission.
GETZCNT Returns the value of semzcnt, if the current process has read
permission.
The following cmds return and set every semval in the set of semaphores.
GETALL Stores semvals into the array pointed to by array, if the current
process has read permission.
SETALL Sets semvals according to the array pointed to by array, if the
current process has write permission. When this cmd is
successfully executed, the semadj value corresponding to each
specified semaphore is cleared in all processes.
The following cmds are also available:
IPC_STAT Stores the current value of each member of the data structure
associated with the semid parameter into the structure pointed to
by buf, if the current process has read permission. This structure
is defined in sys/sem.h and contains the following members:
struct ipc_perm sem_perm; /* Operation permission structure */
struct sem *sem_base; /* Pointer to first semaphore in set */
ushort sem_nsems; /* Number of semaphores in the set */
time_t sem_otime; /* Time of last semop call */
time_t sem_ctime; /* Time of the last change to this */
/* structure with a semctl call */
IPC_SET Sets the value of the following members of the data structure
associated with the semid parameter to the corresponding value
found in the structure pointed to by buf:
sem_perm.uid
sem_perm.gid
sem_perm.mode /* Only the low-order nine 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
Processed November 7, 1990 SEMCTL(3,L) 2
SEMCTL(3,L) AIX Technical Reference SEMCTL(3,L)
sem_perm.uid in the data structure associated with the semid
parameter.
IPC_RMID Removes the semaphore identifier specified by the semid parameter
from the system and destroys the set of semaphores and data
structures 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 sem_perm.uid in the data structure
associated with the semid parameter.
Note: In a Transparent Computing Facility cluster, semaphores are not
maintained across the cluster. This means that a process cannot
communicate via semaphores to processes on another cluster site and the
process itself cannot migrate.
RETURN VALUE
Upon successful completion, the value returned depends on the cmd parameter as
follows:
cmd Return Value
GETVAL Returns the value of semval.
GETPID Returns the value of sempid.
GETNCNT Returns the value of semncnt.
GETZCNT Returns the value of semzcnt.
All others Return a value of 0.
If semctl fails, a value of -1 is returned, and errno is set to indicate the
error.
ERROR CONDITIONS
The semctl system call fails if one or more of the following are true:
EINVAL The semid parameter is not a valid semaphore identifier.
EINVAL The semnum parameter is less than 0 or greater than sem_nsems.
EINVAL The cmd parameter is not a valid command.
EACCES Operation permission is denied to the calling process.
ERANGE The cmd parameter is SETVAL or SETALL and the value to which semval
is to be set is greater than the system-imposed maximum.
EPERM The cmd parameter is equal to IPC_RMID or IPC_SET and the effective
user ID of the calling process is not equal either to that of
superuser or to the value of sem_perm.uid in the data structure
associated with the semid parameter.
EFAULT The buf or array parameter points to a location outside of the
process's allocated address space.
Processed November 7, 1990 SEMCTL(3,L) 3
SEMCTL(3,L) AIX Technical Reference SEMCTL(3,L)
RELATED INFORMATION
In this book: "semget" and "semop."
Processed November 7, 1990 SEMCTL(3,L) 4