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

pthread_attr_getstack.3p (5935B)


  1. '\" et
  2. .TH PTHREAD_ATTR_GETSTACK "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. pthread_attr_getstack,
  12. pthread_attr_setstack
  13. \(em get and set stack attributes
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <pthread.h>
  18. .P
  19. int pthread_attr_getstack(const pthread_attr_t *restrict \fIattr\fP,
  20. void **restrict \fIstackaddr\fP, size_t *restrict \fIstacksize\fP);
  21. int pthread_attr_setstack(pthread_attr_t *\fIattr\fP, void *\fIstackaddr\fP,
  22. size_t \fIstacksize\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIpthread_attr_getstack\fR()
  27. and
  28. \fIpthread_attr_setstack\fR()
  29. functions, respectively, shall get and set the thread creation stack
  30. attributes
  31. .IR stackaddr
  32. and
  33. .IR stacksize
  34. in the
  35. .IR attr
  36. object.
  37. .P
  38. The stack attributes specify the area of storage to be used for the
  39. created thread's stack. The base (lowest addressable byte) of the
  40. storage shall be
  41. .IR stackaddr ,
  42. and the size of the storage shall be
  43. .IR stacksize
  44. bytes. The
  45. .IR stacksize
  46. shall be at least
  47. {PTHREAD_STACK_MIN}.
  48. The
  49. \fIpthread_attr_setstack\fR()
  50. function may fail with
  51. .BR [EINVAL]
  52. if
  53. .IR stackaddr
  54. does not meet implementation-defined alignment requirements.
  55. All pages within the stack described by
  56. .IR stackaddr
  57. and
  58. .IR stacksize
  59. shall be both readable and writable by the thread.
  60. .P
  61. If the
  62. \fIpthread_attr_getstack\fR()
  63. function is called before the
  64. .IR stackaddr
  65. attribute has been set, the behavior is unspecified.
  66. .P
  67. The behavior is undefined if the value specified by the
  68. .IR attr
  69. argument to
  70. \fIpthread_attr_getstack\fR()
  71. or
  72. \fIpthread_attr_setstack\fR()
  73. does not refer to an initialized thread attributes object.
  74. .SH "RETURN VALUE"
  75. Upon successful completion, these functions shall return a value of 0;
  76. otherwise, an error number shall be returned to indicate the error.
  77. .P
  78. The
  79. \fIpthread_attr_getstack\fR()
  80. function shall store the stack attribute values in
  81. .IR stackaddr
  82. and
  83. .IR stacksize
  84. if successful.
  85. .SH ERRORS
  86. .P
  87. The
  88. \fIpthread_attr_setstack\fR()
  89. function shall fail if:
  90. .TP
  91. .BR EINVAL
  92. The value of
  93. .IR stacksize
  94. is less than
  95. {PTHREAD_STACK_MIN}
  96. or exceeds an implementation-defined limit.
  97. .P
  98. The
  99. \fIpthread_attr_setstack\fR()
  100. function may fail if:
  101. .TP
  102. .BR EINVAL
  103. The value of
  104. .IR stackaddr
  105. does not have proper alignment to be used as a stack, or ((\c
  106. .BR "char *" )\c
  107. .IR stackaddr
  108. +
  109. .IR stacksize )
  110. lacks proper alignment.
  111. .TP
  112. .BR EACCES
  113. The stack page(s) described by
  114. .IR stackaddr
  115. and
  116. .IR stacksize
  117. are not both readable and writable by the thread.
  118. .P
  119. These functions shall not return an error code of
  120. .BR [EINTR] .
  121. .LP
  122. .IR "The following sections are informative."
  123. .SH EXAMPLES
  124. None.
  125. .SH "APPLICATION USAGE"
  126. These functions are appropriate for use by applications in an
  127. environment where the stack for a thread must be placed in some
  128. particular region of memory.
  129. .P
  130. While it might seem that an application could detect stack overflow by
  131. providing a protected page outside the specified stack region, this
  132. cannot be done portably. Implementations are free to place the thread's
  133. initial stack pointer anywhere within the specified region to
  134. accommodate the machine's stack pointer behavior and allocation
  135. requirements. Furthermore, on some architectures, such as the IA\(hy64,
  136. ``overflow'' might mean that two separate stack pointers allocated
  137. within the region will overlap somewhere in the middle of the region.
  138. .P
  139. After a successful call to
  140. \fIpthread_attr_setstack\fR(),
  141. the storage area specified by the
  142. .IR stackaddr
  143. parameter is under the control of the implementation, as described in
  144. .IR "Section 2.9.8" ", " "Use of Application-Managed Thread Stacks".
  145. .P
  146. The specification of the
  147. .IR stackaddr
  148. attribute presents several ambiguities that make portable use of these
  149. functions impossible. For example, the standard allows implementations
  150. to impose arbitrary alignment requirements on
  151. .IR stackaddr .
  152. Applications cannot assume that a buffer obtained from
  153. \fImalloc\fR()
  154. is suitably aligned. Note that although the
  155. .IR stacksize
  156. value passed to
  157. \fIpthread_attr_setstack\fR()
  158. must satisfy alignment requirements, the same is not true for
  159. \fIpthread_attr_setstacksize\fR()
  160. where the implementation must increase the specified size if
  161. necessary to achieve the proper alignment.
  162. .SH RATIONALE
  163. If an implementation detects that the value specified by the
  164. .IR attr
  165. argument to
  166. \fIpthread_attr_getstack\fR()
  167. or
  168. \fIpthread_attr_setstack\fR()
  169. does not refer to an initialized thread attributes object, it is
  170. recommended that the function should fail and report an
  171. .BR [EINVAL]
  172. error.
  173. .SH "FUTURE DIRECTIONS"
  174. None.
  175. .SH "SEE ALSO"
  176. .ad l
  177. .IR "\fIpthread_attr_destroy\fR\^(\|)",
  178. .IR "\fIpthread_attr_getdetachstate\fR\^(\|)",
  179. .IR "\fIpthread_attr_getstacksize\fR\^(\|)",
  180. .IR "\fIpthread_create\fR\^(\|)"
  181. .ad b
  182. .P
  183. The Base Definitions volume of POSIX.1\(hy2017,
  184. .IR "\fB<limits.h>\fP",
  185. .IR "\fB<pthread.h>\fP"
  186. .\"
  187. .SH COPYRIGHT
  188. Portions of this text are reprinted and reproduced in electronic form
  189. from IEEE Std 1003.1-2017, Standard for Information Technology
  190. -- Portable Operating System Interface (POSIX), The Open Group Base
  191. Specifications Issue 7, 2018 Edition,
  192. Copyright (C) 2018 by the Institute of
  193. Electrical and Electronics Engineers, Inc and The Open Group.
  194. In the event of any discrepancy between this version and the original IEEE and
  195. The Open Group Standard, the original IEEE and The Open Group Standard
  196. is the referee document. The original Standard can be obtained online at
  197. http://www.opengroup.org/unix/online.html .
  198. .PP
  199. Any typographical or formatting errors that appear
  200. in this page are most likely
  201. to have been introduced during the conversion of the source files to
  202. man page format. To report such errors, see
  203. https://www.kernel.org/doc/man-pages/reporting_bugs.html .