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 <lttng/lttng-export.h>
  12
  13 #include <stdbool.h>
  14
  15 struct lttng_event_expr;
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 /*
  22  * Types of an event expression.
  23  */
  24 enum lttng_event_expr_type {
  25         /*
  26          * Returned by lttng_event_expr_get_type() with an invalid
  27          * parameter.
  28          */
  29         LTTNG_EVENT_EXPR_TYPE_INVALID = -1,
  30
  31         /*
  32          * The named payload field of an event.
  33          *
  34          * Command-line expression example:
  35          *
  36          *     next_prio
  37          */
  38         LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD = 0,
  39
  40         /*
  41          * The named per-channel context field of an event.
  42          *
  43          * Command-line expression example:
  44          *
  45          *     $ctx.vpid
  46          */
  47         LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD = 1,
  48
  49         /*
  50          * The named application-specific context field of an event.
  51          *
  52          * Command-line expression example:
  53          *
  54          *     $app.iga:active-clients
  55          */
  56         LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD = 2,
  57
  58         /*
  59          * The element of an array field.
  60          *
  61          * Command-line expression example:
  62          *
  63          *     my_field[4]
  64          *     $ctx.some_context[5][1]
  65          */
  66         LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT = 3,
  67 };
  68
  69 /*
  70  * Event expression API status codes.
  71  */
  72 enum lttng_event_expr_status {
  73         /*
  74          * Invalid parameter.
  75          */
  76         LTTNG_EVENT_EXPR_STATUS_INVALID = -1,
  77
  78         /*
  79          * Success.
  80          */
  81         LTTNG_EVENT_EXPR_STATUS_OK = 0,
  82 };
  83
  84 /*
  85  * Returns the type of the event expression `expr`, or
  86  * `LTTNG_EVENT_EXPR_TYPE_INVALID` if `expr` is `NULL`.
  87  */
  88 LTTNG_EXPORT extern enum lttng_event_expr_type
  89 lttng_event_expr_get_type(const struct lttng_event_expr *expr);
  90
  91 /*
  92  * Creates an event payload field expression for the payload field named
  93  * `field_name`.
  94  *
  95  * Returns `NULL` if:
  96  *
  97  * * There's a memory error.
  98  * * `field_name` is `NULL`.
  99  */
 100 LTTNG_EXPORT extern struct lttng_event_expr *
 101 lttng_event_expr_event_payload_field_create(const char *field_name);
 102
 103 /*
 104  * Returns the field name of the event payload field expression `expr`,
 105  * or `NULL` if:
 106  *
 107  * * `expr` is `NULL`.
 108  * * The type of `expr` is not
 109  *   `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`.
 110  */
 111 LTTNG_EXPORT extern const char *
 112 lttng_event_expr_event_payload_field_get_name(const struct lttng_event_expr *expr);
 113
 114 /*
 115  * Creates a per-channel context field expression for the per-channel
 116  * context field named `field_name`.
 117  *
 118  * Returns `NULL` if:
 119  *
 120  * * There's a memory error.
 121  * * `field_name` is `NULL`.
 122  */
 123 LTTNG_EXPORT extern struct lttng_event_expr *
 124 lttng_event_expr_channel_context_field_create(const char *field_name);
 125
 126 /*
 127  * Returns the field name of the per-channel context field
 128  * expression `expr`, or `NULL` if:
 129  *
 130  * `expr` is `NULL`.
 131  * * The type of `expr` is not
 132  *   `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`.
 133  */
 134 LTTNG_EXPORT extern const char *
 135 lttng_event_expr_channel_context_field_get_name(const struct lttng_event_expr *expr);
 136
 137 /*
 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`.
 141  *
 142  * Returns `NULL` if:
 143  *
 144  * * There's a memory error.
 145  * * `provider_name` is `NULL`.
 146  * * `type_name` is `NULL`.
 147  */
 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);
 151
 152 /*
 153  * Returns the provider name of the application-specific context field
 154  * expression `expr`, or `NULL` if:
 155  *
 156  * * `expr` is `NULL`.
 157  * * The type of `expr` is not
 158  *   `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`.
 159  */
 160 LTTNG_EXPORT extern const char *
 161 lttng_event_expr_app_specific_context_field_get_provider_name(const struct lttng_event_expr *expr);
 162
 163 /*
 164  * Returns the type name of the application-specific context field
 165  * expression `expr`, or `NULL` if:
 166  *
 167  * * `expr` is `NULL`.
 168  * * The type of `expr` is not
 169  *   `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`.
 170  */
 171 LTTNG_EXPORT extern const char *
 172 lttng_event_expr_app_specific_context_field_get_type_name(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 LTTNG_EXPORT extern struct lttng_event_expr *
 191 lttng_event_expr_array_field_element_create(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 LTTNG_EXPORT extern const struct lttng_event_expr *
 203 lttng_event_expr_array_field_element_get_parent_expr(const struct lttng_event_expr *expr);
 204
 205 /*
 206  * Sets `*index` to the index of the array field element expression
 207  * `expr`.
 208  *
 209  * Returns:
 210  *
 211  * `LTTNG_EVENT_EXPR_STATUS_OK`:
 212  *     Success.
 213  *
 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`.
 219  */
 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);
 223
 224 /*
 225  * Returns whether or not the event expressions `expr_a` and `expr_b`
 226  * are equal.
 227  *
 228  * `expr_a` and `expr_b` can be `NULL`.
 229  */
 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);
 232
 233 /*
 234  * Destroys the event expression `expr` if not `NULL`.
 235  */
 236 LTTNG_EXPORT extern void lttng_event_expr_destroy(struct lttng_event_expr *expr);
 237
 238 #ifdef __cplusplus
 239 }
 240 #endif
 241
 242 #endif /* LTTNG_EVENT_EXPR_H */