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

posix_trace_attr_getinherited.3p (8677B)

    

  1. '\" et
  2. .TH POSIX_TRACE_ATTR_GETINHERITED "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. .ad l
  12. posix_trace_attr_getinherited,
  13. posix_trace_attr_getlogfullpolicy,
  14. posix_trace_attr_getstreamfullpolicy,
  15. posix_trace_attr_setinherited,
  16. posix_trace_attr_setlogfullpolicy,
  17. posix_trace_attr_setstreamfullpolicy
  18. \(em retrieve and set the behavior of a trace stream
  19. (\fBTRACING\fP)
  20. .ad b
  21. .SH SYNOPSIS
  22. .LP
  23. .nf
  24. #include <trace.h>
  25. .P
  26. int posix_trace_attr_getinherited(const trace_attr_t *restrict \fIattr\fP,
  27.     int *restrict \fIinheritancepolicy\fP);
  28. int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict \fIattr\fP,
  29.     int *restrict \fIlogpolicy\fP);
  30. int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict
  31.     \fIattr\fP, int *restrict \fIstreampolicy\fP);
  32. int posix_trace_attr_setinherited(trace_attr_t *\fIattr\fP,
  33.     int \fIinheritancepolicy\fP);
  34. int posix_trace_attr_setlogfullpolicy(trace_attr_t *\fIattr\fP,
  35.     int \fIlogpolicy\fP);
  36. int posix_trace_attr_setstreamfullpolicy(trace_attr_t *\fIattr\fP,
  37.     int \fIstreampolicy\fP);
  38. .fi
  39. .SH DESCRIPTION
  40. The
  41. \fIposix_trace_attr_getinherited\fR()
  42. and
  43. \fIposix_trace_attr_setinherited\fR()
  44. functions, respectively, shall get and set the inheritance policy
  45. stored in the
  46. .IR inheritance
  47. attribute for traced processes across the
  48. \fIfork\fR()
  49. and
  50. \fIspawn\fR()
  51. operations. The
  52. .IR inheritance
  53. attribute of the attributes object pointed to by the
  54. .IR attr
  55. argument shall be set to one of the following values defined by
  56. manifest constants in the
  57. .IR <trace.h> 
  58. header:
  59. .IP POSIX_TRACE_CLOSE_FOR_CHILD 6
  60. .br
  61. After a
  62. \fIfork\fR()
  63. or
  64. \fIspawn\fR()
  65. operation, the child shall not be traced, and tracing of the parent
  66. shall continue.
  67. .IP POSIX_TRACE_INHERITED 6
  68. .br
  69. After a
  70. \fIfork\fR()
  71. or
  72. \fIspawn\fR()
  73. operation, if the parent is being traced, its child shall be
  74. concurrently traced using the same trace stream.
  75. .P
  76. The default value for the
  77. .IR inheritance
  78. attribute is POSIX_TRACE_CLOSE_FOR_CHILD.
  79. .P
  80. The
  81. \fIposix_trace_attr_getlogfullpolicy\fR()
  82. and
  83. \fIposix_trace_attr_setlogfullpolicy\fR()
  84. functions, respectively, shall get and set the trace log full policy
  85. stored in the
  86. .IR log-full-policy
  87. attribute of the attributes object pointed to by the
  88. .IR attr
  89. argument.
  90. .P
  91. The
  92. .IR log-full-policy
  93. attribute shall be set to one of the following values defined by
  94. manifest constants in the
  95. .IR <trace.h> 
  96. header:
  97. .IP POSIX_TRACE_LOOP 6
  98. .br
  99. The trace log shall loop until the associated trace stream is stopped.
  100. This policy means that when the trace log gets full, the file system
  101. shall reuse the resources allocated to the oldest trace events that
  102. were recorded. In this way, the trace log will always contain the most
  103. recent trace events flushed.
  104. .IP POSIX_TRACE_UNTIL_FULL 6
  105. .br
  106. The trace stream shall be flushed to the trace log until the trace log
  107. is full. This condition can be deduced from the
  108. .IR posix_log_full_status
  109. member status (see the
  110. .BR posix_trace_status_info
  111. structure defined in
  112. .IR <trace.h> ).
  113. The last recorded trace event shall be the POSIX_TRACE_STOP trace event.
  114. .IP POSIX_TRACE_APPEND 6
  115. .br
  116. The associated trace stream shall be flushed to the trace log without
  117. log size limitation. If the application specifies POSIX_TRACE_APPEND,
  118. the implementation shall ignore the
  119. .IR log-max-size
  120. attribute.
  121. .P
  122. The default value for the
  123. .IR log-full-policy
  124. attribute is POSIX_TRACE_LOOP.
  125. .P
  126. The
  127. \fIposix_trace_attr_getstreamfullpolicy\fR()
  128. and
  129. \fIposix_trace_attr_setstreamfullpolicy\fR()
  130. functions, respectively, shall get and set the trace stream full policy
  131. stored in the
  132. .IR stream-full-policy
  133. attribute of the attributes object pointed to by the
  134. .IR attr
  135. argument.
  136. .P
  137. The
  138. .IR stream-full-policy
  139. attribute shall be set to one of the following values defined by
  140. manifest constants in the
  141. .IR <trace.h> 
  142. header:
  143. .IP POSIX_TRACE_LOOP 6
  144. .br
  145. The trace stream shall loop until explicitly stopped by the
  146. \fIposix_trace_stop\fR()
  147. function. This policy means that when the trace stream is full, the
  148. trace system shall reuse the resources allocated to the oldest trace
  149. events recorded. In this way, the trace stream will always contain the
  150. most recent trace events recorded.
  151. .IP POSIX_TRACE_UNTIL_FULL 6
  152. .br
  153. The trace stream will run until the trace stream resources are
  154. exhausted. Then the trace stream will stop. This condition can be
  155. deduced from
  156. .IR posix_stream_status
  157. and
  158. .IR posix_stream_full_status
  159. (see the
  160. .BR posix_trace_status_info
  161. structure defined in
  162. .IR <trace.h> ).
  163. When this trace stream is read, a POSIX_TRACE_STOP trace
  164. event shall be reported after reporting the last recorded trace event.
  165. The trace system shall reuse the resources allocated to any trace
  166. events already reported\(emsee the
  167. \fIposix_trace_getnext_event\fR(),
  168. \fIposix_trace_trygetnext_event\fR(),
  169. and
  170. \fIposix_trace_timedgetnext_event\fR()
  171. functions\(emor already flushed for an active trace stream with log if
  172. the Trace Log option is supported; see the
  173. \fIposix_trace_flush\fR()
  174. function. The trace system shall restart the trace stream when it is
  175. empty and may restart it sooner. A POSIX_TRACE_START trace event shall
  176. be reported before reporting the next recorded trace event.
  177. .IP POSIX_TRACE_FLUSH 6
  178. .br
  179. If the Trace Log option is supported, this policy is identical to the
  180. POSIX_TRACE_UNTIL_FULL trace stream full policy except that the trace
  181. stream shall be flushed regularly as if
  182. \fIposix_trace_flush\fR()
  183. had been explicitly called. Defining this policy for an active trace
  184. stream without log shall be invalid.
  185. .P
  186. The default value for the
  187. .IR stream-full-policy
  188. attribute shall be POSIX_TRACE_LOOP for an active trace stream without
  189. log.
  190. .P
  191. If the Trace Log option is supported, the default value for the
  192. .IR stream-full-policy
  193. attribute shall be POSIX_TRACE_FLUSH for an active trace stream with
  194. log.
  195. .SH "RETURN VALUE"
  196. Upon successful completion, these functions shall return a value of
  197. zero. Otherwise, they shall return the corresponding error number.
  198. .P
  199. If successful, the
  200. \fIposix_trace_attr_getinherited\fR()
  201. function shall store the
  202. .IR inheritance
  203. attribute value in the object pointed to by
  204. .IR inheritancepolicy .
  205. Otherwise, the content of this object is undefined.
  206. .P
  207. If successful, the
  208. \fIposix_trace_attr_getlogfullpolicy\fR()
  209. function shall store the
  210. .IR log-full-policy
  211. attribute value in the object pointed to by
  212. .IR logpolicy .
  213. Otherwise, the content of this object is undefined.
  214. .P
  215. If successful, the
  216. \fIposix_trace_attr_getstreamfullpolicy\fR()
  217. function shall store the
  218. .IR stream-full-policy
  219. attribute value in the object pointed to by
  220. .IR streampolicy .
  221. Otherwise, the content of this object is undefined.
  222. .SH ERRORS
  223. These functions may fail if:
  224. .TP
  225. .BR EINVAL
  226. The value specified by at least one of the arguments is invalid.
  227. .LP
  228. .IR "The following sections are informative."
  229. .SH EXAMPLES
  230. None.
  231. .SH "APPLICATION USAGE"
  232. None.
  233. .SH RATIONALE
  234. None.
  235. .SH "FUTURE DIRECTIONS"
  236. The following functions:
  237. .sp
  238. .RS
  239. .nf
  240. \fIposix_trace_attr_getinherited\fR()
  241. \fIposix_trace_attr_getlogfullpolicy\fR()
  242. \fIposix_trace_attr_getstreamfullpolicy\fR()
  243. \fIposix_trace_attr_setinherited\fR()
  244. \fIposix_trace_attr_setlogfullpolicy\fR()
  245. \fIposix_trace_attr_setstreamfullpolicy\fR()
  246. .fi
  247. .RE
  248. .P
  249. may be removed in a future version.
  250. .SH "SEE ALSO"
  251. .ad l
  252. .IR "\fIfork\fR\^(\|)",
  253. .IR "\fIposix_trace_attr_destroy\fR\^(\|)",
  254. .IR "\fIposix_trace_create\fR\^(\|)",
  255. .IR "\fIposix_trace_get_attr\fR\^(\|)",
  256. .IR "\fIposix_trace_getnext_event\fR\^(\|)",
  257. .IR "\fIposix_trace_start\fR\^(\|)"
  258. .ad b
  259. .P
  260. The Base Definitions volume of POSIX.1\(hy2017,
  261. .IR "\fB<trace.h>\fP"
  262. .\"
  263. .SH COPYRIGHT
  264. Portions of this text are reprinted and reproduced in electronic form
  265. from IEEE Std 1003.1-2017, Standard for Information Technology
  266. -- Portable Operating System Interface (POSIX), The Open Group Base
  267. Specifications Issue 7, 2018 Edition,
  268. Copyright (C) 2018 by the Institute of
  269. Electrical and Electronics Engineers, Inc and The Open Group.
  270. In the event of any discrepancy between this version and the original IEEE and
  271. The Open Group Standard, the original IEEE and The Open Group Standard
  272. is the referee document. The original Standard can be obtained online at
  273. http://www.opengroup.org/unix/online.html .
  274. .PP
  275. Any typographical or formatting errors that appear
  276. in this page are most likely
  277. to have been introduced during the conversion of the source files to
  278. man page format. To report such errors, see
  279. https://www.kernel.org/doc/man-pages/reporting_bugs.html .