# posix_trace_event

## PROLOG



           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



           posix_trace_event, posix_trace_eventid_open — trace functions for
           instrumenting application code (**TRACING**)
    


## SYNOPSIS



           #include <sys/types.h>
           #include <trace.h>
    
           void posix_trace_event(trace_event_id_t _event_id_ ,
               const void *restrict _data_ptr_ , size_t _data_len_);
           int posix_trace_eventid_open(const char *restrict _event_name_ ,
               trace_event_id_t *restrict _event_id_);
    


## DESCRIPTION



           The _posix_trace_event_() function shall record the _event_id_ and the
           user data pointed to by _data_ptr_ in the trace stream into which
           the calling process is being traced and in which _event_id_ is not
           filtered out. If the total size of the user trace event data
           represented by _data_len_ is not greater than the declared maximum
           size for user trace event data, then the _truncation-status_
           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 _truncation-_
           _status_ 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 _event_id_ is filtered out in the trace stream, the
           _posix_trace_event_() function shall have no effect.
    
           The _posix_trace_eventid_open_() 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 _event_name_.  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
           _posix_trace_eventid_open_() function shall associate the user trace
           event name pointed to by the _event_name_ argument with a trace
           event type identifier that is unique for the traced process, and
           is returned in the variable pointed to by the _event_id_ 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 _Table 2-7_ ,
           _Trace Option: User Trace Event_) user trace event shall be
           returned.
    
           If the Trace Inherit option is supported, the
           _posix_trace_eventid_open_() function shall associate the user trace
           event name pointed to by the _event_name_ 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 _event_id_ 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 (_Table 2-7_ , _Trace Option: User Trace_
           _Event_) user trace event shall be returned.
    
           **Note:** 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
           _posix_trace_eventid_open_() function shall store this information
           for future trace streams created for this process.
    


## RETURN VALUE



           No return value is defined for the _posix_trace_event_() function.
    
           Upon successful completion, the _posix_trace_eventid_open_()
           function shall return a value of zero. Otherwise, it shall return
           the corresponding error number. The _posix_trace_eventid_open_()
           function stores the trace event type identifier value in the
           object pointed to by _event_id_ , if successful.
    


## ERRORS



           The _posix_trace_eventid_open_() function shall fail if:
    
           **ENAMETOOLONG**
                  The size of the name pointed to by the _event_name_ argument
                  was longer than the implementation-defined value
                  {TRACE_EVENT_NAME_MAX}.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           The _posix_trace_event_() and _posix_trace_eventid_open_() functions
           may be removed in a future version.
    


* * *