X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Fevent-expr.h;fp=include%2Flttng%2Fevent-expr.h;h=911648779c5872bb5a525032e6601362b689e578;hp=0000000000000000000000000000000000000000;hb=2463b7879c00298daa79744cdaae82ac061a4ed8;hpb=3a4595c2469472dee1656cde5f8882c2123efd3c diff --git a/include/lttng/event-expr.h b/include/lttng/event-expr.h new file mode 100644 index 000000000..911648779 --- /dev/null +++ b/include/lttng/event-expr.h @@ -0,0 +1,243 @@ +/* + * Copyright (C) 2020 Philippe Proulx + * + * SPDX-License-Identifier: LGPL-2.1-only + * + */ + +#ifndef LTTNG_EVENT_EXPR_H +#define LTTNG_EVENT_EXPR_H + +#include + +struct lttng_event_expr; + +#ifdef __cplusplus +extern "C" { +#endif + +/* + * Types of an event expression. + */ +enum lttng_event_expr_type { + /* + * Returned by lttng_event_expr_get_type() with an invalid + * parameter. + */ + LTTNG_EVENT_EXPR_TYPE_INVALID = -1, + + /* + * The named payload field of an event. + * + * Command-line expression example: + * + * next_prio + */ + LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD = 0, + + /* + * The named per-channel context field of an event. + * + * Command-line expression example: + * + * $ctx.vpid + */ + LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD = 1, + + /* + * The named application-specific context field of an event. + * + * Command-line expression example: + * + * $app.iga:active-clients + */ + LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD = 2, + + /* + * The element of an array field. + * + * Command-line expression example: + * + * my_field[4] + * $ctx.some_context[5][1] + */ + LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT = 3, +}; + +/* + * Event expression API status codes. + */ +enum lttng_event_expr_status { + /* + * Invalid parameter. + */ + LTTNG_EVENT_EXPR_STATUS_INVALID = -1, + + /* + * Success. + */ + LTTNG_EVENT_EXPR_STATUS_OK = 0, +}; + +/* + * Returns the type of the event expression `expr`, or + * `LTTNG_EVENT_EXPR_TYPE_INVALID` if `expr` is `NULL`. + */ +extern enum lttng_event_expr_type lttng_event_expr_get_type( + const struct lttng_event_expr *expr); + +/* + * Creates an event payload field expression for the payload field named + * `field_name`. + * + * Returns `NULL` if: + * + * * There's a memory error. + * * `field_name` is `NULL`. + */ +extern struct lttng_event_expr *lttng_event_expr_event_payload_field_create( + const char *field_name); + +/* + * Returns the field name of the event payload field expression `expr`, + * or `NULL` if: + * + * * `expr` is `NULL`. + * * The type of `expr` is not + * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`. + */ +extern const char *lttng_event_expr_event_payload_field_get_name( + const struct lttng_event_expr *expr); + +/* + * Creates a per-channel context field expression for the per-channel + * context field named `field_name`. + * + * Returns `NULL` if: + * + * * There's a memory error. + * * `field_name` is `NULL`. + */ +extern struct lttng_event_expr * +lttng_event_expr_channel_context_field_create(const char *field_name); + +/* + * Returns the field name of the per-channel context field + * expression `expr`, or `NULL` if: + * + * `expr` is `NULL`. + * * The type of `expr` is not + * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`. + */ +extern const char *lttng_event_expr_channel_context_field_get_name( + const struct lttng_event_expr *expr); + +/* + * Creates an application-specific context field expression for the + * application-specific context field provided by the provider named + * `provider_name` and having the type named `type_name`. + * + * Returns `NULL` if: + * + * * There's a memory error. + * * `provider_name` is `NULL`. + * * `type_name` is `NULL`. + */ +extern struct lttng_event_expr * +lttng_event_expr_app_specific_context_field_create( + const char *provider_name, const char *type_name); + +/* + * Returns the provider name of the application-specific context field + * expression `expr`, or `NULL` if: + * + * * `expr` is `NULL`. + * * The type of `expr` is not + * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`. + */ +extern const char * +lttng_event_expr_app_specific_context_field_get_provider_name( + const struct lttng_event_expr *expr); + +/* + * Returns the type name of the application-specific context field + * expression `expr`, or `NULL` if: + * + * * `expr` is `NULL`. + * * The type of `expr` is not + * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`. + */ +extern const char * +lttng_event_expr_app_specific_context_field_get_type_name( + const struct lttng_event_expr *expr); + +/* + * Creates an array field element expression for the parent array field + * `array_field_expr` (transfering the ownership) and the index `index`. + * + * Returns `NULL` if: + * + * * There's a memory error. + * * `array_field_expr` is `NULL`. + * * `array_field_expr` is not a locator expression, that is, its type + * is not one of: + * + * * `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` + */ +extern struct lttng_event_expr *lttng_event_expr_array_field_element_create( + struct lttng_event_expr *array_field_expr, + unsigned int index); + +/* + * Returns the parent array field expression of the array field element + * expression `expr`, or `NULL` if: + * + * * `expr` is `NULL`. + * * The type of `expr` is not + * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`. + */ +extern const struct lttng_event_expr * +lttng_event_expr_array_field_element_get_parent_expr( + const struct lttng_event_expr *expr); + +/* + * Sets `*index` to the index of the array field element expression + * `expr`. + * + * Returns: + * + * `LTTNG_EVENT_EXPR_STATUS_OK`: + * Success. + * + * `LTTNG_EVENT_EXPR_STATUS_INVALID`: + * * `expr` is `NULL`. + * * The type of `expr` is not + * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`. + * * `index` is `NULL`. + */ +extern enum lttng_event_expr_status +lttng_event_expr_array_field_element_get_index( + const struct lttng_event_expr *expr, unsigned int *index); + +/* + * Returns whether or not the event expressions `expr_a` and `expr_b` + * are equal. + * + * `expr_a` and `expr_b` can be `NULL`. + */ +extern bool lttng_event_expr_is_equal(const struct lttng_event_expr *expr_a, + const struct lttng_event_expr *expr_b); + +/* + * Destroys the event expression `expr` if not `NULL`. + */ +extern void lttng_event_expr_destroy(struct lttng_event_expr *expr); + +#ifdef __cplusplus +} +#endif + +#endif /* LTTNG_EVENT_EXPR_H */