Linux kernel system call event rule API

Collaboration diagram for Linux kernel system call event rule API:

Enumerations
enum	lttng_event_rule_kernel_syscall_emission_site { LTTNG_EVENT_RULE_KERNEL_SYSCALL_EMISSION_SITE_ENTRY_EXIT , LTTNG_EVENT_RULE_KERNEL_SYSCALL_EMISSION_SITE_ENTRY , LTTNG_EVENT_RULE_KERNEL_SYSCALL_EMISSION_SITE_EXIT , LTTNG_EVENT_RULE_KERNEL_SYSCALL_EMISSION_SITE_UNKNOWN }
	Emission site of a Linux kernel system call. More...

Functions
struct lttng_event_rule *	lttng_event_rule_kernel_syscall_create (enum lttng_event_rule_kernel_syscall_emission_site emission_site)
	Creates a default Linux kernel system call event rule for the emission site emission_site.
enum lttng_event_rule_kernel_syscall_emission_site	lttng_event_rule_kernel_syscall_get_emission_site (const struct lttng_event_rule *rule)
	Returns the emission site of system call events to match of the Linux kernel system call event rule rule.
enum lttng_event_rule_status	lttng_event_rule_kernel_syscall_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 Linux kernel system call event rule rule.
enum lttng_event_rule_status	lttng_event_rule_kernel_syscall_get_name_pattern (const struct lttng_event_rule *rule, const char **pattern)
	Sets *pattern to the event name pattern of the Linux kernel system call event rule rule.
enum lttng_event_rule_status	lttng_event_rule_kernel_syscall_set_filter (struct lttng_event_rule *rule, const char *filter_expr)
	Sets the event payload and context filter of the Linux kernel system call event rule rule to filter_expr.
enum lttng_event_rule_status	lttng_event_rule_kernel_syscall_set_name_pattern (struct lttng_event_rule *rule, const char *pattern)
	Sets the event name pattern of the Linux kernel system call event rule rule to pattern.

Detailed Description

A Linux kernel system call event rule is an event rule with the LTTNG_EVENT_RULE_TYPE_KERNEL_SYSCALL type.

A Linux kernel system call event rule matches an event which LTTng creates from the entry, exit, or both of a kernel system call.

Create a Linux kernel system call event rule with lttng_event_rule_kernel_syscall_create().

The specific event rule conditions accessors of a Linux kernel system call event rule are:

Condition	Setter	Getter
Event name	lttng_event_rule_kernel_syscall_set_name_pattern()	lttng_event_rule_kernel_syscall_get_name_pattern()
Event payload and context filter	lttng_event_rule_kernel_syscall_set_filter()	lttng_event_rule_kernel_syscall_get_filter()

Enumeration Type Documentation

lttng_event_rule_kernel_syscall_emission_site

enum lttng_event_rule_kernel_syscall_emission_site

Emission site of a Linux kernel system call.

Enumerator
LTTNG_EVENT_RULE_KERNEL_SYSCALL_EMISSION_SITE_ENTRY_EXIT	Entry and exit.
LTTNG_EVENT_RULE_KERNEL_SYSCALL_EMISSION_SITE_ENTRY	Entry only.
LTTNG_EVENT_RULE_KERNEL_SYSCALL_EMISSION_SITE_EXIT	Exit only.
LTTNG_EVENT_RULE_KERNEL_SYSCALL_EMISSION_SITE_UNKNOWN	Unknown (error).

Function Documentation

lttng_event_rule_kernel_syscall_create()

struct lttng_event_rule * lttng_event_rule_kernel_syscall_create ( enum lttng_event_rule_kernel_syscall_emission_site  emission_site )

extern

Creates a default Linux kernel system call event rule for the emission site emission_site.

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

Condition	Value	Setter
Instrumentation point type	LTTNG_EVENT_RULE_TYPE_KERNEL_SYSCALL using emission_site	Not applicable
Event name	Any name	lttng_event_rule_kernel_syscall_set_name_pattern()
Event payload and context filter	No filter	lttng_event_rule_kernel_syscall_set_filter()

Parameters

[in]

emission_site

Emission site of system call events to match.

Returns

Linux kernel system call event rule on success, or NULL on error.

Destroy the returned event rule with lttng_event_rule_destroy().

lttng_event_rule_kernel_syscall_get_emission_site()

enum lttng_event_rule_kernel_syscall_emission_site lttng_event_rule_kernel_syscall_get_emission_site ( const struct lttng_event_rule *  rule )

extern

Returns the emission site of system call events to match of the Linux kernel system call event rule rule.

See the instrumentation point type condition.

Parameters

[in]

rule

Linux kernel system call event rule of which to get the system call emission site.

Returns

System call emission site of rule.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_KERNEL_SYSCALL.

lttng_event_rule_kernel_syscall_get_filter()

enum lttng_event_rule_status lttng_event_rule_kernel_syscall_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 Linux kernel system call event rule rule.

See the event payload and context filter condition.

Parameters

[in]	rule	Linux kernel system call 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_SYSCALL.
• filter_expr is not NULL.

See also

lttng_event_rule_kernel_syscall_set_filter() – Set the event payload and context filter of a Linux kernel system call event rule.

lttng_event_rule_kernel_syscall_get_name_pattern()

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

extern

Sets *pattern to the event name pattern of the Linux kernel system call event rule rule.

See the event name condition.

Parameters

[in]	rule	Linux kernel system call 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_SYSCALL.
• pattern is not NULL.

See also

lttng_event_rule_kernel_syscall_set_name_pattern() – Set the event name pattern of a Linux kernel system call event rule.

lttng_event_rule_kernel_syscall_set_filter()

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

extern

Sets the event payload and context filter of the Linux kernel system call event rule rule to filter_expr.

See the event payload and context filter condition.

Parameters

[in]	rule	Linux kernel system call 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_SYSCALL.
• 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_syscall_get_filter() – Get the event payload and context filter of a Linux kernel system call event rule.

lttng_event_rule_kernel_syscall_set_name_pattern()

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

extern

Sets the event name pattern of the Linux kernel system call event rule rule to pattern.

See the event name condition.

Note

The event name to match doesn't have any sys_ prefix.

Parameters

[in]	rule	Linux kernel system call 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_SYSCALL.
• pattern is not NULL.
• pattern is not empty.

See also

lttng_event_rule_kernel_syscall_get_name_pattern() – Get the event name pattern of a Linux kernel system call event rule.