Retrieves a trace event.
#include <sys/types.h>
#include <trace.h>
int posix_trace_trygetnext_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_trygetnext_event subroutine reports a recorded trace event from an active trace stream without a log 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_trygetnext_event subroutine does not block. This function returns an error if the trid parameter identifies a pre-recorded trace stream. If a recorded trace event was reported, the variable pointed to by the unavailable parameter is set to 0. Otherwise, if no trace event was reported, the variable pointed to by the unavailable parameter is set to a value different from zero.
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 recorded trace event data, the data transferred is truncated to a length of num_bytes, 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.
| 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 the value of nonzero. |
On successful completion, the posix_trace_trygetnext_event subroutine returns a value of 0. Otherwise, it returns the corresponding error number.
If successful, the posix_trace_trygetnext_event subroutine stores:
The posix_trace_trygetnext_event subroutine fails if the following error code returns:
| Item | Description |
|---|---|
| EINVAL | The trace stream identifier parameter trid is
not valid. The trace stream identifier parameter trid does not correspond to an active trace stream. |