Linux user space probe event rule API

Collaboration diagram for Linux user space probe event rule API:

Functions
struct lttng_event_rule *	lttng_event_rule_kernel_uprobe_create (const struct lttng_userspace_probe_location *location)
	Creates a default Linux user space probe event rule for the user space probe location location.
enum lttng_event_rule_status	lttng_event_rule_kernel_uprobe_get_event_name (const struct lttng_event_rule *rule, const char **name)
	Sets *name to the event name of the Linux user space probe event rule rule.
enum lttng_event_rule_status	lttng_event_rule_kernel_uprobe_get_location (const struct lttng_event_rule *rule, const struct lttng_userspace_probe_location **location)
	Sets *location to the user space probe location of the Linux user space probe event rule rule, a copy of the user space probe location you passed when you called lttng_event_rule_kernel_uprobe_create().
enum lttng_event_rule_status	lttng_event_rule_kernel_uprobe_set_event_name (struct lttng_event_rule *rule, const char *name)
	Sets the event name of the Linux user space probe event rule rule to name.

Detailed Description

A Linux user space probe event rule is an event rule with the LTTNG_EVENT_RULE_TYPE_KERNEL_UPROBE type.

A Linux user space probe is a user space tracing mechanism that allows intercepting and monitoring function calls in user space applications.

A Linux user space probe makes it possible to insert handlers into almost any user space function dynamically at run time, without modifying or recompiling the application. LTTng can attach to such a dynamic probe and and create an event from its execution.

Create a Linux user space probe event rule with lttng_event_rule_kernel_uprobe_create().

lttng_event_rule_kernel_uprobe_create() sets an initial event name from the user space probe location. Override the event name of a Linux user space probe event rule with lttng_event_rule_kernel_uprobe_set_event_name(). Get the event name with lttng_event_rule_kernel_uprobe_get_event_name().

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

Function Documentation

lttng_event_rule_kernel_uprobe_create()

struct lttng_event_rule * lttng_event_rule_kernel_uprobe_create ( const struct lttng_userspace_probe_location *  location )

extern

Creates a default Linux user space probe event rule for the user space probe location location.

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

Condition	Value
Instrumentation point type	LTTNG_EVENT_RULE_TYPE_KERNEL_UPROBE using location

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

LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION

The elf: prefix followed with the colon-delimited binary path and function name.

Example: elf:/usr/local/bin/my-server:acceptClient.

LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_TRACEPOINT_SDT

The sdt: prefix followed with the colon-delimited binary path, provider name, and probe name.

Example: sdt:/usr/local/bin/my-server:my_comp:user_cfg.

Override this initial event name with lttng_event_rule_kernel_uprobe_set_event_name().

Parameters

[in]

location

Location of user space probe events to match (copied).

Returns

Linux user space probe event rule on success, or NULL on error.

Destroy the returned event rule with lttng_event_rule_destroy().

lttng_event_rule_kernel_uprobe_get_event_name()

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

extern

Sets *name to the event name of the Linux user space probe event rule rule.

name is the name of the event which LTTng creates when the Linux user space probe of rule (see lttng_event_rule_kernel_uprobe_get_location()) is executed.

Parameters

[in]	rule	Linux user space probe 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_UPROBE.
• name is not NULL.

See also

lttng_event_rule_kernel_uprobe_set_event_name() – Set the event name of a Linux user space probe event rule.

lttng_event_rule_kernel_uprobe_get_location()

enum lttng_event_rule_status lttng_event_rule_kernel_uprobe_get_location ( const struct lttng_event_rule *  rule, const struct lttng_userspace_probe_location **  location  )

extern

Sets *location to the user space probe location of the Linux user space probe event rule rule, a copy of the user space probe location you passed when you called lttng_event_rule_kernel_uprobe_create().

See the instrumentation point type condition.

Parameters

[in]	rule	Linux user space probe event rule of which to get the user space probe location.
[out]	location	On success, this function sets *location to the user space probe 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_UPROBE.
• location is not NULL.

lttng_event_rule_kernel_uprobe_set_event_name()

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

extern

Sets the event name of the Linux user space probe event rule rule to name.

name is the name of the event which LTTng creates when the Linux user space probe of rule (see lttng_event_rule_kernel_uprobe_get_location()) is executed.

Parameters

[in]	rule	Linux user space probe 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_UPROBE.
• name is not NULL.
• name is not empty.

See also

lttng_event_rule_kernel_uprobe_get_event_name() – Get the event name of a Linux user space probe event rule.