summaryrefslogtreecommitdiffstats
path: root/man2/semop.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/semop.2')
-rw-r--r--man2/semop.2523
1 files changed, 0 insertions, 523 deletions
diff --git a/man2/semop.2 b/man2/semop.2
deleted file mode 100644
index b04fe6a..0000000
--- 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 2023-10-31 "Linux man-pages 6.7"
-.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)