diff options
Diffstat (limited to 'man2/semop.2')
| -rw-r--r-- | man2/semop.2 | 453 |
1 files changed, 453 insertions, 0 deletions
diff --git a/man2/semop.2 b/man2/semop.2 new file mode 100644 index 000000000..2b80f3ab2 --- /dev/null +++ b/man2/semop.2 @@ -0,0 +1,453 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified 1996-10-22, Eric S. Raymond <esr@thyrsus.com> +.\" Modified 2002-01-08, Michael Kerrisk <mtk16@ext.canterbury.ac.nz> +.\" Modified 2003-04-28, Ernie Petrides <petrides@redhat.com> +.\" Modified 2004-05-27, Michael Kerrisk <mtk16@ext.canterbury.ac.nz> +.\" +.TH SEMOP 2 2003-04-28 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +semop, semtimedop \- semaphore operations +.SH SYNOPSIS +.nf +.B +#include <sys/types.h> +.B +#include <sys/ipc.h> +.B +#include <sys/sem.h> +.fi +.sp +.BI "int semop(int " semid , +.BI "struct sembuf *" sops , +.BI "unsigned " nsops ); +.sp +.BI "int semtimedop(int " semid , +.BI "struct sembuf *" sops , +.BI "unsigned " nsops , +.BI "struct timespec *" timeout ); +.SH DESCRIPTION +A semaphore is represented by an anonymous structure +including the following members: +.sp +.in +4n +.nf +unsigned short semval; /* semaphore value */ +unsigned short semzcnt; /* # waiting for zero */ +unsigned short semncnt; /* # waiting for increase */ +pid_t sempid; /* process that did last op */ +.sp +.in -4n +.fi +The function +.B semop +performs operations on selected members of the semaphore set indicated by +.IR semid . +Each of the +.I nsops +elements in the array pointed to by +.I sops +specifies an operation to be performed on a semaphore by a +.B "struct sembuf" +including the following members: +.sp +.in +4n +.nf +unsigned short sem_num; /* semaphore number */ +short sem_op; /* semaphore operation */ +short sem_flg; /* operation flags */ +.sp +.in -4n +.fi +Flags recognized in +.I sem_flg +are +.B IPC_NOWAIT +and +.BR SEM_UNDO . +If an operation asserts +.BR SEM_UNDO , +it will be undone when the process exits. +.PP +The set of operations contained in +.I sops +is performed +.IR atomically , +that is, the operations are performed at the same time, and only +if they can all be simultaneously performed. +The behaviour 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. + +Each operation is performed on the +.IR sem_num \-th +semaphore of the semaphore set, where the first semaphore of the set +is semaphore +.BR 0 . +There are three types of operation, distinguished by the value of +.IR sem_op . +.PP +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 asserted for this operation, the system updates the process undo count +.RI ( semadj ) +for this semaphore. +This operation can always proceed \- it never forces a process to wait. +The calling process must have alter permission on the semaphore set. +.PP +If +.I sem_op +is zero, the process must have read access 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 asserted in +.IR sem_flg , +the system call fails with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +Otherwise +.I semzcnt +(the count of processes waiting until this semaphore's value becomes zero) +is incremented by one and the process sleeps until +one of the following occurs: +.IP \(bu +.I semval +becomes 0, at which time the value of +.I semzcnt +is decremented. +.IP \(bu +The semaphore set +is removed: the system call fails, with +.I errno +set to +.BR EIDRM . +.IP \(bu +The calling process catches a signal: +the value of +.I semzcnt +is decremented and the system call fails, with +.I errno +set to +.BR EINTR . +.IP \(bu +The time limit specified by +.I timeout +in a +.B semtimedop +call expires: the system call fails, with +.I errno +set to +.BR EAGAIN . +.PP +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 asserted for this operation, the system updates the process undo count +.RI ( semadj ) +for this semaphore. +If the absolute value of +.I sem_op +is greater than +.IR semval , +and +.B IPC_NOWAIT +is asserted in +.IR sem_flg , +the system call fails, with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +Otherwise +.I semncnt +(the counter of processes waiting for this semaphore's value to increase) +is incremented by one and the process sleeps until +one of the following occurs: +.IP \(bu +.I semval +becomes greater than or equal to the absolute value of +.IR sem_op , +at which time the value of +.I semncnt +is decremented, the absolute value of +.I sem_op +is subtracted from +.I semval +and, if +.B SEM_UNDO +is asserted for this operation, the system updates the process undo count +.RI ( semadj ) +for this semaphore. +.IP \(bu +The semaphore set is removed from the system: the system call fails with +.I errno +set to +.BR EIDRM . +.IP \(bu +The calling process catches a signal: +the value of +.I semncnt +is decremented and the system call fails with +.I errno +set to +.BR EINTR . +.IP \(bu +The time limit specified by +.I timeout +in a +.B semtimedop +call expires: the system call fails, with +.I errno +set to +.BR EAGAIN . +.PP +On successful completion, the +.I sempid +value for each semaphore specified in the array pointed to by +.I sops +is set to the process ID of the calling process. +In addition, the +.I sem_otime +.\" and +.\" .I sem_ctime +is set to the current time. +.PP +The function +.B semtimedop +behaves identically to the function +.B semop +except that in those cases were the calling process would sleep, +the duration of that sleep is limited by the amount of elapsed +time specified by the +.B timespec +structure whose address is passed in the +.I timeout +parameter. If the specified time limit has been reached, +the system call fails with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +If the +.I timeout +parameter is +.BR NULL , +then +.B semtimedop +behaves exactly like +.BR semop . +.SH "RETURN VALUE" +If successful the system call returns +.BR 0 , +otherwise it returns +.B \-1 +with +.I errno +indicating the error. +.SH ERRORS +On failure, +.I errno +is set to one of the following: +.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. +.TP +.B EAGAIN +An operation could not proceed immediately and either +.BR IPC_NOWAIT +was asserted in its +.I sem_flg +or the time limit specified in +.I timeout +expired. +.TP +.B EFAULT +An address specified in either the +.I sops +or +.I timeout +parameters 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 process caught a signal. +.TP +.B EINVAL +The semaphore set doesn't exist, or +.I semid +is less than zero, or +.I nsops +has a non-positive value. +.TP +.B ENOMEM +The +.I sem_flg +of some operation asserted +.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 NOTES +The +.I sem_undo +structures of a process aren't inherited across a +.BR fork (2) +system call, but they are inherited across a +.BR execve (2) +system call. +.PP +.B semop +is never automatically restarted after being interrupted by a signal handler, +regardless of the setting of the +.B SA_RESTART +flags when establishing a signal handler. +.PP +.I semadj +is a per\-process integer which is simply the (negative) count +of all semaphore operations performed specifying the +.B SEM_UNDO +flag. +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. +.PP +The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values +for a semaphore can all be retrieved using appropriate +.BR semctl (2) +calls. +.PP +The followings are limits on semaphore set resources affecting a +.B semop +call: +.TP +.B SEMOPM +Maximum number of operations allowed for one +.B semop +call (32). +.TP +.B SEMVMX +Maximum allowable value for +.IR semval : +implementation dependent (32767). +.PP +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. +.SH "CONFORMING TO" +SVr4, SVID. SVr4 documents additional error conditions EINVAL, EFBIG, +ENOSPC. +.SH "SEE ALSO" +.BR semctl (2), +.BR semget (2), +.BR sigaction (2), +.BR ipc (5), +.BR capabilities (7) |