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 */