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_eventid_equal.3p (7072B)


  1. '\" et
  2. .TH POSIX_TRACE_EVENTID_EQUAL "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_eventid_equal,
  12. posix_trace_eventid_get_name,
  13. posix_trace_trid_eventid_open
  14. \(em manipulate the trace event type identifier
  15. (\fBTRACING\fP)
  16. .SH SYNOPSIS
  17. .LP
  18. .nf
  19. #include <trace.h>
  20. .P
  21. int posix_trace_eventid_equal(trace_id_t \fItrid\fP, trace_event_id_t \fIevent1\fP,
  22. trace_event_id_t \fIevent2\fP);
  23. int posix_trace_eventid_get_name(trace_id_t \fItrid\fP,
  24. trace_event_id_t \fIevent\fP, char *\fIevent_name\fP);
  25. int posix_trace_trid_eventid_open(trace_id_t \fItrid\fP,
  26. const char *restrict \fIevent_name\fP,
  27. trace_event_id_t *restrict \fIevent\fP);
  28. .fi
  29. .SH DESCRIPTION
  30. The
  31. \fIposix_trace_eventid_equal\fR()
  32. function shall compare the trace event type identifiers
  33. .IR event1
  34. and
  35. .IR event2
  36. from the same trace stream or the same trace log identified by the
  37. .IR trid
  38. argument. If the trace event type identifiers
  39. .IR event1
  40. and
  41. .IR event2
  42. are from different trace streams, the return value shall be
  43. unspecified.
  44. .P
  45. The
  46. \fIposix_trace_eventid_get_name\fR()
  47. function shall return, in the argument pointed to by
  48. .IR event_name ,
  49. the trace event name associated with the trace event type identifier
  50. identified by the argument
  51. .IR event ,
  52. for the trace stream or for the trace log identified by the
  53. .IR trid
  54. argument. The name of the trace event shall have a maximum of
  55. {TRACE_EVENT_NAME_MAX}
  56. characters (which has the minimum value
  57. {_POSIX_TRACE_EVENT_NAME_MAX}).
  58. Successive calls to this function with the same trace event type
  59. identifier and the same trace stream identifier shall return the same
  60. event name.
  61. .P
  62. The
  63. \fIposix_trace_trid_eventid_open\fR()
  64. function shall associate a user trace event name with a trace
  65. event type identifier for a given trace stream. The trace stream is
  66. identified by the
  67. .IR trid
  68. argument, and it shall be an active trace stream. The trace event name
  69. is the string pointed to by the argument
  70. .IR event_name .
  71. It shall have a maximum of
  72. {TRACE_EVENT_NAME_MAX}
  73. characters (which has the minimum value
  74. {_POSIX_TRACE_EVENT_NAME_MAX}).
  75. The number of user trace event type identifiers that can be defined for
  76. any given process is limited by the maximum value
  77. {TRACE_USER_EVENT_MAX},
  78. which has the minimum value
  79. {_POSIX_TRACE_USER_EVENT_MAX}.
  80. .P
  81. If the Trace Inherit option is not supported, the
  82. \fIposix_trace_trid_eventid_open\fR()
  83. function shall associate the user trace event name pointed to by the
  84. .IR event_name
  85. argument with a trace event type identifier that is unique for the
  86. process being traced in the trace stream identified by the
  87. .IR trid
  88. argument, and is returned in the variable pointed to by the
  89. .IR event
  90. argument. If the user trace event name has already been mapped for the
  91. traced process, then the previously assigned trace event type
  92. identifier shall be returned. If the per-process user trace event name
  93. limit represented by
  94. {TRACE_USER_EVENT_MAX}
  95. has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see
  96. .IR "Table 2-7" ", " "Trace Option: User Trace Event")
  97. user trace event shall be returned.
  98. .P
  99. If the Trace Inherit option is supported, the
  100. \fIposix_trace_trid_eventid_open\fR()
  101. function shall associate the user trace event name pointed to by the
  102. .IR event_name
  103. argument with a trace event type identifier that is unique for all the
  104. processes being traced in the trace stream identified by the
  105. .IR trid
  106. argument, and is returned in the variable pointed to by the
  107. .IR event
  108. argument. If the user trace event name has already been mapped for the
  109. traced processes, then the previously assigned trace event type
  110. identifier shall be returned. If the per-process user trace event name
  111. limit represented by
  112. {TRACE_USER_EVENT_MAX}
  113. has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see
  114. .IR "Table 2-7" ", " "Trace Option: User Trace Event")
  115. user trace event shall be returned.
  116. .SH "RETURN VALUE"
  117. Upon successful completion, the
  118. \fIposix_trace_eventid_get_name\fR()
  119. and
  120. \fIposix_trace_trid_eventid_open\fR()
  121. functions shall return a value of zero. Otherwise, they shall return
  122. the corresponding error number.
  123. .P
  124. The
  125. \fIposix_trace_eventid_equal\fR()
  126. function shall return a non-zero value if
  127. .IR event1
  128. and
  129. .IR event2
  130. are equal; otherwise, a value of zero shall be returned. No errors are
  131. defined. If either
  132. .IR event1
  133. or
  134. .IR event2
  135. are not valid trace event type identifiers for the trace stream
  136. specified by
  137. .IR trid
  138. or if the
  139. .IR trid
  140. is invalid, the behavior shall be unspecified.
  141. .P
  142. The
  143. \fIposix_trace_eventid_get_name\fR()
  144. function stores the trace event name value in the object pointed to by
  145. .IR event_name ,
  146. if successful.
  147. .P
  148. The
  149. \fIposix_trace_trid_eventid_open\fR()
  150. function stores the trace event type identifier value in the object
  151. pointed to by
  152. .IR event ,
  153. if successful.
  154. .SH ERRORS
  155. The
  156. \fIposix_trace_eventid_get_name\fR()
  157. and
  158. \fIposix_trace_trid_eventid_open\fR()
  159. functions shall fail if:
  160. .TP
  161. .BR EINVAL
  162. The
  163. .IR trid
  164. argument was not a valid trace stream identifier.
  165. .P
  166. The
  167. \fIposix_trace_trid_eventid_open\fR()
  168. function shall fail if:
  169. .TP
  170. .BR ENAMETOOLONG
  171. .br
  172. The size of the name pointed to by the
  173. .IR event_name
  174. argument was longer than the implementation-defined value
  175. {TRACE_EVENT_NAME_MAX}.
  176. .P
  177. The
  178. \fIposix_trace_eventid_get_name\fR()
  179. function shall fail if:
  180. .TP
  181. .BR EINVAL
  182. The trace event type identifier
  183. .IR event
  184. was not associated with any name.
  185. .LP
  186. .IR "The following sections are informative."
  187. .SH EXAMPLES
  188. None.
  189. .SH "APPLICATION USAGE"
  190. None.
  191. .SH RATIONALE
  192. None.
  193. .SH "FUTURE DIRECTIONS"
  194. The
  195. \fIposix_trace_eventid_equal\fR(),
  196. \fIposix_trace_eventid_get_name\fR(),
  197. and
  198. \fIposix_trace_trid_eventid_open\fR()
  199. functions may be removed in a future version.
  200. .SH "SEE ALSO"
  201. .ad l
  202. .IR "Table 2-7" ", " "Trace Option: User Trace Event",
  203. .IR "\fIexec\fR\^",
  204. .IR "\fIposix_trace_event\fR\^(\|)",
  205. .IR "\fIposix_trace_getnext_event\fR\^(\|)"
  206. .ad b
  207. .P
  208. The Base Definitions volume of POSIX.1\(hy2017,
  209. .IR "\fB<trace.h>\fP"
  210. .\"
  211. .SH COPYRIGHT
  212. Portions of this text are reprinted and reproduced in electronic form
  213. from IEEE Std 1003.1-2017, Standard for Information Technology
  214. -- Portable Operating System Interface (POSIX), The Open Group Base
  215. Specifications Issue 7, 2018 Edition,
  216. Copyright (C) 2018 by the Institute of
  217. Electrical and Electronics Engineers, Inc and The Open Group.
  218. In the event of any discrepancy between this version and the original IEEE and
  219. The Open Group Standard, the original IEEE and The Open Group Standard
  220. is the referee document. The original Standard can be obtained online at
  221. http://www.opengroup.org/unix/online.html .
  222. .PP
  223. Any typographical or formatting errors that appear
  224. in this page are most likely
  225. to have been introduced during the conversion of the source files to
  226. man page format. To report such errors, see
  227. https://www.kernel.org/doc/man-pages/reporting_bugs.html .