semctl, semctl64 - semaphore control operations

Syntax

#include <sys/sem.h>

int semctl(int semid, int semnum, int cmd, ...); 

CRTE111A30

int semctl64(int semid, int semnum, int cmd, ...); (End)

Description

semctl() provides a variety of operations for controlling semaphores, as specified by cmd.

cmd is used to specify one of the semaphore control operations listed below; semid and semnum are used to specify the semaphore for which the specified operation is to be performed. The access permissions required for a particular operation are shown under the relevant command (see also section “Interprocess communication” ).

The type of the fourth argument depends on the value of cmd.

The function semctl64() behaves like the function semctl(), except that it uses a semid_ds64 structure instead of a semid_ds structure for the cmd values IPC_STAT and IPC_SET and therefore will work correctly after 01/19/2038 03:14:07 UTC.

The semid_ds contains the following elements:

struct ipc_perm sem_perm;       /* operation permission struct */
struct sem      *sem_base;      /* ptr to first semaphore in set */
ushort_t        sem_nsems;      /* # of semaphores in set */
time_t          sem_otime;      /* last semop time */
time_t          sem_ctime;      /* last change time */

The elements of the structure semid_ds64 structure are defined like the semid_ds structure except for the following components:

time64_t        sem_otime;
time64_t        sem_ctime;

The symbolic names for the values for cmd are defined in the header file sys/sem.h:

GETVAL	Return the value of semval (see also sys/sem.h). Requires read permission.
SETVAL	Set the value of semval to the value of the fourth argument of type int. Upon successful execution of this cmd, the semadj value corresponding to the specified semaphore is cleared in all processes. Requires alter permission (see also section “Interprocess communication”).
GETPID	Return the value of sempid. Requires read permission.
GETNCNT	Return the value of semncnt. Requires read permission.
GETZCNT	Return the value of semzcnt. Requires read permission.

The following commands affect every semval in the set of permissible semaphore:

GETALL	Return the value of semval and place into the array pointed to by arg.array. Requires read permission.
SETALL	Set semval to the value of the array of type unsigned short pointed to by 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 commands are also available:

IPC_STAT	Place the current value of each member of the semid_ds resp. semid_ds64 data structure associated with semid into the semid_ds resp. semid_ds64 structure pointed to by the fourth argument to semctl().
IPC_SET	Set the value of the following members of the semid_ds resp. semid_ds64 data structure associated with semid to the corresponding value found in the semid_ds resp. semid_ds64 structure pointed to by the fourth argument to semctl(): sem_perm.uid sem_perm.gid sem_perm.mode /* only the least-significant 9 bits */ This command may be executed only by a process that has an effective user ID equal to that of a process with appropriate privileges or which matches the value of sem_perm.cuid or sem_perm.uid 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 the data structure associated with it. This command can only be executed by a process that has an effective user ID equal to that of a process with appropriate privileges or which matches the value of sem_perm.cuid or sem_perm.uid in the data structure associated with semid.

Return val.

If successful, semctl() and semctl64() return one of the values below, which depends on cmd as follows:

Value of semval 

if GETVAL was specified for cmd.

Value of sempid 

if GETPID was specified for cmd.

Value of semcnt 

if GETCNT was specified for cmd.

Value of semzcnt 

if GETZCNT was specified for cmd.

0

if other cmd values were specified.

-1

if unsuccessful. errno is set to indicate the error.

Errors

semctl() and semctl64() will fail if:

EACCES

The calling process does not have the required access permission for the command to be executed (see section “Interprocess communication”).

Extension

EFAULT

msgp points to an invalid address. (End)

EINVAL

semid is not a valid semaphore ID, semnum has a value less than 0 or greater
than sem_nsems, or cmd is not a valid command.

EPERM

cmd is equal to IPC_RMID or IPC_SET and the effective user ID of the calling process is not that of a process with appropriate privileges and does not match sem_perm.cuid or sem_perm.uid in the data structure associated with semid.

ERANGE

cmd is equal to SETVAL or SETALL and the value to which semval is to be set exceeds the highest value permitted in the system.

semctl() will fail if: 
Extension

 

EOVERFLOW

cmd is equal to IPC_SET and a timestamp is too large for a time-t component (this will happen after 01/19/2038 03:14:07 a.m. UTC). (End)

semctl64() will fail if:

 

EINVAL

POSIX-BC correction status < A47.

Notes

The fourth argument in the "Syntax" section is identified in XPG4 as ... in order to avoid a clash with the ISO C standard. The fourth argument can be defined by the application programmer as follows:

union semun 
{  int val;
   struct semid_ds *buf;
   unsigned short *array;
} arg;

See also

semget(), semop(), sys/sem.h, section “Interprocess communication”.