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

timer_getoverrun.3p (9065B)


  1. '\" et
  2. .TH TIMER_GETOVERRUN "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. timer_getoverrun,
  12. timer_gettime,
  13. timer_settime
  14. \(em per-process timers
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <time.h>
  19. .P
  20. int timer_getoverrun(timer_t \fItimerid\fP);
  21. int timer_gettime(timer_t \fItimerid\fP, struct itimerspec *\fIvalue\fP);
  22. int timer_settime(timer_t \fItimerid\fP, int \fIflags\fP,
  23. const struct itimerspec *restrict \fIvalue\fP,
  24. struct itimerspec *restrict \fIovalue\fP);
  25. .fi
  26. .SH DESCRIPTION
  27. The
  28. \fItimer_gettime\fR()
  29. function shall store the amount of time until the specified timer,
  30. .IR timerid ,
  31. expires and the reload value of the timer into the space pointed to by
  32. the
  33. .IR value
  34. argument. The
  35. .IR it_value
  36. member of this structure shall contain the amount of time before the timer
  37. expires, or zero if the timer is disarmed. This value is returned as
  38. the interval until timer expiration, even if the timer was armed with
  39. absolute time. The
  40. .IR it_interval
  41. member of
  42. .IR value
  43. shall contain the reload value last set by
  44. \fItimer_settime\fR().
  45. .P
  46. The
  47. \fItimer_settime\fR()
  48. function shall set the time until the next expiration of the timer
  49. specified by
  50. .IR timerid
  51. from the
  52. .IR it_value
  53. member of the
  54. .IR value
  55. argument and arm the timer if the
  56. .IR it_value
  57. member of
  58. .IR value
  59. is non-zero. If the specified timer was already armed when
  60. \fItimer_settime\fR()
  61. is called, this call shall reset the time until next expiration to the
  62. .IR value
  63. specified. If the
  64. .IR it_value
  65. member of
  66. .IR value
  67. is zero, the timer shall be disarmed. The effect of disarming or
  68. resetting a timer with pending expiration notifications is unspecified.
  69. .P
  70. If the flag TIMER_ABSTIME is not set in the argument
  71. .IR flags ,
  72. \fItimer_settime\fR()
  73. shall behave as if the time until next expiration is set to be equal
  74. to the interval specified by the
  75. .IR it_value
  76. member of
  77. .IR value .
  78. That is, the timer shall expire in
  79. .IR it_value
  80. nanoseconds from when the call is made. If the flag TIMER_ABSTIME is
  81. set in the argument
  82. .IR flags ,
  83. \fItimer_settime\fR()
  84. shall behave as if the time until next expiration is set to be equal
  85. to the difference between the absolute time specified by the
  86. .IR it_value
  87. member of
  88. .IR value
  89. and the current value of the clock associated with
  90. .IR timerid .
  91. That is, the timer shall expire when the clock reaches the value
  92. specified by the
  93. .IR it_value
  94. member of
  95. .IR value .
  96. If the specified time has already passed, the function shall succeed
  97. and the expiration notification shall be made.
  98. .P
  99. The reload value of the timer shall be set to the value specified by the
  100. .IR it_interval
  101. member of
  102. .IR value .
  103. When a timer is armed with a non-zero
  104. .IR it_interval ,
  105. a periodic (or repetitive) timer is specified.
  106. .P
  107. Time values that are between two consecutive non-negative integer
  108. multiples of the resolution of the specified timer shall be rounded up
  109. to the larger multiple of the resolution. Quantization error shall not
  110. cause the timer to expire earlier than the rounded time value.
  111. .P
  112. If the argument
  113. .IR ovalue
  114. is not NULL, the
  115. \fItimer_settime\fR()
  116. function shall store, in the location referenced by
  117. .IR ovalue ,
  118. a value representing the previous amount of time before the timer would
  119. have expired, or zero if the timer was disarmed, together with the
  120. previous timer reload value. Timers shall not expire before their
  121. scheduled time.
  122. .P
  123. Only a single signal shall be queued to the process for a given timer
  124. at any point in time. When a timer for which a signal is still pending
  125. expires, no signal shall be queued, and a timer overrun shall occur.
  126. When a timer expiration signal is delivered to or accepted by a
  127. process, the
  128. \fItimer_getoverrun\fR()
  129. function shall return the timer expiration overrun count for the
  130. specified timer. The overrun count returned contains the number of
  131. extra timer expirations that occurred between the time the signal was
  132. generated (queued) and when it was delivered or accepted, up to but not
  133. including an implementation-defined maximum of
  134. {DELAYTIMER_MAX}.
  135. If the number of such extra expirations is greater than or equal to
  136. {DELAYTIMER_MAX},
  137. then the overrun count shall be set to
  138. {DELAYTIMER_MAX}.
  139. The value returned by
  140. \fItimer_getoverrun\fR()
  141. shall apply to the most recent expiration signal delivery or acceptance
  142. for the timer. If no expiration signal has been delivered for the timer,
  143. the return value of
  144. \fItimer_getoverrun\fR()
  145. is unspecified.
  146. .P
  147. The behavior is undefined if the value specified by the
  148. .IR timerid
  149. argument to
  150. \fItimer_getoverrun\fR(),
  151. \fItimer_gettime\fR(),
  152. or
  153. \fItimer_settime\fR()
  154. does not correspond to a timer ID returned by
  155. \fItimer_create\fR()
  156. but not yet deleted by
  157. \fItimer_delete\fR().
  158. .SH "RETURN VALUE"
  159. If the
  160. \fItimer_getoverrun\fR()
  161. function succeeds, it shall return the timer expiration overrun count
  162. as explained above.
  163. .P
  164. If the
  165. \fItimer_gettime\fR()
  166. or
  167. \fItimer_settime\fR()
  168. functions succeed, a value of 0 shall be returned.
  169. .P
  170. If an error occurs for any of these functions, the value \-1 shall be
  171. returned, and
  172. .IR errno
  173. set to indicate the error.
  174. .SH ERRORS
  175. The
  176. \fItimer_settime\fR()
  177. function shall fail if:
  178. .TP
  179. .BR EINVAL
  180. A
  181. .IR value
  182. structure specified a nanosecond value less than zero or greater than
  183. or equal to 1\|000 million, and the
  184. .IR it_value
  185. member of that structure did not specify zero seconds and nanoseconds.
  186. .P
  187. The
  188. \fItimer_settime\fR()
  189. function may fail if:
  190. .TP
  191. .BR EINVAL
  192. The
  193. .IR it_interval
  194. member of
  195. .IR value
  196. is not zero and the timer was created with notification by creation of
  197. a new thread (\c
  198. .IR sigev_sigev_notify
  199. was SIGEV_THREAD) and a fixed stack address has been set in the thread
  200. attribute pointed to by
  201. .IR sigev_notify_attributes .
  202. .LP
  203. .IR "The following sections are informative."
  204. .SH EXAMPLES
  205. None.
  206. .SH "APPLICATION USAGE"
  207. Using fixed stack addresses is problematic when timer expiration is
  208. signaled by the creation of a new thread. Since it cannot be assumed
  209. that the thread created for one expiration is finished before the next
  210. expiration of the timer, it could happen that two threads use the same
  211. memory as a stack at the same time. This is invalid and produces
  212. undefined results.
  213. .SH RATIONALE
  214. Practical clocks tick at a finite rate, with rates of 100 hertz and
  215. 1\|000 hertz being common. The inverse of this tick rate is the clock
  216. resolution, also called the clock granularity, which in either case is
  217. expressed as a time duration, being 10 milliseconds and 1 millisecond
  218. respectively for these common rates. The granularity of practical
  219. clocks implies that if one reads a given clock twice in rapid
  220. succession, one may get the same time value twice; and that timers must
  221. wait for the next clock tick after the theoretical expiration time, to
  222. ensure that a timer never returns too soon. Note also that the
  223. granularity of the clock may be significantly coarser than the
  224. resolution of the data format used to set and get time and interval
  225. values. Also note that some implementations may choose to adjust time
  226. and/or interval values to exactly match the ticks of the underlying
  227. clock.
  228. .P
  229. This volume of POSIX.1\(hy2017 defines functions that allow an application to determine
  230. the implementation-supported resolution for the clocks and requires an
  231. implementation to document the resolution supported for timers and
  232. \fInanosleep\fR()
  233. if they differ from the supported clock resolution. This is more of a
  234. procurement issue than a runtime application issue.
  235. .P
  236. If an implementation detects that the value specified by the
  237. .IR timerid
  238. argument to
  239. \fItimer_getoverrun\fR(),
  240. \fItimer_gettime\fR(),
  241. or
  242. \fItimer_settime\fR()
  243. does not correspond to a timer ID returned by
  244. \fItimer_create\fR()
  245. but not yet deleted by
  246. \fItimer_delete\fR(),
  247. it is recommended that the function should fail and report an
  248. .BR [EINVAL]
  249. error.
  250. .SH "FUTURE DIRECTIONS"
  251. None.
  252. .SH "SEE ALSO"
  253. .IR "\fIclock_getres\fR\^(\|)",
  254. .IR "\fItimer_create\fR\^(\|)"
  255. .P
  256. The Base Definitions volume of POSIX.1\(hy2017,
  257. .IR "\fB<time.h>\fP"
  258. .\"
  259. .SH COPYRIGHT
  260. Portions of this text are reprinted and reproduced in electronic form
  261. from IEEE Std 1003.1-2017, Standard for Information Technology
  262. -- Portable Operating System Interface (POSIX), The Open Group Base
  263. Specifications Issue 7, 2018 Edition,
  264. Copyright (C) 2018 by the Institute of
  265. Electrical and Electronics Engineers, Inc and The Open Group.
  266. In the event of any discrepancy between this version and the original IEEE and
  267. The Open Group Standard, the original IEEE and The Open Group Standard
  268. is the referee document. The original Standard can be obtained online at
  269. http://www.opengroup.org/unix/online.html .
  270. .PP
  271. Any typographical or formatting errors that appear
  272. in this page are most likely
  273. to have been introduced during the conversion of the source files to
  274. man page format. To report such errors, see
  275. https://www.kernel.org/doc/man-pages/reporting_bugs.html .