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

sleep.3p (7806B)


  1. '\" et
  2. .TH SLEEP "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. sleep
  12. \(em suspend execution for an interval of time
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. unsigned sleep(unsigned \fIseconds\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIsleep\fR()
  23. function shall cause the calling thread to be suspended from execution
  24. until either the number of realtime seconds specified by the argument
  25. .IR seconds
  26. has elapsed or a signal is delivered to the calling thread and its
  27. action is to invoke a signal-catching function or to terminate the
  28. process. The suspension time may be longer than requested due to the
  29. scheduling of other activity by the system.
  30. .P
  31. In single-threaded programs,
  32. \fIsleep\fR()
  33. may make use of SIGALRM. In multi-threaded programs,
  34. \fIsleep\fR()
  35. shall not make use of SIGALRM and the remainder of this DESCRIPTION
  36. does not apply.
  37. .P
  38. If a SIGALRM signal is generated for the calling process during
  39. execution of
  40. \fIsleep\fR()
  41. and if the SIGALRM signal is being ignored or blocked from delivery, it
  42. is unspecified whether
  43. \fIsleep\fR()
  44. returns when the SIGALRM signal is scheduled. If the signal is being
  45. blocked, it is also unspecified whether it remains pending after
  46. \fIsleep\fR()
  47. returns or it is discarded.
  48. .P
  49. If a SIGALRM signal is generated for the calling process during
  50. execution of
  51. \fIsleep\fR(),
  52. except as a result of a prior call to
  53. \fIalarm\fR(),
  54. and if the SIGALRM signal is not being ignored or blocked from
  55. delivery, it is unspecified whether that signal has any effect other
  56. than causing
  57. \fIsleep\fR()
  58. to return.
  59. .P
  60. If a signal-catching function interrupts
  61. \fIsleep\fR()
  62. and examines or changes either the time a SIGALRM is scheduled to be
  63. generated, the action associated with the SIGALRM signal, or whether
  64. the SIGALRM signal is blocked from delivery, the results are
  65. unspecified.
  66. .P
  67. If a signal-catching function interrupts
  68. \fIsleep\fR()
  69. and calls
  70. \fIsiglongjmp\fR()
  71. or
  72. \fIlongjmp\fR()
  73. to restore an environment saved prior to the
  74. \fIsleep\fR()
  75. call, the action associated with the SIGALRM signal and the time at
  76. which a SIGALRM signal is scheduled to be generated are unspecified.
  77. It is also unspecified whether the SIGALRM signal is blocked, unless
  78. the signal mask of the process is restored as part of the environment.
  79. .P
  80. Interactions between
  81. \fIsleep\fR()
  82. and
  83. \fIsetitimer\fR()
  84. are unspecified.
  85. .SH "RETURN VALUE"
  86. If
  87. \fIsleep\fR()
  88. returns because the requested time has elapsed, the value returned
  89. shall be 0. If
  90. \fIsleep\fR()
  91. returns due to delivery of a signal, the return value shall be
  92. the ``unslept'' amount (the requested time minus the time actually
  93. slept) in seconds.
  94. .SH ERRORS
  95. No errors are defined.
  96. .LP
  97. .IR "The following sections are informative."
  98. .SH EXAMPLES
  99. None.
  100. .SH "APPLICATION USAGE"
  101. None.
  102. .SH RATIONALE
  103. There are two general approaches to the implementation of the
  104. \fIsleep\fR()
  105. function. One is to use the
  106. \fIalarm\fR()
  107. function to schedule a SIGALRM
  108. signal and then suspend the calling thread waiting for that signal. The
  109. other is to implement an independent facility. This volume of POSIX.1\(hy2017 permits either
  110. approach in single-threaded programs, but the simple alarm/suspend
  111. implementation is not appropriate for multi-threaded programs.
  112. .P
  113. In order to comply with the requirement that no primitive shall change
  114. a process attribute unless explicitly described by this volume of POSIX.1\(hy2017, an
  115. implementation using SIGALRM must carefully take into account any
  116. SIGALRM signal scheduled by previous
  117. \fIalarm\fR()
  118. calls, the action previously established for SIGALRM, and whether
  119. SIGALRM was blocked. If a SIGALRM has been scheduled before the
  120. \fIsleep\fR()
  121. would ordinarily complete, the
  122. \fIsleep\fR()
  123. must be shortened to that time and a SIGALRM generated (possibly
  124. simulated by direct invocation of the signal-catching function) before
  125. \fIsleep\fR()
  126. returns. If a SIGALRM has been scheduled after the
  127. \fIsleep\fR()
  128. would ordinarily complete, it must be rescheduled for the same time
  129. before
  130. \fIsleep\fR()
  131. returns. The action and blocking for SIGALRM must be saved and
  132. restored.
  133. .P
  134. Historical implementations often implement the SIGALRM-based version
  135. using
  136. \fIalarm\fR()
  137. and
  138. \fIpause\fR().
  139. One such implementation is prone to infinite hangups, as described in
  140. .IR "\fIpause\fR\^(\|)".
  141. Another such implementation uses the C-language
  142. \fIsetjmp\fR()
  143. and
  144. \fIlongjmp\fR()
  145. functions to avoid that window. That implementation introduces a
  146. different problem: when the SIGALRM signal interrupts a signal-catching
  147. function installed by the user to catch a different signal, the
  148. \fIlongjmp\fR()
  149. aborts that signal-catching function. An implementation based on
  150. \fIsigprocmask\fR(),
  151. \fIalarm\fR(),
  152. and
  153. \fIsigsuspend\fR()
  154. can avoid these problems.
  155. .P
  156. Despite all reasonable care, there are several very subtle, but
  157. detectable and unavoidable, differences between the two types of
  158. implementations. These are the cases mentioned in this volume of POSIX.1\(hy2017 where
  159. some other activity relating to SIGALRM takes place, and the results
  160. are stated to be unspecified. All of these cases are sufficiently
  161. unusual as not to be of concern to most applications.
  162. .P
  163. See also the discussion of the term
  164. .IR realtime
  165. in
  166. .IR "\fIalarm\fR\^(\|)".
  167. .P
  168. Since
  169. \fIsleep\fR()
  170. can be implemented using
  171. \fIalarm\fR(),
  172. the discussion about alarms occurring early under
  173. \fIalarm\fR()
  174. applies to
  175. \fIsleep\fR()
  176. as well.
  177. .P
  178. Application developers should note that the type of the argument
  179. .IR seconds
  180. and the return value of
  181. \fIsleep\fR()
  182. is
  183. .BR unsigned .
  184. That means that a Strictly Conforming POSIX System Interfaces
  185. Application
  186. cannot pass a value greater than the minimum guaranteed value for
  187. {UINT_MAX},
  188. which the ISO\ C standard sets as 65\|535, and any application passing a larger
  189. value is restricting its portability. A different type was considered,
  190. but historical implementations, including those with a 16-bit
  191. .BR int
  192. type, consistently use either
  193. .BR unsigned
  194. or
  195. .BR int .
  196. .P
  197. Scheduling delays may cause the process to return from the
  198. \fIsleep\fR()
  199. function significantly after the requested time. In such cases, the
  200. return value should be set to zero, since the formula (requested time
  201. minus the time actually spent) yields a negative number and
  202. \fIsleep\fR()
  203. returns an
  204. .BR unsigned .
  205. .SH "FUTURE DIRECTIONS"
  206. A future version of this standard may require that
  207. \fIsleep\fR()
  208. does not make use of SIGALRM in all programs, not just multi-threaded
  209. programs.
  210. .SH "SEE ALSO"
  211. .IR "\fIalarm\fR\^(\|)",
  212. .IR "\fIgetitimer\fR\^(\|)",
  213. .IR "\fInanosleep\fR\^(\|)",
  214. .IR "\fIpause\fR\^(\|)",
  215. .IR "\fIsigaction\fR\^(\|)",
  216. .IR "\fIsigsetjmp\fR\^(\|)"
  217. .P
  218. The Base Definitions volume of POSIX.1\(hy2017,
  219. .IR "\fB<unistd.h>\fP"
  220. .\"
  221. .SH COPYRIGHT
  222. Portions of this text are reprinted and reproduced in electronic form
  223. from IEEE Std 1003.1-2017, Standard for Information Technology
  224. -- Portable Operating System Interface (POSIX), The Open Group Base
  225. Specifications Issue 7, 2018 Edition,
  226. Copyright (C) 2018 by the Institute of
  227. Electrical and Electronics Engineers, Inc and The Open Group.
  228. In the event of any discrepancy between this version and the original IEEE and
  229. The Open Group Standard, the original IEEE and The Open Group Standard
  230. is the referee document. The original Standard can be obtained online at
  231. http://www.opengroup.org/unix/online.html .
  232. .PP
  233. Any typographical or formatting errors that appear
  234. in this page are most likely
  235. to have been introduced during the conversion of the source files to
  236. man page format. To report such errors, see
  237. https://www.kernel.org/doc/man-pages/reporting_bugs.html .