# posix_trace_get_filter

## 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_get_filter, posix_trace_set_filter — retrieve and set
           the filter of an initialized trace stream (**TRACING**)
    


## SYNOPSIS



           #include <trace.h>
    
           int posix_trace_get_filter(trace_id_t _trid_ , trace_event_set_t *_set_);
           int posix_trace_set_filter(trace_id_t _trid_ ,
               const trace_event_set_t *_set_ , int _how_);
    


## DESCRIPTION



           The _posix_trace_get_filter_() function shall retrieve, into the
           argument pointed to by _set_ , the actual trace event filter from the
           trace stream specified by _trid_.
    
           The _posix_trace_set_filter_() function shall change the set of
           filtered trace event types after a trace stream identified by the
           _trid_ argument is created. This function may be called prior to
           starting the trace stream, or while the trace stream is active. By
           default, if no call is made to _posix_trace_set_filter_(), all trace
           events shall be recorded (that is, none of the trace event types
           are filtered out).
    
           If this function is called while the trace is in progress, a
           special system trace event, POSIX_TRACE_FILTER, shall be recorded
           in the trace indicating both the old and the new sets of filtered
           trace event types (see _Table 2-4_ , _Trace and Trace Event Filter_
           _Options: System Trace Events_ and _Table 2-6_ , _Trace_ , _Trace Log_ , _and_
           _Trace Event Filter Options: System Trace Events_).
    
           If the _posix_trace_set_filter_() function is interrupted by a
           signal, an error shall be returned and the filter shall not be
           changed. In this case, the state of the trace stream shall not be
           changed.
    
           The value of the argument _how_ indicates the manner in which the
           set is to be changed and shall have one of the following values,
           as defined in the _< trace.h>_ header:
    
           POSIX_TRACE_SET_EVENTSET
                 The resulting set of trace event types to be filtered shall
                 be the trace event type set pointed to by the argument _set_.
    
           POSIX_TRACE_ADD_EVENTSET
                 The resulting set of trace event types to be filtered shall
                 be the union of the current set and the trace event type set
                 pointed to by the argument _set_.
    
           POSIX_TRACE_SUB_EVENTSET
                 The resulting set of trace event types to be filtered shall
                 be all trace event types in the current set that are not in
                 the set pointed to by the argument _set_ ; that is, remove each
                 element of the specified set from the current filter.
    


## RETURN VALUE



           Upon successful completion, these functions shall return a value
           of zero. Otherwise, they shall return the corresponding error
           number.
    
           The _posix_trace_get_filter_() function stores the set of filtered
           trace event types in _set_ , if successful.
    


## ERRORS



           These functions shall fail if:
    
           **EINVAL** The value of the _trid_ argument does not correspond to an
                  active trace stream or the value of the argument pointed to
                  by _set_ is invalid.
    
           **EINTR** The operation was interrupted by a signal.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           The _posix_trace_get_filter_() and _posix_trace_set_filter_()
           functions may be removed in a future version.
    


* * *