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 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 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 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 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. |