posix_trace_getnext_event(3p) — Linux manual page

PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

POSIX_T...XT_EVENT(3P)  POSIX Programmer's Manual POSIX_T...XT_EVENT(3P)

PROLOG         top

       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.

NAME         top

       posix_trace_getnext_event, posix_trace_timedgetnext_event,
       posix_trace_trygetnext_event — retrieve a trace event (TRACING)

SYNOPSIS         top

       #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);

DESCRIPTION         top

       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.

RETURN VALUE         top

       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

ERRORS         top

       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.

EXAMPLES         top

       None.

APPLICATION USAGE         top

       None.

RATIONALE         top

       None.

FUTURE DIRECTIONS         top

       These functions may be removed in a future version.

SEE ALSO         top

       posix_trace_close(3p), posix_trace_create(3p)

       The Base Definitions volume of POSIX.1‐2017, sys_types.h(0p),
       trace.h(0p)

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic
       form from IEEE Std 1003.1-2017, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The
       Open Group Base Specifications Issue 7, 2018 Edition, Copyright
       (C) 2018 by the Institute of Electrical and Electronics
       Engineers, Inc and The Open Group.  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.opengroup.org/unix/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               2017            POSIX_T...XT_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)