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_getlogsize.3p (8401B)


  1. '\" et
  2. .TH POSIX_TRACE_ATTR_GETLOGSIZE "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_getlogsize,
  13. posix_trace_attr_getmaxdatasize,
  14. posix_trace_attr_getmaxsystemeventsize,
  15. posix_trace_attr_getmaxusereventsize,
  16. posix_trace_attr_getstreamsize,
  17. posix_trace_attr_setlogsize,
  18. posix_trace_attr_setmaxdatasize,
  19. posix_trace_attr_setstreamsize
  20. \(em retrieve and set trace stream size attributes
  21. (\fBTRACING\fP)
  22. .ad b
  23. .SH SYNOPSIS
  24. .LP
  25. .nf
  26. #include <sys/types.h>
  27. #include <trace.h>
  28. .P
  29. int posix_trace_attr_getlogsize(const trace_attr_t *restrict \fIattr\fP,
  30. size_t *restrict \fIlogsize\fP);
  31. int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict \fIattr\fP,
  32. size_t *restrict \fImaxdatasize\fP);
  33. int posix_trace_attr_getmaxsystemeventsize(
  34. const trace_attr_t *restrict \fIattr\fP,
  35. size_t *restrict \fIeventsize\fP);
  36. int posix_trace_attr_getmaxusereventsize(
  37. const trace_attr_t *restrict \fIattr\fP,
  38. size_t \fIdata_len\fP, size_t *restrict \fIeventsize\fP);
  39. int posix_trace_attr_getstreamsize(const trace_attr_t *restrict \fIattr\fP,
  40. size_t *restrict \fIstreamsize\fP);
  41. int posix_trace_attr_setlogsize(trace_attr_t *\fIattr\fP,
  42. size_t \fIlogsize\fP);
  43. int posix_trace_attr_setmaxdatasize(trace_attr_t *\fIattr\fP,
  44. size_t \fImaxdatasize\fP);
  45. int posix_trace_attr_setstreamsize(trace_attr_t *\fIattr\fP,
  46. size_t \fIstreamsize\fP);
  47. .fi
  48. .SH DESCRIPTION
  49. The
  50. \fIposix_trace_attr_getlogsize\fR()
  51. function shall copy the log size, in bytes, from the
  52. .IR log-max-size
  53. attribute of the attributes object pointed to by the
  54. .IR attr
  55. argument into the variable pointed to by the
  56. .IR logsize
  57. argument. This log size is the maximum total of bytes that shall be
  58. allocated for system and user trace events in the trace log. The
  59. default value for the
  60. .IR log-max-size
  61. attribute is implementation-defined.
  62. .P
  63. The
  64. \fIposix_trace_attr_setlogsize\fR()
  65. function shall set the maximum allowed size, in bytes, in the
  66. .IR log-max-size
  67. attribute of the attributes object pointed to by the
  68. .IR attr
  69. argument, using the size value supplied by the
  70. .IR logsize
  71. argument.
  72. .P
  73. The trace log size shall be used if the
  74. .IR log-full-policy
  75. attribute is set to POSIX_TRACE_LOOP or POSIX_TRACE_UNTIL_FULL. If the
  76. .IR log-full-policy
  77. attribute is set to POSIX_TRACE_APPEND, the implementation shall ignore
  78. the
  79. .IR log-max-size
  80. attribute.
  81. .P
  82. The
  83. \fIposix_trace_attr_getmaxdatasize\fR()
  84. function shall copy the maximum user trace event data size, in bytes,
  85. from the
  86. .IR max-data-size
  87. attribute of the attributes object pointed to by the
  88. .IR attr
  89. argument into the variable pointed to by the
  90. .IR maxdatasize
  91. argument. The default value for the
  92. .IR max-data-size
  93. attribute is implementation-defined.
  94. .P
  95. The
  96. \fIposix_trace_attr_getmaxsystemeventsize\fR()
  97. function shall calculate the maximum memory size, in bytes, required to
  98. store a single system trace event. This value is calculated for the
  99. trace stream attributes object pointed to by the
  100. .IR attr
  101. argument and is returned in the variable pointed to by the
  102. .IR eventsize
  103. argument.
  104. .P
  105. The values returned as the maximum memory sizes of the user and system
  106. trace events shall be such that if the sum of the maximum memory sizes
  107. of a set of the trace events that may be recorded in a trace stream is
  108. less than or equal to the
  109. .IR stream-min-size
  110. attribute of that trace stream, the system provides the necessary
  111. resources for recording all those trace events, without loss.
  112. .P
  113. The
  114. \fIposix_trace_attr_getmaxusereventsize\fR()
  115. function shall calculate the maximum memory size, in bytes, required to
  116. store a single user trace event generated by a call to
  117. \fIposix_trace_event\fR()
  118. with a
  119. .IR data_len
  120. parameter equal to the
  121. .IR data_len
  122. value specified in this call. This value is calculated for the trace
  123. stream attributes object pointed to by the
  124. .IR attr
  125. argument and is returned in the variable pointed to by the
  126. .IR eventsize
  127. argument.
  128. .P
  129. The
  130. \fIposix_trace_attr_getstreamsize\fR()
  131. function shall copy the stream size, in bytes, from the
  132. .IR stream-min-size
  133. attribute of the attributes object pointed to by the
  134. .IR attr
  135. argument into the variable pointed to by the
  136. .IR streamsize
  137. argument.
  138. .P
  139. This stream size is the current total memory size reserved for system
  140. and user trace events in the trace stream. The default value for the
  141. .IR stream-min-size
  142. attribute is implementation-defined. The stream size refers to memory
  143. used to store trace event records. Other stream data (for example,
  144. trace attribute values) shall not be included in this size.
  145. .P
  146. The
  147. \fIposix_trace_attr_setmaxdatasize\fR()
  148. function shall set the maximum allowed size, in bytes, in the
  149. .IR max-data-size
  150. attribute of the attributes object pointed to by the
  151. .IR attr
  152. argument, using the size value supplied by the
  153. .IR maxdatasize
  154. argument. This maximum size is the maximum allowed size for the user
  155. data argument which may be passed to
  156. \fIposix_trace_event\fR().
  157. The implementation shall be allowed to truncate data passed to
  158. .IR trace_user_event
  159. which is longer than
  160. .IR maxdatasize .
  161. .P
  162. The
  163. \fIposix_trace_attr_setstreamsize\fR()
  164. function shall set the minimum allowed size, in bytes, in the
  165. .IR stream-min-size
  166. attribute of the attributes object pointed to by the
  167. .IR attr
  168. argument, using the size value supplied by the
  169. .IR streamsize
  170. argument.
  171. .SH "RETURN VALUE"
  172. Upon successful completion, these functions shall return a value of
  173. zero. Otherwise, they shall return the corresponding error number.
  174. .P
  175. The
  176. \fIposix_trace_attr_getlogsize\fR()
  177. function stores the maximum trace log allowed size in the object
  178. pointed to by
  179. .IR logsize ,
  180. if successful.
  181. .P
  182. The
  183. \fIposix_trace_attr_getmaxdatasize\fR()
  184. function stores the maximum trace event record memory size in the
  185. object pointed to by
  186. .IR maxdatasize ,
  187. if successful.
  188. .P
  189. The
  190. \fIposix_trace_attr_getmaxsystemeventsize\fR()
  191. function stores the maximum memory size to store a single system trace
  192. event in the object pointed to by
  193. .IR eventsize ,
  194. if successful.
  195. .P
  196. The
  197. \fIposix_trace_attr_getmaxusereventsize\fR()
  198. function stores the maximum memory size to store a single user trace
  199. event in the object pointed to by
  200. .IR eventsize ,
  201. if successful.
  202. .P
  203. The
  204. \fIposix_trace_attr_getstreamsize\fR()
  205. function stores the maximum trace stream allowed size in the object
  206. pointed to by
  207. .IR streamsize ,
  208. if successful.
  209. .SH ERRORS
  210. These functions may fail if:
  211. .TP
  212. .BR EINVAL
  213. The value specified by one of the arguments is invalid.
  214. .LP
  215. .IR "The following sections are informative."
  216. .SH EXAMPLES
  217. None.
  218. .SH "APPLICATION USAGE"
  219. None.
  220. .SH RATIONALE
  221. None.
  222. .SH "FUTURE DIRECTIONS"
  223. The following functions:
  224. .sp
  225. .RS
  226. .nf
  227. \fIposix_trace_attr_getlogsize\fR()
  228. \fIposix_trace_attr_getmaxdatasize\fR()
  229. \fIposix_trace_attr_getmaxsystemeventsize\fR()
  230. \fIposix_trace_attr_getmaxusereventsize\fR()
  231. \fIposix_trace_attr_getstreamsize\fR()
  232. \fIposix_trace_attr_setlogsize\fR()
  233. \fIposix_trace_attr_setmaxdatasize\fR()
  234. \fIposix_trace_attr_setstreamsize\fR()
  235. .fi
  236. .RE
  237. .P
  238. may be removed in a future version.
  239. .SH "SEE ALSO"
  240. .ad l
  241. .IR "\fIposix_trace_attr_destroy\fR\^(\|)",
  242. .IR "\fIposix_trace_create\fR\^(\|)",
  243. .IR "\fIposix_trace_event\fR\^(\|)",
  244. .IR "\fIposix_trace_get_attr\fR\^(\|)"
  245. .ad b
  246. .P
  247. The Base Definitions volume of POSIX.1\(hy2017,
  248. .IR "\fB<sys_types.h>\fP",
  249. .IR "\fB<trace.h>\fP"
  250. .\"
  251. .SH COPYRIGHT
  252. Portions of this text are reprinted and reproduced in electronic form
  253. from IEEE Std 1003.1-2017, Standard for Information Technology
  254. -- Portable Operating System Interface (POSIX), The Open Group Base
  255. Specifications Issue 7, 2018 Edition,
  256. Copyright (C) 2018 by the Institute of
  257. Electrical and Electronics Engineers, Inc and The Open Group.
  258. In the event of any discrepancy between this version and the original IEEE and
  259. The Open Group Standard, the original IEEE and The Open Group Standard
  260. is the referee document. The original Standard can be obtained online at
  261. http://www.opengroup.org/unix/online.html .
  262. .PP
  263. Any typographical or formatting errors that appear
  264. in this page are most likely
  265. to have been introduced during the conversion of the source files to
  266. man page format. To report such errors, see
  267. https://www.kernel.org/doc/man-pages/reporting_bugs.html .