[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

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:

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:

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:

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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The semget subroutine, semop subroutine.

[ Previous | Next | Contents | Glossary | Home | Search ]