semctl Subroutine

Purpose

Controls semaphore operations.

Library

Standard C Library (libc.a)

Syntax

#include <sys/sem.h> int semctl (SemaphoreID, SemaphoreNumber, Command, arg) OR int semctl (SemaphoreID, SemaphoreNumber, Command) int SemaphoreID; int SemaphoreNumber; int Command; union semun { int val; struct semid_ds *buf; unsigned short *array; } arg;

If the fourth argument is required for the operation requested, it must be of type union semun and explicitly declared as shown above.

Description

The semctl subroutine performs a variety of semaphore control operations as specified by the Command parameter.

The following limits apply to semaphores:

Maximum number of semaphore IDs is 4096 for operating system releases before AIX® 4.3.2 and 131072 for AIX 4.3.2 and following.
Maximum number of semaphores per ID is 65,535.
Maximum number of operations per call by the semop (semop and semtimedop Subroutines) subroutine is 1024.
Maximum number of undo entries per procedure is 1024.
Maximum semaphore value is 32,767.
Maximum adjust-on-exit value is 16,384.

Parameters

SemaphoreID

Specifies the semaphore identifier.

SemaphoreNumber

Specifies the semaphore number.

arg.val

Specifies the value for the semaphore for the SETVAL command.

arg.buf

Specifies the buffer for status information for the IPC_STAT and IPC_SET commands.

arg.array

Specifies the values for all the semaphores in a set for the GETALL and SETALL commands.

Command

Specifies semaphore control operations.

The following Command parameter values are executed with respect to the semaphore specified by the SemaphoreID and SemaphoreNumber parameters. These operations get and set the values of a sem structure, which is defined in the sys/sem.h file.

GETVAL: Returns the semval value, if the current process has read permission.
SETVAL: Sets the semval value to the value specified by the arg.val parameter, if the current process has write permission. When this Command parameter is successfully executed, the semadj value corresponding to the specified semaphore is cleared in all processes.
GETPID: Returns the value of the sempid field, if the current process has read permission.
GETNCNT: Returns the value of the semncnt field, if the current process has read permission.
GETZCNT: Returns the value of the semzcnt field, if the current process has read permission.

The following Command parameter values return and set every semval value in the set of semaphores. These operations get and set the values of a sem structure, which is defined in the sys/sem.h file.

GETALL: Stores semvals values into the array pointed to by the arg.array parameter, if the current process has read permission.
SETALL: Sets semvals values according to the array pointed to by the arg.array parameter, if the current process has write permission. When this Command parameter is successfully executed, the semadj value corresponding to each specified semaphore is cleared in all processes.

The following Commands parameter values get and set the values of a semid_ds structure, defined in the sys/sem.h file. These operations get and set the values of a sem structure, which is defined in the sys/sem.h file.

IPC_STAT

Obtains status information about the semaphore identified by the SemaphoreID parameter. This information is stored in the area pointed to by the arg.buf parameter.

IPC_SET

Sets the owning user and group IDs, and the access permissions for the set of semaphores associated with the SemaphoreID parameter. The IPC_SET operation uses as input the values found in the arg.buf parameter structure.

IPC_SET sets the following fields:

Item	Description
sem_perm.uid	User ID of the owner
sem_perm.gid	Group ID of the owner
sem_perm.mode	Permission bits only
sem_perm.cuid	Creator's user ID

IPC_SET can only be executed by a process that has root user authority or an effective user ID equal to the value of the sem_perm.uid or sem_perm.cuid field in the data structure associated with the SemaphoreID parameter.

IPC_RMID

Removes the semaphore identifier specified by the SemaphoreID parameter from the system and destroys the set of semaphores and data structures associated with it. This Command parameter can only be executed by a process that has root user authority or an effective user ID equal to the value of the sem_perm.uid or sem_perm.cuid field in the data structure associated with the SemaphoreID parameter.

Return Values

Upon successful completion, the value returned depends on the Command parameter as follows:

Command	Return Value
GETVAL	Returns the value of the `semval` field.
GETPID	Returns the value of the `sempid` field.
GETNCNT	Returns the value of the `semncnt` field.
GETZCNT	Returns the value of the `semzcnt` field.
All Others	Return a value of 0.

If the semctl subroutine is unsuccessful, a value of -1 is returned and the global variable errno is set to indicate the error.

Error Codes

The semctl subroutine is unsuccessful if any of the following is true:

Item	Description
EINVAL	The SemaphoreID parameter is not a valid semaphore identifier.
EINVAL	The SemaphoreNumber parameter is less than 0 or greater than or equal to the sem_nsems value.
EINVAL	The Command parameter is not a valid command.
EACCES	The calling process is denied permission for the specified operation.
ERANGE	The Command parameter is equal to the SETVAL or SETALL value and the value to which semval value is to be set is greater than the system-imposed maximum.
EPERM	The Command parameter is equal to the IPC_RMID or IPC_SET value and the calling process does not have root user authority or an effective user ID equal to the value of the `sem_perm.uid` or `sem_perm.cuid` field in the data structure associated with the SemaphoreID parameter.
EFAULT	The arg.buf or arg.array parameter points outside of the allocated address space of the process.
ENOMEM	The system does not have enough memory to complete the subroutine.