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

sighold.3p (6530B)


  1. '\" et
  2. .TH SIGHOLD "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. sighold,
  12. sigignore,
  13. sigpause,
  14. sigrelse,
  15. sigset
  16. \(em signal management
  17. .SH SYNOPSIS
  18. .LP
  19. .nf
  20. #include <signal.h>
  21. .P
  22. int sighold(int \fIsig\fP);
  23. int sigignore(int \fIsig\fP);
  24. int sigpause(int \fIsig\fP);
  25. int sigrelse(int \fIsig\fP);
  26. void (*sigset(int \fIsig\fP, void (*\fIdisp\fP)(int)))(int);
  27. .fi
  28. .SH DESCRIPTION
  29. Use of any of these functions is unspecified in a multi-threaded
  30. process.
  31. .P
  32. The
  33. \fIsighold\fR(),
  34. \fIsigignore\fR(),
  35. \fIsigpause\fR(),
  36. \fIsigrelse\fR(),
  37. and
  38. \fIsigset\fR()
  39. functions provide simplified signal management.
  40. .P
  41. The
  42. \fIsigset\fR()
  43. function shall modify signal dispositions. The
  44. .IR sig
  45. argument specifies the signal, which may be any signal except SIGKILL
  46. and SIGSTOP. The
  47. .IR disp
  48. argument specifies the signal's disposition, which may be SIG_DFL,
  49. SIG_IGN, or the address of a signal handler. If
  50. \fIsigset\fR()
  51. is used, and
  52. .IR disp
  53. is the address of a signal handler, the system shall add
  54. .IR sig
  55. to the signal mask of the calling process before executing the signal
  56. handler; when the signal handler returns, the system shall restore the
  57. signal mask of the calling process to its state prior to the delivery
  58. of the signal. In addition, if
  59. \fIsigset\fR()
  60. is used, and
  61. .IR disp
  62. is equal to SIG_HOLD,
  63. .IR sig
  64. shall be added to the
  65. signal mask of the calling process and
  66. .IR sig 's
  67. disposition shall remain unchanged. If
  68. \fIsigset\fR()
  69. is used, and
  70. .IR disp
  71. is not equal to SIG_HOLD,
  72. .IR sig
  73. shall be removed from the signal mask of the calling process.
  74. .P
  75. The
  76. \fIsighold\fR()
  77. function shall add
  78. .IR sig
  79. to the signal mask of the calling process.
  80. .P
  81. The
  82. \fIsigrelse\fR()
  83. function shall remove
  84. .IR sig
  85. from the signal mask of the calling process.
  86. .P
  87. The
  88. \fIsigignore\fR()
  89. function shall set the disposition of
  90. .IR sig
  91. to SIG_IGN.
  92. .P
  93. The
  94. \fIsigpause\fR()
  95. function shall remove
  96. .IR sig
  97. from the signal mask of the calling process and suspend the calling process
  98. until a signal is received. The
  99. \fIsigpause\fR()
  100. function shall restore the signal mask of the process to its original
  101. state before returning.
  102. .P
  103. If the action for the SIGCHLD signal is set to SIG_IGN, child processes
  104. of the
  105. calling processes shall not be transformed into zombie processes when
  106. they terminate. If the calling process subsequently waits for its
  107. children, and the process has no unwaited-for children that were
  108. transformed into zombie processes, it shall block until all of its
  109. children terminate, and
  110. \fIwait\fR(),
  111. \fIwaitid\fR(),
  112. and
  113. \fIwaitpid\fR()
  114. shall fail and set
  115. .IR errno
  116. to
  117. .BR [ECHILD] .
  118. .SH "RETURN VALUE"
  119. Upon successful completion,
  120. \fIsigset\fR()
  121. shall return SIG_HOLD if the signal had been blocked and the signal's
  122. previous disposition if it had not been blocked. Otherwise, SIG_ERR
  123. shall be returned and
  124. .IR errno
  125. set to indicate the error.
  126. .P
  127. The
  128. \fIsigpause\fR()
  129. function shall suspend execution of the thread until a signal is
  130. received, whereupon it shall return \-1 and set
  131. .IR errno
  132. to
  133. .BR [EINTR] .
  134. .P
  135. For all other functions, upon successful completion, 0 shall be returned.
  136. Otherwise, \-1 shall be returned and
  137. .IR errno
  138. set to indicate the error.
  139. .SH ERRORS
  140. These functions shall fail if:
  141. .TP
  142. .BR EINVAL
  143. The
  144. .IR sig
  145. argument is an illegal signal number.
  146. .P
  147. The
  148. \fIsigset\fR()
  149. and
  150. \fIsigignore\fR()
  151. functions shall fail if:
  152. .TP
  153. .BR EINVAL
  154. An attempt is made to catch a signal that cannot be caught, or to
  155. ignore a signal that cannot be ignored.
  156. .LP
  157. .IR "The following sections are informative."
  158. .SH EXAMPLES
  159. None.
  160. .SH "APPLICATION USAGE"
  161. The
  162. \fIsigaction\fR()
  163. function provides a more comprehensive and reliable mechanism for
  164. controlling signals; new applications should use the
  165. \fIsigaction\fR()
  166. function instead of the obsolescent
  167. \fIsigset\fR()
  168. function.
  169. .P
  170. The
  171. \fIsighold\fR()
  172. function, in conjunction with
  173. \fIsigrelse\fR()
  174. or
  175. \fIsigpause\fR(),
  176. may be used to establish critical regions of code that require the
  177. delivery of a signal to be temporarily deferred. For broader
  178. portability, the
  179. \fIpthread_sigmask\fR()
  180. or
  181. \fIsigprocmask\fR()
  182. functions should be used instead of the obsolescent
  183. \fIsighold\fR()
  184. and
  185. \fIsigrelse\fR()
  186. functions.
  187. .P
  188. For broader portability, the
  189. \fIsigsuspend\fR()
  190. function should be used instead of the obsolescent
  191. \fIsigpause\fR()
  192. function.
  193. .SH RATIONALE
  194. Each of these historic functions has a direct analog in the other
  195. functions which are required to be per-thread and thread-safe (aside
  196. from
  197. \fIsigprocmask\fR(),
  198. which is replaced by
  199. \fIpthread_sigmask\fR()).
  200. The
  201. \fIsigset\fR()
  202. function can be implemented as a simple wrapper for
  203. \fIsigaction\fR().
  204. The
  205. \fIsighold\fR()
  206. function is equivalent to
  207. \fIsigprocmask\fR()
  208. or
  209. \fIpthread_sigmask\fR()
  210. with SIG_BLOCK set. The
  211. \fIsigignore\fR()
  212. function is equivalent to
  213. \fIsigaction\fR()
  214. with SIG_IGN set. The
  215. \fIsigpause\fR()
  216. function is equivalent to
  217. \fIsigsuspend\fR().
  218. The
  219. \fIsigrelse\fR()
  220. function is equivalent to
  221. \fIsigprocmask\fR()
  222. or
  223. \fIpthread_sigmask\fR()
  224. with SIG_UNBLOCK set.
  225. .SH "FUTURE DIRECTIONS"
  226. These functions may be removed in a future version.
  227. .SH "SEE ALSO"
  228. .IR "Section 2.4" ", " "Signal Concepts",
  229. .IR "\fIexec\fR\^",
  230. .IR "\fIpause\fR\^(\|)",
  231. .IR "\fIpthread_sigmask\fR\^(\|)",
  232. .IR "\fIsigaction\fR\^(\|)",
  233. .IR "\fIsignal\fR\^(\|)",
  234. .IR "\fIsigsuspend\fR\^(\|)",
  235. .IR "\fIwait\fR\^(\|)",
  236. .IR "\fIwaitid\fR\^(\|)"
  237. .P
  238. The Base Definitions volume of POSIX.1\(hy2017,
  239. .IR "\fB<signal.h>\fP"
  240. .\"
  241. .SH COPYRIGHT
  242. Portions of this text are reprinted and reproduced in electronic form
  243. from IEEE Std 1003.1-2017, Standard for Information Technology
  244. -- Portable Operating System Interface (POSIX), The Open Group Base
  245. Specifications Issue 7, 2018 Edition,
  246. Copyright (C) 2018 by the Institute of
  247. Electrical and Electronics Engineers, Inc and The Open Group.
  248. In the event of any discrepancy between this version and the original IEEE and
  249. The Open Group Standard, the original IEEE and The Open Group Standard
  250. is the referee document. The original Standard can be obtained online at
  251. http://www.opengroup.org/unix/online.html .
  252. .PP
  253. Any typographical or formatting errors that appear
  254. in this page are most likely
  255. to have been introduced during the conversion of the source files to
  256. man page format. To report such errors, see
  257. https://www.kernel.org/doc/man-pages/reporting_bugs.html .