# posix_trace_create

## 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_create, posix_trace_create_withlog, posix_trace_flush,
           posix_trace_shutdown — trace stream initialization, flush, and
           shutdown from a process (**TRACING**)
    


## SYNOPSIS



           #include <sys/types.h>
           #include <trace.h>
    
           int posix_trace_create(pid_t _pid_ ,
               const trace_attr_t *restrict _attr_ ,
               trace_id_t *restrict _trid_);
           int posix_trace_create_withlog(pid_t _pid_ ,
               const trace_attr_t *restrict _attr_ , int _file_desc_ ,
               trace_id_t *restrict _trid_);
           int posix_trace_flush(trace_id_t _trid_);
           int posix_trace_shutdown(trace_id_t _trid_);
    


## DESCRIPTION



           The _posix_trace_create_() function shall create an active trace
           stream. It allocates all the resources needed by the trace stream
           being created for tracing the process specified by _pid_ in
           accordance with the _attr_ argument. The _attr_ argument represents
           the initial attributes of the trace stream and shall have been
           initialized by the function _posix_trace_attr_init_() prior to the
           _posix_trace_create_() call. If the argument _attr_ is NULL, the
           default attributes shall be used. The _attr_ attributes object shall
           be manipulated through a set of functions described in the
           _posix_trace_attr_ family of functions. If the attributes of the
           object pointed to by _attr_ are modified later, the attributes of
           the trace stream shall not be affected. The _creation-time_
           attribute of the newly created trace stream shall be set to the
           value of the system clock, if the Timers option is not supported,
           or to the value of the CLOCK_REALTIME clock, if the Timers option
           is supported.
    
           The _pid_ argument represents the target process to be traced. If
           the process executing this function does not have appropriate
           privileges to trace the process identified by _pid_ , an error shall
           be returned. If the _pid_ argument is zero, the calling process
           shall be traced.
    
           The _posix_trace_create_() function shall store the trace stream
           identifier of the new trace stream in the object pointed to by the
           _trid_ argument. This trace stream identifier shall be used in
           subsequent calls to control tracing. The _trid_ argument may only be
           used by the following functions:
           _posix_trace_clear_()                      _posix_trace_getnext_event_()
           _posix_trace_eventid_equal_()              _posix_trace_shutdown_()
           _posix_trace_eventid_get_name_()           _posix_trace_start_()
           _posix_trace_eventtypelist_getnext_id_()   _posix_trace_stop_()
           _posix_trace_eventtypelist_rewind_()       _posix_trace_timedgetnext_event_()
           _posix_trace_get_attr_()                   _posix_trace_trid_eventid_open_()
           _posix_trace_get_status_()                 _posix_trace_trygetnext_event_()
    
           If the Trace Event Filter option is supported, the following
           additional functions may use the _trid_ argument:
           _posix_trace_get_filter_()   _posix_trace_set_filter_()
    
           In particular, notice that the operations normally used by a trace
           analyzer process, such as _posix_trace_rewind_() or
           _posix_trace_close_(), cannot be invoked using the trace stream
           identifier returned by the _posix_trace_create_() function.
    
           A trace stream shall be created in a suspended state.  If the
           Trace Event Filter option is supported, its trace event type
           filter shall be empty.
    
           The _posix_trace_create_() function may be called multiple times
           from the same or different processes, with the system-wide limit
           indicated by the runtime invariant value {TRACE_SYS_MAX}, which
           has the minimum value {_POSIX_TRACE_SYS_MAX}.
    
           The trace stream identifier returned by the _posix_trace_create_()
           function in the argument pointed to by _trid_ is valid only in the
           process that made the function call. If it is used from another
           process, that is a child process, in functions defined in
           POSIX.1‐2008, these functions shall return with the error
           **[EINVAL]**.
    
           The _posix_trace_create_withlog_() function shall be equivalent to
           _posix_trace_create_(), except that it associates a trace log with
           this stream. The _file_desc_ argument shall be the file descriptor
           designating the trace log destination. The function shall fail if
           this file descriptor refers to a file with a file type that is not
           compatible with the log policy associated with the trace log. The
           list of the appropriate file types that are compatible with each
           log policy is implementation-defined.
    
           The _posix_trace_create_withlog_() function shall return in the
           parameter pointed to by _trid_ the trace stream identifier, which
           uniquely identifies the newly created trace stream, and shall be
           used in subsequent calls to control tracing. The _trid_ argument may
           only be used by the following functions:
           _posix_trace_clear_()                      _posix_trace_get_status_()
           _posix_trace_eventid_equal_()              _posix_trace_getnext_event_()
           _posix_trace_eventid_get_name_()           _posix_trace_shutdown_()
           _posix_trace_eventtypelist_getnext_id_()   _posix_trace_start_()
           _posix_trace_eventtypelist_rewind_()       _posix_trace_stop_()
           _posix_trace_flush_()                      _posix_trace_timedgetnext_event_()
           _posix_trace_get_attr_()                   _posix_trace_trid_eventid_open_()
    
           If the Trace Event Filter option is supported, the following
           additional functions may use the _trid_ argument:
           _posix_trace_get_filter_()   _posix_trace_set_filter_()
    
           In particular, notice that the operations normally used by a trace
           analyzer process, such as _posix_trace_rewind_() or
           _posix_trace_close_(), cannot be invoked using the trace stream
           identifier returned by the _posix_trace_create_withlog_() function.
    
           The _posix_trace_flush_() function shall initiate a flush operation
           which copies the contents of the trace stream identified by the
           argument _trid_ into the trace log associated with the trace stream
           at the creation time. If no trace log has been associated with the
           trace stream pointed to by _trid_ , this function shall return an
           error. The termination of the flush operation can be polled by the
           _posix_trace_get_status_() function. During the flush operation, it
           shall be possible to trace new trace events up to the point when
           the trace stream becomes full.  After flushing is completed, the
           space used by the flushed trace events shall be available for
           tracing new trace events.
    
           If flushing the trace stream causes the resulting trace log to
           become full, the trace log full policy shall be applied. If the
           trace _log-full-policy_ attribute is set, the following occurs:
    
           POSIX_TRACE_UNTIL_FULL
                 The trace events that have not yet been flushed shall be
                 discarded.
    
           POSIX_TRACE_LOOP
                 The trace events that have not yet been flushed shall be
                 written to the beginning of the trace log, overwriting
                 previous trace events stored there.
    
           POSIX_TRACE_APPEND
                 The trace events that have not yet been flushed shall be
                 appended to the trace log.
    
           The _posix_trace_shutdown_() function shall stop the tracing of
           trace events in the trace stream identified by _trid_ , as if
           _posix_trace_stop_() had been invoked. The _posix_trace_shutdown_()
           function shall free all the resources associated with the trace
           stream.
    
           The _posix_trace_shutdown_() function shall not return until all the
           resources associated with the trace stream have been freed. When
           the _posix_trace_shutdown_() function returns, the _trid_ argument
           becomes an invalid trace stream identifier. A call to this
           function shall unconditionally deallocate the resources regardless
           of whether all trace events have been retrieved by the analyzer
           process.  Any thread blocked on one of the _trace_getnext_event_()
           functions (which specified this _trid_) before this call is
           unblocked with the error **[EINVAL]**.
    
           If the process exits, invokes a member of the _exec_ family of
           functions, or is terminated, the trace streams that the process
           had created and that have not yet been shut down, shall be
           automatically shut down as if an explicit call were made to the
           _posix_trace_shutdown_() function.
    
           For an active trace stream with log, when the
           _posix_trace_shutdown_() function is called, all trace events that
           have not yet been flushed to the trace log shall be flushed, as in
           the _posix_trace_flush_() function, and the trace log shall be
           closed.
    
           When a trace log is closed, all the information that may be
           retrieved later from the trace log through the trace interface
           shall have been written to the trace log. This information
           includes the trace attributes, the list of trace event types (with
           the mapping between trace event names and trace event type
           identifiers), and the trace status.
    
           In addition, unspecified information shall be written to the trace
           log to allow detection of a valid trace log during the
           _posix_trace_open_() operation.
    
           The _posix_trace_shutdown_() function shall not return until all
           trace events have been flushed.
    


## RETURN VALUE



           Upon successful completion, these functions shall return a value
           of zero. Otherwise, they shall return the corresponding error
           number.
    
           The _posix_trace_create_() and _posix_trace_create_withlog_()
           functions store the trace stream identifier value in the object
           pointed to by _trid_ , if successful.
    


## ERRORS



           The _posix_trace_create_() and _posix_trace_create_withlog_()
           functions shall fail if:
    
           **EAGAIN** No more trace streams can be started now.  {TRACE_SYS_MAX}
                  has been exceeded.
    
           **EINTR** The operation was interrupted by a signal. No trace stream
                  was created.
    
           **EINVAL** One or more of the trace parameters specified by the _attr_
                  parameter is invalid.
    
           **ENOMEM** The implementation does not currently have sufficient
                  memory to create the trace stream with the specified
                  parameters.
    
           **EPERM** The caller does not have appropriate privileges to trace
                  the process specified by _pid_.
    
           **ESRCH** The _pid_ argument does not refer to an existing process.
    
           The _posix_trace_create_withlog_() function shall fail if:
    
           **EBADF** The _file_desc_ argument is not a valid file descriptor open
                  for writing.
    
           **EINVAL** The _file_desc_ argument refers to a file with a file type
                  that does not support the log policy associated with the
                  trace log.
    
           **ENOSPC** No space left on device. The device corresponding to the
                  argument _file_desc_ does not contain the space required to
                  create this trace log.
    
           The _posix_trace_flush_() and _posix_trace_shutdown_() functions shall
           fail if:
    
           **EINVAL** The value of the _trid_ argument does not correspond to an
                  active trace stream with log.
    
           **EFBIG** The trace log file has attempted to exceed an
                  implementation-defined maximum file size.
    
           **ENOSPC** No space left on device.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           The _posix_trace_create_(), _posix_trace_create_withlog_(),
           _posix_trace_flush_(), and _posix_trace_shutdown_() functions may be
           removed in a future version.
    


* * *