trace.h File

Purpose

Defines implementation trace that IEEE POSIX 1003 identifies.

Description

The <trace.h> header defines the posix_trace_event_info structure that includes the following members:

trace_event_id_t          posix_event_id
pid_t                     posix_pid
void                     *posix_prog_address
int                       posix_truncation_status
struct timespec           posix_timestamp
pthread_t                 posix_thread_id

The <trace.h> header defines the posix_trace_status_info structure that includes the following members:

int     posix_stream_status
int     posix_stream_full_status
int     posix_stream_overrun_status
int     posix_stream_flush_status
int     posix_stream_flush_error
int     posix_log_overrun_status
int     posix_log_full_status

The <trace.h> header defines the following symbols:
Table 1. Symbols for the trace.h header
Symbol Usage Description
POSIX_TRACE_ADD_EVENTSET how argument of the posix_trace_set_filter() function

The resulting set of trace event types to be filtered is the union of the current set and the trace event type set that the argument set points to.
POSIX_TRACE_ALL_EVENTS what argument of the posix_trace_eventset_fill() function

All trace event types defined, both system and user, are included in the set.
POSIX_TRACE_APPEND logpolicy argument of the posix_trace_attr_setlogfullpolicy() function

The associated trace stream is flushed to the trace log without log size limitation.
POSIX_TRACE_CLOSE_FOR_CHILD inheritancepolicy argument of the posix_trace_eventset_fill() function

After a fork() operation or a spawn() operation, the child is not traced, and tracing of the parent continues.
POSIX_TRACE_FILTER  

This event is recorded in the stream when a trace-event-type filter is changed.

POSIX_TRACE_FLUSH streampolicy argument of the posix_trace_attr_setstreamfullpolicy() function

This policy is identical to the POSIX_TRACE_UNTIL_FULL trace-stream full policy, except that the trace stream is flushed regularly as if the posix_trace_flush() operation has been explicitly called.

POSIX_TRACE_FLUSH_START  

This event is recorded in the stream marking the beginning of a flush operation.
POSIX_TRACE_FLUSH_STOP  

This event is recorded in the stream marking the end of a flush operation.

POSIX_TRACE_FLUSHING posix_stream_flush_status member of the posix_trace_status_info structure

The trace stream is being flushed to the trace log.

POSIX_TRACE_FULL posix_stream_full_status member of the posix_trace_status_info structure

The space in the trace stream for trace events is exhausted.

POSIX_TRACE_FULL posix_log_full_status member of the posix_trace_status_info structure

The space in the trace log is exhausted.
POSIX_TRACE_LOOP streampolicy argument of the posix_trace_attr_setstreamfullpolicy() function

The trace stream loops until the posix_trace_stop() subroutine explicitly stops it.

POSIX_TRACE_LOOP logpolicy argument of the posix_trace_attr_setlogfullpolicy() function

The trace log loops until the associated trace stream is stopped.

POSIX_TRACE_NO_OVERRUN posix_stream_overrun_status member of the posix_trace_status_info structure

No trace events are lost in the stream.
POSIX_TRACE_NO_OVERRUN posix_log_overrun_status member of the posix_trace_status_info structure

No trace events are lost in the trace log.
POSIX_TRACE_NOT_FLUSHING posix_stream_flush_status member of the posix_trace_status_info structure

No flush operation is in progress.
POSIX_TRACE_NOT_FULL posix_stream_full_status member of the posix_trace_status_info structure

There is space available in the trace stream.
POSIX_TRACE_NOT_FULL posix_log_full_status member of the posix_trace_status_info structure

There is space available in the trace log.
POSIX_TRACE_INHERITED inheritancepolicy argument of the posix_trace_attr_setinherited() function

After a fork() operation or a spawn() operation, if the parent is traced, its child is traced concurrently using the same trace stream.
POSIX_TRACE_NOT_TRUNCATED posix_truncation_status member of the posix_trace_event_info structure

All of the traced data is available.

POSIX_TRACE_OVERFLOW  

This event is recorded in the stream marking the beginning of a trace overflow condition.

POSIX_TRACE_OVERRUN posix_stream_overrun_status member of the posix_trace_status_info structure

At least one trace event is lost and not recorded in the trace stream.
POSIX_TRACE_OVERRUN posix_log_overrun_status member of the posix_trace_status_info structure

At least one trace event is lost in the trace log.
POSIX_TRACE_RESUME  

This event is recorded in the stream marking the end of a trace overflow condition.

POSIX_TRACE_RUNNING posix_stream_status member of the posix_trace_status_info structure

Tracing is in progress.
POSIX_TRACE_SET_EVENTSET how argument of the posix_trace_set_filter() function

The resulting set of trace event types to be filtered is the trace event type set that the argument set points to.
POSIX_TRACE_START  

This event is recorded in the stream on a trace start operation.
POSIX_TRACE_STOP  

This event is recorded in the stream on a trace stop operation.

POSIX_TRACE_SUB_EVENTSET how argument of the posix_trace_set_filter() function

The resulting set of trace event types to be filtered includes all trace event types in the current set. These trace event types are not in the set pointed to by the argument set. Each element of the current set of trace event types is removed from the current filter.

POSIX_TRACE_SUSPENDED posix_stream_status member of the posix_trace_status_info structure

The tracing operation has not started, or has stopped.

POSIX_TRACE_SYSTEM_EVENTS what argument of the posix_trace_eventset_fill() function

All the system-trace-event types are included in the set.
POSIX_TRACE_TRUNCATED_READ posix_truncation_status member of the posix_trace_event_info structure

Data is truncated at the time the trace event is read from a trace stream or a trace log because the reader's buffer is too small.

POSIX_TRACE_TRUNCATED_RECORD posix_truncation_status member of the posix_trace_event_info structure

Data is truncated at the time the trace event is generated.

POSIX_TRACE_UNNAMED_USER_EVENT  

If the per-process user name of the trace event is reached, the POSIX_TRACE_UNNAMED_USEREVENT user trace event is returned on posix_trace_eventid_open() or posix_trace_trid_eventid_open().

POSIX_TRACE_UNTIL_FULL streampolicy argument of the posix_trace_attr_getstreamfullpolicy() function

The trace stream runs until the trace stream resources are exhausted; then the trace stream stops.
POSIX_TRACE_UNTIL_FULL logpolicy argument of the posix_trace_attr_getlogfullpolicy() function

The trace stream is flushed to the trace log until the trace log is full.

POSIX_TRACE_WOPID_EVENTS what argument of the posix_trace_eventset_fill() function

All the process-independent, system-trace-event types are included in the set.
The following types are defined as described in the header types.h file:

trace_attr_t
trace_id_t
trace_event_id_t
trace_event_set_t

int  posix_trace_attr_destroy(trace_attr_t *);
int  posix_trace_attr_getclockres(const trace_attr_t *,
         struct timespec *);
int  posix_trace_attr_getcreatetime(const trace_attr_t *,
         struct timespec *);
int  posix_trace_attr_getgenversion(const trace_attr_t *, char *);
int  posix_trace_attr_getinherited(const trace_attr_t *restrict,
         int *restrict);
int  posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict,
         int *restrict);
int  posix_trace_attr_getlogsize(const trace_attr_t *restrict,
         size_t *restrict);
int  posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict,
         size_t *restrict);
int  posix_trace_attr_getmaxsystemeventsize(const trace_attr_t *restrict,
         size_t *restrict);
int  posix_trace_attr_getmaxusereventsize(const trace_attr_t *restrict,
         size_t, size_t *restrict);
int  posix_trace_attr_getname(const trace_attr_t *, char *);
int  posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict,
         int *restrict);
int  posix_trace_attr_getstreamsize(const trace_attr_t *restrict,
         size_t *restrict);
int  posix_trace_attr_init(trace_attr_t *);
int  posix_trace_attr_setinherited(trace_attr_t *, int);
int  posix_trace_attr_setlogfullpolicy(trace_attr_t *, int);
int  posix_trace_attr_setlogsize(trace_attr_t *, size_t);
int  posix_trace_attr_setmaxdatasize(trace_attr_t *, size_t);
int  posix_trace_attr_setname(trace_attr_t *, const char *);
int  posix_trace_attr_setstreamsize(trace_attr_t *, size_t);
int  posix_trace_attr_setstreamfullpolicy(trace_attr_t *, int);
int  posix_trace_clear(trace_id_t);
int  posix_trace_close(trace_id_t);
int  posix_trace_create(pid_t, const trace_attr_t *restrict,
         trace_id_t *restrict);
int  posix_trace_create_withlog(pid_t, const trace_attr_t *restrict,
         int, trace_id_t *restrict);
void posix_trace_event(trace_event_id_t, const void *restrict, size_t);
int  posix_trace_eventid_equal(trace_id_t, trace_event_id_t,
         trace_event_id_t);
int  posix_trace_eventid_get_name(trace_id_t, trace_event_id_t, char *);
int  posix_trace_eventid_open(const char *restrict,
         trace_event_id_t *restrict);
int  posix_trace_eventset_add(trace_event_id_t, trace_event_set_t *);
int  posix_trace_eventset_del(trace_event_id_t, trace_event_set_t *);
int  posix_trace_eventset_empty(trace_event_set_t *);
int  posix_trace_eventset_fill(trace_event_set_t *, int);
int  posix_trace_eventset_ismember(trace_event_id_t,
         const trace_event_set_t *restrict, int *restrict);
int  posix_trace_eventtypelist_getnext_id(trace_id_t,
         trace_event_id_t *restrict, int *restrict);
int  posix_trace_eventtypelist_rewind(trace_id_t);
int  posix_trace_flush(trace_id_t);
int  posix_trace_get_attr(trace_id_t, trace_attr_t *);
int  posix_trace_get_filter(trace_id_t, trace_event_set_t *);
int  posix_trace_get_status(trace_id_t,
         struct posix_trace_status_info *);
int  posix_trace_getnext_event(trace_id_t,
         struct posix_trace_event_info *restrict , void *restrict,
         size_t, size_t *restrict, int *restrict);
int  posix_trace_open(int, trace_id_t *);
int  posix_trace_rewind(trace_id_t);
int  posix_trace_set_filter(trace_id_t, const trace_event_set_t *, int);
int  posix_trace_shutdown(trace_id_t);
int  posix_trace_start(trace_id_t);
int  posix_trace_stop(trace_id_t);
int  posix_trace_timedgetnext_event(trace_id_t,
         struct posix_trace_event_info *restrict, void *restrict,
         size_t, size_t *restrict, int *restrict,
         const struct timespec *restrict);
int  posix_trace_trid_eventid_open(trace_id_t, const char *restrict,
          trace_event_id_t *restrict);
int  posix_trace_trygetnext_event(trace_id_t,
          struct posix_trace_event_info *restrict, void *restrict, size_t,
          size_t *restrict, int *restrict);