1POSIX_TRACE_GET_FILTER(3P) POSIX Programmer's ManualPOSIX_TRACE_GET_FILTER(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       posix_trace_get_filter, posix_trace_set_filter — retrieve and  set  the
13       filter of an initialized trace stream (TRACING)
14

SYNOPSIS

16       #include <trace.h>
17
18       int posix_trace_get_filter(trace_id_t trid, trace_event_set_t *set);
19       int posix_trace_set_filter(trace_id_t trid,
20           const trace_event_set_t *set, int how);
21

DESCRIPTION

23       The posix_trace_get_filter() function shall retrieve, into the argument
24       pointed to by set, the actual trace event filter from the trace  stream
25       specified by trid.
26
27       The  posix_trace_set_filter() function shall change the set of filtered
28       trace event types after a trace stream identified by the trid  argument
29       is  created.  This  function  may be called prior to starting the trace
30       stream, or while the trace stream is active. By default, if no call  is
31       made  to  posix_trace_set_filter(),  all trace events shall be recorded
32       (that is, none of the trace event types are filtered out).
33
34       If this function is called while the trace is in  progress,  a  special
35       system  trace event, POSIX_TRACE_FILTER, shall be recorded in the trace
36       indicating both the old and the new sets of filtered trace event  types
37       (see  Table  2-4,  Trace  and  Trace Event Filter Options: System Trace
38       Events and Table 2-6, Trace, Trace Log, and Trace Event Filter Options:
39       System Trace Events).
40
41       If the posix_trace_set_filter() function is interrupted by a signal, an
42       error shall be returned and the filter shall not be  changed.  In  this
43       case, the state of the trace stream shall not be changed.
44
45       The  value of the argument how indicates the manner in which the set is
46       to be changed and shall have one of the following values, as defined in
47       the <trace.h> header:
48
49       POSIX_TRACE_SET_EVENTSET
50             The  resulting  set  of trace event types to be filtered shall be
51             the trace event type set pointed to by the argument set.
52
53       POSIX_TRACE_ADD_EVENTSET
54             The resulting set of trace event types to be  filtered  shall  be
55             the union of the current set and the trace event type set pointed
56             to by the argument set.
57
58       POSIX_TRACE_SUB_EVENTSET
59             The resulting set of trace event types to be  filtered  shall  be
60             all  trace event types in the current set that are not in the set
61             pointed to by the argument set; that is, remove each  element  of
62             the specified set from the current filter.
63

RETURN VALUE

65       Upon  successful  completion,  these  functions shall return a value of
66       zero. Otherwise, they shall return the corresponding error number.
67
68       The posix_trace_get_filter() function stores the set of filtered  trace
69       event types in set, if successful.
70

ERRORS

72       These functions shall fail if:
73
74       EINVAL The  value of the trid argument does not correspond to an active
75              trace stream or the value of the argument pointed to by  set  is
76              invalid.
77
78       EINTR  The operation was interrupted by a signal.
79
80       The following sections are informative.
81

EXAMPLES

83       None.
84

APPLICATION USAGE

86       None.
87

RATIONALE

89       None.
90

FUTURE DIRECTIONS

92       The posix_trace_get_filter() and posix_trace_set_filter() functions may
93       be removed in a future version.
94

SEE ALSO

96       Table 2-4, Trace and Trace Event Filter Options: System Trace Events,
97       Table 2-6, Trace, Trace Log, and Trace Event Filter Options: System
98       Trace Events, posix_trace_eventset_add()
99
100       The Base Definitions volume of POSIX.1‐2017, <trace.h>
101
103       Portions of this text are reprinted and reproduced in  electronic  form
104       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
105       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
106       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
107       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
108       event of any discrepancy between this version and the original IEEE and
109       The Open Group Standard, the original IEEE and The Open Group  Standard
110       is  the  referee document. The original Standard can be obtained online
111       at http://www.opengroup.org/unix/online.html .
112
113       Any typographical or formatting errors that appear  in  this  page  are
114       most likely to have been introduced during the conversion of the source
115       files to man page format. To report such errors,  see  https://www.ker
116       nel.org/doc/man-pages/reporting_bugs.html .
117
118
119
120IEEE/The Open Group                  2017           POSIX_TRACE_GET_FILTER(3P)
Impressum