logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

sem_timedwait.3p (6526B)


  1. '\" et
  2. .TH SEM_TIMEDWAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. sem_timedwait
  12. \(em lock a semaphore
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <semaphore.h>
  17. #include <time.h>
  18. .P
  19. int sem_timedwait(sem_t *restrict \fIsem\fP,
  20. const struct timespec *restrict \fIabstime\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIsem_timedwait\fR()
  25. function shall lock the semaphore referenced by
  26. .IR sem
  27. as in the
  28. \fIsem_wait\fR()
  29. function. However, if the semaphore cannot be locked without waiting
  30. for another process or thread to unlock the semaphore by performing a
  31. \fIsem_post\fR()
  32. function, this wait shall be terminated when the specified timeout
  33. expires.
  34. .P
  35. The timeout shall expire when the absolute time specified by
  36. .IR abstime
  37. passes, as measured by the clock on which timeouts are based (that is,
  38. when the value of that clock equals or exceeds
  39. .IR abstime ),
  40. or if the absolute time specified by
  41. .IR abstime
  42. has already been passed at the time of the call.
  43. .P
  44. The timeout shall be based on the CLOCK_REALTIME clock.
  45. The resolution of the timeout shall be the resolution of the
  46. clock on which it is based. The
  47. .BR timespec
  48. data type is defined as a structure in the
  49. .IR <time.h>
  50. header.
  51. .P
  52. Under no circumstance shall the function fail with a timeout if the
  53. semaphore can be locked immediately. The validity of the
  54. .IR abstime
  55. need not be checked if the semaphore can be locked immediately.
  56. .SH "RETURN VALUE"
  57. The
  58. \fIsem_timedwait\fR()
  59. function shall return zero if the calling process successfully
  60. performed the semaphore lock operation on the semaphore designated by
  61. .IR sem .
  62. If the call was unsuccessful, the state of the semaphore shall be
  63. unchanged, and the function shall return a value of \-1 and set
  64. .IR errno
  65. to indicate the error.
  66. .SH ERRORS
  67. The
  68. \fIsem_timedwait\fR()
  69. function shall fail if:
  70. .TP
  71. .BR EINVAL
  72. The process or thread would have blocked, and the
  73. .IR abstime
  74. parameter specified a nanoseconds field value less than zero or greater
  75. than or equal to 1\|000 million.
  76. .TP
  77. .BR ETIMEDOUT
  78. The semaphore could not be locked before the specified timeout expired.
  79. .P
  80. The
  81. \fIsem_timedwait\fR()
  82. function may fail if:
  83. .TP
  84. .BR EDEADLK
  85. A deadlock condition was detected.
  86. .TP
  87. .BR EINTR
  88. A signal interrupted this function.
  89. .TP
  90. .BR EINVAL
  91. The
  92. .IR sem
  93. argument does not refer to a valid semaphore.
  94. .LP
  95. .IR "The following sections are informative."
  96. .SH EXAMPLES
  97. The program shown below operates on an unnamed semaphore. The program
  98. expects two command-line arguments. The first argument specifies a
  99. seconds value that is used to set an alarm timer to generate a SIGALRM
  100. signal. This handler performs a
  101. .IR sem_post (3)
  102. to increment the semaphore that is being waited on in
  103. \fImain\fR()
  104. using
  105. \fIsem_timedwait\fR().
  106. The second command-line argument specifies the length of the timeout,
  107. in seconds, for
  108. \fIsem_timedwait\fR().
  109. .sp
  110. .RS 4
  111. .nf
  112. #include <unistd.h>
  113. #include <stdio.h>
  114. #include <stdlib.h>
  115. #include <semaphore.h>
  116. #include <time.h>
  117. #include <assert.h>
  118. #include <errno.h>
  119. #include <signal.h>
  120. .P
  121. sem_t sem;
  122. .P
  123. static void
  124. handler(int sig)
  125. {
  126. int sav_errno = errno;
  127. static const char info_msg[] = "sem_post() from handler\en";
  128. write(STDOUT_FILENO, info_msg, sizeof info_msg - 1);
  129. if (sem_post(&sem) == -1) {
  130. static const char err_msg[] = "sem_post() failed\en";
  131. write(STDERR_FILENO, err_msg, sizeof err_msg - 1);
  132. _exit(EXIT_FAILURE);
  133. }
  134. errno = sav_errno;
  135. }
  136. .P
  137. int
  138. main(int argc, char *argv[])
  139. {
  140. struct sigaction sa;
  141. struct timespec ts;
  142. int s;
  143. .P
  144. if (argc != 3) {
  145. fprintf(stderr, "Usage: %s <alarm-secs> <wait-secs>\en",
  146. argv[0]);
  147. exit(EXIT_FAILURE);
  148. }
  149. .P
  150. if (sem_init(&sem, 0, 0) == -1) {
  151. perror("sem_init");
  152. exit(EXIT_FAILURE);
  153. }
  154. .P
  155. /* Establish SIGALRM handler; set alarm timer using argv[1] */
  156. .P
  157. sa.sa_handler = handler;
  158. sigemptyset(&sa.sa_mask);
  159. sa.sa_flags = 0;
  160. if (sigaction(SIGALRM, &sa, NULL) == -1) {
  161. perror("sigaction");
  162. exit(EXIT_FAILURE);
  163. }
  164. .P
  165. alarm(atoi(argv[1]));
  166. .P
  167. /* Calculate relative interval as current time plus
  168. number of seconds given argv[2] */
  169. .P
  170. if (clock_gettime(CLOCK_REALTIME, &ts) == -1) {
  171. perror("clock_gettime");
  172. exit(EXIT_FAILURE);
  173. }
  174. ts.tv_sec += atoi(argv[2]);
  175. .P
  176. printf("main() about to call sem_timedwait()\en");
  177. while ((s = sem_timedwait(&sem, &ts)) == -1 && errno == EINTR)
  178. continue; /* Restart if interrupted by handler */
  179. .P
  180. /* Check what happened */
  181. .P
  182. if (s == -1) {
  183. if (errno == ETIMEDOUT)
  184. printf("sem_timedwait() timed out\en");
  185. else
  186. perror("sem_timedwait");
  187. } else
  188. printf("sem_timedwait() succeeded\en");
  189. .P
  190. exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
  191. }
  192. .fi
  193. .P
  194. .RE
  195. .SH "APPLICATION USAGE"
  196. Applications using these functions may be subject to priority
  197. inversion, as discussed in the Base Definitions volume of POSIX.1\(hy2017,
  198. .IR "Section 3.291" ", " "Priority Inversion".
  199. .SH RATIONALE
  200. None.
  201. .SH "FUTURE DIRECTIONS"
  202. None.
  203. .SH "SEE ALSO"
  204. .IR "\fIsem_post\fR\^(\|)",
  205. .IR "\fIsem_trywait\fR\^(\|)",
  206. .IR "\fIsemctl\fR\^(\|)",
  207. .IR "\fIsemget\fR\^(\|)",
  208. .IR "\fIsemop\fR\^(\|)",
  209. .IR "\fItime\fR\^(\|)"
  210. .P
  211. The Base Definitions volume of POSIX.1\(hy2017,
  212. .IR "Section 3.291" ", " "Priority Inversion",
  213. .IR "\fB<semaphore.h>\fP",
  214. .IR "\fB<time.h>\fP"
  215. .\"
  216. .SH COPYRIGHT
  217. Portions of this text are reprinted and reproduced in electronic form
  218. from IEEE Std 1003.1-2017, Standard for Information Technology
  219. -- Portable Operating System Interface (POSIX), The Open Group Base
  220. Specifications Issue 7, 2018 Edition,
  221. Copyright (C) 2018 by the Institute of
  222. Electrical and Electronics Engineers, Inc and The Open Group.
  223. In the event of any discrepancy between this version and the original IEEE and
  224. The Open Group Standard, the original IEEE and The Open Group Standard
  225. is the referee document. The original Standard can be obtained online at
  226. http://www.opengroup.org/unix/online.html .
  227. .PP
  228. Any typographical or formatting errors that appear
  229. in this page are most likely
  230. to have been introduced during the conversion of the source files to
  231. man page format. To report such errors, see
  232. https://www.kernel.org/doc/man-pages/reporting_bugs.html .