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_close.3p (4816B)

    

  1. '\" et
  2. .TH POSIX_TRACE_CLOSE "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_close,
  12. posix_trace_open,
  13. posix_trace_rewind
  14. \(em trace log management
  15. (\fBTRACING\fP)
  16. .SH SYNOPSIS
  17. .LP
  18. .nf
  19. #include <trace.h>
  20. .P
  21. int posix_trace_close(trace_id_t \fItrid\fP);
  22. int posix_trace_open(int \fIfile_desc\fP, trace_id_t *\fItrid\fP);
  23. int posix_trace_rewind(trace_id_t \fItrid\fP);
  24. .fi
  25. .SH DESCRIPTION
  26. The
  27. \fIposix_trace_close\fR()
  28. function shall deallocate the trace log identifier indicated by
  29. .IR trid ,
  30. and all of its associated resources. If there is no valid trace log
  31. pointed to by the
  32. .IR trid ,
  33. this function shall fail.
  34. .P
  35. The
  36. \fIposix_trace_open\fR()
  37. function shall allocate the necessary resources and establish the
  38. connection between a trace log identified by the
  39. .IR file_desc
  40. argument and a trace stream identifier identified by the object pointed
  41. to by the
  42. .IR trid
  43. argument. The
  44. .IR file_desc
  45. argument should be a valid open file descriptor that corresponds to a
  46. trace log. The
  47. .IR file_desc
  48. argument shall be open for reading. The current trace event timestamp,
  49. which specifies the timestamp of the trace event that will be read by
  50. the next call to
  51. \fIposix_trace_getnext_event\fR(),
  52. shall be set to the timestamp of the oldest trace event recorded in the
  53. trace log identified by
  54. .IR trid .
  55. .P
  56. The
  57. \fIposix_trace_open\fR()
  58. function shall return a trace stream identifier in the variable
  59. pointed to by the
  60. .IR trid
  61. argument, that may only be used by the following functions:
  62. .TS
  63. tab(!);
  64. l l.
  65. T{
  66. .nf
  67. \fIposix_trace_close\fR()
  68. \fIposix_trace_eventid_equal\fR()
  69. \fIposix_trace_eventid_get_name\fR()
  70. \fIposix_trace_eventtypelist_getnext_id\fR()
  71. \fIposix_trace_eventtypelist_rewind\fR()
  72. T}!T{
  73. .nf
  74. \fIposix_trace_get_attr\fR()
  75. \fIposix_trace_get_status\fR()
  76. \fIposix_trace_getnext_event\fR()
  77. \fIposix_trace_rewind\fR()
  78. .fi
  79. T}
  80. .TE
  81. .P
  82. In particular, notice that the operations normally used by a trace
  83. controller process, such as
  84. \fIposix_trace_start\fR(),
  85. \fIposix_trace_stop\fR(),
  86. or
  87. \fIposix_trace_shutdown\fR(),
  88. cannot be invoked using the trace stream identifier returned by the
  89. \fIposix_trace_open\fR()
  90. function.
  91. .P
  92. The
  93. \fIposix_trace_rewind\fR()
  94. function shall reset the current trace event timestamp, which specifies
  95. the timestamp of the trace event that will be read by the next call to
  96. \fIposix_trace_getnext_event\fR(),
  97. to the timestamp of the oldest trace event recorded in the trace log
  98. identified by
  99. .IR trid .
  100. .SH "RETURN VALUE"
  101. Upon successful completion, these functions shall return a value of
  102. zero. Otherwise, they shall return the corresponding error number.
  103. .P
  104. If successful, the
  105. \fIposix_trace_open\fR()
  106. function stores the trace stream identifier value in the object pointed
  107. to by
  108. .IR trid .
  109. .SH ERRORS
  110. The
  111. \fIposix_trace_open\fR()
  112. function shall fail if:
  113. .TP
  114. .BR EINTR
  115. The operation was interrupted by a signal and thus no trace log was
  116. opened.
  117. .TP
  118. .BR EINVAL
  119. The object pointed to by
  120. .IR file_desc
  121. does not correspond to a valid trace log.
  122. .br
  123. .P
  124. The
  125. \fIposix_trace_close\fR()
  126. and
  127. \fIposix_trace_rewind\fR()
  128. functions may fail if:
  129. .TP
  130. .BR EINVAL
  131. The object pointed to by
  132. .IR trid
  133. does not correspond to a valid trace log.
  134. .LP
  135. .IR "The following sections are informative."
  136. .SH EXAMPLES
  137. None.
  138. .SH "APPLICATION USAGE"
  139. None.
  140. .SH RATIONALE
  141. None.
  142. .SH "FUTURE DIRECTIONS"
  143. The
  144. \fIposix_trace_close\fR(),
  145. \fIposix_trace_open\fR(),
  146. and
  147. \fIposix_trace_rewind\fR()
  148. functions may be removed in a future version.
  149. .SH "SEE ALSO"
  150. .ad l
  151. .IR "\fIposix_trace_get_attr\fR\^(\|)",
  152. .IR "\fIposix_trace_get_filter\fR\^(\|)",
  153. .IR "\fIposix_trace_getnext_event\fR\^(\|)"
  154. .ad b
  155. .P
  156. The Base Definitions volume of POSIX.1\(hy2017,
  157. .IR "\fB<trace.h>\fP"
  158. .\"
  159. .SH COPYRIGHT
  160. Portions of this text are reprinted and reproduced in electronic form
  161. from IEEE Std 1003.1-2017, Standard for Information Technology
  162. -- Portable Operating System Interface (POSIX), The Open Group Base
  163. Specifications Issue 7, 2018 Edition,
  164. Copyright (C) 2018 by the Institute of
  165. Electrical and Electronics Engineers, Inc and The Open Group.
  166. In the event of any discrepancy between this version and the original IEEE and
  167. The Open Group Standard, the original IEEE and The Open Group Standard
  168. is the referee document. The original Standard can be obtained online at
  169. http://www.opengroup.org/unix/online.html .
  170. .PP
  171. Any typographical or formatting errors that appear
  172. in this page are most likely
  173. to have been introduced during the conversion of the source files to
  174. man page format. To report such errors, see
  175. https://www.kernel.org/doc/man-pages/reporting_bugs.html .