1SEM_TIMEDWAIT(3P)          POSIX Programmer's Manual         SEM_TIMEDWAIT(3P)
2
3
4

PROLOG

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
11

NAME

13       sem_timedwait — lock a semaphore
14

SYNOPSIS

16       #include <semaphore.h>
17       #include <time.h>
18
19       int sem_timedwait(sem_t *restrict sem,
20           const struct timespec *restrict abstime);
21

DESCRIPTION

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
29       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
35       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
40       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

RETURN VALUE

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

ERRORS

52       The sem_timedwait() function shall fail if:
53
54       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
58       ETIMEDOUT
59              The  semaphore  could not be locked before the specified timeout
60              expired.
61
62       The sem_timedwait() function may fail if:
63
64       EDEADLK
65              A deadlock condition was detected.
66
67       EINTR  A signal interrupted this function.
68
69       EINVAL The sem argument does not refer to a valid semaphore.
70
71       The following sections are informative.
72

EXAMPLES

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
82           #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
91           sem_t sem;
92
93           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
107           int
108           main(int argc, char *argv[])
109           {
110               struct sigaction sa;
111               struct timespec ts;
112               int s;
113
114               if (argc != 3) {
115                   fprintf(stderr, "Usage: %s <alarm-secs> <wait-secs>\n",
116                       argv[0]);
117                   exit(EXIT_FAILURE);
118               }
119
120               if (sem_init(&sem, 0, 0) == -1) {
121                   perror("sem_init");
122                   exit(EXIT_FAILURE);
123               }
124
125               /* Establish SIGALRM handler; set alarm timer using argv[1] */
126
127               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
135               alarm(atoi(argv[1]));
136
137               /* Calculate relative interval as current time plus
138                  number of seconds given argv[2] */
139
140               if (clock_gettime(CLOCK_REALTIME, &ts) == -1) {
141                   perror("clock_gettime");
142                   exit(EXIT_FAILURE);
143               }
144               ts.tv_sec += atoi(argv[2]);
145
146               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
150               /* Check what happened */
151
152               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
160               exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
161           }
162

APPLICATION USAGE

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

RATIONALE

169       None.
170

FUTURE DIRECTIONS

172       None.
173

SEE ALSO

175       sem_post(), sem_trywait(), semctl(), semget(), semop(), time()
176
177       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
192       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 .
196
197
198
199IEEE/The Open Group                  2013                    SEM_TIMEDWAIT(3P)
Impressum