|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
POSIX_TRACE_GETNEXT_EVENT(3P)IX Programmer's ManualX_TRACE_GETNEXT_EVENT(3P)
This manual page is part of the POSIX Programmer's Manual. The Linux
implementation of this interface may differ (consult the
corresponding Linux manual page for details of Linux behavior), or
the interface may not be implemented on Linux.
posix_trace_getnext_event, posix_trace_timedgetnext_event,
posix_trace_trygetnext_event — retrieve a trace event (TRACING)
#include <sys/types.h>
#include <trace.h>
int posix_trace_getnext_event(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);
int posix_trace_timedgetnext_event(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 abstime);
int posix_trace_trygetnext_event(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() function shall report a recorded
trace event either from an active trace stream without log or a pre-
recorded trace stream identified by the trid argument. The
posix_trace_trygetnext_event() function shall report a recorded trace
event from an active trace stream without log identified by the trid
argument.
The trace event information associated with the recorded trace event
shall be copied by the function into the structure pointed to by the
argument event and the data associated with the trace event shall be
copied into the buffer pointed to by the data argument.
The posix_trace_getnext_event() function shall block if the trid
argument 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
argument shall be set to zero. Otherwise, the variable pointed to by
the unavailable argument shall be set to a value different from zero.
The posix_trace_timedgetnext_event() function shall attempt to get
another trace event from an active trace stream without log, as in
the posix_trace_getnext_event() function. However, if no trace event
is available from the trace stream, the implied wait shall be
terminated when the timeout specified by the argument abstime
expires, and the function shall return the error [ETIMEDOUT].
The timeout shall expire when the absolute time specified by abstime
passes, as measured by the clock upon which timeouts are based (that
is, when the value of that clock equals or exceeds abstime), or if
the absolute time specified by abstime has already passed at the time
of the call.
The timeout shall be based on the CLOCK_REALTIME clock. The
resolution of the timeout shall be the resolution of the clock on
which it is based. The timespec data type is defined in the <time.h>
header.
Under no circumstance shall the function fail with a timeout if a
trace event is immediately available from the trace stream. The
validity of the abstime argument need not be checked if a trace event
is immediately available from the trace stream.
The behavior of this function for a pre-recorded trace stream is
unspecified.
The posix_trace_trygetnext_event() function shall not block. This
function shall return an error if the trid argument identifies a pre-
recorded trace stream. If a recorded trace event was reported, the
variable pointed to by the unavailable argument shall be set to zero.
Otherwise, if no trace event was reported, the variable pointed to by
the unavailable argument shall be set to a value different from zero.
The argument num_bytes shall be the size of the buffer pointed to by
the data argument. The argument data_len 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 argument, all the recorded data
shall be transferred. In this case, the truncation-status member of
the trace event structure shall be 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 argument is less
than the length of recorded trace event data, the data transferred
shall be truncated to a length of num_bytes, the value stored in the
variable pointed to by data_len shall be equal to num_bytes, and the
truncation-status member of the event structure argument shall be set
to POSIX_TRACE_TRUNCATED_READ (see the posix_trace_event_info
structure defined in <trace.h>).
The report of a trace event shall be sequential starting from the
oldest recorded trace event. Trace events shall be 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. Once reported, a trace event
cannot be reported again from an active trace stream. Once a trace
event is reported from an active trace stream without log, the trace
stream shall make the resources associated with that trace event
available to record future generated trace events.
Upon successful completion, these functions shall return a value of
zero. Otherwise, they shall return the corresponding error number.
If successful, these functions store:
* 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 zero in the object pointed to by unavailable
These functions shall fail if:
EINVAL The trace stream identifier argument trid is invalid.
The posix_trace_getnext_event() and posix_trace_timedgetnext_event()
functions shall fail if:
EINTR The operation was interrupted by a signal, and so the call had
no effect.
The posix_trace_trygetnext_event() function shall fail if:
EINVAL The trace stream identifier argument trid does not correspond
to an active trace stream.
The posix_trace_timedgetnext_event() function shall fail if:
EINVAL There is no trace event immediately available from the trace
stream, and the timeout argument is invalid.
ETIMEDOUT
No trace event was available from the trace stream before the
specified timeout timeout expired.
The following sections are informative.
None.
None.
None.
These functions may be removed in a future version.
posix_trace_close(3p), posix_trace_create(3p)
The Base Definitions volume of POSIX.1‐2008, sys_types.h(0p),
trace.h(0p)
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information
Technology -- Portable Operating System Interface (POSIX), The Open
Group Base Specifications Issue 7, Copyright (C) 2013 by the
Institute of Electrical and Electronics Engineers, Inc and The Open
Group. (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
applied.) In the event of any discrepancy between this version and
the original IEEE and The Open Group Standard, the original IEEE and
The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.unix.org/online.html .
Any typographical or formatting errors that appear in this page are
most likely to have been introduced during the conversion of the
source files to man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2013 POSIX_TRACE_GETNEXT_EVENT(3P)
Pages that refer to this page: trace.h(0p), posix_trace_attr_getinherited(3p), posix_trace_close(3p), posix_trace_create(3p), posix_trace_eventid_equal(3p), posix_trace_eventtypelist_getnext_id(3p), posix_trace_timedgetnext_event(3p), posix_trace_trygetnext_event(3p)