diff options
Diffstat (limited to 'man2/semop.2')
| -rw-r--r-- | man2/semop.2 | 523 |
1 files changed, 0 insertions, 523 deletions
diff --git a/man2/semop.2 b/man2/semop.2 deleted file mode 100644 index 92bfec80a..000000000 --- a/man2/semop.2 +++ /dev/null @@ -1,523 +0,0 @@ -.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" Modified 1996-10-22, Eric S. Raymond <esr@thyrsus.com> -.\" Modified 2002-01-08, Michael Kerrisk <mtk.manpages@gmail.com> -.\" Modified 2003-04-28, Ernie Petrides <petrides@redhat.com> -.\" Modified 2004-05-27, Michael Kerrisk <mtk.manpages@gmail.com> -.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> -.\" Language and formatting clean-ups -.\" Added notes on /proc files -.\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop() -.\" 2007-07-09, mtk, Added an EXAMPLE code segment. -.\" -.TH semop 2 (date) "Linux man-pages (unreleased)" -.SH NAME -semop, semtimedop \- System V semaphore operations -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <sys/sem.h> -.P -.BI "int semop(int " semid ", struct sembuf *" sops ", size_t " nsops ); -.BI "int semtimedop(int " semid ", struct sembuf *" sops ", size_t " nsops , -.BI " const struct timespec *_Nullable " timeout ); -.fi -.P -.RS -4 -Feature Test Macro Requirements for glibc (see -.BR feature_test_macros (7)): -.RE -.P -.BR semtimedop (): -.nf - _GNU_SOURCE -.fi -.SH DESCRIPTION -Each semaphore in a System\ V semaphore set -has the following associated values: -.P -.in +4n -.EX -unsigned short semval; /* semaphore value */ -unsigned short semzcnt; /* # waiting for zero */ -unsigned short semncnt; /* # waiting for increase */ -pid_t sempid; /* PID of process that last - modified the semaphore value */ -.EE -.in -.P -.BR semop () -performs operations on selected semaphores in the set indicated by -.IR semid . -Each of the -.I nsops -elements in the array pointed to by -.I sops -is a structure that -specifies an operation to be performed on a single semaphore. -The elements of this structure are of type -.IR "struct sembuf" , -containing the following members: -.P -.in +4n -.EX -unsigned short sem_num; /* semaphore number */ -short sem_op; /* semaphore operation */ -short sem_flg; /* operation flags */ -.EE -.in -.P -Flags recognized in -.I sem_flg -are -.B IPC_NOWAIT -and -.BR SEM_UNDO . -If an operation specifies -.BR SEM_UNDO , -it will be automatically undone when the process terminates. -.P -The set of operations contained in -.I sops -is performed in -.IR "array order" , -and -.IR atomically , -that is, the operations are performed either as a complete unit, -or not at all. -The behavior of the system call if not all operations can be -performed immediately depends on the presence of the -.B IPC_NOWAIT -flag in the individual -.I sem_flg -fields, as noted below. -.P -Each operation is performed on the -.IR sem_num \-th -semaphore of the semaphore set, where the first semaphore of the set -is numbered 0. -There are three types of operation, distinguished by the value of -.IR sem_op . -.P -If -.I sem_op -is a positive integer, the operation adds this value to -the semaphore value -.RI ( semval ). -Furthermore, if -.B SEM_UNDO -is specified for this operation, the system subtracts the value -.I sem_op -from the semaphore adjustment -.RI ( semadj ) -value for this semaphore. -This operation can always proceed\[em]it never forces a thread to wait. -The calling process must have alter permission on the semaphore set. -.P -If -.I sem_op -is zero, the process must have read permission on the semaphore -set. -This is a "wait-for-zero" operation: if -.I semval -is zero, the operation can immediately proceed. -Otherwise, if -.B IPC_NOWAIT -is specified in -.IR sem_flg , -.BR semop () -fails with -.I errno -set to -.B EAGAIN -(and none of the operations in -.I sops -is performed). -Otherwise, -.I semzcnt -(the count of threads waiting until this semaphore's value becomes zero) -is incremented by one and the thread sleeps until -one of the following occurs: -.IP \[bu] 3 -.I semval -becomes 0, at which time the value of -.I semzcnt -is decremented. -.IP \[bu] -The semaphore set -is removed: -.BR semop () -fails, with -.I errno -set to -.BR EIDRM . -.IP \[bu] -The calling thread catches a signal: -the value of -.I semzcnt -is decremented and -.BR semop () -fails, with -.I errno -set to -.BR EINTR . -.P -If -.I sem_op -is less than zero, the process must have alter permission on the -semaphore set. -If -.I semval -is greater than or equal to the absolute value of -.IR sem_op , -the operation can proceed immediately: -the absolute value of -.I sem_op -is subtracted from -.IR semval , -and, if -.B SEM_UNDO -is specified for this operation, the system adds the absolute value of -.I sem_op -to the semaphore adjustment -.RI ( semadj ) -value for this semaphore. -If the absolute value of -.I sem_op -is greater than -.IR semval , -and -.B IPC_NOWAIT -is specified in -.IR sem_flg , -.BR semop () -fails, with -.I errno -set to -.B EAGAIN -(and none of the operations in -.I sops -is performed). -Otherwise, -.I semncnt -(the counter of threads waiting for this semaphore's value to increase) -is incremented by one and the thread sleeps until -one of the following occurs: -.IP \[bu] 3 -.I semval -becomes greater than or equal to the absolute value of -.IR sem_op : -the operation now proceeds, as described above. -.IP \[bu] -The semaphore set is removed from the system: -.BR semop () -fails, with -.I errno -set to -.BR EIDRM . -.IP \[bu] -The calling thread catches a signal: -the value of -.I semncnt -is decremented and -.BR semop () -fails, with -.I errno -set to -.BR EINTR . -.P -On successful completion, the -.I sempid -value for each semaphore specified in the array pointed to by -.I sops -is set to the caller's process ID. -In addition, the -.I sem_otime -.\" and -.\" .I sem_ctime -is set to the current time. -.SS semtimedop() -.BR semtimedop () -behaves identically to -.BR semop () -except that in those cases where the calling thread would sleep, -the duration of that sleep is limited by the amount of elapsed -time specified by the -.I timespec -structure whose address is passed in the -.I timeout -argument. -(This sleep interval will be rounded up to the system clock granularity, -and kernel scheduling delays mean that the interval -may overrun by a small amount.) -If the specified time limit has been reached, -.BR semtimedop () -fails with -.I errno -set to -.B EAGAIN -(and none of the operations in -.I sops -is performed). -If the -.I timeout -argument is NULL, -then -.BR semtimedop () -behaves exactly like -.BR semop (). -.P -Note that if -.BR semtimedop () -is interrupted by a signal, causing the call to fail with the error -.BR EINTR , -the contents of -.I timeout -are left unchanged. -.SH RETURN VALUE -On success, -.BR semop () -and -.BR semtimedop () -return 0. -On failure, they return \-1, and set -.I errno -to indicate the error. -.SH ERRORS -.TP -.B E2BIG -The argument -.I nsops -is greater than -.BR SEMOPM , -the maximum number of operations allowed per system -call. -.TP -.B EACCES -The calling process does not have the permissions required -to perform the specified semaphore operations, -and does not have the -.B CAP_IPC_OWNER -capability in the user namespace that governs its IPC namespace. -.TP -.B EAGAIN -An operation could not proceed immediately and either -.B IPC_NOWAIT -was specified in -.I sem_flg -or the time limit specified in -.I timeout -expired. -.TP -.B EFAULT -An address specified in either the -.I sops -or the -.I timeout -argument isn't accessible. -.TP -.B EFBIG -For some operation the value of -.I sem_num -is less than 0 or greater than or equal to the number -of semaphores in the set. -.TP -.B EIDRM -The semaphore set was removed. -.TP -.B EINTR -While blocked in this system call, the thread caught a signal; see -.BR signal (7). -.TP -.B EINVAL -The semaphore set doesn't exist, or -.I semid -is less than zero, or -.I nsops -has a nonpositive value. -.TP -.B ENOMEM -The -.I sem_flg -of some operation specified -.B SEM_UNDO -and the system does not have enough memory to allocate the undo -structure. -.TP -.B ERANGE -For some operation -.I sem_op+semval -is greater than -.BR SEMVMX , -the implementation dependent maximum value for -.IR semval . -.SH STANDARDS -POSIX.1-2008. -.SH VERSIONS -Linux 2.5.52 (backported into Linux 2.4.22), -glibc 2.3.3. -POSIX.1-2001, SVr4. -.\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC. -.SH NOTES -The -.I sem_undo -structures of a process aren't inherited by the child produced by -.BR fork (2), -but they are inherited across an -.BR execve (2) -system call. -.P -.BR semop () -is never automatically restarted after being interrupted by a signal handler, -regardless of the setting of the -.B SA_RESTART -flag when establishing a signal handler. -.P -A semaphore adjustment -.RI ( semadj ) -value is a per-process, per-semaphore integer that is the negated sum -of all operations performed on a semaphore specifying the -.B SEM_UNDO -flag. -Each process has a list of -.I semadj -values\[em]one value for each semaphore on which it has operated using -.BR SEM_UNDO . -When a process terminates, each of its per-semaphore -.I semadj -values is added to the corresponding semaphore, -thus undoing the effect of that process's operations on the semaphore -(but see BUGS below). -When a semaphore's value is directly set using the -.B SETVAL -or -.B SETALL -request to -.BR semctl (2), -the corresponding -.I semadj -values in all processes are cleared. -The -.BR clone (2) -.B CLONE_SYSVSEM -flag allows more than one process to share a -.I semadj -list; see -.BR clone (2) -for details. -.P -The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values -for a semaphore can all be retrieved using appropriate -.BR semctl (2) -calls. -.SS Semaphore limits -The following limits on semaphore set resources affect the -.BR semop () -call: -.TP -.B SEMOPM -Maximum number of operations allowed for one -.BR semop () -call. -Before Linux 3.19, -.\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4 -the default value for this limit was 32. -Since Linux 3.19, the default value is 500. -On Linux, this limit can be read and modified via the third field of -.IR /proc/sys/kernel/sem . -.\" This /proc file is not available in Linux 2.2 and earlier -- MTK -.IR Note : -this limit should not be raised above 1000, -.\" See comment in Linux 3.19 source file include/uapi/linux/sem.h -because of the risk of that -.BR semop () -fails due to kernel memory fragmentation when allocating memory to copy the -.I sops -array. -.TP -.B SEMVMX -Maximum allowable value for -.IR semval : -implementation dependent (32767). -.P -The implementation has no intrinsic limits for -the adjust on exit maximum value -.RB ( SEMAEM ), -the system wide maximum number of undo structures -.RB ( SEMMNU ) -and the per-process maximum number of undo entries system parameters. -.SH BUGS -When a process terminates, its set of associated -.I semadj -structures is used to undo the effect of all of the -semaphore operations it performed with the -.B SEM_UNDO -flag. -This raises a difficulty: if one (or more) of these semaphore adjustments -would result in an attempt to decrease a semaphore's value below zero, -what should an implementation do? -One possible approach would be to block until all the semaphore -adjustments could be performed. -This is however undesirable since it could force process termination to -block for arbitrarily long periods. -Another possibility is that such semaphore adjustments could be ignored -altogether (somewhat analogously to failing when -.B IPC_NOWAIT -is specified for a semaphore operation). -Linux adopts a third approach: decreasing the semaphore value -as far as possible (i.e., to zero) and allowing process -termination to proceed immediately. -.P -In Linux 2.6.x, x <= 10, there is a bug that in some circumstances -prevents a thread that is waiting for a semaphore value to become -zero from being woken up when the value does actually become zero. -This bug is fixed in Linux 2.6.11. -.\" The bug report: -.\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2 -.\" the fix: -.\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2 -.SH EXAMPLES -The following code segment uses -.BR semop () -to atomically wait for the value of semaphore 0 to become zero, -and then increment the semaphore value by one. -.P -.in +4n -.EX -struct sembuf sops[2]; -int semid; -\& -/* Code to set \fIsemid\fP omitted */ -\& -sops[0].sem_num = 0; /* Operate on semaphore 0 */ -sops[0].sem_op = 0; /* Wait for value to equal 0 */ -sops[0].sem_flg = 0; -\& -sops[1].sem_num = 0; /* Operate on semaphore 0 */ -sops[1].sem_op = 1; /* Increment value by one */ -sops[1].sem_flg = 0; -\& -if (semop(semid, sops, 2) == \-1) { - perror("semop"); - exit(EXIT_FAILURE); -} -.EE -.in -.P -A further example of the use of -.BR semop () -can be found in -.BR shmop (2). -.SH SEE ALSO -.BR clone (2), -.BR semctl (2), -.BR semget (2), -.BR sigaction (2), -.BR capabilities (7), -.BR sem_overview (7), -.BR sysvipc (7), -.BR time (7) |