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



PPRROOLLOOGG
       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.

NNAAMMEE
       posix_trace_getnext_event, posix_trace_timedgetnext_event,
       posix_trace_trygetnext_event -- retrieve a trace event (TTRRAACCIINNGG)

SSYYNNOOPPSSIISS
       #include <sys/types.h>
       #include <trace.h>

       int posix_trace_getnext_event(trace_id_t _t_r_i_d,
           struct posix_trace_event_info *restrict _e_v_e_n_t,
           void *restrict _d_a_t_a, size_t _n_u_m___b_y_t_e_s,
           size_t *restrict _d_a_t_a___l_e_n, int *restrict _u_n_a_v_a_i_l_a_b_l_e);
       int posix_trace_timedgetnext_event(trace_id_t _t_r_i_d,
           struct posix_trace_event_info *restrict _e_v_e_n_t,
           void *restrict _d_a_t_a, size_t _n_u_m___b_y_t_e_s,
           size_t *restrict _d_a_t_a___l_e_n, int *restrict _u_n_a_v_a_i_l_a_b_l_e,
           const struct timespec *restrict _a_b_s_t_i_m_e);
       int posix_trace_trygetnext_event(trace_id_t _t_r_i_d,
           struct posix_trace_event_info *restrict _e_v_e_n_t,
           void *restrict _d_a_t_a, size_t _n_u_m___b_y_t_e_s,
           size_t *restrict _d_a_t_a___l_e_n, int *restrict _u_n_a_v_a_i_l_a_b_l_e);

DDEESSCCRRIIPPTTIIOONN
       The _p_o_s_i_x___t_r_a_c_e___g_e_t_n_e_x_t___e_v_e_n_t() function shall report a recorded trace
       event either from an active trace stream without log or a pre-recorded
       trace stream identified by the _t_r_i_d argument.  The
       _p_o_s_i_x___t_r_a_c_e___t_r_y_g_e_t_n_e_x_t___e_v_e_n_t() function shall report a recorded trace
       event from an active trace stream without log identified by the _t_r_i_d
       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 _e_v_e_n_t and the data associated with the trace event shall be
       copied into the buffer pointed to by the _d_a_t_a argument.

       The _p_o_s_i_x___t_r_a_c_e___g_e_t_n_e_x_t___e_v_e_n_t() function shall block if the _t_r_i_d
       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 _u_n_a_v_a_i_l_a_b_l_e argument
       shall be set to zero. Otherwise, the variable pointed to by the
       _u_n_a_v_a_i_l_a_b_l_e argument shall be set to a value different from zero.

       The _p_o_s_i_x___t_r_a_c_e___t_i_m_e_d_g_e_t_n_e_x_t___e_v_e_n_t() function shall attempt to get
       another trace event from an active trace stream without log, as in the
       _p_o_s_i_x___t_r_a_c_e___g_e_t_n_e_x_t___e_v_e_n_t() 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 _a_b_s_t_i_m_e expires, and the
       function shall return the error [[EETTIIMMEEDDOOUUTT]].

       The timeout shall expire when the absolute time specified by _a_b_s_t_i_m_e
       passes, as measured by the clock upon which timeouts are based (that
       is, when the value of that clock equals or exceeds _a_b_s_t_i_m_e), or if the
       absolute time specified by _a_b_s_t_i_m_e 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 ttiimmeessppeecc data type is defined in the _<_t_i_m_e_._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 _a_b_s_t_i_m_e 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 _p_o_s_i_x___t_r_a_c_e___t_r_y_g_e_t_n_e_x_t___e_v_e_n_t() function shall not block.  This
       function shall return an error if the _t_r_i_d argument identifies a pre-
       recorded trace stream.  If a recorded trace event was reported, the
       variable pointed to by the _u_n_a_v_a_i_l_a_b_l_e argument shall be set to zero.
       Otherwise, if no trace event was reported, the variable pointed to by
       the _u_n_a_v_a_i_l_a_b_l_e argument shall be set to a value different from zero.

       The argument _n_u_m___b_y_t_e_s shall be the size of the buffer pointed to by
       the _d_a_t_a argument. The argument _d_a_t_a___l_e_n reports to the application the
       length in bytes of the data record just transferred. If _n_u_m___b_y_t_e_s is
       greater than or equal to the size of the data associated with the trace
       event pointed to by the _e_v_e_n_t argument, all the recorded data shall be
       transferred. In this case, the _t_r_u_n_c_a_t_i_o_n_-_s_t_a_t_u_s 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 _n_u_m___b_y_t_e_s argument is less than the length
       of recorded trace event data, the data transferred shall be truncated
       to a length of _n_u_m___b_y_t_e_s, the value stored in the variable pointed to
       by _d_a_t_a___l_e_n shall be equal to _n_u_m___b_y_t_e_s, and the _t_r_u_n_c_a_t_i_o_n_-_s_t_a_t_u_s
       member of the _e_v_e_n_t structure argument shall be set to
       POSIX_TRACE_TRUNCATED_READ (see the ppoossiixx__ttrraaccee__eevveenntt__iinnffoo structure
       defined in _<_t_r_a_c_e_._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.

RREETTUURRNN VVAALLUUEE
       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 _e_v_e_n_t

        *  The trace event information associated with the recorded trace
           event in the object pointed to by _d_a_t_a

        *  The length of this trace event information in the object pointed to
           by _d_a_t_a___l_e_n

        *  The value of zero in the object pointed to by _u_n_a_v_a_i_l_a_b_l_e

EERRRROORRSS
       These functions shall fail if:

       EEIINNVVAALL The trace stream identifier argument _t_r_i_d is invalid.

       The _p_o_s_i_x___t_r_a_c_e___g_e_t_n_e_x_t___e_v_e_n_t() and _p_o_s_i_x___t_r_a_c_e___t_i_m_e_d_g_e_t_n_e_x_t___e_v_e_n_t()
       functions shall fail if:

       EEIINNTTRR  The operation was interrupted by a signal, and so the call had
              no effect.

       The _p_o_s_i_x___t_r_a_c_e___t_r_y_g_e_t_n_e_x_t___e_v_e_n_t() function shall fail if:

       EEIINNVVAALL The trace stream identifier argument _t_r_i_d does not correspond to
              an active trace stream.

       The _p_o_s_i_x___t_r_a_c_e___t_i_m_e_d_g_e_t_n_e_x_t___e_v_e_n_t() function shall fail if:

       EEIINNVVAALL There is no trace event immediately available from the trace
              stream, and the _t_i_m_e_o_u_t argument is invalid.

       EETTIIMMEEDDOOUUTT
              No trace event was available from the trace stream before the
              specified timeout _t_i_m_e_o_u_t expired.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       These functions may be removed in a future version.

SSEEEE AALLSSOO
       _p_o_s_i_x___t_r_a_c_e___c_l_o_s_e(), _p_o_s_i_x___t_r_a_c_e___c_r_e_a_t_e()

       The Base Definitions volume of POSIX.1-2017, <<ssyyss__ttyyppeess..hh>>, <<ttrraaccee..hh>>

CCOOPPYYRRIIGGHHTT
       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)
