Retrieves a trace event.
#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;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.
| Item | Description |
|---|---|
| trid | Specifies the trace stream identifier. |
| event | Specifies the posix_trace_event_info structure that contains the trace event information of the recorded event. |
| data | Specifies the user data associated with the trace event. |
| num_bytes | Specifies the size, in bytes, of the buffer pointed to by the data parameter. |
| data_len | Specifies the size, in bytes, of the user data record just transferred. |
| unavailable | Specifies the location set to 0 if an event is reported. Otherwise, specifies a value of nonzero. |
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 posix_trace_getnext_event subroutine fails if the following error codes return:
| Item | Description |
|---|---|
| EINVAL | The trace stream identifier parameter trid is not valid. |
| EINTR | The operation was interrupted by a signal, and so the call had no effect. |