semctl(2) DG/UX R4.11MU05 semctl(2)
NAME
semctl - semaphore control operations
SYNOPSIS
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
#include <sys/dgsemun.h>
/* or */
union semun {
int val;
struct semidds *buf;
unsigned short *array;
};
int semctl (semid, semnum, cmd, arg)
int semid;
int semnum;
int cmd;
union semun arg;
where:
semid A semaphore set identifier
semnum The subject semaphore (used only if cmd is GETVAL, SETVAL,
GETNCNT, GETZCNT or GETPID)
cmd The semaphore operation to be performed
arg An argument (used only if cmd is SETVAL, GETALL, SETALL,
IPC_STAT, OR IPC_SET)
DESCRIPTION
The semctl system call provides semaphore control operations as
specified by cmd. The subject semaphore set is identified by semid.
The action taken depends on the value of cmd as follows:
SETVAL Set the value of semaphore number semnum to arg.val.
When this cmd is successfully executed, all processes
having a semaphore adjustment value corresponding to
semaphore number semnum will have those values set to zero.
If an error occurs, the semaphore set is unchanged.
GETVAL Return the value of semaphore number semnum.
GETPID Return the process id of the last process to perform an
operation on semaphore number semnum.
GETNCNT Return the number of processes waiting for the value of
semaphore number semnum to increase.
GETZCNT Return the number of processes waiting for the value of
semaphore number semnum to become zero.
SETALL Set the value of all semaphores in the specified semaphore
set to the values contained in the array pointed to by
arg.array.
When this cmd is successfully executed, all processes
having a semaphore adjustment value corresponding to a
semaphore in the specified semaphore set will have those
values set to zero.
If an error occurs, the semaphore set is unchanged.
GETALL Return the value of all semaphores in the specified
semaphore set using the array pointed to by arg.array.
If an error occurs, the contents of arg.array are
undefined.
IPC_STAT The current semaphore set attributes are stored in the
structure pointed to by arg.buf.
If an error occurs, the contents of arg.buf are undefined.
IPC_SET The following semaphore set attributes are set to the
values found in the structure pointed to by arg.buf: user
id (sem_perm.uid), group id (sem_perm.gid), and permission
rights (in sem_perm.mode).
If an error occurs, the semaphore set remains unchanged.
Otherwise, the last change time (sem_ctime) is set to the
current time.
IPC_RMID The semaphore set is destroyed. All resources consumed by
the semaphore set are freed and the semaphore set
identifier is invalidated.
If an error occurs, the semaphore set remains unchanged.
Access Control
Operation permission depends on the value of cmd as follows:
· If cmd is GETVAL, GETPID, GETNCNT, GETZCNT, GETALL, or
IPC_STAT, the calling process is required to have read access
to the semaphore set.
· If cmd is SETVAL or SETALL, the calling process is required to
have alter access to the semaphore set.
· If cmd is IPC_SET or IPC_RMID, the effective user id of the
calling process must be equal to the semaphore set's user id
(sem_perm.uid), the semaphore set creator's user id
(sem_perm.cuid), or the calling process must have appropriate
privilege. For systems supporting the DG/UX Capability
Option, appropriate privilege is defined as having one or more
specific capabilities enabled in the effective capability set
of the calling process. See capdefaults(5) for the default
capability for this system call.
On systems without the DG/UX Capability Option, appropriate privilege
means that the process has an effective UID of root. See the
appropriateprivilege(5) man page for more information.
Return Value
The value returned may be the following regardless of the value of
cmd:
-1 An error occurred. errno is set to indicate the
error.
If cmd is GETVAL, the value returned may be the following:
semaphorevalue Completed successfully. The specified semaphore's
value is returned.
If cmd is GETPID, the value returned may be the following:
processid Completed successfully. The process id of the last
process to perform an operation on the specified
semaphore is returned.
If cmd is GETNCNT, the value returned may be the following:
processidcount Completed successfully. The number of processes
waiting for the value of the specified semaphore to
increase is returned.
If cmd is GETZCNT, the value returned may be the following:
processidcount Completed successfully. The number of processes
waiting for the value of the specified semaphore to
become zero is returned.
If cmd is SETVAL, GETALL, SETALL, IPC_STAT, IPC_SET, or IPC_RMID, the
value returned may be the following:
0 Completed successfully.
DIAGNOSTICS
Errno may be set to one of the following error code regardless of the
value of cmd:
EINVAL Semid is not a valid semaphore set identifier, or cmd is
invalid.
If cmd is GETVAL, GETPID, GETNCNT, or GETZCNT, errno may be set to
one of these values:
EINVAL Semnum is less than zero, or is greater than or equal to
the number of semaphores in the semaphore set identified by
semid.
EACCES Read permission is denied to the calling process.
If cmd is SETVAL, errno may be set to one of the following:
EINVAL Semaphore is less than zero, or is greater or equal to the
number of semaphores in the semaphore set identified by
semid.
EACCES Alter permission is denied to the calling process.
ERANGE arg.val, the value to which the selected semaphore is to be
set, is greater than the system-imposed maximum.
If cmd is GETALL, errno may be set to one of these values:
EACCES Read permission is denied to the calling process.
EFAULT Argument.array points to an illegal address.
If cmd is SETALL, errno may be set to one of these values:
EACCES Alter permission is denied to the calling process.
ERANGE The value to which one of the semaphores is to be set is
greater than the system-imposed maximum.
EFAULT Argument.array points to an illegal address.
If cmd is IPC_STAT, errno may be set to one of these values:
EACCES Read permission is denied to the calling process.
EFAULT Argument.buf points to an illegal address.
If cmd is IPC_SET, errno may be set to one of these values:
EPERM Permission to change the semaphore set attributes is denied
to the calling process.
EFAULT Argument.buf points to an illegal address.
If cmd is IPC_RMID, errno may be set to this value:
EPERM Permission to remove the semaphore set is denied to the
calling process.
SEE ALSO
intro(2), ipcrm(1), ipcs(1), semget(2), semop(2),
appropriateprivilege(5).
capdefaults(5).
Licensed material--property of copyright holder(s)