Collaboration diagram for Event expression API:

Enumerations
enum	lttng_event_expr_status { LTTNG_EVENT_EXPR_STATUS_OK , LTTNG_EVENT_EXPR_STATUS_INVALID }
	Return type of event expression API functions. More...

enum	lttng_event_expr_type { LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD , LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD , LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD , LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT , LTTNG_EVENT_EXPR_TYPE_INVALID }
	Event expression type. More...

Functions
struct lttng_event_expr *	lttng_event_expr_app_specific_context_field_create (const char provider_name, const char type_name)
	Creates an application-specific context field reference expression for the application-specific context field provided by the provider named `provider_name` and having the type named `type_name`.

const char *	lttng_event_expr_app_specific_context_field_get_provider_name (const struct lttng_event_expr *expr)
	Returns the provider name of the referenced field of the application-specific context field reference expression `expr`.

const char *	lttng_event_expr_app_specific_context_field_get_type_name (const struct lttng_event_expr *expr)
	Returns the type name of the referenced field of the application-specific context field reference expression `expr`.

struct lttng_event_expr *	lttng_event_expr_array_field_element_create (struct lttng_event_expr *array_field_expr, unsigned int index)
	Creates an array field element reference expression for the parent array field referred by `array_field_expr` and the index `index`.

enum lttng_event_expr_status	lttng_event_expr_array_field_element_get_index (const struct lttng_event_expr expr, unsigned int index)
	Sets `*index` to the index of the array field element reference expression`expr`.

const struct lttng_event_expr *	lttng_event_expr_array_field_element_get_parent_expr (const struct lttng_event_expr *expr)
	Returns the parent array field expression of the array field element reference expression`expr`.

struct lttng_event_expr *	lttng_event_expr_channel_context_field_create (const char *field_name)
	Creates a statically-known context field reference expression for the context field named `field_name`.

const char *	lttng_event_expr_channel_context_field_get_name (const struct lttng_event_expr *expr)
	Returns the name of the referenced context field of the statically-known context field reference expression `expr`.

void	lttng_event_expr_destroy (struct lttng_event_expr *expr)
	Destroys the event expression `expr`.

struct lttng_event_expr *	lttng_event_expr_event_payload_field_create (const char *field_name)
	Creates an event payload field reference expression for the payload field named `field_name`.

const char *	lttng_event_expr_event_payload_field_get_name (const struct lttng_event_expr *expr)
	Returns the name of the referenced payload field of the event payload field reference expression `expr`.

enum lttng_event_expr_type	lttng_event_expr_get_type (const struct lttng_event_expr *expr)
	Returns the type of the event expression `expr`.

bool	lttng_event_expr_is_equal (const struct lttng_event_expr expr_a, const struct lttng_event_expr expr_b)
	Returns whether or not the event expressions `expr_a` and `expr_b` are equal.

Detailed Description

An event expression is a structured representation of logic that can reference event fields, apply operators, and compose conditions. Such an object is similar to an abstract syntax tree (AST) node of which the dynamic input comes from the context and payload fields of an event.

See Event rule API to learn more about LTTng events.

As of LTTng-tools 16.2, the event expression API only offers field reference expressions. Its sole purpose is to append capture descriptors to an “event rule matches” trigger condition with lttng_condition_event_rule_matches_append_capture_descriptor(). With more expression types (constants, operators, conditionals, and the rest), you'll be able to programmatically create an event payload and context filter expression.

The available event field expression types are:

Event expression type	Type enumerator	Creation function	Accessor(s)
Payload field reference	LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD	lttng_event_expr_event_payload_field_create()	lttng_event_expr_event_payload_field_get_name()
Statically-known context field reference	LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD	lttng_event_expr_channel_context_field_create()	lttng_event_expr_channel_context_field_get_name()
Application-specific context field reference	LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD	lttng_event_expr_app_specific_context_field_create()	lttng_event_expr_app_specific_context_field_get_provider_name() and lttng_event_expr_app_specific_context_field_get_type_name()
Array field element reference	LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT	lttng_event_expr_array_field_element_create()	lttng_event_expr_array_field_element_get_parent_expr() and lttng_event_expr_array_field_element_get_index()

Get the type of an event expression with lttng_event_expr_get_type().

Check whether or not two event expressions are equal with lttng_event_expr_is_equal().

Destroy an event expression with lttng_event_expr_destroy().

Enumeration Type Documentation

◆ lttng_event_expr_status

enum lttng_event_expr_status

Return type of event expression API functions.

Enumerator
LTTNG_EVENT_EXPR_STATUS_OK	Success.
LTTNG_EVENT_EXPR_STATUS_INVALID	Unsatisfied precondition.

◆ lttng_event_expr_type

enum lttng_event_expr_type

Event expression type.

Get the type of an event expression with lttng_event_expr_get_type().

Enumerator
LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD	Payload field reference.
LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD	Statically-known context field reference.
LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD	Application-specific context field reference.
LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT	Array field element reference.
LTTNG_EVENT_EXPR_TYPE_INVALID	Unsatisfied precondition.

Function Documentation

◆ lttng_event_expr_app_specific_context_field_create()

struct lttng_event_expr * lttng_event_expr_app_specific_context_field_create	(	const char *	provider_name,
		const char *	type_name
	)

extern

Creates an application-specific context field reference expression for the application-specific context field provided by the provider named provider_name and having the type named type_name.

Parameters

[in]	provider_name	Name of the provider of the application-specific context field to refer to (copied).
[in]	type_name	Name of the type of the application-specific context field to refer to (copied).

Returns: Application-specific context field reference expression for the provider named provider_name and the type named type_name, or NULL on error.

Precondition

provider_name is not NULL.
type_name is not NULL.

◆ lttng_event_expr_app_specific_context_field_get_provider_name()

const char * lttng_event_expr_app_specific_context_field_get_provider_name ( const struct lttng_event_expr * expr )

extern

Returns the provider name of the referenced field of the application-specific context field reference expression expr.

Parameters

[in] expr Application-specific context field reference expression of which to get the provider name of the referenced field.

Returns

Provider name of the referenced field of expr, or NULL on error.

expr owns the returned string.

The returned string remains valid as long as expr exists.

Precondition

expr is not NULL.
expr has the type LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD.

◆ lttng_event_expr_app_specific_context_field_get_type_name()

const char * lttng_event_expr_app_specific_context_field_get_type_name ( const struct lttng_event_expr * expr )

extern

Returns the type name of the referenced field of the application-specific context field reference expression expr.

Parameters

[in] expr Application-specific context field reference expression of which to get the type name of the referenced field.

Returns

Type name of the referenced field of expr, or NULL on error.

expr owns the returned string.

The returned string remains valid as long as expr exists.

Precondition

expr is not NULL.
expr has the type LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD.

◆ lttng_event_expr_array_field_element_create()

struct lttng_event_expr * lttng_event_expr_array_field_element_create	(	struct lttng_event_expr *	array_field_expr,
		unsigned int	index
	)

extern

Creates an array field element reference expression for the parent array field referred by array_field_expr and the index index.

Parameters

[in]

array_field_expr

Parent array field containing the field element to refer to.

On success, the ownership of this expression is moved to the returned expression.

[in] index Index of the field element to refer to within array_field_expr.

Returns: Array field element reference expression for the parent array field array_field_expr and the index index.

Precondition

array_field_expr is not NULL.

◆ lttng_event_expr_array_field_element_get_index()

enum lttng_event_expr_status lttng_event_expr_array_field_element_get_index	(	const struct lttng_event_expr *	expr,
		unsigned int *	index
	)

extern

Sets *index to the index of the array field element reference expressionexpr.

Parameters

[in]	expr	Array field element reference expression of which to get the index.
[out]	index	On success, this function sets `*index` to the index of `expr`.

Return values

LTTNG_EVENT_EXPR_STATUS_OK	Success.
LTTNG_EVENT_EXPR_STATUS_INVALID	Unsatisfied precondition.

Precondition

expr is not NULL.
expr has the type LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT.
index is not NULL.

See also: lttng_event_expr_array_field_element_get_parent_expr() – Get the parent array field expression of an array field element reference expression.

◆ lttng_event_expr_array_field_element_get_parent_expr()

const struct lttng_event_expr * lttng_event_expr_array_field_element_get_parent_expr ( const struct lttng_event_expr * expr )

extern

Returns the parent array field expression of the array field element reference expressionexpr.

Parameters

[in] expr Array field element reference expression of which to get the parent array field expression.

Returns

Parent array field expression of expr, or NULL on error.

expr owns the returned expression.

The returned expression remains valid as long as expr exists.

Precondition

expr is not NULL.
expr has the type LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT.

See also: lttng_event_expr_array_field_element_get_index() – Get the index of an array field element reference expression.

◆ lttng_event_expr_channel_context_field_create()

struct lttng_event_expr * lttng_event_expr_channel_context_field_create ( const char * field_name )

extern

Creates a statically-known context field reference expression for the context field named field_name.

Parameters

[in]

field_name

Name of the statically-known context field to refer to (copied).

Use one of the statically known names in the “Field name” column of the table of lttng_event_context_type (that is, excluding the LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER, LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, and LTTNG_EVENT_CONTEXT_APP_CONTEXT rows).

Returns: Statically-known context field reference expression for the context field named field_name, or NULL on error.

Precondition

field_name is not NULL.
field_name is one of the names in the “Field name” column of the table of lttng_event_context_type, excluding the LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER, LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, and LTTNG_EVENT_CONTEXT_APP_CONTEXT rows.

◆ lttng_event_expr_channel_context_field_get_name()

const char * lttng_event_expr_channel_context_field_get_name ( const struct lttng_event_expr * expr )

extern

Returns the name of the referenced context field of the statically-known context field reference expression expr.

Parameters

[in] expr Event payload field reference expression of which to get the name of the referenced field.

Returns

Name of the referenced field of expr, or NULL on error.

expr owns the returned string.

The returned string remains valid as long as expr exists.

Precondition

expr is not NULL.
expr has the type LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD.

◆ lttng_event_expr_destroy()

void lttng_event_expr_destroy ( struct lttng_event_expr * expr )

extern

Destroys the event expression expr.

Parameters

[in]

expr

Event expression to destroy.

May be NULL.

◆ lttng_event_expr_event_payload_field_create()

struct lttng_event_expr * lttng_event_expr_event_payload_field_create ( const char * field_name )

extern

Creates an event payload field reference expression for the payload field named field_name.

Parameters

[in] field_name Name of the payload field to reference to (copied).

Returns: Event payload field reference expression for the payload field named field_name, or NULL on error.

Precondition

field_name is not NULL.

◆ lttng_event_expr_event_payload_field_get_name()

const char * lttng_event_expr_event_payload_field_get_name ( const struct lttng_event_expr * expr )

extern

Returns the name of the referenced payload field of the event payload field reference expression expr.

Parameters

[in] expr Event payload field reference expression of which to get the name of the referenced field.

Returns

Name of the referenced field of expr, or NULL on error.

expr owns the returned string.

The returned string remains valid as long as expr exists.

Precondition

expr is not NULL.
expr has the type LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD.

◆ lttng_event_expr_get_type()

enum lttng_event_expr_type lttng_event_expr_get_type ( const struct lttng_event_expr * expr )

extern

Returns the type of the event expression expr.

Parameters

[in] expr Event expression of which to get the type.

Returns: Type of expr.

Precondition

expr is not NULL.

◆ lttng_event_expr_is_equal()

bool lttng_event_expr_is_equal	(	const struct lttng_event_expr *	expr_a,
		const struct lttng_event_expr *	expr_b
	)

extern

Returns whether or not the event expressions expr_a and expr_b are equal.

Parameters

[in]

expr_a

Event expression to compare to expr_b.

May be NULL.

[in]

expr_b

Event expression to compare to expr_a.

May be NULL.

Returns: true if expr_a and expr_b are equal.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ lttng_event_expr_status

◆ lttng_event_expr_type

Function Documentation

◆ lttng_event_expr_app_specific_context_field_create()

◆ lttng_event_expr_app_specific_context_field_get_provider_name()

◆ lttng_event_expr_app_specific_context_field_get_type_name()

◆ lttng_event_expr_array_field_element_create()

◆ lttng_event_expr_array_field_element_get_index()

◆ lttng_event_expr_array_field_element_get_parent_expr()

◆ lttng_event_expr_channel_context_field_create()

◆ lttng_event_expr_channel_context_field_get_name()

◆ lttng_event_expr_destroy()

◆ lttng_event_expr_event_payload_field_create()

◆ lttng_event_expr_event_payload_field_get_name()

◆ lttng_event_expr_get_type()

◆ lttng_event_expr_is_equal()