posix_trace_getnext_event Subroutine

Purpose

Retrieves a trace event.

Syntax

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

int posix_trace_getnext_event(trid, event, data, num_bytes, data_len, unavailable)
trace_id_t trid;
struct posix_trace_event_info *restrict event;
void *restrict data;
size_t num_bytes;
size_t *restrict data_len;
int *restrict unavailable;

Description

The posix_trace_getnext_event subroutine reports a recorded trace event either from an active trace stream without a log or a pre-recorded trace stream identified by the trid parameter.

The trace event information associated with the recorded trace event is copied by the function into the structure pointed to by the event parameter, and the data associated with the trace event is copied into the buffer pointed to by the data parameter.

The posix_trace_getnext_event subroutine blocks if the trid parameter identifies an active trace stream and there is currently no trace event ready to be retrieved. When returning, if a recorded trace event was reported, the variable pointed to by the unavailable parameter is set to 0. Otherwise, the variable pointed to by the unavailable parameter is set to a value different from 0.

The num_bytes parameter equals the size of the buffer pointed to by the data parameter. The data_len parameter reports to the application the length, in bytes, of the data record just transferred. If num_bytes is greater than or equal to the size of the data associated with the trace event pointed to by the event parameter, all the recorded data is transferred. In this case, the truncation-status member of the trace event structure is either POSIX_TRACE_NOT_TRUNCATED (if the trace event data was recorded without truncation while tracing) or POSIX_TRACE_TRUNCATED_RECORD (if the trace event data was truncated when it was recorded). If the num_bytes parameter is less than the length of the recorded trace event data, the data transferred is truncated to the length of num_bytes, that is the value stored in the variable pointed to by data_len equals num_bytes, and the truncation-status member of the event structure parameter is set to POSIX_TRACE_TRUNCATED_READ (see the posix_trace_event_info structure defined in trace.h).

The report of a trace event is sequential starting from the oldest recorded trace event. Trace events are reported in the order in which they were generated, up to an implementation-defined time resolution that causes the ordering of trace events to be occurring very close to each other to be unknown. After it is reported, a trace event cannot be reported again from an active trace stream. After a trace event is reported from an active trace stream without the log, the trace stream makes the resources associated with that trace event available to record future generated trace events.

Parameters

Return Values

On successful completion, the posix_trace_getnext_event subroutine returns a value of 0. Otherwise, it returns the corresponding error number.

If successful, the posix_trace_getnext_event subroutine stores:

• The recorded trace event in the object pointed to by event
• The trace event information associated with the recorded trace event in the object pointed to by data
• The length of this trace event information in the object pointed to by data_len
• The value of 0 in the object pointed to by unavailable

Error Codes

the posix_trace_getnext_event subroutine fails if the following error codes return:

Files

The pthread.h, trace.h and types.h in Files Reference.