semctl(), semctl64() — Semaphore control operations

Standards

Standards / Extensions	C or C++	Dependencies
XPG4 XPG4.2 Single UNIX Specification, Version 3	both

Format

semctl:

#define _XOPEN_SOURCE
#include <sys/sem.h>

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

semctl64:

#define _LARGE_TIME_API
#define _XOPEN_SOURCE
#include <sys/sem.h>


int semctl64(int semid, int semnum, int cmd, …);

Compile requirement: Use of the semctl64() function requires the long long data type. For more information on how to make the long long data type available, see z/OS XL C/C++ Language Reference.

General description

The semctl()or semctl64() function performs control operations in semaphore set semid as specified by the argument cmd.

Depending on the value of argument cmd, argument semnum may be ignored or identify one specific semaphore number.

The fourth argument is optional and depends upon the operation requested. If required, it is of type union semun, which the application program must explicitly declare:

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

Each semaphore in the semaphore set is represented by the following anonymous data structure:

unsigned short int semval Semaphore value

pid_t sempid Process ID of last operation

unsigned sort int semcnt Number of processes waiting for semval to become greater than current value

unsigned short int semzcnt Number of processes waiting for semval to become zero

When semctl() or semctl64() is used to identify one specific semaphore number for commands GETVAL, SETVAL, GETPID, GETNCNT, and GETZCNT, then references are made to this anonymous data structure for the semaphore semnum.

The following semaphore control operations as specified by argument cmd may be specified. The level of permission required for each operation is shown with each command. These symbolic constants are defined by the <sys/sem.h> header:

GETVAL

Returns the value of semval, if the current process has read permission.

SETVAL

Sets the value of semval to arg.val, where arg is the value of the fourth argument to semctl() or semctl64(). When this command is successfully executed, the semadj value corresponding to the specified semaphore in all processes is cleared. This command requires alter permission. For an __IPC_BINSEM semaphore set the only values that may be set are zero and one.

GETPID

Returns the most recent process to update the semaphore (sempid), if the current process has read permission.

GETNCNT

Returns the number of threads waiting on the semaphore to become greater than the current value, if the current process has read permission.

GETZCNT

Returns the number of threads waiting on the semaphore to become zero, if the current process has read permission. For an __IPC_BINSEM semaphore set this operation will always return a zero; threads are not allowed to wait for the semaphore to become zero in this type of semaphore set.

GETALL

Stores semvals for each semaphore in the semaphore set and place into the array pointed to by arg.array, where arg. is the fourth argument to semctl() or semctl64(). GETALL requires read permission. It is the caller's responsibility to ensure that the storage allocated is large enough to hold the number of semaphore elements. The number of semaphore values stored is sem_nsems, which may be obtained using the IPC_STAT command.

SETALL

Sets semval values for each semaphore in the semaphore set according to the array pointed to by arg.array, where arg is the fourth argument to semctl() or semctl64(). SETALL requires alter permission. Each semval value must be zero or positive. When this command is successfully executed, the semadj values corresponding to each specified semaphore in all processes are cleared. It is the caller's responsibility to ensure that the storage allocated is large enough to hold the number of semaphore elements. The number of semaphore values set is sem_nsems, which may be obtained using the IPC_STAT command. If __IPC_BINSEM was specified on the semget, this option should not be used while there is the possibility of other threads performing semaphore operations on this semaphore, as there may be no serialization while updating the semaphore values; therefore a SETALL will not be allowed after a semop has been done to the __IPC_BINSEM semaphore set. Also, for the __IPC_BINSEM semaphore set, the only values that may be set are zero and one.

IPC_STAT

This command obtains status information for the semaphore identifier specified by semid. This requires read permission. This information is stored in the address specified by the fourth argument defined by data structure semid_ds or semid_ds64.

IPC_SET

Set the value of the sem_perm.uid, sem_perm.gid, and sem_perm.mode in semid_ds or semid_ds64 data structure for the semaphore identifier specified by semid. These values are set to the values found in semid_ds or semid_ds64 structure pointed to by the fourth argument.

Any value for sem_perm.uid and semperm.gid may be set.

Only mode bits defined under semget() function argument semflg may be set in sem_perm.mode.

IPC_RMID

Remove the semaphore identifier specified by argument semid from the system and free the storage for the set of semaphores in the semid_ds or semid_ds64 structure.

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 or semid_ds64 structure associated with semid. For an __IPC_BINSEM semaphore set, it is recommended that all use of semop should be completed before removing the semaphore ID.

The semctl64() function behaves exactly like semctl() except semctl64() uses union semun64 instead of union semun if required to support time beyond 03:14:07 UTC on January 19, 2038. semun64 needs application program's explicit declaration:

union semun64 {
	int val;
	struct semid_ds64 *buf;
	unsigned short *array;
} arg;

Union semun64 uses struct semid_ds64 pointer as its second member instead of struct semid_ds pointer.

Returned value

If successful, the value returned by semctl() or semctl64() depends on the value of the argument cmd as follows:

GETVAL: value of semval is returned
GETPID: value of sempid is returned
GETNCNT: value of semncnt is returned
GETZCNT: value of semzcnt is returned
All others: value of zero is returned

If unsuccessful, semctl() or semctl64() returns -1 and sets errno to one of the following values:

Error Code: Description
EACCES: Operation permission (read or write) is denied to the calling process.
EINVAL: The value of argument semid is not a valid semaphore identifier, or the value of semnum is less than zero or greater than or equal to the number of semaphores in the set, or the argument cmd is not a valid command, or the bits specified for sem_perm.mode are undefined. Note that the valid range of semnum is 0 to (number of semaphores in the set minus 1).
EPERM: The argument cmd has a value of IPC_RMID or IPC_SET and the effective user ID of the caller is not that of a process with appropriate privileges and is not the value of sem_perm.cuid or sem_perm.uid in the semid_ds or semid_ds64 data structure associated with semid.
ERANGE: The argument cmd has a value of SETVAL or SETALL and the semval value to be set exceeds the system limit as defined in <sys/sem.h>.