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

clock_nanosleep.3p (8915B)

    

  1. '\" et
  2. .TH CLOCK_NANOSLEEP "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. clock_nanosleep
  12. \(em high resolution sleep with specifiable clock
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <time.h>
  17. .P
  18. int clock_nanosleep(clockid_t \fIclock_id\fP, int \fIflags\fP,
  19.     const struct timespec *\fIrqtp\fP, struct timespec *\fIrmtp\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. If the flag TIMER_ABSTIME
  23. is not set in the
  24. .IR flags
  25. argument, the
  26. \fIclock_nanosleep\fR()
  27. function shall cause the current thread to be suspended from execution
  28. until either the time interval specified by the
  29. .IR rqtp
  30. argument has elapsed, or a signal is delivered to the calling thread
  31. and its action is to invoke a signal-catching function, or the process
  32. is terminated. The clock used to measure the time shall be the clock
  33. specified by
  34. .IR clock_id .
  35. .P
  36. If the flag TIMER_ABSTIME is set in the
  37. .IR flags
  38. argument, the
  39. \fIclock_nanosleep\fR()
  40. function shall cause the current thread to be suspended from execution
  41. until either the time value of the clock specified by
  42. .IR clock_id
  43. reaches the absolute time specified by the
  44. .IR rqtp
  45. argument, or a signal is delivered to the calling thread and its action
  46. is to invoke a signal-catching function, or the process is terminated.
  47. If, at the time of the call, the time value specified by
  48. .IR rqtp
  49. is less than or equal to the time value of the specified clock, then
  50. \fIclock_nanosleep\fR()
  51. shall return immediately and the calling process shall not be
  52. suspended.
  53. .P
  54. The suspension time caused by this function may be longer than
  55. requested because the argument value is rounded up to an integer
  56. multiple of the sleep resolution, or because of the scheduling of other
  57. activity by the system. But, except for the case of being interrupted
  58. by a signal, the suspension time for the relative
  59. \fIclock_nanosleep\fR()
  60. function (that is, with the TIMER_ABSTIME flag not set) shall not be
  61. less than the time interval specified by
  62. .IR rqtp ,
  63. as measured by the corresponding clock. The suspension for the absolute
  64. \fIclock_nanosleep\fR()
  65. function (that is, with the TIMER_ABSTIME flag set) shall be in effect
  66. at least until the value of the corresponding clock reaches the
  67. absolute time specified by
  68. .IR rqtp ,
  69. except for the case of being interrupted by a signal.
  70. .P
  71. The use of the
  72. \fIclock_nanosleep\fR()
  73. function shall have no effect on the action or blockage of any signal.
  74. .P
  75. The
  76. \fIclock_nanosleep\fR()
  77. function shall fail if the
  78. .IR clock_id
  79. argument refers to the CPU-time clock of the calling thread. It is
  80. unspecified whether
  81. .IR clock_id
  82. values of other CPU-time clocks are allowed.
  83. .SH "RETURN VALUE"
  84. If the
  85. \fIclock_nanosleep\fR()
  86. function returns because the requested time has elapsed, its return
  87. value shall be zero.
  88. .P
  89. If the
  90. \fIclock_nanosleep\fR()
  91. function returns because it has been interrupted by a signal, it shall
  92. return the corresponding error value. For the relative
  93. \fIclock_nanosleep\fR()
  94. function, if the
  95. .IR rmtp
  96. argument is non-NULL, the
  97. .BR timespec
  98. structure referenced by it shall be updated to contain the amount of
  99. time remaining in the interval (the requested time minus the time
  100. actually slept). The
  101. .IR rqtp
  102. and
  103. .IR rmtp
  104. arguments can point to the same object. If the
  105. .IR rmtp
  106. argument is NULL, the remaining time is not returned. The absolute
  107. \fIclock_nanosleep\fR()
  108. function has no effect on the structure referenced by
  109. .IR rmtp .
  110. .P
  111. If
  112. \fIclock_nanosleep\fR()
  113. fails, it shall return the corresponding error value.
  114. .SH ERRORS
  115. The
  116. \fIclock_nanosleep\fR()
  117. function shall fail if:
  118. .TP
  119. .BR EINTR
  120. The
  121. \fIclock_nanosleep\fR()
  122. function was interrupted by a signal.
  123. .TP
  124. .BR EINVAL
  125. The
  126. .IR rqtp
  127. argument specified a nanosecond value less than zero or greater than or
  128. equal to 1\|000 million; or the TIMER_ABSTIME flag was specified in
  129. flags and the
  130. .IR rqtp
  131. argument is outside the range for the clock specified by
  132. .IR clock_id ;
  133. or the
  134. .IR clock_id
  135. argument does not specify a known clock, or specifies the CPU-time
  136. clock of the calling thread.
  137. .TP
  138. .BR ENOTSUP
  139. The
  140. .IR clock_id
  141. argument specifies a clock for which
  142. \fIclock_nanosleep\fR()
  143. is not supported, such as a CPU-time clock.
  144. .LP
  145. .IR "The following sections are informative."
  146. .SH EXAMPLES
  147. None.
  148. .SH "APPLICATION USAGE"
  149. Calling
  150. \fIclock_nanosleep\fR()
  151. with the value TIMER_ABSTIME not set in the
  152. .IR flags
  153. argument and with a
  154. .IR clock_id
  155. of CLOCK_REALTIME is equivalent to calling
  156. \fInanosleep\fR()
  157. with the same
  158. .IR rqtp
  159. and
  160. .IR rmtp
  161. arguments.
  162. .SH RATIONALE
  163. The
  164. \fInanosleep\fR()
  165. function specifies that the system-wide clock CLOCK_REALTIME is used to
  166. measure the elapsed time for this time service. However, with the
  167. introduction of the monotonic clock CLOCK_MONOTONIC a new relative
  168. sleep function is needed to allow an application to take advantage of
  169. the special characteristics of this clock.
  170. .P
  171. There are many applications in which a process needs to be suspended
  172. and then activated multiple times in a periodic way; for example, to
  173. poll the status of a non-interrupting device or to refresh a display
  174. device. For these cases, it is known that precise periodic activation
  175. cannot be achieved with a relative
  176. \fIsleep\fR()
  177. or
  178. \fInanosleep\fR()
  179. function call. Suppose, for example, a periodic process that is
  180. activated at time
  181. .IR T 0,
  182. executes for a while, and then wants to suspend itself until time
  183. .IR T 0+\c
  184. .IR T ,
  185. the period being
  186. .IR T .
  187. If this process wants to use the
  188. \fInanosleep\fR()
  189. function, it must first call
  190. \fIclock_gettime\fR()
  191. to get the current time, then calculate the difference between the
  192. current time and
  193. .IR T 0+\c
  194. .IR T
  195. and, finally, call
  196. \fInanosleep\fR()
  197. using the computed interval. However, the process could be preempted by
  198. a different process between the two function calls, and in this case
  199. the interval computed would be wrong; the process would wake up later
  200. than desired. This problem would not occur with the absolute
  201. \fIclock_nanosleep\fR()
  202. function, since only one function call would be necessary to suspend
  203. the process until the desired time. In other cases, however, a relative
  204. sleep is needed, and that is why both functionalities are required.
  205. .P
  206. Although it is possible to implement periodic processes using the
  207. timers interface, this implementation would require the use of signals,
  208. and the reservation of some signal numbers. In this regard, the reasons
  209. for including an absolute version of the
  210. \fIclock_nanosleep\fR()
  211. function in POSIX.1\(hy2008 are the same as for the inclusion of the relative
  212. \fInanosleep\fR().
  213. .P
  214. It is also possible to implement precise periodic processes using
  215. \fIpthread_cond_timedwait\fR(),
  216. in which an absolute timeout is specified that takes effect if the
  217. condition variable involved is never signaled. However, the use of this
  218. interface is unnatural, and involves performing other operations on
  219. mutexes and condition variables that imply an unnecessary overhead.
  220. Furthermore,
  221. \fIpthread_cond_timedwait\fR()
  222. is not available in implementations that do not support threads.
  223. .P
  224. Although the interface of the relative and absolute versions of the new
  225. high resolution sleep service is the same
  226. \fIclock_nanosleep\fR()
  227. function, the
  228. .IR rmtp
  229. argument is only used in the relative sleep. This argument is needed in
  230. the relative
  231. \fIclock_nanosleep\fR()
  232. function to reissue the function call if it is interrupted by a signal,
  233. but it is not needed in the absolute
  234. \fIclock_nanosleep\fR()
  235. function call; if the call is interrupted by a signal, the absolute
  236. \fIclock_nanosleep\fR()
  237. function can be invoked again with the same
  238. .IR rqtp
  239. argument used in the interrupted call.
  240. .SH "FUTURE DIRECTIONS"
  241. None.
  242. .SH "SEE ALSO"
  243. .IR "\fIclock_getres\fR\^(\|)",
  244. .IR "\fInanosleep\fR\^(\|)",
  245. .IR "\fIpthread_cond_timedwait\fR\^(\|)",
  246. .IR "\fIsleep\fR\^(\|)"
  247. .P
  248. The Base Definitions volume of POSIX.1\(hy2017,
  249. .IR "\fB<time.h>\fP"
  250. .\"
  251. .SH COPYRIGHT
  252. Portions of this text are reprinted and reproduced in electronic form
  253. from IEEE Std 1003.1-2017, Standard for Information Technology
  254. -- Portable Operating System Interface (POSIX), The Open Group Base
  255. Specifications Issue 7, 2018 Edition,
  256. Copyright (C) 2018 by the Institute of
  257. Electrical and Electronics Engineers, Inc and The Open Group.
  258. In the event of any discrepancy between this version and the original IEEE and
  259. The Open Group Standard, the original IEEE and The Open Group Standard
  260. is the referee document. The original Standard can be obtained online at
  261. http://www.opengroup.org/unix/online.html .
  262. .PP
  263. Any typographical or formatting errors that appear
  264. in this page are most likely
  265. to have been introduced during the conversion of the source files to
  266. man page format. To report such errors, see
  267. https://www.kernel.org/doc/man-pages/reporting_bugs.html .