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