.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "POSIX_TRACE_CLEAR" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" posix_trace_clear 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
posix_trace_clear \- clear trace stream and trace log (\fBTRACING\fP)
.SH SYNOPSIS
.LP
\fB#include <sys/types.h>
.br
#include <trace.h>
.br
.sp
int posix_trace_clear(trace_id_t\fP \fItrid\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIposix_trace_clear\fP() function shall reinitialize the trace
stream identified by the argument \fItrid\fP as if it were
returning from the \fIposix_trace_create\fP() function, except that
the same
allocated resources shall be reused, the mapping of trace event type
identifiers to trace event names shall be unchanged, and the
trace stream status shall remain unchanged (that is, if it was running,
it remains running and if it was suspended, it remains
suspended).
.LP
All trace events in the trace stream recorded before the call to \fIposix_trace_clear\fP()
shall be lost. The
\fIposix_stream_full_status\fP status shall be set to POSIX_TRACE_NOT_FULL.
There is no guarantee that all trace events that
occurred during the \fIposix_trace_clear\fP() call are recorded; the
behavior with respect to trace points that may occur during
this call is unspecified.
.LP
If the Trace Log option is supported and the trace stream has been
created with a log, the \fIposix_trace_clear\fP() function
shall reinitialize the trace stream with the same behavior as if the
trace stream was created without the log, plus it shall
reinitialize the trace log associated with the trace stream identified
by the argument \fItrid\fP as if it were returning from the
\fIposix_trace_create_withlog\fP() function, except that the same
allocated resources, for the trace log, may be reused and the associated
trace stream status remains unchanged. The first trace
event recorded in the trace log after the call to \fIposix_trace_clear\fP()
shall be the same as the first trace event recorded in
the active trace stream after the call to \fIposix_trace_clear\fP().
The \fIposix_log_full_status\fP status shall be set to
POSIX_TRACE_NOT_FULL. There is no guarantee that all trace events
that occurred during the \fIposix_trace_clear\fP() call are
recorded in the trace log; the behavior with respect to trace points
that may occur during this call is unspecified. If the log
full policy is POSIX_TRACE_APPEND, the effect of a call to this function
is unspecified for the trace log associated with the trace
stream identified by the \fItrid\fP argument. 
.SH RETURN VALUE
.LP
Upon successful completion, the \fIposix_trace_clear\fP() function
shall return a value of zero. Otherwise, it shall return the
corresponding error number.
.SH ERRORS
.LP
The \fIposix_trace_clear\fP() function shall fail if:
.TP 7
.B EINVAL
The value of the \fItrid\fP argument does not correspond to an active
trace stream.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIposix_trace_attr_init\fP(), \fIposix_trace_create\fP(), \fIposix_trace_flush\fP(),
\fIposix_trace_get_attr\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
\fI<sys/types.h>\fP, \fI<trace.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .