man3p/posix_trace_clear.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "POSIX_TRACE_CLEAR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" posix_trace_clear
   4 .SH NAME
   5 posix_trace_clear \- clear trace stream and trace log (\fBTRACING\fP)
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <sys/types.h>
   9 .br
  10 #include <trace.h>
  11 .br
  12 .sp
  13 int posix_trace_clear(trace_id_t\fP \fItrid\fP\fB); \fP
  14 \fB
  15 .br
  16 \fP
  17 .SH DESCRIPTION
  18 .LP
  19 The \fIposix_trace_clear\fP() function shall reinitialize the trace
  20 stream identified by the argument \fItrid\fP as if it were
  21 returning from the \fIposix_trace_create\fP() function, except that
  22 the same
  23 allocated resources shall be reused, the mapping of trace event type
  24 identifiers to trace event names shall be unchanged, and the
  25 trace stream status shall remain unchanged (that is, if it was running,
  26 it remains running and if it was suspended, it remains
  27 suspended).
  28 .LP
  29 All trace events in the trace stream recorded before the call to \fIposix_trace_clear\fP()
  30 shall be lost. The
  31 \fIposix_stream_full_status\fP status shall be set to POSIX_TRACE_NOT_FULL.
  32 There is no guarantee that all trace events that
  33 occurred during the \fIposix_trace_clear\fP() call are recorded; the
  34 behavior with respect to trace points that may occur during
  35 this call is unspecified.
  36 .LP
  37 If the Trace Log option is supported and the trace stream has been
  38 created with a log, the \fIposix_trace_clear\fP() function
  39 shall reinitialize the trace stream with the same behavior as if the
  40 trace stream was created without the log, plus it shall
  41 reinitialize the trace log associated with the trace stream identified
  42 by the argument \fItrid\fP as if it were returning from the
  43 \fIposix_trace_create_withlog\fP() function, except that the same
  44 allocated resources, for the trace log, may be reused and the associated
  45 trace stream status remains unchanged. The first trace
  46 event recorded in the trace log after the call to \fIposix_trace_clear\fP()
  47 shall be the same as the first trace event recorded in
  48 the active trace stream after the call to \fIposix_trace_clear\fP().
  49 The \fIposix_log_full_status\fP status shall be set to
  50 POSIX_TRACE_NOT_FULL. There is no guarantee that all trace events
  51 that occurred during the \fIposix_trace_clear\fP() call are
  52 recorded in the trace log; the behavior with respect to trace points
  53 that may occur during this call is unspecified. If the log
  54 full policy is POSIX_TRACE_APPEND, the effect of a call to this function
  55 is unspecified for the trace log associated with the trace
  56 stream identified by the \fItrid\fP argument.
  57 .SH RETURN VALUE
  58 .LP
  59 Upon successful completion, the \fIposix_trace_clear\fP() function
  60 shall return a value of zero. Otherwise, it shall return the
  61 corresponding error number.
  62 .SH ERRORS
  63 .LP
  64 The \fIposix_trace_clear\fP() function shall fail if:
  65 .TP 7
  66 .B EINVAL
  67 The value of the \fItrid\fP argument does not correspond to an active
  68 trace stream.
  69 .sp
  70 .LP
  71 \fIThe following sections are informative.\fP
  72 .SH EXAMPLES
  73 .LP
  74 None.
  75 .SH APPLICATION USAGE
  76 .LP
  77 None.
  78 .SH RATIONALE
  79 .LP
  80 None.
  81 .SH FUTURE DIRECTIONS
  82 .LP
  83 None.
  84 .SH SEE ALSO
  85 .LP
  86 \fIposix_trace_attr_init\fP() , \fIposix_trace_create\fP() , \fIposix_trace_flush\fP()
  87 , \fIposix_trace_get_attr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
  88 \fI<sys/types.h>\fP, \fI<trace.h>\fP
  89 .SH COPYRIGHT
  90 Portions of this text are reprinted and reproduced in electronic form
  91 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
  92 -- Portable Operating System Interface (POSIX), The Open Group Base
  93 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
  94 Electrical and Electronics Engineers, Inc and The Open Group. In the
  95 event of any discrepancy between this version and the original IEEE and
  96 The Open Group Standard, the original IEEE and The Open Group Standard
  97 is the referee document. The original Standard can be obtained online at
  98 http://www.opengroup.org/unix/online.html .