Linux kprobe event rule API

Collaboration diagram for Linux kprobe event rule API:

Modules
	Linux kprobe location API

Functions
struct lttng_event_rule *	lttng_event_rule_kernel_kprobe_create (const struct lttng_kernel_probe_location *location)
	Creates a default Linux kprobe event rule for the kprobe location location.
enum lttng_event_rule_status	lttng_event_rule_kernel_kprobe_get_event_name (const struct lttng_event_rule *rule, const char **name)
	Sets *name to the event name of the Linux kprobe event rule rule.
enum lttng_event_rule_status	lttng_event_rule_kernel_kprobe_get_location (const struct lttng_event_rule *rule, const struct lttng_kernel_probe_location **location)
	Sets *location to the kprobe location of the Linux kprobe event rule rule, a copy of the kprobe location you passed when you called lttng_event_rule_kernel_kprobe_create().
enum lttng_event_rule_status	lttng_event_rule_kernel_kprobe_set_event_name (struct lttng_event_rule *rule, const char *name)
	Sets the event name of the Linux kprobe event rule rule to name.

Detailed Description

A Linux kprobe event rule is an event rule with the LTTNG_EVENT_RULE_TYPE_KERNEL_KPROBE type.

A Linux kprobe is a kernel debugging/tracing mechanism that intercepts and monitors kernel function calls.

A Linux kprobe lets you insert handlers into nearly any kernel routine dynamically at run time, without having to recompile the kernel. LTTng is able to attach to such a dynamic probe and create an event from its execution.

Create a Linux kprobe event rule with lttng_event_rule_kernel_kprobe_create().

lttng_event_rule_kernel_kprobe_create() sets an initial event name from the kprobe location. Override the event name of a Linux kprobe event rule with lttng_event_rule_kernel_kprobe_set_event_name(). Get the event name with lttng_event_rule_kernel_kprobe_get_event_name().

Get the location, as passed to lttng_event_rule_kernel_kprobe_create(), of a Linux kprobe event rule with lttng_event_rule_kernel_kprobe_get_location().

Function Documentation

lttng_event_rule_kernel_kprobe_create()

struct lttng_event_rule * lttng_event_rule_kernel_kprobe_create ( const struct lttng_kernel_probe_location *  location )

extern

Creates a default Linux kprobe event rule for the kprobe location location.

On success, the returned event rule has the following condition:

Condition	Value
Instrumentation point type	LTTNG_EVENT_RULE_TYPE_KERNEL_KPROBE using location

The initial event name of the returned event rule is, depending on the type location:

LTTNG_KERNEL_PROBE_LOCATION_TYPE_SYMBOL_OFFSET

The symbol name of location followed with, if not zero, the offset from symbol of location (hexadecimal with the 0x prefix).

Examples:

• copy_from_user
• schedule+0x4c0

LTTNG_KERNEL_PROBE_LOCATION_TYPE_ADDRESS

The address within the kernel of location (hexadecimal with the 0x prefix).

Example: 0xffffffff814abc30.

Override this initial event name with lttng_event_rule_kernel_kprobe_set_event_name().

Parameters

[in]

location

Location of kprobe events to match (copied).

Returns

Linux kprobe event rule on success, or NULL on error.

Destroy the returned event rule with lttng_event_rule_destroy().

lttng_event_rule_kernel_kprobe_get_event_name()

enum lttng_event_rule_status lttng_event_rule_kernel_kprobe_get_event_name ( const struct lttng_event_rule *  rule, const char **  name  )

extern

Sets *name to the event name of the Linux kprobe event rule rule.

name is the name of the event which LTTng creates when the Linux kprobe of rule (see lttng_event_rule_kernel_kprobe_get_location()) is executed.

Parameters

[in]	rule	Linux kprobe event rule of which to get the event name.
[out]	name	On success, this function sets *name to the event name of rule. rule owns *name. *name 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.
LTTNG_EVENT_RULE_STATUS_INVALID	Unsatisfied precondition.

Precondition

• rule is not NULL.
• rule has the type LTTNG_EVENT_RULE_TYPE_KERNEL_KPROBE.
• name is not NULL.

See also

lttng_event_rule_kernel_kprobe_set_event_name() – Set the event name of a Linux kprobe event rule.

lttng_event_rule_kernel_kprobe_get_location()

enum lttng_event_rule_status lttng_event_rule_kernel_kprobe_get_location ( const struct lttng_event_rule *  rule, const struct lttng_kernel_probe_location **  location  )

extern

Sets *location to the kprobe location of the Linux kprobe event rule rule, a copy of the kprobe location you passed when you called lttng_event_rule_kernel_kprobe_create().

See the instrumentation point type condition.

Parameters

[in]	rule	Linux kprobe event rule of which to get the kprobe location.
[out]	location	On success, this function sets *location to the kprobe location of rule. rule owns *location. *location remains valid until the next function call with rule.

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_KPROBE.
• location is not NULL.

lttng_event_rule_kernel_kprobe_set_event_name()

enum lttng_event_rule_status lttng_event_rule_kernel_kprobe_set_event_name ( struct lttng_event_rule *  rule, const char *  name  )

extern

Sets the event name of the Linux kprobe event rule rule to name.

name is the name of the event which LTTng creates when the Linux kprobe of rule (see lttng_event_rule_kernel_kprobe_get_location()) is executed.

Parameters

[in]	rule	Linux kprobe event rule of which to set the event name.
[in]	name	Event name 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_KPROBE.
• name is not NULL.
• name is not empty.

See also

lttng_event_rule_kernel_kprobe_get_event_name() – Get the event name of a Linux kprobe event rule.