Tracing data structures

This section describes tracing data structure.

The <trace.h> header file defines the posix_trace_status_info structure and posix_trace_event_info structures.

posix_trace_status_info structure

To facilitate the control of a trace stream, call the posix_trace_get_status subroutine to dynamically obtain the information about the current state of an active trace stream.

The posix_trace_status_info structure defined in the <trace.h> file contains the following members:

Member type	Member name	Description
int	posix_stream_status	The operating mode of the trace stream.
int	posix_stream_full_status	The full status of the trace stream.
int	posix_stream_overrun_status	Indicates whether trace events were lost in the trace stream.
int	posix_stream_flush_status	Indicates whether a flush is in progress.
int	posix_stream_flush_error	Indicates whether any error occurred during the last flush operation.
int	posix_log_overrun_status	Indicates whether trace events were lost in the trace log.
int	posix_log_full_status	The full status of the trace log.

The posix_stream_status member indicates the operating mode of the trace stream. It can have one of the following values defined by the manifest constants in the <trace.h> header:

POSIX_TRACE_RUNNING: The tracing is in progress. The trace stream is accepting trace events.
POSIX_TRACE_SUSPENDED: The trace stream is not accepting trace events. The tracing operation has not started or has stopped, either following a posix_trace_stop subroutine call or because the trace resources are exhausted.

The posix_stream_full_status member indicates the full status of the trace stream. It can have one of the following values defined by manifest constants in the <trace.h> header:

POSIX_TRACE_FULL: The space in the trace stream for trace events is exhausted.
POSIX_TRACE_NOT_FULL: The space in the trace stream is not full.

The combination of the posix_stream_status and posix_stream_full_status members indicate the actual status of the stream. The status can be interpreted as follows:

POSIX_TRACE_RUNNING and POSIX_TRACE_NOT_FULL: The tracing is in progress, and the space is available for recording more trace events.
POSIX_TRACE_RUNNING and POSIX_TRACE_FULL: The tracing is in progress, and the trace stream is full of trace events. If the stream full policy is set to POSIX_TRACE_LOOP, this status might occur. The trace stream contains trace events recorded during a moving time window of previous trace events, and some previous trace events might be overwritten and lost.
POSIX_TRACE_SUSPENDED and POSIX_TRACE_NOT_FULL: The tracing has not started, the posix_trace_stop subroutine stopped the tracing, or the posix_trace_clear subroutine cleared the tracing.
POSIX_TRACE_SUSPENDED and POSIX_TRACE_FULL: The tracing stops. It stops because the stream full policy attribute is set to POSIX_TRACE_UNTIL_FULL and the trace resources is exhausted, or because calling the posix_trace_stop subroutine when the trace resource is exhausted.

The posix_stream_overrun_status member indicates whether trace events are lost in the trace stream. This member can have one of the following values that are defined by manifest constants in the <trace.h> header:

POSIX_TRACE_OVERRUN: At least one trace event is lost and is not recorded in the trace stream.
POSIX_TRACE_NO_OVERRUN: No trace events are lost.

When the corresponding trace stream is created, the posix_stream_overrun_status member is set to POSIX_TRACE_NO_OVERRUN. When an overrun occurs, the status is set to POSIX_TRACE_OVERRUN.

An overrun occurs in the following situations:

The policy is POSIX_TRACE_LOOP and a recorded trace event is overwritten.
The policy is POSIX_TRACE_UNTIL_FULL and the trace stream is full when a trace event is generated.
The policy is POSIX_TRACE_FLUSH and more than one trace event is lost while flushing the trace stream to the trace log.

The posix_stream_overrun_status member is reset to zero after its value is read.

The posix_stream_flush_status member indicates whether a flush operation is being performed and can have one of the following values that the manifest constants in the <trace.h> header file define:

POSIX_TRACE_FLUSHING: The trace stream is being flushed to the trace log.
POSIX_TRACE_NOT_FLUSHING: The posix_stream_flush_status member is set to POSIX_TRACE_NOT_FLUSHING if no flush operation is in progress.

The posix_stream_flush_status member is set to POSIX_TRACE_FLUSHING in the following situations:

A flush operation is in progress because calling the posix_trace_flush subroutine.
A flush operation is in progress because the trace stream becomes full with the stream-full-policy attribute set to POSIX_TRACE_FLUSH.

The posix_stream_flush_error member is set to zero if no error occurs in the flushing. If an error occurs in a previous flushing operation, the posix_stream_flush_error member is set to the value of the first error that occurs. If more than one error occurs in the flushing operation, the first error value is used and the others are discarded. The posix_stream_flush_error member is reset to zero after its value is read.

The posix_log_overrun_status member indicates whether trace events are lost in the trace log. This member can have one of the following values that the manifest constants in the <trace.h> header defines:

POSIX_TRACE_OVERRUN: At least one trace event is lost.
POSIX_TRACE_NO_OVERRUN: No trace event is lost.

Whenever an overrun occurs, the posix_log_overrun_status member is set to POSIX_TRACE_OVERRUN. When the corresponding trace stream is created, the posix_log_overrun_status member is set to POSIX_TRACE_NO_OVERRUN.

The posix_log_overrun_status member is reset to zero after its value is read.

If an active trace stream is created by the posix_trace_create subroutine and it has no log, the posix_log_overrun_status member is set to POSIX_TRACE_NO_OVERRUN.

The posix_log_full_status member indicates the full status of the trace log, and it can have one of the following values defined by manifest constants in the <trace.h> header:

POSIX_TRACE_FULL: The space in the trace log is full.
POSIX_TRACE_NOT_FULL: The space in the trace log is not full.

The posix_log_full_status member is meaningful only when the log-full-policy attribute is either POSIX_TRACE_UNTIL_FULL or POSIX_TRACE_LOOP.

If an active trace stream is created by the posix_trace_create subroutine and it has no log, the posix_log_full_status member is set to POSIX_TRACE_NOT_FULL.

posix_trace_event_info Structure

The trace event structure posix_trace_event_info contains the information for a recorded trace event. The posix_trace_getnext_event, posix_trace_timedgetnext_event, and posix_trace_trygetnext_event subroutines return this subroutine.

The posix_trace_event_info structure that is defined in the <trace.h> header file contains the following members:

Member type	Member name	Description
trace_event_id_t	posix_event_id	Trace event type identification.
pid_t	posix_pid	Process ID of the process that generates the trace event.
void*	posix_prog_address	Address where the trace point is invoked.
int	posix_truncation_status	Truncation status of the data associated with this trace event.
struct timespec	posix_timestamp	Time at which the trace event is generated.
pthread_t	posix_thread_id	ID of the thread that generates the trace event.

The posix_event_id member represents the identification of the trace event type. You cannot define the member value directly. To return the identification, run one of the following subroutines:

posix_trace_trid_eventid_open
posix_trace_eventtypelist_getnext_id
posix_trace_eventid_open

To obtain the name of the trace event type, run the posix_trace_eventid_get_name subroutine.

The posix_pid is the process identifier of the traced process that generates the trace event. If the posix_event_id member is one of the system trace events and the trace event is not associated with any process, the posix_pid member is set to zero.

For a user trace event, the posix_prog_address member is the mapped address of a process and the point at which the associated call to the posix_trace_event subroutine is made.

The posix_truncation_status member defines the truncation status of the data associated with a trace event. The posix_truncation_status member can have one of the following values that the manifest constants in the <trace.h> header define:

POSIX_TRACE_NOT_TRUNCATED: All of the traced data is available.
POSIX_TRACE_TRUNCATED_RECORD: Data is truncated when the trace event is generated.
POSIX_TRACE_TRUNCATED_READ: Data is truncated when the trace event is read from a trace stream or a trace log. This truncation status overrides the POSIX_TRACE_TRUNCATED_RECORD status.

The posix_timestamp member defines the time when the trace event is generated. The clock used is CLOCK_REALTIME. To retrieve the resolution of this clock, call the posix_trace_attr_getclockres subroutine.

The posix_thread_id member is the identifier of the thread that generates the trace event. If the posix_event_id member is one of the system trace events and that trace event is not associated with any thread, the posix_thread_id member is set to zero.