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.