SoW-2020-0002: Trace Hit Counters: trigger error reporting integration
[lttng-tools.git] / include / lttng / event-expr.h
1 /*
2 * Copyright (C) 2020 Philippe Proulx <pproulx@efficios.com>
3 *
4 * SPDX-License-Identifier: LGPL-2.1-only
5 *
6 */
7
8 #ifndef LTTNG_EVENT_EXPR_H
9 #define LTTNG_EVENT_EXPR_H
10
11 #include <stdbool.h>
12
13 struct lttng_event_expr;
14
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18
19 /*
20 * Types of an event expression.
21 */
22 enum lttng_event_expr_type {
23 /*
24 * Returned by lttng_event_expr_get_type() with an invalid
25 * parameter.
26 */
27 LTTNG_EVENT_EXPR_TYPE_INVALID = -1,
28
29 /*
30 * The named payload field of an event.
31 *
32 * Command-line expression example:
33 *
34 * next_prio
35 */
36 LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD = 0,
37
38 /*
39 * The named per-channel context field of an event.
40 *
41 * Command-line expression example:
42 *
43 * $ctx.vpid
44 */
45 LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD = 1,
46
47 /*
48 * The named application-specific context field of an event.
49 *
50 * Command-line expression example:
51 *
52 * $app.iga:active-clients
53 */
54 LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD = 2,
55
56 /*
57 * The element of an array field.
58 *
59 * Command-line expression example:
60 *
61 * my_field[4]
62 * $ctx.some_context[5][1]
63 */
64 LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT = 3,
65 };
66
67 /*
68 * Event expression API status codes.
69 */
70 enum lttng_event_expr_status {
71 /*
72 * Invalid parameter.
73 */
74 LTTNG_EVENT_EXPR_STATUS_INVALID = -1,
75
76 /*
77 * Success.
78 */
79 LTTNG_EVENT_EXPR_STATUS_OK = 0,
80 };
81
82 /*
83 * Returns the type of the event expression `expr`, or
84 * `LTTNG_EVENT_EXPR_TYPE_INVALID` if `expr` is `NULL`.
85 */
86 extern enum lttng_event_expr_type lttng_event_expr_get_type(
87 const struct lttng_event_expr *expr);
88
89 /*
90 * Creates an event payload field expression for the payload field named
91 * `field_name`.
92 *
93 * Returns `NULL` if:
94 *
95 * * There's a memory error.
96 * * `field_name` is `NULL`.
97 */
98 extern struct lttng_event_expr *lttng_event_expr_event_payload_field_create(
99 const char *field_name);
100
101 /*
102 * Returns the field name of the event payload field expression `expr`,
103 * or `NULL` if:
104 *
105 * * `expr` is `NULL`.
106 * * The type of `expr` is not
107 * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`.
108 */
109 extern const char *lttng_event_expr_event_payload_field_get_name(
110 const struct lttng_event_expr *expr);
111
112 /*
113 * Creates a per-channel context field expression for the per-channel
114 * context field named `field_name`.
115 *
116 * Returns `NULL` if:
117 *
118 * * There's a memory error.
119 * * `field_name` is `NULL`.
120 */
121 extern struct lttng_event_expr *
122 lttng_event_expr_channel_context_field_create(const char *field_name);
123
124 /*
125 * Returns the field name of the per-channel context field
126 * expression `expr`, or `NULL` if:
127 *
128 * `expr` is `NULL`.
129 * * The type of `expr` is not
130 * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`.
131 */
132 extern const char *lttng_event_expr_channel_context_field_get_name(
133 const struct lttng_event_expr *expr);
134
135 /*
136 * Creates an application-specific context field expression for the
137 * application-specific context field provided by the provider named
138 * `provider_name` and having the type named `type_name`.
139 *
140 * Returns `NULL` if:
141 *
142 * * There's a memory error.
143 * * `provider_name` is `NULL`.
144 * * `type_name` is `NULL`.
145 */
146 extern struct lttng_event_expr *
147 lttng_event_expr_app_specific_context_field_create(
148 const char *provider_name, const char *type_name);
149
150 /*
151 * Returns the provider name of the application-specific context field
152 * expression `expr`, or `NULL` if:
153 *
154 * * `expr` is `NULL`.
155 * * The type of `expr` is not
156 * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`.
157 */
158 extern const char *
159 lttng_event_expr_app_specific_context_field_get_provider_name(
160 const struct lttng_event_expr *expr);
161
162 /*
163 * Returns the type name of the application-specific context field
164 * expression `expr`, or `NULL` if:
165 *
166 * * `expr` is `NULL`.
167 * * The type of `expr` is not
168 * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`.
169 */
170 extern const char *
171 lttng_event_expr_app_specific_context_field_get_type_name(
172 const struct lttng_event_expr *expr);
173
174 /*
175 * Creates an array field element expression for the parent array field
176 * `array_field_expr` (transfering the ownership) and the index `index`.
177 *
178 * Returns `NULL` if:
179 *
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
183 * is not one of:
184 *
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`
189 */
190 extern struct lttng_event_expr *lttng_event_expr_array_field_element_create(
191 struct lttng_event_expr *array_field_expr,
192 unsigned int index);
193
194 /*
195 * Returns the parent array field expression of the array field element
196 * expression `expr`, or `NULL` if:
197 *
198 * * `expr` is `NULL`.
199 * * The type of `expr` is not
200 * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`.
201 */
202 extern const struct lttng_event_expr *
203 lttng_event_expr_array_field_element_get_parent_expr(
204 const struct lttng_event_expr *expr);
205
206 /*
207 * Sets `*index` to the index of the array field element expression
208 * `expr`.
209 *
210 * Returns:
211 *
212 * `LTTNG_EVENT_EXPR_STATUS_OK`:
213 * Success.
214 *
215 * `LTTNG_EVENT_EXPR_STATUS_INVALID`:
216 * * `expr` is `NULL`.
217 * * The type of `expr` is not
218 * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`.
219 * * `index` is `NULL`.
220 */
221 extern enum lttng_event_expr_status
222 lttng_event_expr_array_field_element_get_index(
223 const struct lttng_event_expr *expr, unsigned int *index);
224
225 /*
226 * Returns whether or not the event expressions `expr_a` and `expr_b`
227 * are equal.
228 *
229 * `expr_a` and `expr_b` can be `NULL`.
230 */
231 extern bool lttng_event_expr_is_equal(const struct lttng_event_expr *expr_a,
232 const struct lttng_event_expr *expr_b);
233
234 /*
235 * Destroys the event expression `expr` if not `NULL`.
236 */
237 extern void lttng_event_expr_destroy(struct lttng_event_expr *expr);
238
239 #ifdef __cplusplus
240 }
241 #endif
242
243 #endif /* LTTNG_EVENT_EXPR_H */
This page took 0.051532 seconds and 5 git commands to generate.