1SEM_TIMEDWAIT(3P) POSIX Programmer's Manual SEM_TIMEDWAIT(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 sem_timedwait — lock a semaphore
14
16 #include <semaphore.h>
17 #include <time.h>
18 int sem_timedwait(sem_t *restrict sem,
20 const struct timespec *restrict abstime);
21
23 The sem_timedwait() function shall lock the semaphore referenced by sem
24 as in the sem_wait() function. However, if the semaphore cannot be
25 locked without waiting for another process or thread to unlock the sem‐
26 aphore by performing a sem_post() function, this wait shall be termi‐
27 nated when the specified timeout expires.
28 The timeout shall expire when the absolute time specified by abstime
30 passes, as measured by the clock on which timeouts are based (that is,
31 when the value of that clock equals or exceeds abstime), or if the
32 absolute time specified by abstime has already been passed at the time
33 of the call.
34 The timeout shall be based on the CLOCK_REALTIME clock. The resolution
36 of the timeout shall be the resolution of the clock on which it is
37 based. The timespec data type is defined as a structure in the <time.h>
38 header.
39 Under no circumstance shall the function fail with a timeout if the
41 semaphore can be locked immediately. The validity of the abstime need
42 not be checked if the semaphore can be locked immediately.
43
45 The sem_timedwait() function shall return zero if the calling process
46 successfully performed the semaphore lock operation on the semaphore
47 designated by sem. If the call was unsuccessful, the state of the sem‐
48 aphore shall be unchanged, and the function shall return a value of −1
49 and set errno to indicate the error.
50
52 The sem_timedwait() function shall fail if:
53 EINVAL The process or thread would have blocked, and the abstime param‐
55 eter specified a nanoseconds field value less than zero or
56 greater than or equal to 1000 million.
57 ETIMEDOUT
59 The semaphore could not be locked before the specified timeout
60 expired.
61 The sem_timedwait() function may fail if:
63 EDEADLK
65 A deadlock condition was detected.
66 EINTR A signal interrupted this function.
68 EINVAL The sem argument does not refer to a valid semaphore.
70 The following sections are informative.
72
74 The program shown below operates on an unnamed semaphore. The program
75 expects two command-line arguments. The first argument specifies a sec‐
76 onds value that is used to set an alarm timer to generate a SIGALRM
77 signal. This handler performs a sem_post(3) to increment the semaphore
78 that is being waited on in main() using sem_timedwait(). The second
79 command-line argument specifies the length of the timeout, in seconds,
80 for sem_timedwait().
81 #include <unistd.h>
83 #include <stdio.h>
84 #include <stdlib.h>
85 #include <semaphore.h>
86 #include <time.h>
87 #include <assert.h>
88 #include <errno.h>
89 #include <signal.h>
90 sem_t sem;
92 static void
94 handler(int sig)
95 {
96 int sav_errno = errno;
97 static const char info_msg[] = "sem_post() from handler\n";
98 write(STDOUT_FILENO, info_msg, sizeof info_msg - 1);
99 if (sem_post(&sem) == -1) {
100 static const char err_msg[] = "sem_post() failed\n";
101 write(STDERR_FILENO, err_msg, sizeof err_msg - 1);
102 _exit(EXIT_FAILURE);
103 }
104 errno = sav_errno;
105 }
106 int
108 main(int argc, char *argv[])
109 {
110 struct sigaction sa;
111 struct timespec ts;
112 int s;
113 if (argc != 3) {
115 fprintf(stderr, "Usage: %s <alarm-secs> <wait-secs>\n",
116 argv[0]);
117 exit(EXIT_FAILURE);
118 }
119 if (sem_init(&sem, 0, 0) == -1) {
121 perror("sem_init");
122 exit(EXIT_FAILURE);
123 }
124 /* Establish SIGALRM handler; set alarm timer using argv[1] */
126 sa.sa_handler = handler;
128 sigemptyset(&sa.sa_mask);
129 sa.sa_flags = 0;
130 if (sigaction(SIGALRM, &sa, NULL) == -1) {
131 perror("sigaction");
132 exit(EXIT_FAILURE);
133 }
134 alarm(atoi(argv[1]));
136 /* Calculate relative interval as current time plus
138 number of seconds given argv[2] */
139 if (clock_gettime(CLOCK_REALTIME, &ts) == -1) {
141 perror("clock_gettime");
142 exit(EXIT_FAILURE);
143 }
144 ts.tv_sec += atoi(argv[2]);
145 printf("main() about to call sem_timedwait()\n");
147 while ((s = sem_timedwait(&sem, &ts)) == -1 && errno == EINTR)
148 continue; /* Restart if interrupted by handler */
149 /* Check what happened */
151 if (s == -1) {
153 if (errno == ETIMEDOUT)
154 printf("sem_timedwait() timed out\n");
155 else
156 perror("sem_timedwait");
157 } else
158 printf("sem_timedwait() succeeded\n");
159 exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
161 }
162
164 Applications using these functions may be subject to priority inver‐
165 sion, as discussed in the Base Definitions volume of POSIX.1‐2008, Sec‐
166 tion 3.287, Priority Inversion.
167
169 None.
170
172 None.
173
175 sem_post(), sem_trywait(), semctl(), semget(), semop(), time()
176 The Base Definitions volume of POSIX.1‐2008, Section 3.287, Priority
178 Inversion, <semaphore.h>, <time.h>
179
181 Portions of this text are reprinted and reproduced in electronic form
182 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
183 -- Portable Operating System Interface (POSIX), The Open Group Base
184 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
185 cal and Electronics Engineers, Inc and The Open Group. (This is
186 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
187 event of any discrepancy between this version and the original IEEE and
188 The Open Group Standard, the original IEEE and The Open Group Standard
189 is the referee document. The original Standard can be obtained online
190 at http://www.unix.org/online.html .
191 Any typographical or formatting errors that appear in this page are
193 most likely to have been introduced during the conversion of the source
194 files to man page format. To report such errors, see https://www.ker‐
195 nel.org/doc/man-pages/reporting_bugs.html .
196IEEE/The Open Group 2013 SEM_TIMEDWAIT(3P)