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
12 sem_timedwait — lock a semaphore
13
15 #include <semaphore.h>
16 #include <time.h>
17 int sem_timedwait(sem_t *restrict sem,
19 const struct timespec *restrict abstime);
20
22 The sem_timedwait() function shall lock the semaphore referenced by sem
23 as in the sem_wait() function. However, if the semaphore cannot be
24 locked without waiting for another process or thread to unlock the sem‐
25 aphore by performing a sem_post() function, this wait shall be termi‐
26 nated when the specified timeout expires.
27 The timeout shall expire when the absolute time specified by abstime
29 passes, as measured by the clock on which timeouts are based (that is,
30 when the value of that clock equals or exceeds abstime), or if the
31 absolute time specified by abstime has already been passed at the time
32 of the call.
33 The timeout shall be based on the CLOCK_REALTIME clock. The resolution
35 of the timeout shall be the resolution of the clock on which it is
36 based. The timespec data type is defined as a structure in the <time.h>
37 header.
38 Under no circumstance shall the function fail with a timeout if the
40 semaphore can be locked immediately. The validity of the abstime need
41 not be checked if the semaphore can be locked immediately.
42
44 The sem_timedwait() function shall return zero if the calling process
45 successfully performed the semaphore lock operation on the semaphore
46 designated by sem. If the call was unsuccessful, the state of the sem‐
47 aphore shall be unchanged, and the function shall return a value of -1
48 and set errno to indicate the error.
49
51 The sem_timedwait() function shall fail if:
52 EINVAL The process or thread would have blocked, and the abstime param‐
54 eter specified a nanoseconds field value less than zero or
55 greater than or equal to 1000 million.
56 ETIMEDOUT
58 The semaphore could not be locked before the specified timeout
59 expired.
60 The sem_timedwait() function may fail if:
62 EDEADLK
64 A deadlock condition was detected.
65 EINTR A signal interrupted this function.
67 EINVAL The sem argument does not refer to a valid semaphore.
69 The following sections are informative.
71
73 The program shown below operates on an unnamed semaphore. The program
74 expects two command-line arguments. The first argument specifies a sec‐
75 onds value that is used to set an alarm timer to generate a SIGALRM
76 signal. This handler performs a sem_post(3) to increment the semaphore
77 that is being waited on in main() using sem_timedwait(). The second
78 command-line argument specifies the length of the timeout, in seconds,
79 for sem_timedwait().
80 #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‐2017, Sec‐
166 tion 3.291, 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‐2017, Section 3.291, 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-2017, Standard for Information Technology -- Por‐
183 table Operating System Interface (POSIX), The Open Group Base Specifi‐
184 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
185 Electrical and Electronics Engineers, Inc and The Open Group. In the
186 event of any discrepancy between this version and the original IEEE and
187 The Open Group Standard, the original IEEE and The Open Group Standard
188 is the referee document. The original Standard can be obtained online
189 at http://www.opengroup.org/unix/online.html .
190 Any typographical or formatting errors that appear in this page are
192 most likely to have been introduced during the conversion of the source
193 files to man page format. To report such errors, see https://www.ker‐
194 nel.org/doc/man-pages/reporting_bugs.html .
195IEEE/The Open Group 2017 SEM_TIMEDWAIT(3P)