posix_trace_clear Subroutine
Purpose
Clears trace stream and trace log.
Library
Posix Trace Library (libposixtrace.a)
Syntax
#include <sys/types.h>
#include <trace.h>
int posix_trace_clear(trid)
trace_id_t trid;Description
The posix_trace_clear subroutine initializes the trace stream that is identified by the trid parameter again. It returns the same result as that of the posix_trace_create subroutine. The posix_trace_clear subroutine reuses the allocated resources of the posix_trace_create subroutine, but does not change the mapping of trace event type identifiers, which is used to trace event names, and it does not change the trace stream status.
All trace events in the trace stream that is recorded before the call to the
posix_trace_clear subroutine are lost. The status of the
posix_stream_full_status is set to the POSIX_TRACE_NOT_FULL status.
There is no guarantee that all trace events that occurred during the
posix_trace_clear call are recorded.
If the trace stream is created with a log, the posix_trace_clear subroutine
initializes the trace stream with the same behavior again as if the trace stream was created without
the log. It initializes the trace log associated with the trace stream that is identified by the
trid parameter again. It uses the same allocated resources for the trace log of
the posix_trace_create_withlog subroutine and the associated trace stream status
remains unchanged. The first trace event that is recorded in the trace log after the call to the
posix_trace_clear subroutine is the same as the first trace event recorded in the
active trace stream after the call to posix_trace_clear subroutine. The
posix_log_full_status status is set to POSIX_TRACE_NOT_FULL and the
posix_log_overrun_status is set to POSIX_TRACE_NO_OVERRUN. There is no
guarantee that all trace events that occurred during the posix_trace_clear call
are recorded in the trace log. If the log full policy is POSIX_TRACE_APPEND, the stream and
the trace log are initialized again as if it is returning from the
posix_trace_withlog subroutine.
Parameters
| Item | Description |
|---|---|
| trid | Specifies the trace stream identifier of an active trace stream. |
Return Values
Upon successful completion, the posix_trace_clear subroutine returns a value of zero. Otherwise, it returns the corresponding error number.
Errors
| Item | Description |
|---|---|
EINVAL |
The value of the trid parameter does not correspond to an active trace stream. |