| blob | 3b90139ac85cdf9d901daf8e44dcc6112067f60a |
1 '\" te
2 .\" Copyright 1989 AT&T.
3 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
4 .\" 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.
5 .\" 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.
6 .\" 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]
7 .TH SEMOP 2 "May 12, 2006"
8 .SH NAME
9 semop, semtimedop \- semaphore operations
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <sys/types.h>
14 #include <sys/ipc.h>
15 #include <sys/sem.h>
17 \fBint\fR \fBsemop\fR(\fBint\fR \fIsemid\fR, \fBstruct sembuf *\fR\fIsops\fR, \fBsize_t\fR \fInsops\fR);
18 .fi
20 .LP
21 .nf
22 \fBint\fR \fBsemtimedop\fR(\fBint\fR \fIsemid\fR, \fBstruct sembuf *\fR\fIsops\fR, \fBsize_t\fR \fInsops\fR,
23 \fBconst struct timespec *\fR\fItimeout\fR);
24 .fi
26 .SH DESCRIPTION
27 .sp
28 .LP
29 The \fBsemop()\fR function is used to perform atomically an array of semaphore
30 operations on the set of semaphores associated with the semaphore identifier
31 specified by \fIsemid\fR. The \fIsops\fR argument is a pointer to the array of
32 semaphore-operation structures. The \fInsops\fR argument is the number of such
33 structures in the array.
34 .sp
35 .LP
36 Each \fBsembuf\fR structure contains the following members:
37 .sp
38 .in +2
39 .nf
40 short sem_num; /* semaphore number */
41 short sem_op; /* semaphore operation */
42 short sem_flg; /* operation flags */
43 .fi
44 .in -2
46 .sp
47 .LP
48 Each semaphore operation specified by \fBsem_op\fR is performed on the
49 corresponding semaphore specified by \fIsemid\fR and \fBsem_num\fR. The
50 permission required for a semaphore operation is given as {\fItoken\fR}, where
51 \fItoken\fR is the type of permission needed. The types of permission are
52 interpreted as follows:
53 .sp
54 .in +2
55 .nf
56 00400 READ by user
57 00200 ALTER by user
58 00040 READ by group
59 00020 ALTER by group
60 00004 READ by others
61 00002 ALTER by others
62 .fi
63 .in -2
65 .sp
66 .LP
67 See the \fBSemaphore Operation Permissions\fR section of \fBIntro\fR(2) for
68 more information.
69 .sp
70 .LP
71 A process maintains a value, \fBsemadj\fR, for each semaphore it modifies. This
72 value contains the cumulative effect of operations the process has performed on
73 an individual semaphore with the \fBSEM_UNDO\fR flag set (so that they can be
74 undone if the process terminates unexpectedly). The value of \fBsemadj\fR can
75 affect the behavior of calls to \fBsemop()\fR, \fBsemtimedop()\fR,
76 \fBexit()\fR, and \fB_exit()\fR (the latter two functions documented on
77 \fBexit\fR(2)), but is otherwise unobservable. See below for details.
78 .sp
79 .LP
80 The \fBsem_op\fR member specifies one of three semaphore operations:
81 .RS +4
82 .TP
83 1.
84 The \fBsem_op\fR member is a negative integer; {ALTER}
85 .RS +4
86 .TP
87 .ie t \(bu
88 .el o
89 If \fBsemval\fR (see \fBIntro\fR(2)) is greater than or equal to the absolute
90 value of \fBsem_op\fR, the absolute value of \fBsem_op\fR is subtracted from
91 \fBsemval\fR. Also, if (\fIsem_flg\fR\fB&SEM_UNDO\fR) is true, the absolute
92 value of \fBsem_op\fR is added to the calling process's \fBsemadj\fR value (see
93 \fBexit\fR(2)) for the specified semaphore.
94 .RE
95 .RS +4
96 .TP
97 .ie t \(bu
98 .el o
99 If \fBsemval\fR is less than the absolute value of \fBsem_op\fR and
100 (\fIsem_flg\fR\fB&IPC_NOWAIT\fR) is true, \fBsemop()\fR returns immediately.
101 .RE
102 .RS +4
103 .TP
104 .ie t \(bu
105 .el o
106 If \fBsemval\fR is less than the absolute value of \fBsem_op\fR and
107 (\fIsem_flg\fR\fB&IPC_NOWAIT\fR) is false, \fBsemop()\fR increments the
108 \fBsemncnt\fR associated with the specified semaphore and suspends execution of
109 the calling thread until one of the following conditions occur:
110 .RS +4
111 .TP
112 .ie t \(bu
113 .el o
114 The value of \fBsemval\fR becomes greater than or equal to the absolute value
115 of \fBsem_op\fR. When this occurs, the value of \fBsemncnt\fR associated with
116 the specified semaphore is decremented, the absolute value of \fBsem_op\fR is
117 subtracted from \fBsemval\fR and, if (\fIsem_flg\fR\fB&SEM_UNDO\fR) is true,
118 the absolute value of \fBsem_op\fR is added to the calling process's
119 \fBsemadj\fR value for the specified semaphore.
120 .RE
121 .RS +4
122 .TP
123 .ie t \(bu
124 .el o
125 The \fIsemid\fR for which the calling thread is awaiting action is removed from
126 the system (see \fBsemctl\fR(2)). When this occurs, \fBerrno\fR is set to
127 \fBEIDRM\fR and \fB\(mi1\fR is returned.
128 .RE
129 .RS +4
130 .TP
131 .ie t \(bu
132 .el o
133 The calling thread receives a signal that is to be caught. When this occurs,
134 the value of \fBsemncnt\fR associated with the specified semaphore is
135 decremented, and the calling thread resumes execution in the manner prescribed
136 in \fBsigaction\fR(2).
137 .RE
138 .RE
139 .RE
140 .RS +4
141 .TP
142 2.
143 The \fBsem_op\fR member is a positive integer; {ALTER}
144 .sp
145 The value of \fBsem_op\fR is added to \fBsemval\fR and, if
146 (\fIsem_flg\fR\fB&SEM_UNDO\fR) is true, the value of \fBsem_op\fR is subtracted
147 from the calling process's \fBsemadj\fR value for the specified semaphore.
148 .RE
149 .RS +4
150 .TP
151 3.
152 The \fBsem_op\fR member is 0; {READ}
153 .RS +4
154 .TP
155 .ie t \(bu
156 .el o
157 If \fBsemval\fR is 0, \fBsemop()\fR returns immediately.
158 .RE
159 .RS +4
160 .TP
161 .ie t \(bu
162 .el o
163 If \fBsemval\fR is not equal to 0 and (\fIsem_flg\fR\fB&IPC_NOWAIT\fR) is true,
164 \fBsemop()\fR returns immediately.
165 .RE
166 .RS +4
167 .TP
168 .ie t \(bu
169 .el o
170 If \fBsemval\fR is not equal to 0 and (\fIsem_flg\fR\fB&IPC_NOWAIT\fR) is
171 false, \fBsemop()\fR increments the \fBsemzcnt\fR associated with the specified
172 semaphore and suspends execution of the calling thread until one of the
173 following occurs:
174 .RS +4
175 .TP
176 .ie t \(bu
177 .el o
178 The value of \fBsemval\fR becomes 0, at which time the value of \fBsemzcnt\fR
179 associated with the specified semaphore is set to 0 and all processes waiting
180 on \fBsemval\fR to become 0 are awakened.
181 .RE
182 .RS +4
183 .TP
184 .ie t \(bu
185 .el o
186 The \fIsemid\fR for which the calling thread is awaiting action is removed from
187 the system. When this occurs, \fBerrno\fR is set to \fBEIDRM\fR and \fB\(mi1\fR
188 is returned.
189 .RE
190 .RS +4
191 .TP
192 .ie t \(bu
193 .el o
194 The calling thread receives a signal that is to be caught. When this occurs,
195 the value of \fBsemzcnt\fR associated with the specified semaphore is
196 decremented, and the calling thread resumes execution in the manner prescribed
197 in \fBsigaction\fR(2).
198 .RE
199 .RE
200 .RE
201 .sp
202 .LP
203 Upon successful completion, the value of \fBsempid\fR for each semaphore
204 specified in the array pointed to by \fIsops\fR is set to the process \fBID\fR
205 of the calling process.
206 .sp
207 .LP
208 The \fBsemtimedop()\fR function behaves as \fBsemop()\fR except when it must
209 suspend execution of the calling process to complete its operation. If
210 \fBsemtimedop()\fR must suspend the calling process after the time interval
211 specified in \fItimeout\fR expires, or if the timeout expires while the process
212 is suspended, \fBsemtimedop()\fR returns with an error. If the \fBtimespec\fR
213 structure pointed to by \fItimeout\fR is zero-valued and \fBsemtimedop()\fR
214 needs to suspend the calling process to complete the requested operation(s), it
215 returns immediately with an error. If \fItimeout\fR is the \fINULL\fR pointer,
216 the behavior of \fBsemtimedop()\fR is identical to that of \fBsemop()\fR.
217 .SH RETURN VALUES
218 .sp
219 .LP
220 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
221 returned and \fBerrno\fR is set to indicate the error.
222 .SH ERRORS
223 .sp
224 .LP
225 The \fBsemop()\fR and \fBsemtimedop()\fR functions will fail if:
226 .sp
227 .ne 2
228 .na
229 \fB\fBE2BIG\fR\fR
230 .ad
231 .RS 10n
232 The \fInsops\fR argument is greater than the system-imposed maximum. See NOTES.
233 .RE
235 .sp
236 .ne 2
237 .na
238 \fB\fBEACCES\fR\fR
239 .ad
240 .RS 10n
241 Operation permission is denied to the calling process (see \fBIntro\fR(2)).
242 .RE
244 .sp
245 .ne 2
246 .na
247 \fB\fBEAGAIN\fR\fR
248 .ad
249 .RS 10n
250 The operation would result in suspension of the calling process but
251 (\fIsem_flg\fR\fB&IPC_NOWAIT\fR) is true.
252 .RE
254 .sp
255 .ne 2
256 .na
257 \fB\fBEFAULT\fR\fR
258 .ad
259 .RS 10n
260 The \fIsops\fR argument points to an illegal address.
261 .RE
263 .sp
264 .ne 2
265 .na
266 \fB\fBEFBIG\fR\fR
267 .ad
268 .RS 10n
269 The value of \fBsem_num\fR is less than 0 or greater than or equal to the
270 number of semaphores in the set associated with \fIsemid\fR.
271 .RE
273 .sp
274 .ne 2
275 .na
276 \fB\fBEIDRM\fR\fR
277 .ad
278 .RS 10n
279 A \fIsemid\fR was removed from the system.
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fBEINTR\fR\fR
286 .ad
287 .RS 10n
288 A signal was received.
289 .RE
291 .sp
292 .ne 2
293 .na
294 \fB\fBEINVAL\fR\fR
295 .ad
296 .RS 10n
297 The \fIsemid\fR argument is not a valid semaphore identifier, or the number of
298 individual semaphores for which the calling process requests a \fBSEM_UNDO\fR
299 operation would exceed the system-imposed limit. Solaris does not impose a
300 limit on the number of individual semaphores for which the calling process
301 requests a \fBSEM_UNDO\fR operation.
302 .RE
304 .sp
305 .ne 2
306 .na
307 \fB\fBENOSPC\fR\fR
308 .ad
309 .RS 10n
310 The limit on the number of individual processes requesting a \fBSEM_UNDO\fR
311 operation would be exceeded. Solaris does not impose a limit on the number of
312 individual processes requesting an \fBSEM_UNDO\fR operation.
313 .RE
315 .sp
316 .ne 2
317 .na
318 \fB\fBERANGE\fR\fR
319 .ad
320 .RS 10n
321 An operation would cause a \fBsemval\fR or a \fBsemadj\fR value to overflow the
322 system-imposed limit.
323 .RE
325 .sp
326 .LP
327 The \fBsemtimedop()\fR function will fail if:
328 .sp
329 .ne 2
330 .na
331 \fB\fBEAGAIN\fR\fR
332 .ad
333 .RS 10n
334 The timeout expired before the requested operation could be completed.
335 .RE
337 .sp
338 .LP
339 The \fBsemtimedop()\fR function will fail if one of the following is detected:
340 .sp
341 .ne 2
342 .na
343 \fB\fBEFAULT\fR\fR
344 .ad
345 .RS 10n
346 The \fItimeout\fR argument points to an illegal address.
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fBEINVAL\fR\fR
353 .ad
354 .RS 10n
355 The \fItimeout\fR argument specified a \fBtv_sec\fR or \fBtv_nsec\fR value less
356 than 0, or a \fBtv_nsec\fR value greater than or equal to 1000 million.
357 .RE
359 .SH ATTRIBUTES
360 .sp
361 .LP
362 See \fBattributes\fR(5) for descriptions of the following attributes:
363 .sp
365 .sp
366 .TS
367 box;
368 c | c
369 l | l .
370 ATTRIBUTE TYPE ATTRIBUTE VALUE
371 _
372 Interface Stability \fBsemop()\fR is Standard.
373 .TE
375 .SH SEE ALSO
376 .sp
377 .LP
378 \fBipcs\fR(1), \fBrctladm\fR(8), \fBIntro\fR(2), \fBexec\fR(2), \fBexit\fR(2),
379 \fBfork\fR(2), \fBsemctl\fR(2), \fBsemget\fR(2), \fBsetrctl\fR(2),
380 \fBsigaction\fR(2), \fBattributes\fR(5), \fBstandards\fR(5)
381 .SH NOTES
382 .sp
383 .LP
384 The system-imposed maximum on \fInsops\fR for a semaphore identifier is the
385 minimum enforced value of the \fBprocess.max-sem-ops\fR resource control of the
386 creating process at the time \fBsemget\fR(2) was used to allocate the
387 identifier.
388 .sp
389 .LP
390 See \fBrctladm\fR(8) and \fBsetrctl\fR(2) for information about using resource
391 controls.