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

sigaltstack.3p (5528B)


  1. '\" et
  2. .TH SIGALTSTACK "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. sigaltstack
  12. \(em set and get signal alternate stack context
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <signal.h>
  17. .P
  18. int sigaltstack(const stack_t *restrict \fIss\fP, stack_t *restrict \fIoss\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIsigaltstack\fR()
  23. function allows a process to define and examine the state of an
  24. alternate stack for signal handlers for the current thread. Signals
  25. that have been explicitly declared to execute on the alternate stack
  26. shall be delivered on the alternate stack.
  27. .P
  28. If
  29. .IR ss
  30. is not a null pointer, it points to a
  31. .BR stack_t
  32. structure that specifies the alternate signal stack that shall take
  33. effect upon return from
  34. \fIsigaltstack\fR().
  35. The
  36. .IR ss_flags
  37. member specifies the new stack state. If it is set to SS_DISABLE, the
  38. stack is disabled and
  39. .IR ss_sp
  40. and
  41. .IR ss_size
  42. are ignored. Otherwise, the stack shall be enabled, and the
  43. .IR ss_sp
  44. and
  45. .IR ss_size
  46. members specify the new address and size of the stack.
  47. .P
  48. The range of addresses starting at
  49. .IR ss_sp
  50. up to but not including
  51. .IR ss_sp +\c
  52. .IR ss_size
  53. is available to the implementation for use as the stack. This function
  54. makes no assumptions regarding which end is the stack base and in which
  55. direction the stack grows as items are pushed.
  56. .P
  57. If
  58. .IR oss
  59. is not a null pointer, upon successful completion it shall point to a
  60. .BR stack_t
  61. structure that specifies the alternate signal stack that was in effect
  62. prior to the call to
  63. \fIsigaltstack\fR().
  64. The
  65. .IR ss_sp
  66. and
  67. .IR ss_size
  68. members specify the address and size of that stack. The
  69. .IR ss_flags
  70. member specifies the stack's state, and may contain one of the
  71. following values:
  72. .IP SS_ONSTACK 12
  73. The process is currently executing on the alternate signal stack.
  74. Attempts to modify the alternate signal stack while the process is
  75. executing on it fail. This flag shall not be modified by processes.
  76. .IP SS_DISABLE 12
  77. The alternate signal stack is currently disabled.
  78. .P
  79. The value SIGSTKSZ is a system default specifying the number of bytes
  80. that would be used to cover the usual case when manually allocating an
  81. alternate stack area. The value MINSIGSTKSZ is defined to be the
  82. minimum stack size for
  83. a signal handler. In computing an alternate stack size, a program
  84. should add that amount to its stack requirements to allow for the
  85. system implementation overhead. The constants SS_ONSTACK, SS_DISABLE,
  86. SIGSTKSZ, and MINSIGSTKSZ are
  87. defined in
  88. .IR <signal.h> .
  89. .P
  90. After a successful call to one of the
  91. .IR exec
  92. functions, there are no alternate signal stacks in the new process
  93. image.
  94. .P
  95. In some implementations, a signal (whether or not indicated to execute
  96. on the alternate stack) shall always execute on the alternate stack if
  97. it is delivered while another signal is being caught using the
  98. alternate stack.
  99. .P
  100. Use of this function by library threads that are not bound to
  101. kernel-scheduled entities results in undefined behavior.
  102. .SH "RETURN VALUE"
  103. Upon successful completion,
  104. \fIsigaltstack\fR()
  105. shall return 0; otherwise, it shall return \-1 and set
  106. .IR errno
  107. to indicate the error.
  108. .SH ERRORS
  109. The
  110. \fIsigaltstack\fR()
  111. function shall fail if:
  112. .TP
  113. .BR EINVAL
  114. The
  115. .IR ss
  116. argument is not a null pointer, and the
  117. .IR ss_flags
  118. member pointed to by
  119. .IR ss
  120. contains flags other than SS_DISABLE.
  121. .TP
  122. .BR ENOMEM
  123. The size of the alternate stack area is less than MINSIGSTKSZ.
  124. .TP
  125. .BR EPERM
  126. An attempt was made to modify an active stack.
  127. .LP
  128. .IR "The following sections are informative."
  129. .SH EXAMPLES
  130. .SS "Allocating Memory for an Alternate Stack"
  131. .P
  132. The following example illustrates a method for allocating memory for an
  133. alternate stack.
  134. .sp
  135. .RS 4
  136. .nf
  137. #include <signal.h>
  138. \&...
  139. if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)
  140. /* Error return. */
  141. sigstk.ss_size = SIGSTKSZ;
  142. sigstk.ss_flags = 0;
  143. if (sigaltstack(&sigstk,(stack_t *)0) < 0)
  144. perror("sigaltstack");
  145. .fi
  146. .P
  147. .RE
  148. .SH "APPLICATION USAGE"
  149. On some implementations, stack space is automatically extended as
  150. needed. On those implementations, automatic extension is typically not
  151. available for an alternate stack. If the stack overflows, the
  152. behavior is undefined.
  153. .SH RATIONALE
  154. None.
  155. .SH "FUTURE DIRECTIONS"
  156. None.
  157. .SH "SEE ALSO"
  158. .IR "Section 2.4" ", " "Signal Concepts",
  159. .IR "\fIexec\fR\^",
  160. .IR "\fIsigaction\fR\^(\|)",
  161. .IR "\fIsigsetjmp\fR\^(\|)"
  162. .P
  163. The Base Definitions volume of POSIX.1\(hy2017,
  164. .IR "\fB<signal.h>\fP"
  165. .\"
  166. .SH COPYRIGHT
  167. Portions of this text are reprinted and reproduced in electronic form
  168. from IEEE Std 1003.1-2017, Standard for Information Technology
  169. -- Portable Operating System Interface (POSIX), The Open Group Base
  170. Specifications Issue 7, 2018 Edition,
  171. Copyright (C) 2018 by the Institute of
  172. Electrical and Electronics Engineers, Inc and The Open Group.
  173. In the event of any discrepancy between this version and the original IEEE and
  174. The Open Group Standard, the original IEEE and The Open Group Standard
  175. is the referee document. The original Standard can be obtained online at
  176. http://www.opengroup.org/unix/online.html .
  177. .PP
  178. Any typographical or formatting errors that appear
  179. in this page are most likely
  180. to have been introduced during the conversion of the source files to
  181. man page format. To report such errors, see
  182. https://www.kernel.org/doc/man-pages/reporting_bugs.html .