.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "POSIX_TRACE_GET_FILTER" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" posix_trace_get_filter 
.SH NAME
posix_trace_get_filter, posix_trace_set_filter \- retrieve and set
the filter of an initialized trace stream
(\fBTRACING\fP)
.SH SYNOPSIS
.LP
\fB#include <trace.h>
.br
.sp
int posix_trace_get_filter(trace_id_t\fP \fItrid\fP\fB, trace_event_set_t
*\fP\fIset\fP\fB);
.br
int posix_trace_set_filter(trace_id_t\fP \fItrid\fP\fB,
.br
\ \ \ \ \ \  const trace_event_set_t *\fP\fIset\fP\fB, int\fP \fIhow\fP\fB);
\fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIposix_trace_get_filter\fP() function shall retrieve, into the
argument pointed to by \fIset\fP, the actual trace event
filter from the trace stream specified by \fItrid\fP.
.LP
The \fIposix_trace_set_filter\fP() function shall change the set of
filtered trace event types after a trace stream identified
by the \fItrid\fP 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 \fIposix_trace_set_filter\fP(),
all trace events shall be recorded (that is, none of
the trace event types are filtered out).
.LP
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 \fITrace and Trace Event Filter Options: System
Trace Events\fP and \fITrace, Trace Log, and Trace Event Filter Options:
System Trace Events\fP ).
.LP
If the \fIposix_trace_set_filter\fP() 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.
.LP
The value of the argument \fIhow\fP indicates the manner in which
the set is to be changed and shall have one of the following
values, as defined in the \fI<trace.h>\fP header:
.TP 7
POSIX_TRACE_SET_EVENTSET
.sp
The resulting set of trace event types to be filtered shall be the
trace event type set pointed to by the argument \fIset\fP.
.TP 7
POSIX_TRACE_ADD_EVENTSET
.sp
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 \fIset\fP.
.TP 7
POSIX_TRACE_SUB_EVENTSET
.sp
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 \fIset\fP; that is, remove each element
of the specified set from the current filter.
.sp
.SH RETURN VALUE
.LP
Upon successful completion, these functions shall return a value of
zero. Otherwise, they shall return the corresponding error
number.
.LP
The \fIposix_trace_get_filter\fP() function stores the set of filtered
trace event types in \fIset\fP, if successful.
.SH ERRORS
.LP
These functions shall fail if:
.TP 7
.B EINVAL
The value of the \fItrid\fP argument does not correspond to an active
trace stream or the value of the argument pointed to by
\fIset\fP is invalid.
.TP 7
.B EINTR
The operation was interrupted by a signal.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fITrace and Trace Event Filter Options: System Trace Events\fP ,
\fITrace, Trace Log, and Trace Event Filter Options: System Trace
Events\fP , \fIposix_trace_eventset_add\fP() , the Base Definitions
volume of
IEEE\ Std\ 1003.1-2001, \fI<trace.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .