1SEM_WAIT(3) Linux Programmer's Manual SEM_WAIT(3)
2
3
4
6 sem_wait - lock a semaphore
7
9 #include <semaphore.h>
10
11 int sem_wait(sem_t *sem);
12 int sem_trywait(sem_t *sem);
13
14 #define _XOPEN_SOURCE 600
15 #include <semaphore.h>
16
17 int sem_timedwait(sem_t *sem, const struct timespec *abs_timeout);
18
20 sem_wait() decrements (locks) the semaphore pointed to by sem. If the
21 semaphore's value is greater than zero, then the decrement proceeds,
22 and the function returns, immediately. If the semaphore currently has
23 the value zero, then the call blocks until either it becomes possible
24 to perform the decrement (i.e., the semaphore value rises above zero),
25 or a signal handler interrupts the call.
26
27 sem_trywait() is the same as sem_wait(), except that if the decrement
28 cannot be immediately performed, then call returns an error (errno set
29 to EAGAIN) instead of blocking.
30
31 sem_timedwait() is the same as sem_wait(), except that abs_timeout
32 specifies a limit on the amount of time that the call should block if
33 the decrement cannot be immediately performed. The abs_timeout argu‐
34 ment points to a structure that specifies an absolute timeout in sec‐
35 onds and nanoseconds since the Epoch (00:00:00, 1 January 1970). This
36 structure is defined as follows:
37
38 struct timespec {
39 time_t tv_sec; /* Seconds */
40 long tv_nsec; /* Nanoseconds [0 .. 999999999] */
41 };
42
43
44 If the timeout has already expired by the time of the call, and the
45 semaphore could not be locked immediately, then sem_timedwait() fails
46 with a timeout error (errno set to ETIMEDOUT).
47
48 If the operation can be performed immediately, then sem_timedwait()
49 never fails with a timeout error, regardless of the value of abs_time‐
50 out. Furthermore, the validity of abs_timeout is not checked in this
51 case.
52
54 All of these functions return 0 on success; on error, the value of the
55 semaphore is left unchanged, -1 is returned, and errno is set to indi‐
56 cate the error.
57
59 EINTR The call was interrupted by a signal handler.
60
61 EINVAL sem is not a valid semaphore.
62
63 The following additional error can occur for sem_trywait():
64
65 EAGAIN The operation could not be performed without blocking (i.e., the
66 semaphore currently has the value zero).
67
68 The following additional errors can occur for sem_timedwait():
69
70 EINVAL The value of abs_timeout.tv_nsecs is less than 0, or greater
71 than or equal to 1000 million.
72
73 ETIMEDOUT
74 The call timed out before the semaphore could be locked.
75
77 A signal handler always interrupts a blocked call to one of these func‐
78 tions, regardless of the use of the sigaction(2) SA_RESTART flag.
79
81 POSIX.1-2001.
82
84 The (somewhat trivial) program shown below operates on an unnamed sema‐
85 phore. The program expects two command-line arguments. The first
86 argument specifies a seconds value that is used to set an alarm timer
87 to generate a SIGALRM signal. This handler performs a sem_post() to
88 increment the semaphore that is being waited on in main() using
89 sem_timedwait(). The second command-line argument specifies the length
90 of the timeout, in seconds, for sem_timedwait(). The following shows
91 what happens on two different runs of the program:
92
93 $ ./a.out 2 3
94 About to call sem_timedwait()
95 sem_post() from handler
96 sem_getvalue() from handler; value = 1
97 sem_timedwait() succeeded
98 $ ./a.out 2 1
99 About to call sem_timedwait()
100 sem_timedwait() timed out
101
102 The source code of the program is as follows:
103
104 #include <unistd.h>
105 #include <stdio.h>
106 #include <stdlib.h>
107 #include <semaphore.h>
108 #include <time.h>
109 #include <assert.h>
110 #include <errno.h>
111 #include <signal.h>
112
113 #define die(msg) { perror(msg); exit(EXIT_FAILURE); }
114
115 sem_t sem;
116
117 static void
118 handler(int sig)
119 {
120 int sval;
121
122 printf("sem_post() from handler\n");
123 if (sem_post(&sem) == -1) die("sem_post");
124
125 if (sem_getvalue(&sem, &sval) == -1) die("sem_getvalue");
126 printf("sem_getvalue() from handler; value = %d\n", sval);
127 } /* handler */
128
129 int
130 main(int argc, char *argv[])
131 {
132 struct sigaction sa;
133 struct timespec ts;
134 int s;
135
136 assert(argc == 3); /* Usage: ./a.out alarm-secs wait-secs */
137
138 if (sem_init(&sem, 0, 0) == -1) die("sem_init");
139
140 /* Establish SIGALRM handler; set alarm timer using argv[1] */
141
142 sa.sa_handler = handler;
143 sigemptyset(&sa.sa_mask);
144 sa.sa_flags = 0;
145 if (sigaction(SIGALRM, &sa, NULL) == -1) die("sigaction");
146
147 alarm(atoi(argv[1]));
148
149 /* Calculate relative interval as current time plus
150 number of seconds given argv[2] */
151
152 if (clock_gettime(CLOCK_REALTIME, &ts) == -1)
153 die("clock_gettime");
154 ts.tv_sec += atoi(argv[2]);
155
156 printf("main() about to call sem_timedwait()\n");
157 while ((s = sem_timedwait(&sem, &ts)) == -1 && errno == EINTR)
158 continue; /* Restart when interrupted by handler */
159
160 /* Check what happened */
161
162 if (s == -1) {
163 if (errno == ETIMEDOUT)
164 printf("sem_timedwait() timed out\n");
165 else
166 die("sem_timedwait");
167 } else
168 printf("sem_timedwait() succeeded\n");
169
170 exit(EXIT_SUCCESS);
171 }
172
174 sem_getvalue(3), sem_post(3), feature_test_macros(7), sem_overview(7)
175
176
177
178Linux 2.6.16 2006-03-25 SEM_WAIT(3)