mirror of https://github.com/mkerrisk/man-pages
122 lines
4.1 KiB
Plaintext
122 lines
4.1 KiB
Plaintext
.\" 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 .
|