POSIX_TRACE_GETNEXT_EVENT(3)POSIX Programmer's ManuaPlOSIX_TRACE_GETNEXT_EVENT(3)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NAME
       posix_trace_getnext_event, posix_trace_timedgetnext_event,
       posix_trace_trygetnext_event -- retrieve a trace event (TRACING)

SYNOPSIS
       #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
       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
       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
       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
       None.

APPLICATION USAGE
       None.

RATIONALE
       None.

FUTURE DIRECTIONS
       These functions may be removed in a future version.

SEE ALSO
       posix__trace__close(), posix__trace__create()

       The Base Definitions volume of POSIX.1-2017, <sys_types.h>, <trace.h>

COPYRIGHT
       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_TRACE_GETNEXT_EVENT(3)
