[ 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:
- Maximum number of semaphore IDs is
4096 for AIX
releases before 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 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:
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 ]