Debian Codegraph @

upstream/debian-unstable/man3/sem_wait.3

raw
1 '\" t
2 .\" Copyright 2006, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH sem_wait 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 sem_wait, sem_timedwait, sem_trywait \- lock a semaphore
10 .SH LIBRARY
11 POSIX threads library
12 .RI ( libpthread ,\~ \-lpthread )
13 .SH SYNOPSIS
14 .nf
15 .B #include <semaphore.h>
16 .P
17 .BI "int sem_wait(sem_t *" sem );
18 .BI "int sem_trywait(sem_t *" sem );
19 .BI "int sem_timedwait(sem_t *restrict " sem ,
20 .BI " const struct timespec *restrict " abs_timeout );
21 .fi
22 .P
23 .RS -4
24 Feature Test Macro Requirements for glibc (see
25 .BR feature_test_macros (7)):
26 .RE
27 .P
28 .BR sem_timedwait ():
29 .nf
30 _POSIX_C_SOURCE >= 200112L
31 .fi
32 .SH DESCRIPTION
33 .BR sem_wait ()
34 decrements (locks) the semaphore pointed to by
35 .IR sem .
36 If the semaphore's value is greater than zero,
37 then the decrement proceeds, and the function returns, immediately.
38 If the semaphore currently has the value zero,
39 then the call blocks until either it becomes possible to perform
40 the decrement (i.e., the semaphore value rises above zero),
41 or a signal handler interrupts the call.
42 .P
43 .BR sem_trywait ()
44 is the same as
45 .BR sem_wait (),
46 except that if the decrement cannot be immediately performed,
47 then call returns an error
48 .RI ( errno
49 set to
50 .BR EAGAIN )
51 instead of blocking.
52 .P
53 .BR sem_timedwait ()
54 is the same as
55 .BR sem_wait (),
56 except that
57 .I abs_timeout
58 specifies a limit on the amount of time that the call
59 should block if the decrement cannot be immediately performed.
60 The
61 .I abs_timeout
62 argument points to a
63 .BR timespec (3)
64 structure that specifies an absolute timeout
65 in seconds and nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
66 .P
67 If the timeout has already expired by the time of the call,
68 and the semaphore could not be locked immediately,
69 then
70 .BR sem_timedwait ()
71 fails with a timeout error
72 .RI ( errno
73 set to
74 .BR ETIMEDOUT ).
75 .P
76 If the operation can be performed immediately, then
77 .BR sem_timedwait ()
78 never fails with a timeout error, regardless of the value of
79 .IR abs_timeout .
80 Furthermore, the validity of
81 .I abs_timeout
82 is not checked in this case.
83 .SH RETURN VALUE
84 All of these functions return 0 on success;
85 on error, the value of the semaphore is left unchanged,
86 \-1 is returned, and
87 .I errno
88 is set to indicate the error.
89 .SH ERRORS
90 .TP
91 .B EAGAIN
92 .RB ( sem_trywait ())
93 The operation could not be performed without blocking (i.e., the
94 semaphore currently has the value zero).
95 .TP
96 .B EINTR
97 The call was interrupted by a signal handler;
98 see
99 .BR signal (7).
100 .TP
101 .B EINVAL
102 .I sem
103 is not a valid semaphore.
104 .TP
105 .B EINVAL
106 .RB ( sem_timedwait ())
107 The value of
108 .I abs_timeout.tv_nsecs
109 is less than 0, or greater than or equal to 1000 million.
110 .TP
111 .B ETIMEDOUT
112 .RB ( sem_timedwait ())
113 The call timed out before the semaphore could be locked.
114 .\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition
115 .\" was detected", but this does not occur on Linux(?).
116 .SH ATTRIBUTES
117 For an explanation of the terms used in this section, see
118 .BR attributes (7).
119 .TS
120 allbox;
121 lbx lb lb
122 l l l.
123 Interface Attribute Value
124 T{
125 .na
126 .nh
127 .BR sem_wait (),
128 .BR sem_trywait (),
129 .BR sem_timedwait ()
130 T} Thread safety MT-Safe
131 .TE
132 .SH STANDARDS
133 POSIX.1-2008.
134 .SH HISTORY
135 POSIX.1-2001.
136 .SH EXAMPLES
137 The (somewhat trivial) program shown below operates on an
138 unnamed semaphore.
139 The program expects two command-line arguments.
140 The first argument specifies a seconds value that is used to
141 set an alarm timer to generate a
142 .B SIGALRM
143 signal.
144 This handler performs a
145 .BR sem_post (3)
146 to increment the semaphore that is being waited on in
147 .I main()
148 using
149 .BR sem_timedwait ().
150 The second command-line argument specifies the length
151 of the timeout, in seconds, for
152 .BR sem_timedwait ().
153 The following shows what happens on two different runs of the program:
154 .P
155 .in +4n
156 .EX
157 .RB "$" " ./a.out 2 3"
158 About to call sem_timedwait()
159 sem_post() from handler
160 sem_timedwait() succeeded
161 .RB "$" " ./a.out 2 1"
162 About to call sem_timedwait()
163 sem_timedwait() timed out
164 .EE
165 .in
166 .SS Program source
167 \&
168 .\" SRC BEGIN (sem_wait.c)
169 .EX
170 #include <err.h>
171 #include <errno.h>
172 #include <semaphore.h>
173 #include <signal.h>
174 #include <stdio.h>
175 #include <stdlib.h>
176 #include <time.h>
177 #include <unistd.h>
178 \&
179 #include <assert.h>
180 \&
181 sem_t sem;
182 \&
183 static void
184 handler(int sig)
185 {
186 write(STDOUT_FILENO, "sem_post() from handler\[rs]n", 24);
187 if (sem_post(&sem) == \-1) {
188 write(STDERR_FILENO, "sem_post() failed\[rs]n", 18);
189 _exit(EXIT_FAILURE);
190 }
191 }
192 \&
193 int
194 main(int argc, char *argv[])
195 {
196 struct sigaction sa;
197 struct timespec ts;
198 int s;
199 \&
200 if (argc != 3) {
201 fprintf(stderr, "Usage: %s <alarm\-secs> <wait\-secs>\[rs]n",
202 argv[0]);
203 exit(EXIT_FAILURE);
204 }
205 \&
206 if (sem_init(&sem, 0, 0) == \-1)
207 err(EXIT_FAILURE, "sem_init");
208 \&
209 /* Establish SIGALRM handler; set alarm timer using argv[1]. */
210 \&
211 sa.sa_handler = handler;
212 sigemptyset(&sa.sa_mask);
213 sa.sa_flags = 0;
214 if (sigaction(SIGALRM, &sa, NULL) == \-1)
215 err(EXIT_FAILURE, "sigaction");
216 \&
217 alarm(atoi(argv[1]));
218 \&
219 /* Calculate relative interval as current time plus
220 number of seconds given argv[2]. */
221 \&
222 if (clock_gettime(CLOCK_REALTIME, &ts) == \-1)
223 err(EXIT_FAILURE, "clock_gettime");
224 \&
225 ts.tv_sec += atoi(argv[2]);
226 \&
227 printf("%s() about to call sem_timedwait()\[rs]n", __func__);
228 while ((s = sem_timedwait(&sem, &ts)) == \-1 && errno == EINTR)
229 continue; /* Restart if interrupted by handler. */
230 \&
231 /* Check what happened. */
232 \&
233 if (s == \-1) {
234 if (errno == ETIMEDOUT)
235 printf("sem_timedwait() timed out\[rs]n");
236 else
237 perror("sem_timedwait");
238 } else
239 printf("sem_timedwait() succeeded\[rs]n");
240 \&
241 exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
242 }
243 .EE
244 .\" SRC END
245 .SH SEE ALSO
246 .BR clock_gettime (2),
247 .BR sem_getvalue (3),
248 .BR sem_post (3),
249 .BR timespec (3),
250 .BR sem_overview (7),
251 .BR time (7)