2 * Copyright (C) 2020 Philippe Proulx <pproulx@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_EVENT_EXPR_H
9 #define LTTNG_EVENT_EXPR_H
11 #include <lttng/lttng-export.h>
15 struct lttng_event_expr
;
22 * Types of an event expression.
24 enum lttng_event_expr_type
{
26 * Returned by lttng_event_expr_get_type() with an invalid
29 LTTNG_EVENT_EXPR_TYPE_INVALID
= -1,
32 * The named payload field of an event.
34 * Command-line expression example:
38 LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD
= 0,
41 * The named per-channel context field of an event.
43 * Command-line expression example:
47 LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD
= 1,
50 * The named application-specific context field of an event.
52 * Command-line expression example:
54 * $app.iga:active-clients
56 LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD
= 2,
59 * The element of an array field.
61 * Command-line expression example:
64 * $ctx.some_context[5][1]
66 LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT
= 3,
70 * Event expression API status codes.
72 enum lttng_event_expr_status
{
76 LTTNG_EVENT_EXPR_STATUS_INVALID
= -1,
81 LTTNG_EVENT_EXPR_STATUS_OK
= 0,
85 * Returns the type of the event expression `expr`, or
86 * `LTTNG_EVENT_EXPR_TYPE_INVALID` if `expr` is `NULL`.
88 LTTNG_EXPORT
extern enum lttng_event_expr_type
89 lttng_event_expr_get_type(const struct lttng_event_expr
*expr
);
92 * Creates an event payload field expression for the payload field named
97 * * There's a memory error.
98 * * `field_name` is `NULL`.
100 LTTNG_EXPORT
extern struct lttng_event_expr
*
101 lttng_event_expr_event_payload_field_create(const char *field_name
);
104 * Returns the field name of the event payload field expression `expr`,
107 * * `expr` is `NULL`.
108 * * The type of `expr` is not
109 * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`.
111 LTTNG_EXPORT
extern const char *
112 lttng_event_expr_event_payload_field_get_name(const struct lttng_event_expr
*expr
);
115 * Creates a per-channel context field expression for the per-channel
116 * context field named `field_name`.
120 * * There's a memory error.
121 * * `field_name` is `NULL`.
123 LTTNG_EXPORT
extern struct lttng_event_expr
*
124 lttng_event_expr_channel_context_field_create(const char *field_name
);
127 * Returns the field name of the per-channel context field
128 * expression `expr`, or `NULL` if:
131 * * The type of `expr` is not
132 * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`.
134 LTTNG_EXPORT
extern const char *
135 lttng_event_expr_channel_context_field_get_name(const struct lttng_event_expr
*expr
);
138 * Creates an application-specific context field expression for the
139 * application-specific context field provided by the provider named
140 * `provider_name` and having the type named `type_name`.
144 * * There's a memory error.
145 * * `provider_name` is `NULL`.
146 * * `type_name` is `NULL`.
148 LTTNG_EXPORT
extern struct lttng_event_expr
*
149 lttng_event_expr_app_specific_context_field_create(const char *provider_name
,
150 const char *type_name
);
153 * Returns the provider name of the application-specific context field
154 * expression `expr`, or `NULL` if:
156 * * `expr` is `NULL`.
157 * * The type of `expr` is not
158 * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`.
160 LTTNG_EXPORT
extern const char *
161 lttng_event_expr_app_specific_context_field_get_provider_name(const struct lttng_event_expr
*expr
);
164 * Returns the type name of the application-specific context field
165 * expression `expr`, or `NULL` if:
167 * * `expr` is `NULL`.
168 * * The type of `expr` is not
169 * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`.
171 LTTNG_EXPORT
extern const char *
172 lttng_event_expr_app_specific_context_field_get_type_name(const struct lttng_event_expr
*expr
);
175 * Creates an array field element expression for the parent array field
176 * `array_field_expr` (transfering the ownership) and the index `index`.
180 * * There's a memory error.
181 * * `array_field_expr` is `NULL`.
182 * * `array_field_expr` is not a locator expression, that is, its type
185 * * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`
186 * * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`
187 * * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`
188 * * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`
190 LTTNG_EXPORT
extern struct lttng_event_expr
*
191 lttng_event_expr_array_field_element_create(struct lttng_event_expr
*array_field_expr
,
195 * Returns the parent array field expression of the array field element
196 * expression `expr`, or `NULL` if:
198 * * `expr` is `NULL`.
199 * * The type of `expr` is not
200 * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`.
202 LTTNG_EXPORT
extern const struct lttng_event_expr
*
203 lttng_event_expr_array_field_element_get_parent_expr(const struct lttng_event_expr
*expr
);
206 * Sets `*index` to the index of the array field element expression
211 * `LTTNG_EVENT_EXPR_STATUS_OK`:
214 * `LTTNG_EVENT_EXPR_STATUS_INVALID`:
215 * * `expr` is `NULL`.
216 * * The type of `expr` is not
217 * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`.
218 * * `index` is `NULL`.
220 LTTNG_EXPORT
extern enum lttng_event_expr_status
221 lttng_event_expr_array_field_element_get_index(const struct lttng_event_expr
*expr
,
222 unsigned int *index
);
225 * Returns whether or not the event expressions `expr_a` and `expr_b`
228 * `expr_a` and `expr_b` can be `NULL`.
230 LTTNG_EXPORT
extern bool lttng_event_expr_is_equal(const struct lttng_event_expr
*expr_a
,
231 const struct lttng_event_expr
*expr_b
);
234 * Destroys the event expression `expr` if not `NULL`.
236 LTTNG_EXPORT
extern void lttng_event_expr_destroy(struct lttng_event_expr
*expr
);
242 #endif /* LTTNG_EVENT_EXPR_H */