SEMCTL


Perform the control operation specified by esi on the semaphore set identified by ecx, or on the nth semaphore of that set specified by edx. (The semaphores in a set are numbered starting at 0.)

Arguments

ecx Semaphore set ID.
edx Index (null based) of a semaphore within the semaphore set.
esi Control operation to perform. It should be one of the following values:
IPC_RMID Immediately remove the semaphore set, awakening all processes blocked in SEMOP calls on the set (with an errno -EIDRM). The effective user ID of the calling process must match the creator or owner of the semaphore set, or the caller must be privileged.
edi
should point to a null integer. edx is ignored.
IPC_SET Write the values of some members of the semid_ds structure pointed to by the pinter pointed by edi to the kernel data structure associated with this semaphore set, updating also its sem_ctime member. The following members of the structure are updated: sem_perm.uid, sem_perm.gid, and (the least significant 9 bits of) sem_perm.mode. The effective UID of the calling process must match the owner (sem_perm.uid) or creator (sem_perm.cuid) of the semaphore set, or the caller must be privileged. The argument in edx is ignored.
IPC_STAT Copy information from the kernel data structure associated with argument in ecx into the semid_ds structure pointed by the pointer pointed by edi. The argument in edx is ignored. The calling process must have read permission on the semaphore set.
IPC_INFO Returns information about system-wide semaphore limits and parameters in the seminfo structure pointed to by pointer pointed by edi:

struc seminfo
{
.semmap rd 1 ; # of entries in semaphore map; unused.
.semmni rd 1 ; Max. # of semaphore sets.
.semmns rd 1 ; Max. # of semaphores in all semaphore sets.
.semmnu rd 1 ; System-wide max. # of undo structures; unused.
.semmsl rd 1 ; Max. # of semaphores in a set.
.semopm rd 1 ; Max. # of operations for SEMOP.
.semume rd 1 ; Max. # of undo entries per process; unused.
.semusz rd 1 ; Size of struct sem_undo.
.semvmx rd 1 ; Maximum semaphore value.
.semaem rd 1 ; Max. value that can be recorded for semaphore adjustment (SEM_UNDO).
}

The semmsl, semmns, semopm, and semmni settings can be changed via /proc/sys/kernel/sem.
SEM_STAT Returns a semid_ds structure as for IPC_STAT. However, the semid argument is not a semaphore identifier, but instead an index into the kernel's internal array that maintains information about all semaphore sets on the system.
SEM_INFO Returns a seminfo structure containing the same information as for IPC_INFO, except that the following fields are returned with information about system resources consumed by semaphores: the semusz field returns the number of semaphore sets that currently exist on the system; and the semaem field returns the total number of semaphores in all semaphore sets on the system.
GETPID The system call returns the value of sempid for the nth semaphore of the set specified by edx (i.e. the PID of the process that executed the last SEMOP call for the nth semaphore of the set). The calling process must have read permission on the semaphore set.
GETVAL The system call returns the value of semval for the nth semaphore of the set specified by edx. The calling process must have read permission on the semaphore set.
GETALL Return semval (i.e., the current value) for all semaphores of the set into semun.array. The argument in edx is ignored. The calling process must have read permission on the semaphore set.
GETNCNT The system call returns the value of semncnt (i.e., the number of processes waiting for the value of this semaphore to increase) for the nth semaphore of the set specified by edx (i.e. the number of processes waiting for an increase of semval for the nth semaphore of the set). The calling process must have read permission on the semaphore set.
GETZCNT The system call returns the value of semzcnt (i.e., the number of processes waiting for the value of this semaphore to become zero) for the nth semaphore of the set specified by edx (i.e. the number of processes waiting for semval of the nth semaphore of the set to become 0). The calling process must have read permission on the semaphore set.
SETVAL Set the value of semval to semun.val for the nth semaphore of the set specified by edx, updating also the sem_ctime member of the semid_ds structure associated with the set. Undo entries are cleared for altered semaphores in all processes. If the changes to semaphore values would permit blocked SEMOP calls in other processes to proceed, then those processes are woken up. The calling process must have alter permission on the semaphore set.
SETALL Set semval for all semaphores of the set using the array pointed by the pointer pointed by edi, updating also the sem_ctime member of the semid_ds structure associated with the set. Undo entries (see SEMOP) are cleared for altered semaphores in all processes. If the changes to semaphore values would permit blocked SEMOP calls in other processes to proceed, then those processes are woken up. The argument in edx is ignored. The calling process must have alter (write) permission on the semaphore set.
edi Value of this argument depends on the command used (esi) and may be either ignored or contain a pointer to one of the following strcutres/arrays:
For GETALL,
or SETALL
edi points to a pointer to an array of word values.
For SETVAL edi points to a pointer to an integer value.
For IPC_STAT,
or IPC_SET
edi points to a pointer to a semid_ds structure:
struc semid_ds
{
.sem_perm         ipc_perm ; Permissions.
.sem_otime        rd 1 ; Last SEMOP time.
.sem_ctime        rd 1 ; Last change time.
.sem_base         rd 1 ; Pointer to a sem structure specifing first semaphore in array.
.sem_pending      rd 1 ; Pointer to a sem_queue structure specifing pending operations to be processed.
.sem_pending_last rd 1 ; Pointer to a pointer to a sem_queue structure specifing last pending operation.
.undo             rd 1 ; Pointer to a sem_undo structure specifing undo requests on this array.
.sem_nsems        rw 1 ; Number of semaphores in array.
}

Where ipc_perm, sem, sem_queue, and sem_undo defined as follows:

struc ipc_perm
{
.key  rd 1 ; Key supplied to SEMGET.
.uid  rw 1 ; Effective UID of owner.
.gid  rw 1 ; Effective GID of owner.
.cuid rw 1 ; Effective UID of creator.
.cgid rw 1 ; Effective GID of creator.
.mode rw 1 ; Permissions.
.seq  rw 1 ; Sequence number.
}

struc sem
{
.semval rd 1 ; Current value.
.sempid rd 1 ; PID of last operation.
}

struc sem_undo
{
.proc_next rd 1 ; Pointer to a sem_undo structure identifying next entry on this process.
.id_next   rd 1 ; Pointer to a sem_undo structure identifying next entry on this semaphore set.
.semid     rd 1 ; Semaphore set identifier.
.semadj    rd 1 ; Pointer to an array of adjustments, one per semaphore.
}

struc sem_queue
{
next    rd 1 ; Pointer to a sem_queue structure identifying next entry in the queue.
prev    rd 1 ; Pointer to a pointer to a sem_queue structure identifying previous entry in the queue.
sleeper rd 1 ; Pointer to a task_struct (*to be documented*).
undo    rd 1 ; Pointer to a sem_undo structure.
pid     rd 1 ; Process id of requesting process.
status  rd 1 ; Completion status of operation.
sma     rd 1 ; Pointer to a sem_array structure identifying semaphore array for operations (see below).
id      rd 1 ; Internal sem ID.
sops    rd 1 ; Pointer to a sembuf structure identifying array of pending operations (see below).
nsops   rd 1 ; Number of operations.
alter   rd 1 ; Specifies whether the operation alters the array or not.
}


struc sembuf
{
sem_num rw 1 ; Semaphore index in array.
sem_op  rw 1 ; Semaphore operation.
sem_flg rw 1 ; Operation flags.
ends

struc sem_array
{
.sem_perm         kern_ipc_perm ; Permissions (see below)
.sem_id           rd 1 ;
.sem_otime        rd 1 ; Last SEMOP time.
.sem_ctime        rd 1 ; Last change time.
.sem_base         rd 1 ; Pointer to a sem structure identifying first semaphore in the array.
.sem_pending      rd 1 ; Pointer to a sem_queue structure identifying pending operations to be processed.
.sem_pending_last rd 1 ; Pointer to a pointer to a sem_queue structure identifying last pending operation.
.undo             rd 1 ; Pointer to a sem_undo structure identifying undo requests on this array.
.sem_nsems        rd 1 ; Number of semaphores in array.
}

struc kern_ipc_perm
{
.lock     spinlock_t
.deleted  rd 1
.key      rd 1
.uid      rd 1
.gid      rd 1
.cuid     rd 1
.cgid     rd 1
.mode     rw 1
.seq      rd 1
.security rd 1
}

struc spinlock_t
{
raw_lock raw_spinlock_t
        match =1 =1, CONFIG_PREEMPT CONFIG_SMP
        {
        .break_lock rd 1
        }
        match =1, CONFIG_DEBUG_SPINLOCK
        {
        .magic     rd 1
        .owner_cpu rd 1
        .owner     rd 1
        }
}

Return values

If the function succeeds the return value depends on the command used and may be one of the following:

GETNCNT The value of semncnt.
GETPID The value of semncnt.
GETVAL The value of semval.
GETZCNT The value of semzcnt.
IPC_INFO The index of the highest used entry in the kernel's internal array recording information about all semaphore sets. (This information can be used with repeated SEM_STAT operations to obtain information about all semaphore sets on the system.)
SEM_INFO As for IPC_INFO.
SEM_STAT The identifier of the semaphore set whose index was given in ecx.

If the function fails the return value is one of the following errno values:

-EACCES The argument in esi has one of the values GETALL, GETPID, GETVAL, GETNCNT, GETZCNT, IPC_STAT, SEM_STAT, SETALL, or SETVAL and the calling process does not have the required permissions on the semaphore set and does not have the CAP_IPC_OWNER capability.
-EFAULT The address pointed to by edi or by value pointed by edi isn't accessible.
-EIDRM The semaphore set was removed.
-EINVAL Invalid value for esi or ecx. Or: for a SEM_STAT operation, the index value specified in ecx referred to an array slot that is currently unused.
-EPERM The argument in esi has the value IPC_SET or IPC_RMID but the effective user ID of the calling process is not the creator (as found in sem_perm.cuid) or the owner (as found in sem_perm.uid) of the semaphore set, and the process does not have the CAP_SYS_ADMIN capability.
-ERANGE The argument in esi has the value SETALL or SETVAL and the value to which semval is to be set (for some semaphore of the set) is less than 0 or greater than the implementation limit SEMVMX.

Remarks

The IPC_INFO, SEM_STAT and SEM_INFO operations are used by the ipcs program to provide information on allocated resources. In the future these may modified or moved to a /proc file system interface.

The following system limit on semaphore sets affects a SEMCTL call: SEMVMX - Maximum value for semval: 32767.

See /samples/ipc/semaphore.asm for an example.