OSF

NAME

semctl −  Performs semaphore control operations

SYNOPSIS

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h> int semctl(
int semid,
int semnum,
int cmd,
union semun {
int val,
struct semid_ds ∗buf,
u_short ∗array,
} arg );

PARAMETERS

semidSpecifies the ID of the semaphore set. 

semnumSpecifies the number of the semaphore to be processed. 

cmdSpecifies the type of command.  See DESCRIPTION. 

argThe address of a user data structure to be used either to set or to return semaphore values.  If the structure is specified, the calling process must allocate it before making the call.  The members of this structure are described as follows:

valContains the semaphore value to which semval is set when the SETVAL command is performed. 

bufPoints to the structure containing the contents of the requested semid_ds.  When the IPC_STAT command is performed, the contents of the requested semid_ds structure are copied into arg.buf.  When the IPC_SET command is performed, the contents of arg.buf are copied into the requested the semid.ds structure. 

arrayPoints to an array of semval values.  These semval values are returned by the GETALL command and set by the SETALL command. 

DESCRIPTION

The semctl() function allows a process to perform various operations on an individual semaphore within a semaphore set, on all semaphores within a semaphore set, and on the semid_ds structure associated with the semaphore set.  It also allows a process to remove the semaphore set’s ID and its associated semid_ds structure. 

The cmd value determines which operation is performed.  The following commands operate on the specified semaphore (that is, semnum) within the specified semaphore set:

GETVALReturns the value of semval.  This command requires read permission. 

SETVALSets the value of semval to arg.val.  When this command successfully executes, the kernel clears the semaphore’s adjust-on-exit value in all processes.  This command requires modify permission. 

GETPIDReturns the value of sempid.  This command requires read permission. 

GETNCNTReturns the value of semncnt.  This command requires read permission. 

GETZCNTReturns the value of semzcnt.  This command requires read permission. 

The following commands operate on all the semaphores in the semaphore set:

GETALLReturns all the semval values and places them in the array pointed to by arg.array.  This command requires read permission. 

SETALLSets all the semval values according to the array pointed to by arg.array.  When this command successfully executes, the kernel clears the semaphore’s adjust-on-exit value in all processes.  This command requires modify permission. 

The following IPC commands can also be used:

IPC_STATQueries the semaphore ID by copying the contents of its associated semid_ds structure into the structure pointed to by arg.buf.  This command requires read permission. 

IPC_SETSets the semaphore set by copying the user-supplied values found in the arg.buf structure into corresponding fields in the semid_ds structure associated with the semaphore ID.  This is a restricted operation.  The effective user ID of the calling process must have superuser ’ privilege or must be equal to the value of sem_perm.cuid or sem_perm.uid in the structure associated with the semaphore ID.  The fields are set as follows:

       •The sem_perm.uid field is set to the owner’s user ID. 

       •The sem_perm.gid field is set to the owner’s group ID. 

       •The sem_perm.mode field is set to the access modes for the semaphore set.  Only the low-order nine bits are set. 

IPC_RMIDRemoves the semaphore ID and destroys the set of semaphores and the semid_ds data structure associated with it.  This is a restricted operation.  The effective user ID of the calling process must have superuser privilege or equal to the value of sem_perm.cuid or sem_perm.uid in the associated semid_ds structure. 

RETURN VALUE

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

GETVALReturns the value of semval. 

GETPIDReturns the value of sempid. 

GETNCNTReturns the value of semncnt. 

GETZCNTReturns the value of semzcnt. 

All other commands return a value of 0 (zero). 

If the semctl() function fails, a value of -1 is returned and errno is set to indicate the error. 

ERRORS

If the semctl() function fails, errno may be set to one of the following values:

[EINVAL]The semid parameter is not a valid semaphore ID; the value of semnum is less than 0 (zero) or greater than sem_nsems; or cmd is not a valid command. 

[EACCES]The calling process does not have the required permission. 

[ERANGE]The cmd parameter is SETVAL or SETALL and the value to which semval is to be set is greater than the system-defined maximum. 

[EPERM]Either the cmd parameter is equal to IPC_RMID and the effective user ID of the calling process does not have appropriate privilege, or the cmd parameter is equal to IPC_SET and the effective user ID of the calling process is not equal to the value of sem_perm.cuid or sem_perm.uid in the semid_ds structure associated with the semaphore ID. 

[EFAULT]The cmd parameter is IPC_STAT or IPC_SET and an error occurred in accessing the arg structure. 

[ENOMEM]The system does not have enough memory to complete the function. 

RELATED INFORMATION

Functions: semget(2), semop(2)

Data structures: semid_ds(4)