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_clear.3p (4367B)

    

  1. '\" et
  2. .TH POSIX_TRACE_CLEAR "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_clear
  12. \(em clear trace stream and trace log
  13. (\fBTRACING\fP)
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <sys/types.h>
  18. #include <trace.h>
  19. .P
  20. int posix_trace_clear(trace_id_t \fItrid\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIposix_trace_clear\fR()
  25. function shall reinitialize the trace stream identified by the argument
  26. .IR trid
  27. as if it were returning from the
  28. \fIposix_trace_create\fR()
  29. function, except that the same allocated resources shall be reused, the
  30. mapping of trace event type identifiers to trace event names shall be
  31. unchanged, and the trace stream status shall remain unchanged (that is,
  32. if it was running, it remains running and if it was suspended, it
  33. remains suspended).
  34. .P
  35. All trace events in the trace stream recorded before the call to
  36. \fIposix_trace_clear\fR()
  37. shall be lost. The
  38. .IR posix_stream_full_status
  39. status shall be set to POSIX_TRACE_NOT_FULL.
  40. There is no guarantee that all trace events that occurred during the
  41. \fIposix_trace_clear\fR()
  42. call are recorded; the behavior with respect to trace points that may
  43. occur during this call is unspecified.
  44. .P
  45. If the Trace Log option is supported and the trace stream has been
  46. created with a log, the
  47. \fIposix_trace_clear\fR()
  48. function shall reinitialize the trace stream with the same behavior as
  49. if the trace stream was created without the log, plus it shall
  50. reinitialize the trace log associated with the trace stream identified
  51. by the argument
  52. .IR trid
  53. as if it were returning from the
  54. \fIposix_trace_create_withlog\fR()
  55. function, except that the same allocated resources, for the trace log,
  56. may be reused and the associated trace stream status remains unchanged.
  57. The first trace event recorded in the trace log after the call to
  58. \fIposix_trace_clear\fR()
  59. shall be the same as the first trace event recorded in the active trace
  60. stream after the call to
  61. \fIposix_trace_clear\fR().
  62. The
  63. .IR posix_log_full_status
  64. status shall be set to POSIX_TRACE_NOT_FULL. There is no guarantee
  65. that all trace events that occurred during the
  66. \fIposix_trace_clear\fR()
  67. call are recorded in the trace log; the behavior with respect to trace
  68. points that may occur during this call is unspecified. If the log full
  69. policy is POSIX_TRACE_APPEND, the effect of a call to this function is
  70. unspecified for the trace log associated with the trace stream
  71. identified by the
  72. .IR trid
  73. argument.
  74. .SH "RETURN VALUE"
  75. Upon successful completion, the
  76. \fIposix_trace_clear\fR()
  77. function shall return a value of zero. Otherwise, it shall return the
  78. corresponding error number.
  79. .SH ERRORS
  80. The
  81. \fIposix_trace_clear\fR()
  82. function shall fail if:
  83. .TP
  84. .BR EINVAL
  85. The value of the
  86. .IR trid
  87. argument does not correspond to an active trace stream.
  88. .LP
  89. .IR "The following sections are informative."
  90. .SH EXAMPLES
  91. None.
  92. .SH "APPLICATION USAGE"
  93. None.
  94. .SH RATIONALE
  95. None.
  96. .SH "FUTURE DIRECTIONS"
  97. The
  98. \fIposix_trace_clear\fR()
  99. function may be removed in a future version.
  100. .SH "SEE ALSO"
  101. .ad l
  102. .IR "\fIposix_trace_attr_destroy\fR\^(\|)",
  103. .IR "\fIposix_trace_create\fR\^(\|)",
  104. .IR "\fIposix_trace_get_attr\fR\^(\|)"
  105. .ad b
  106. .P
  107. The Base Definitions volume of POSIX.1\(hy2017,
  108. .IR "\fB<sys_types.h>\fP",
  109. .IR "\fB<trace.h>\fP"
  110. .\"
  111. .SH COPYRIGHT
  112. Portions of this text are reprinted and reproduced in electronic form
  113. from IEEE Std 1003.1-2017, Standard for Information Technology
  114. -- Portable Operating System Interface (POSIX), The Open Group Base
  115. Specifications Issue 7, 2018 Edition,
  116. Copyright (C) 2018 by the Institute of
  117. Electrical and Electronics Engineers, Inc and The Open Group.
  118. In the event of any discrepancy between this version and the original IEEE and
  119. The Open Group Standard, the original IEEE and The Open Group Standard
  120. is the referee document. The original Standard can be obtained online at
  121. http://www.opengroup.org/unix/online.html .
  122. .PP
  123. Any typographical or formatting errors that appear
  124. in this page are most likely
  125. to have been introduced during the conversion of the source files to
  126. man page format. To report such errors, see
  127. https://www.kernel.org/doc/man-pages/reporting_bugs.html .