POSIX_TRACE_EVENT(3)       POSIX Programmer's Manual      POSIX_TRACE_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_event, posix_trace_eventid_open -- trace functions for
       instrumenting application code (TTRRAACCIINNGG)

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

       void posix_trace_event(trace_event_id_t _e_v_e_n_t___i_d,
           const void *restrict _d_a_t_a___p_t_r, size_t _d_a_t_a___l_e_n);
       int posix_trace_eventid_open(const char *restrict _e_v_e_n_t___n_a_m_e,
           trace_event_id_t *restrict _e_v_e_n_t___i_d);

DDEESSCCRRIIPPTTIIOONN
       The _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t() function shall record the _e_v_e_n_t___i_d and the user
       data pointed to by _d_a_t_a___p_t_r in the trace stream into which the calling
       process is being traced and in which _e_v_e_n_t___i_d is not filtered out. If
       the total size of the user trace event data represented by _d_a_t_a___l_e_n is
       not greater than the declared maximum size for user trace event data,
       then the _t_r_u_n_c_a_t_i_o_n_-_s_t_a_t_u_s attribute of the trace event recorded is
       POSIX_TRACE_NOT_TRUNCATED.  Otherwise, the user trace event data is
       truncated to this declared maximum size and the _t_r_u_n_c_a_t_i_o_n_-_s_t_a_t_u_s
       attribute of the trace event recorded is POSIX_TRACE_TRUNCATED_RECORD.

       If there is no trace stream created for the process or if the created
       trace stream is not running, or if the trace event specified by
       _e_v_e_n_t___i_d is filtered out in the trace stream, the _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t()
       function shall have no effect.

       The _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t_i_d___o_p_e_n() function shall associate a user trace
       event name with a trace event type identifier for the calling process.
       The trace event name is the string pointed to by the argument
       _e_v_e_n_t___n_a_m_e.  It shall have a maximum of {TRACE_EVENT_NAME_MAX}
       characters (which has the minimum value {_POSIX_TRACE_EVENT_NAME_MAX}).
       The number of user trace event type identifiers that can be defined for
       any given process is limited by the maximum value
       {TRACE_USER_EVENT_MAX}, which has the minimum value
       {POSIX_TRACE_USER_EVENT_MAX}.

       If the Trace Inherit option is not supported, the
       _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t_i_d___o_p_e_n() function shall associate the user trace
       event name pointed to by the _e_v_e_n_t___n_a_m_e argument with a trace event
       type identifier that is unique for the traced process, and is returned
       in the variable pointed to by the _e_v_e_n_t___i_d argument. If the user trace
       event name has already been mapped for the traced process, then the
       previously assigned trace event type identifier shall be returned. If
       the per-process user trace event name limit represented by
       {TRACE_USER_EVENT_MAX} has been reached, the pre-defined
       POSIX_TRACE_UNNAMED_USEREVENT (see _T_a_b_l_e _2_-_7, _T_r_a_c_e _O_p_t_i_o_n_: _U_s_e_r _T_r_a_c_e
       _E_v_e_n_t) user trace event shall be returned.

       If the Trace Inherit option is supported, the
       _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t_i_d___o_p_e_n() function shall associate the user trace
       event name pointed to by the _e_v_e_n_t___n_a_m_e argument with a trace event
       type identifier that is unique for all the processes being traced in
       this same trace stream, and is returned in the variable pointed to by
       the _e_v_e_n_t___i_d argument. If the user trace event name has already been
       mapped for the traced processes, then the previously assigned trace
       event type identifier shall be returned. If the per-process user trace
       event name limit represented by {TRACE_USER_EVENT_MAX} has been
       reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (_T_a_b_l_e _2_-_7,
       _T_r_a_c_e _O_p_t_i_o_n_: _U_s_e_r _T_r_a_c_e _E_v_e_n_t) user trace event shall be returned.

       NNoottee::     The above procedure, together with the fact that multiple
                 processes can only be traced into the same trace stream by
                 inheritance, ensure that all the processes that are traced
                 into a trace stream have the same mapping of trace event
                 names to trace event type identifiers.

       If there is no trace stream created, the _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t_i_d___o_p_e_n()
       function shall store this information for future trace streams created
       for this process.

RREETTUURRNN VVAALLUUEE
       No return value is defined for the _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t() function.

       Upon successful completion, the _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t_i_d___o_p_e_n() function
       shall return a value of zero. Otherwise, it shall return the
       corresponding error number. The _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t_i_d___o_p_e_n() function
       stores the trace event type identifier value in the object pointed to
       by _e_v_e_n_t___i_d, if successful.

EERRRROORRSS
       The _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t_i_d___o_p_e_n() function shall fail if:

       EENNAAMMEETTOOOOLLOONNGG
              The size of the name pointed to by the _e_v_e_n_t___n_a_m_e argument was
              longer than the implementation-defined value
              {TRACE_EVENT_NAME_MAX}.

       _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
       The _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t() and _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t_i_d___o_p_e_n() functions may be
       removed in a future version.

SSEEEE AALLSSOO
       _T_a_b_l_e _2_-_7, _T_r_a_c_e _O_p_t_i_o_n_: _U_s_e_r _T_r_a_c_e _E_v_e_n_t, _e_x_e_c,
       _p_o_s_i_x___t_r_a_c_e___e_v_e_n_t_i_d___e_q_u_a_l(), _p_o_s_i_x___t_r_a_c_e___s_t_a_r_t()

       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_EVENT(3)
