posix_trace_set_filter Subroutine

Edit online

Purpose

Sets the filter of an initialized trace stream.

Library

Posix Trace Library (libposixtrace.a)

Syntax

#include <trace.h>

int posix_trace_set_filter(trid, set, how)
trace_id_t trid;
const trace_event_set_t *set;
int how;

Description

The posix_trace_set_filter subroutine changes the set of filtered trace event types after a trace stream identified by the trid parameter is created. This subroutine can be called before starting the trace stream, or while the trace stream is active. By default, if no call is made to the posix_trace_set_filter, all trace events are recorded (that is, none of the trace event types is filtered out).

If this subroutine is called while the trace is in progress, a special system trace event, the POSIX_TRACE_FILTER, is recorded in the trace indicating both the old and the new sets of filtered trace event types. The POSIX_TRACE_FILTER is a System Trace Event type associated with a trace event type filter change operation.

The how parameter indicates the way that the set parameter is to be changed. It has one of the following values, as defined in the trace.h header:
POSIX_TRACE_SET_EVENTSET
The set of trace event types to be filtered is the trace event type set that the set parameter points to.
POSIX_TRACE_ADD_EVENTSET
The set of trace event types to be filtered is the union of the current set and the trace event type set that the set parameter points to.
POSIX_TRACE_SUB_EVENTSET
The set of trace event types to be filtered is all trace event types in the current set that are not in the set that the set parameter points to; that is, remove each element of the specified set from the current filter.

Parameters

Item Description
trid Specifies the trace stream identifier.
set Points to the set of trace event types.
how Specifies the operation to be done on the set.

Return Values

On successful completion, it returns a value of zero. Otherwise, it returns the corresponding error number.

Errors

This subroutine fails if the following value returns:
Item Description
EINVAL The value of the trid parameter does not correspond to an active trace stream or the value of the parameter pointed to by the set parameter is not valid.

Files

The trace.h file in Files Reference.