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_getres.3p (9219B)

    

  1. '\" et
  2. .TH CLOCK_GETRES "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_getres,
  12. clock_gettime,
  13. clock_settime
  14. \(em clock and timer functions
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <time.h>
  19. .P
  20. int clock_getres(clockid_t \fIclock_id\fP, struct timespec *\fIres\fP);
  21. int clock_gettime(clockid_t \fIclock_id\fP, struct timespec *\fItp\fP);
  22. int clock_settime(clockid_t \fIclock_id\fP, const struct timespec *\fItp\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIclock_getres\fR()
  27. function shall return the resolution of any clock. Clock resolutions
  28. are implementation-defined and cannot be set by a process. If the
  29. argument
  30. .IR res
  31. is not NULL, the resolution of the specified clock shall be stored in the
  32. location pointed to by
  33. .IR res .
  34. If
  35. .IR res
  36. is NULL, the clock resolution is not returned. If the
  37. .IR time
  38. argument of
  39. \fIclock_settime\fR()
  40. is not a multiple of
  41. .IR res ,
  42. then the value is truncated to a multiple of
  43. .IR res .
  44. .P
  45. The
  46. \fIclock_gettime\fR()
  47. function shall return the current value
  48. .IR tp
  49. for the specified clock,
  50. .IR clock_id .
  51. .P
  52. The
  53. \fIclock_settime\fR()
  54. function shall set the specified clock,
  55. .IR clock_id ,
  56. to the value specified by
  57. .IR tp .
  58. Time values that are between two consecutive non-negative integer
  59. multiples of the resolution of the specified clock shall be truncated
  60. down to the smaller multiple of the resolution.
  61. .P
  62. A clock may be system-wide (that is, visible to all processes) or
  63. per-process (measuring time that is meaningful only within a process).
  64. All implementations shall support a
  65. .IR clock_id
  66. of CLOCK_REALTIME as defined in
  67. .IR <time.h> .
  68. This clock represents the clock measuring real time for the system.
  69. For this clock, the values returned by
  70. \fIclock_gettime\fR()
  71. and specified by
  72. \fIclock_settime\fR()
  73. represent the amount of time (in seconds and nanoseconds) since the
  74. Epoch. An implementation may also support additional clocks. The
  75. interpretation of time values for these clocks is unspecified.
  76. .P
  77. If the value of the CLOCK_REALTIME clock is set via
  78. \fIclock_settime\fR(),
  79. the new value of the clock shall be used to determine the time of
  80. expiration for absolute time services based upon the CLOCK_REALTIME
  81. clock. This applies to the time at which armed absolute timers expire.
  82. If the absolute time requested at the invocation of such a time service
  83. is before the new value of the clock, the time service shall expire
  84. immediately as if the clock had reached the requested time normally.
  85. .P
  86. Setting the value of the CLOCK_REALTIME clock via
  87. \fIclock_settime\fR()
  88. shall have no effect on threads that are blocked waiting for a relative
  89. time service based upon this clock, including the
  90. \fInanosleep\fR()
  91. function; nor on the expiration of relative timers based upon this
  92. clock. Consequently, these time services shall expire when the
  93. requested relative interval elapses, independently of the new or old
  94. value of the clock.
  95. .P
  96. If the Monotonic Clock option is supported, all implementations shall
  97. support a
  98. .IR clock_id
  99. of CLOCK_MONOTONIC defined in
  100. .IR <time.h> .
  101. This clock represents the monotonic clock for the system. For this
  102. clock, the value returned by
  103. \fIclock_gettime\fR()
  104. represents the amount of time (in seconds and nanoseconds) since an
  105. unspecified point in the past (for example, system start-up time, or the
  106. Epoch). This point does not change after system start-up time. The value
  107. of the CLOCK_MONOTONIC clock cannot be set via
  108. \fIclock_settime\fR().
  109. This function shall fail if it is invoked with a
  110. .IR clock_id
  111. argument of CLOCK_MONOTONIC.
  112. .P
  113. The effect of setting a clock via
  114. \fIclock_settime\fR()
  115. on armed per-process timers associated with a clock other than
  116. CLOCK_REALTIME is implementation-defined.
  117. .P
  118. If the value of the CLOCK_REALTIME clock is set via
  119. \fIclock_settime\fR(),
  120. the new value of the clock shall be used to determine the time at which
  121. the system shall awaken a thread blocked on an absolute
  122. \fIclock_nanosleep\fR()
  123. call based upon the CLOCK_REALTIME clock. If the absolute time
  124. requested at the invocation of such a time service is before the new
  125. value of the clock, the call shall return immediately as if the clock
  126. had reached the requested time normally.
  127. .P
  128. Setting the value of the CLOCK_REALTIME clock via
  129. \fIclock_settime\fR()
  130. shall have no effect on any thread that is blocked on a relative
  131. \fIclock_nanosleep\fR()
  132. call. Consequently, the call shall return when the requested relative
  133. interval elapses, independently of the new or old value of the clock.
  134. .P
  135. Appropriate privileges to set a particular clock are
  136. implementation-defined.
  137. .P
  138. If _POSIX_CPUTIME is defined, implementations shall support clock ID
  139. values obtained by invoking
  140. \fIclock_getcpuclockid\fR(),
  141. which represent the CPU-time clock of a given process. Implementations
  142. shall also support the special
  143. .BR clockid_t
  144. value CLOCK_PROCESS_CPUTIME_ID, which represents the CPU-time clock of
  145. the calling process when invoking one of the
  146. .IR clock_* (\|)
  147. or
  148. .IR timer_* (\|)
  149. functions. For these clock IDs, the values returned by
  150. \fIclock_gettime\fR()
  151. and specified by
  152. \fIclock_settime\fR()
  153. represent the amount of execution time of the process associated with
  154. the clock. Changing the value of a CPU-time clock via
  155. \fIclock_settime\fR()
  156. shall have no effect on the behavior of the sporadic server scheduling
  157. policy (see
  158. .IR "Scheduling Policies").
  159. .P
  160. If _POSIX_THREAD_CPUTIME is defined, implementations shall support
  161. clock ID values obtained by invoking
  162. \fIpthread_getcpuclockid\fR(),
  163. which represent the CPU-time clock of a given thread. Implementations
  164. shall also support the special
  165. .BR clockid_t
  166. value CLOCK_THREAD_CPUTIME_ID, which represents the CPU-time clock of
  167. the calling thread when invoking one of the
  168. .IR clock_* (\|)
  169. or
  170. .IR timer_* (\|)
  171. functions. For these clock IDs, the values returned by
  172. \fIclock_gettime\fR()
  173. and specified by
  174. \fIclock_settime\fR()
  175. shall represent the amount of execution time of the thread associated
  176. with the clock. Changing the value of a CPU-time clock via
  177. \fIclock_settime\fR()
  178. shall have no effect on the behavior of the sporadic server scheduling
  179. policy (see
  180. .IR "Scheduling Policies").
  181. .SH "RETURN VALUE"
  182. A return value of 0 shall indicate that the call succeeded. A return
  183. value of \-1 shall indicate that an error occurred, and
  184. .IR errno
  185. shall be set to indicate the error.
  186. .SH ERRORS
  187. The
  188. \fIclock_getres\fR(),
  189. \fIclock_gettime\fR(),
  190. and
  191. \fIclock_settime\fR()
  192. functions shall fail if:
  193. .TP
  194. .BR EINVAL
  195. The
  196. .IR clock_id
  197. argument does not specify a known clock.
  198. .P
  199. The
  200. \fIclock_gettime\fR()
  201. function shall fail if:
  202. .TP
  203. .BR EOVERFLOW
  204. The number of seconds will not fit in an object of type
  205. .BR time_t .
  206. .P
  207. The
  208. \fIclock_settime\fR()
  209. function shall fail if:
  210. .TP
  211. .BR EINVAL
  212. The
  213. .IR tp
  214. argument to
  215. \fIclock_settime\fR()
  216. is outside the range for the given clock ID.
  217. .TP
  218. .BR EINVAL
  219. The
  220. .IR tp
  221. argument specified a nanosecond value less than zero or greater than or
  222. equal to 1\|000 million.
  223. .TP
  224. .BR EINVAL
  225. The value of the
  226. .IR clock_id
  227. argument is CLOCK_MONOTONIC.
  228. .P
  229. The
  230. \fIclock_settime\fR()
  231. function may fail if:
  232. .TP
  233. .BR EPERM
  234. The requesting process does not have appropriate privileges
  235. to set the specified clock.
  236. .LP
  237. .IR "The following sections are informative."
  238. .SH EXAMPLES
  239. None.
  240. .SH "APPLICATION USAGE"
  241. Note that the absolute value of the monotonic clock is meaningless
  242. (because its origin is arbitrary), and thus there is no need to set it.
  243. Furthermore, realtime applications can rely on the fact that the value
  244. of this clock is never set and, therefore, that time intervals measured
  245. with this clock will not be affected by calls to
  246. \fIclock_settime\fR().
  247. .SH RATIONALE
  248. None.
  249. .SH "FUTURE DIRECTIONS"
  250. None.
  251. .SH "SEE ALSO"
  252. .ad l
  253. .IR "Scheduling Policies",
  254. .IR "\fIclock_getcpuclockid\fR\^(\|)",
  255. .IR "\fIclock_nanosleep\fR\^(\|)",
  256. .IR "\fIctime\fR\^(\|)",
  257. .IR "\fImq_receive\fR\^(\|)",
  258. .IR "\fImq_send\fR\^(\|)",
  259. .IR "\fInanosleep\fR\^(\|)",
  260. .IR "\fIpthread_mutex_timedlock\fR\^(\|)",
  261. .IR "\fIsem_timedwait\fR\^(\|)",
  262. .IR "\fItime\fR\^(\|)",
  263. .IR "\fItimer_create\fR\^(\|)",
  264. .IR "\fItimer_getoverrun\fR\^(\|)"
  265. .ad b
  266. .P
  267. The Base Definitions volume of POSIX.1\(hy2017,
  268. .IR "\fB<time.h>\fP"
  269. .\"
  270. .SH COPYRIGHT
  271. Portions of this text are reprinted and reproduced in electronic form
  272. from IEEE Std 1003.1-2017, Standard for Information Technology
  273. -- Portable Operating System Interface (POSIX), The Open Group Base
  274. Specifications Issue 7, 2018 Edition,
  275. Copyright (C) 2018 by the Institute of
  276. Electrical and Electronics Engineers, Inc and The Open Group.
  277. In the event of any discrepancy between this version and the original IEEE and
  278. The Open Group Standard, the original IEEE and The Open Group Standard
  279. is the referee document. The original Standard can be obtained online at
  280. http://www.opengroup.org/unix/online.html .
  281. .PP
  282. Any typographical or formatting errors that appear
  283. in this page are most likely
  284. to have been introduced during the conversion of the source files to
  285. man page format. To report such errors, see
  286. https://www.kernel.org/doc/man-pages/reporting_bugs.html .