path: root/usr/src/man/man2/semop.2

'\" te
.\" Copyright 1989 AT&T.
.\" Copyright (c) 2006, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SEMOP 2 "May 12, 2006"
.SH NAME
semop, semtimedop \- semaphore operations
.SH SYNOPSIS
.LP
.nf
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>

\fBint\fR \fBsemop\fR(\fBint\fR \fIsemid\fR, \fBstruct sembuf *\fR\fIsops\fR, \fBsize_t\fR \fInsops\fR);
.fi

.LP
.nf
\fBint\fR \fBsemtimedop\fR(\fBint\fR \fIsemid\fR, \fBstruct sembuf *\fR\fIsops\fR, \fBsize_t\fR \fInsops\fR,
     \fBconst struct timespec *\fR\fItimeout\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsemop()\fR function is used to perform atomically an array of semaphore
operations on the set of semaphores associated with the semaphore identifier
specified by \fIsemid\fR. The \fIsops\fR argument is a pointer to the array of
semaphore-operation structures. The \fInsops\fR argument is the number of such
structures in the array.
.sp
.LP
Each \fBsembuf\fR structure contains the following members:
.sp
.in +2
.nf
short	sem_num;	  /* semaphore number */
short	sem_op;	  /* semaphore operation */
short	sem_flg;	  /* operation flags */
.fi
.in -2

.sp
.LP
Each semaphore operation specified by \fBsem_op\fR is performed on the
corresponding semaphore specified by \fIsemid\fR and \fBsem_num\fR. The
permission required for a semaphore operation is given as {\fItoken\fR}, where
\fItoken\fR is the type of permission needed.  The types of permission are
interpreted as follows:
.sp
.in +2
.nf
00400    READ by user
00200    ALTER by user
00040    READ by group
00020    ALTER by group
00004    READ by others
00002    ALTER by others
.fi
.in -2

.sp
.LP
See the \fBSemaphore Operation Permissions\fR section of \fBIntro\fR(2) for
more information.
.sp
.LP
A process maintains a value, \fBsemadj\fR, for each semaphore it modifies. This
value contains the cumulative effect of operations the process has performed on
an individual semaphore with the \fBSEM_UNDO\fR flag set (so that they can be
undone if the process terminates unexpectedly).  The value of \fBsemadj\fR can
affect the behavior of calls to \fBsemop()\fR, \fBsemtimedop()\fR,
\fBexit()\fR, and \fB_exit()\fR (the latter two functions documented on
\fBexit\fR(2)), but is otherwise unobservable. See below for details.
.sp
.LP
The \fBsem_op\fR member specifies one of three semaphore operations:
.RS +4
.TP
1.
The \fBsem_op\fR member is a negative integer; {ALTER}
.RS +4
.TP
.ie t \(bu
.el o
If \fBsemval\fR (see \fBIntro\fR(2)) is greater than or equal to the absolute
value of \fBsem_op\fR, the absolute value of \fBsem_op\fR is subtracted from
\fBsemval\fR. Also, if (\fIsem_flg\fR\fB&SEM_UNDO\fR) is true, the absolute
value of \fBsem_op\fR is added to the calling process's \fBsemadj\fR value (see
\fBexit\fR(2)) for the specified semaphore.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fBsemval\fR is less than the absolute value of \fBsem_op\fR and
(\fIsem_flg\fR\fB&IPC_NOWAIT\fR) is true, \fBsemop()\fR returns immediately.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fBsemval\fR is less than the absolute value of \fBsem_op\fR and
(\fIsem_flg\fR\fB&IPC_NOWAIT\fR) is false, \fBsemop()\fR increments the
\fBsemncnt\fR associated with the specified semaphore and suspends execution of
the calling thread until one of the following conditions occur:
.RS +4
.TP
.ie t \(bu
.el o
The value of \fBsemval\fR becomes greater than or equal to the absolute value
of \fBsem_op\fR. When this occurs, the value of \fBsemncnt\fR associated with
the specified semaphore is decremented, the absolute value of \fBsem_op\fR is
subtracted from \fBsemval\fR and, if (\fIsem_flg\fR\fB&SEM_UNDO\fR) is true,
the absolute value of \fBsem_op\fR is added to the calling process's
\fBsemadj\fR value for the specified semaphore.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fIsemid\fR for which the calling thread is awaiting action is removed from
the system (see \fBsemctl\fR(2)). When this occurs, \fBerrno\fR is set to
\fBEIDRM\fR and \fB\(mi1\fR is returned.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The calling thread receives a signal that is to be caught. When this occurs,
the value of \fBsemncnt\fR associated with the specified semaphore is
decremented, and the calling thread resumes execution in the manner prescribed
in \fBsigaction\fR(2).
.RE
.RE
.RE
.RS +4
.TP
2.
The \fBsem_op\fR member is a positive integer; {ALTER}
.sp
The value of \fBsem_op\fR is added to \fBsemval\fR and, if
(\fIsem_flg\fR\fB&SEM_UNDO\fR) is true, the value of \fBsem_op\fR is subtracted
from the calling process's \fBsemadj\fR value for the specified semaphore.
.RE
.RS +4
.TP
3.
The \fBsem_op\fR member is 0; {READ}
.RS +4
.TP
.ie t \(bu
.el o
If \fBsemval\fR is 0, \fBsemop()\fR returns immediately.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fBsemval\fR is not equal to 0 and (\fIsem_flg\fR\fB&IPC_NOWAIT\fR) is true,
\fBsemop()\fR returns immediately.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fBsemval\fR is not equal to 0 and (\fIsem_flg\fR\fB&IPC_NOWAIT\fR) is
false, \fBsemop()\fR increments the \fBsemzcnt\fR associated with the specified
semaphore and suspends execution of the calling thread until one of the
following occurs:
.RS +4
.TP
.ie t \(bu
.el o
The value of \fBsemval\fR becomes 0, at which time the value of \fBsemzcnt\fR
associated with the specified semaphore is set to 0 and all processes waiting
on \fBsemval\fR to become 0 are awakened.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fIsemid\fR for which the calling thread is awaiting action is removed from
the system. When this occurs, \fBerrno\fR is set to \fBEIDRM\fR and \fB\(mi1\fR
is returned.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The calling thread receives a signal that is to be caught. When this occurs,
the value of \fBsemzcnt\fR associated with the specified semaphore is
decremented, and the calling thread resumes execution in the manner prescribed
in \fBsigaction\fR(2).
.RE
.RE
.RE
.sp
.LP
Upon successful completion, the value of \fBsempid\fR for each semaphore
specified in the array pointed to by \fIsops\fR is set to the process \fBID\fR
of the calling process.
.sp
.LP
The \fBsemtimedop()\fR function behaves as \fBsemop()\fR except when it must
suspend execution of the calling process to complete its operation.  If
\fBsemtimedop()\fR must suspend the calling process after the time interval
specified in \fItimeout\fR expires, or if the timeout expires while the process
is suspended, \fBsemtimedop()\fR returns with an error. If the \fBtimespec\fR
structure pointed to by \fItimeout\fR is zero-valued and \fBsemtimedop()\fR
needs to suspend the calling process to complete the requested operation(s), it
returns immediately with an error. If \fItimeout\fR is the \fINULL\fR pointer,
the behavior of \fBsemtimedop()\fR is identical to that of \fBsemop()\fR.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
returned and \fBerrno\fR is set to indicate the error.
.SH ERRORS
.sp
.LP
The \fBsemop()\fR and \fBsemtimedop()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBE2BIG\fR\fR
.ad
.RS 10n
The \fInsops\fR argument is greater than the system-imposed maximum. See NOTES.
.RE

.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 10n
Operation permission is denied to the calling process (see \fBIntro\fR(2)).
.RE

.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
The operation would result in suspension of the calling process but
(\fIsem_flg\fR\fB&IPC_NOWAIT\fR) is true.
.RE

.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
The \fIsops\fR argument points to an illegal address.
.RE

.sp
.ne 2
.na
\fB\fBEFBIG\fR\fR
.ad
.RS 10n
The value of \fBsem_num\fR is less than 0 or greater than or equal to the
number of semaphores in the set associated with \fIsemid\fR.
.RE

.sp
.ne 2
.na
\fB\fBEIDRM\fR\fR
.ad
.RS 10n
A \fIsemid\fR was removed from the system.
.RE

.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 10n
A signal was received.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fIsemid\fR argument is not a valid semaphore identifier, or the number of
individual semaphores for which the calling process requests a \fBSEM_UNDO\fR
operation would exceed the system-imposed limit. Solaris does not impose a
limit on the number of individual semaphores for which the calling process
requests a \fBSEM_UNDO\fR operation.
.RE

.sp
.ne 2
.na
\fB\fBENOSPC\fR\fR
.ad
.RS 10n
The limit on the number of individual processes requesting a \fBSEM_UNDO\fR
operation would be exceeded. Solaris does not impose a limit on the number of
individual processes requesting an \fBSEM_UNDO\fR operation.
.RE

.sp
.ne 2
.na
\fB\fBERANGE\fR\fR
.ad
.RS 10n
An operation would cause a \fBsemval\fR or a \fBsemadj\fR value to overflow the
system-imposed limit.
.RE

.sp
.LP
The \fBsemtimedop()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
The timeout expired before the requested operation could be completed.
.RE

.sp
.LP
The \fBsemtimedop()\fR function will fail if one of the following is detected:
.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
The \fItimeout\fR argument points to an illegal address.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fItimeout\fR argument specified a \fBtv_sec\fR or \fBtv_nsec\fR value less
than 0, or a \fBtv_nsec\fR value greater than or equal to 1000 million.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	\fBsemop()\fR is Standard.
.TE

.SH SEE ALSO
.sp
.LP
.BR ipcs (1),
.BR Intro (2),
.BR exec (2),
.BR exit (2),
.BR fork (2),
.BR semctl (2),
.BR semget (2),
.BR setrctl (2),
.BR sigaction (2),
.BR attributes (7),
.BR standards (7),
.BR rctladm (8)
.SH NOTES
.sp
.LP
The system-imposed maximum on \fInsops\fR for a semaphore identifier is the
minimum enforced value of the \fBprocess.max-sem-ops\fR resource control of the
creating process at the time \fBsemget\fR(2) was used to allocate the
identifier.
.sp
.LP
See \fBrctladm\fR(8) and \fBsetrctl\fR(2) for information about using resource
controls.