posix_trace_flush Subroutine

Purpose

Initiates a flush on the trace stream.

Library

Posix Trace Library (libposixtrace.a)

Syntax

#include <sys/types.h>
#include <trace.h>

int posix_trace_flush (trid)
trace_id_t trid;

Description

The posix_trace_flush subroutine initiates a flush operation that copies the contents of the trace stream identified by the trid parameter into the trace log associated with the trace stream at the creation time. If no trace log has been associated with the trace stream pointed to by the trid parameter, this subroutine returns an error. The termination of the flush operation can be polled by the posix_trace_get_status subroutine. After the flushing is completed, the space used by the flushed trace events is available for tracing new trace events. During the flushing operation, it is possible to trace new trace events until the trace stream becomes full.

If flushing the trace stream makes the trace log full, the trace log full policy is applied. If the trace log-full-policy attribute is set, the following occurs:
POSIX_TRACE_UNTIL_FULL
The trace events that have not been flushed are discarded.
POSIX_TRACE_LOOP
The trace events that have not been flushed are written to the beginning of the trace log, overwriting previous trace events stored there.
POSIX_TRACE_APPEND
The trace events that have not been flushed are appended to the trace log.

For an active trace stream with the log, when the posix_trace_shutdown subroutine is called, all trace events that have not been flushed to the trace log are flushed, and the trace log is closed.

When a trace log is closed, all the information that can be retrieved later from the trace log through the trace interface are written to the trace log. This information includes the trace attributes, the list of trace event types (with the mapping between trace event names and trace event type identifiers), and the trace status.

The posix_trace_shutdown subroutine does not return until all trace events have been flushed.

Parameters

Item Description
trid Specifies the trace stream identifier.

Return Values

On successful completion, these subroutines return a value of zero. Otherwise, they return the corresponding error number.

Errors

Item Description
EINVAL The value of the trid parameter does not correspond to an active trace stream with log.
ENOSPC No space left on device.

Files

The trace.h and the types.h files in AIX® Version 7.1 Files Reference.