| 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) |