LTTng kernel tracepoint event rule API

Collaboration diagram for LTTng kernel tracepoint event rule API:

Functions
struct lttng_event_rule *	lttng_event_rule_kernel_tracepoint_create (void)
	Creates a default LTTng kernel tracepoint event rule.
enum lttng_event_rule_status	lttng_event_rule_kernel_tracepoint_get_filter (const struct lttng_event_rule *rule, const char **filter_expr)
	Sets *filter_expr to the event payload and context filter expression of the LTTng kernel tracepoint event rule rule.
enum lttng_event_rule_status	lttng_event_rule_kernel_tracepoint_get_name_pattern (const struct lttng_event_rule *rule, const char **pattern)
	Sets *pattern to the event name pattern of the LTTng kernel tracepoint event rule rule.
enum lttng_event_rule_status	lttng_event_rule_kernel_tracepoint_set_filter (struct lttng_event_rule *rule, const char *filter_expr)
	Sets the event payload and context filter of the LTTng kernel tracepoint event rule rule to filter_expr.
enum lttng_event_rule_status	lttng_event_rule_kernel_tracepoint_set_name_pattern (struct lttng_event_rule *rule, const char *pattern)
	Sets the event name pattern of the LTTng kernel tracepoint event rule rule to pattern.

Detailed Description

An LTTng kernel tracepoint event rule is an event rule with the LTTNG_EVENT_RULE_TYPE_KERNEL_TRACEPOINT type.

An LTTng kernel tracepoint is a statically defined point in the source code of the kernel image or of a kernel module with LTTng kernel tracer macros.

Create an LTTng kernel tracepoint event rule with lttng_event_rule_kernel_tracepoint_create().

The specific event rule conditions accessors of an LTTng kernel tracepoint event rule are:

Condition	Setter	Getter
Event name	lttng_event_rule_kernel_tracepoint_set_name_pattern()	lttng_event_rule_kernel_tracepoint_get_name_pattern()
Event payload and context filter	lttng_event_rule_kernel_tracepoint_set_filter()	lttng_event_rule_kernel_tracepoint_get_filter()

Function Documentation

lttng_event_rule_kernel_tracepoint_create()

struct lttng_event_rule * lttng_event_rule_kernel_tracepoint_create ( void  )

extern

Creates a default LTTng kernel tracepoint event rule.

On success, the returned event rule has the following initial conditions:

Condition	Value	Setter
Instrumentation point type	LTTNG_EVENT_RULE_TYPE_KERNEL_TRACEPOINT	Not applicable
Event name	Any name	lttng_event_rule_kernel_tracepoint_set_name_pattern()
Event payload and context filter	No filter	lttng_event_rule_kernel_tracepoint_set_filter()

Returns

LTTng kernel tracepoint event rule on success, or NULL on error.

Destroy the returned event rule with lttng_event_rule_destroy().

lttng_event_rule_kernel_tracepoint_get_filter()

enum lttng_event_rule_status lttng_event_rule_kernel_tracepoint_get_filter ( const struct lttng_event_rule *  rule, const char **  filter_expr  )

extern

Sets *filter_expr to the event payload and context filter expression of the LTTng kernel tracepoint event rule rule.

See the event payload and context filter condition.

Parameters

[in]	rule	LTTng kernel tracepoint event rule of which to get the event payload and context filter.
[out]	filter_expr	On success, this function sets *filter_expr to the event payload and context filter expression of rule. rule owns *filter_expr. *filter_expr remains valid until the next function call with rule.

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_UNSET	rule has no event payload and context filter, which corresponds to the filter expression 1.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_KERNEL_TRACEPOINT.
• filter_expr is not NULL.

See also

lttng_event_rule_kernel_tracepoint_set_filter() – Set the event payload and context filter of an LTTng kernel tracepoint event rule.

lttng_event_rule_kernel_tracepoint_get_name_pattern()

enum lttng_event_rule_status lttng_event_rule_kernel_tracepoint_get_name_pattern ( const struct lttng_event_rule *  rule, const char **  pattern  )

extern

Sets *pattern to the event name pattern of the LTTng kernel tracepoint event rule rule.

See the event name condition.

Parameters

[in]	rule	LTTng kernel tracepoint event rule of which to get the event name pattern.
[out]	pattern	On success, this function sets *pattern to the event name pattern of rule. rule owns *pattern. *pattern remains valid until the next function call with rule.

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_UNSET	rule has no event name pattern, which corresponds to the pattern * (any event name).
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_KERNEL_TRACEPOINT.
• pattern is not NULL.

See also

lttng_event_rule_kernel_tracepoint_set_name_pattern() – Set the event name pattern of an LTTng kernel tracepoint event rule.

lttng_event_rule_kernel_tracepoint_set_filter()

enum lttng_event_rule_status lttng_event_rule_kernel_tracepoint_set_filter ( struct lttng_event_rule *  rule, const char *  filter_expr  )

extern

Sets the event payload and context filter of the LTTng kernel tracepoint event rule rule to filter_expr.

See the event payload and context filter condition.

Parameters

[in]	rule	LTTng kernel tracepoint event rule of which to set the event payload and context filter.
[in]	filter_expr	Event payload and context filter expression of rule (copied).

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_KERNEL_TRACEPOINT.
• filter_expr is not NULL.
• filter_expr is a valid filter expression (see the event payload and context filter condition).

See also

lttng_event_rule_kernel_tracepoint_get_filter() – Get the event payload and context filter of an LTTng kernel tracepoint event rule.

lttng_event_rule_kernel_tracepoint_set_name_pattern()

enum lttng_event_rule_status lttng_event_rule_kernel_tracepoint_set_name_pattern ( struct lttng_event_rule *  rule, const char *  pattern  )

extern

Sets the event name pattern of the LTTng kernel tracepoint event rule rule to pattern.

See the event name condition.

Parameters

[in]	rule	LTTng kernel tracepoint event rule of which to set the event name pattern.
[in]	pattern	New event name pattern of rule (copied).

Return values

LTTNG_EVENT_RULE_STATUS_OK	Success.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_KERNEL_TRACEPOINT.
• pattern is not NULL.
• pattern is not empty.

See also

lttng_event_rule_kernel_tracepoint_get_name_pattern() – Get the event name pattern of an LTTng kernel tracepoint event rule.