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_event.3p (6241B)


  1. '\" et
  2. .TH POSIX_TRACE_EVENT "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. posix_trace_event,
  12. posix_trace_eventid_open
  13. \(em trace functions for instrumenting application code
  14. (\fBTRACING\fP)
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <sys/types.h>
  19. #include <trace.h>
  20. .P
  21. void posix_trace_event(trace_event_id_t \fIevent_id\fP,
  22. const void *restrict \fIdata_ptr\fP, size_t \fIdata_len\fP);
  23. int posix_trace_eventid_open(const char *restrict \fIevent_name\fP,
  24. trace_event_id_t *restrict \fIevent_id\fP);
  25. .fi
  26. .SH DESCRIPTION
  27. The
  28. \fIposix_trace_event\fR()
  29. function shall record the
  30. .IR event_id
  31. and the user data pointed to by
  32. .IR data_ptr
  33. in the trace stream into which the calling process is being traced and
  34. in which
  35. .IR event_id
  36. is not filtered out. If the total size of the user trace event data
  37. represented by
  38. .IR data_len
  39. is not greater than the declared maximum size for user trace event
  40. data, then the
  41. .IR truncation-status
  42. attribute of the trace event recorded is POSIX_TRACE_NOT_TRUNCATED.
  43. Otherwise, the user trace event data is truncated to this declared
  44. maximum size and the
  45. .IR truncation-status
  46. attribute of the trace event recorded is POSIX_TRACE_TRUNCATED_RECORD.
  47. .P
  48. If there is no trace stream created for the process or if the created
  49. trace stream is not running, or if the trace event specified by
  50. .IR event_id
  51. is filtered out in the trace stream, the
  52. \fIposix_trace_event\fR()
  53. function shall have no effect.
  54. .P
  55. The
  56. \fIposix_trace_eventid_open\fR()
  57. function shall associate a user trace event name with a trace
  58. event type identifier for the calling process. The trace event name is
  59. the string pointed to by the argument
  60. .IR event_name .
  61. It shall have a maximum of
  62. {TRACE_EVENT_NAME_MAX}
  63. characters (which has the minimum value
  64. {_POSIX_TRACE_EVENT_NAME_MAX}).
  65. The number of user trace event type identifiers that can be defined for
  66. any given process is limited by the maximum value
  67. {TRACE_USER_EVENT_MAX},
  68. which has the minimum value
  69. {POSIX_TRACE_USER_EVENT_MAX}.
  70. .P
  71. If the Trace Inherit option is not supported, the
  72. \fIposix_trace_eventid_open\fR()
  73. function shall associate the user trace event name pointed to by the
  74. .IR event_name
  75. argument with a trace event type identifier that is unique for the
  76. traced process, and is returned in the variable pointed to by the
  77. .IR event_id
  78. argument. If the user trace event name has already been mapped for the
  79. traced process, then the previously assigned trace event type
  80. identifier shall be returned. If the per-process user trace event name
  81. limit represented by
  82. {TRACE_USER_EVENT_MAX}
  83. has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see
  84. .IR "Table 2-7" ", " "Trace Option: User Trace Event")
  85. user trace event shall be returned.
  86. .P
  87. If the Trace Inherit option is supported, the
  88. \fIposix_trace_eventid_open\fR()
  89. function shall associate the user trace event name pointed to by the
  90. .IR event_name
  91. argument with a trace event type identifier that is unique for all the
  92. processes being traced in this same trace stream, and is returned in
  93. the variable pointed to by the
  94. .IR event_id
  95. argument. If the user trace event name has already been mapped for the
  96. traced processes, then the previously assigned trace event type
  97. identifier shall be returned. If the per-process user trace event name
  98. limit represented by
  99. {TRACE_USER_EVENT_MAX}
  100. has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (\c
  101. .IR "Table 2-7" ", " "Trace Option: User Trace Event")
  102. user trace event shall be returned.
  103. .TP 10
  104. .BR Note:
  105. The above procedure, together with the fact that multiple processes can
  106. only be traced into the same trace stream by inheritance, ensure that
  107. all the processes that are traced into a trace stream have the same
  108. mapping of trace event names to trace event type identifiers.
  109. .P
  110. .P
  111. If there is no trace stream created, the
  112. \fIposix_trace_eventid_open\fR()
  113. function shall store this information for future trace streams created
  114. for this process.
  115. .SH "RETURN VALUE"
  116. No return value is defined for the
  117. \fIposix_trace_event\fR()
  118. function.
  119. .P
  120. Upon successful completion, the
  121. \fIposix_trace_eventid_open\fR()
  122. function shall return a value of zero. Otherwise, it shall return the
  123. corresponding error number. The
  124. \fIposix_trace_eventid_open\fR()
  125. function stores the trace event type identifier value in the object
  126. pointed to by
  127. .IR event_id ,
  128. if successful.
  129. .SH ERRORS
  130. The
  131. \fIposix_trace_eventid_open\fR()
  132. function shall fail if:
  133. .TP
  134. .BR ENAMETOOLONG
  135. .br
  136. The size of the name pointed to by the
  137. .IR event_name
  138. argument was longer than the implementation-defined value
  139. {TRACE_EVENT_NAME_MAX}.
  140. .LP
  141. .IR "The following sections are informative."
  142. .SH EXAMPLES
  143. None.
  144. .SH "APPLICATION USAGE"
  145. None.
  146. .SH RATIONALE
  147. None.
  148. .SH "FUTURE DIRECTIONS"
  149. The
  150. \fIposix_trace_event\fR()
  151. and
  152. \fIposix_trace_eventid_open\fR()
  153. functions may be removed in a future version.
  154. .SH "SEE ALSO"
  155. .IR "Table 2-7" ", " "Trace Option: User Trace Event",
  156. .IR "\fIexec\fR\^",
  157. .IR "\fIposix_trace_eventid_equal\fR\^(\|)",
  158. .IR "\fIposix_trace_start\fR\^(\|)"
  159. .P
  160. The Base Definitions volume of POSIX.1\(hy2017,
  161. .IR "\fB<sys_types.h>\fP",
  162. .IR "\fB<trace.h>\fP"
  163. .\"
  164. .SH COPYRIGHT
  165. Portions of this text are reprinted and reproduced in electronic form
  166. from IEEE Std 1003.1-2017, Standard for Information Technology
  167. -- Portable Operating System Interface (POSIX), The Open Group Base
  168. Specifications Issue 7, 2018 Edition,
  169. Copyright (C) 2018 by the Institute of
  170. Electrical and Electronics Engineers, Inc and The Open Group.
  171. In the event of any discrepancy between this version and the original IEEE and
  172. The Open Group Standard, the original IEEE and The Open Group Standard
  173. is the referee document. The original Standard can be obtained online at
  174. http://www.opengroup.org/unix/online.html .
  175. .PP
  176. Any typographical or formatting errors that appear
  177. in this page are most likely
  178. to have been introduced during the conversion of the source files to
  179. man page format. To report such errors, see
  180. https://www.kernel.org/doc/man-pages/reporting_bugs.html .