posix_trace_timedgetnext_event Subroutine

Purpose

Retrieves a trace event.

Syntax

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

int posix_trace_timedgetnext_event
(trid, event, data, num_bytes, data_len, unavailable, abs_timeout)
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;
const struct timespec *restrict abs_timeout;

Description

The posix_trace_timedgetnext_event subroutine attempts to get another trace event from an active trace stream without a log, as in the posix_trace_getnext_event subroutine. However, if no trace event is available from the trace stream, the implied wait terminates when the timeout specified by the parameter abs_timeout expires, and the function returns the error [ETIMEDOUT].

The timeout expires when the absolute time specified by abs_timeout passes or has already passed at the time of the call. The absolute time specified by the abs_timeout is measured by the clock on which a timeout is based (that is, when the value of that clock equals or exceeds abs_timeout).

The timeout is based on the CLOCK_REALTIME clock. The resolution of the timeout is the resolution of the CLOCK_REALTIME. The timespec data type is defined in the time.h header file.

The function never fails with a timeout if a trace event is immediately available from the trace stream. The validity of the abs_timeout parameter is not checked if a trace event is immediately available from the trace stream.

The behavior of this subroutine for a pre-recorded trace stream is not specified.

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 the num_bytes parameter, 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 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 a 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_timedgetnext_event subroutine returns a value of 0. Otherwise, it returns the corresponding error number.

If successful, the posix_trace_timedgetnext_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_timedgetnext_event subroutine fails if the following error codes return:

Files

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