include/lttng/condition/on-event.h

   1 /*
   2  * Copyright (C) 2019 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_CONDITION_ON_EVENT_H
   9 #define LTTNG_CONDITION_ON_EVENT_H
  10
  11 #include <lttng/event-rule/event-rule.h>
  12 #include <lttng/condition/condition.h>
  13 #include <lttng/condition/evaluation.h>
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif
  18
  19 struct lttng_event_expr;
  20 struct lttng_event_field_value;
  21
  22 enum lttng_evaluation_on_event_status {
  23         LTTNG_EVALUATION_ON_EVENT_STATUS_NONE = 1,
  24         LTTNG_EVALUATION_ON_EVENT_STATUS_OK = 0,
  25         LTTNG_EVALUATION_ON_EVENT_STATUS_INVALID = -1,
  26 };
  27
  28 /**
  29  * On event conditions allows an action to be taken whenever an event matching
  30  * the on event is hit by the tracers.
  31  *
  32  * An on event condition can also specify a payload to be captured at runtime.
  33  * This is done via the capture descriptor.
  34  *
  35  * Note: the dynamic runtime capture of payload is only available for the
  36  *       trigger notification subsystem.
  37  */
  38
  39 /*
  40  * Create a newly allocated on event condition.
  41  *
  42  * Returns a new condition on success, NULL on failure. This condition must be
  43  * destroyed using lttng_condition_destroy().
  44  */
  45 extern struct lttng_condition *lttng_condition_on_event_create(
  46                 struct lttng_event_rule *rule);
  47
  48 /*
  49  * Get the rule property of a on event condition.
  50  *
  51  * The caller does not assume the ownership of the returned rule. The
  52  * rule shall only be used for the duration of the condition's
  53  * lifetime.
  54  *
  55  * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule
  56  * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
  57  * parameter is passed. */
  58 extern enum lttng_condition_status lttng_condition_on_event_get_rule(
  59                 const struct lttng_condition *condition,
  60                 const struct lttng_event_rule **rule);
  61
  62 /**
  63  * lttng_evaluation_on_event_hit are specialised lttng_evaluations which
  64  * allow users to query a number of properties resulting from the evaluation
  65  * of a condition which evaluated to true.
  66  *
  67  * The evaluation of a on event hit yields two different results:
  68  *    TEMPORARY - The name of the triggers associated with the condition.
  69  *    TODO - The captured event payload if any
  70  */
  71
  72 /*
  73  * Get the trigger name property of a on event hit evaluation.
  74  *
  75  * Returns LTTNG_EVALUATION_STATUS_OK on success and a trigger name
  76  * or LTTNG_EVALUATION_STATUS_INVALID if
  77  * an invalid parameter is passed.
  78  */
  79 extern enum lttng_evaluation_status
  80 lttng_evaluation_on_event_get_trigger_name(
  81                 const struct lttng_evaluation *evaluation,
  82                 const char **name);
  83
  84 /*
  85  * Sets `*field_val` to the array event field value of the on event
  86  * condition evaluation `evaluation` which contains its captured values.
  87  *
  88  * Returns:
  89  *
  90  * `LTTNG_EVALUATION_ON_EVENT_STATUS_OK`:
  91  *     Success.
  92  *
  93  *     `*field_val` is an array event field value with a length of at
  94  *     least one.
  95  *
  96  * `LTTNG_EVALUATION_ON_EVENT_STATUS_INVALID`:
  97  *     * `evaluation` is `NULL`.
  98  *     * The type of the condition of `evaluation` is not
  99  *       `LTTNG_CONDITION_TYPE_ON_EVENT`.
 100  *     * `field_val` is `NULL`.
 101  *
 102  * `LTTNG_EVALUATION_ON_EVENT_STATUS_NONE`:
 103  *     * The condition of `evaluation` has no capture descriptors.
 104  */
 105 extern enum lttng_evaluation_on_event_status
 106 lttng_evaluation_on_event_get_captured_values(
 107                 const struct lttng_evaluation *evaluation,
 108                 const struct lttng_event_field_value **field_val);
 109
 110 /*
 111  * Appends (transfering the ownership) the capture descriptor `expr` to
 112  * the on event condition `condition`.
 113  *
 114  * Returns:
 115  *
 116  * `LTTNG_CONDITION_STATUS_OK`:
 117  *     Success.
 118  *
 119  * `LTTNG_CONDITION_STATUS_ERROR`:
 120  *     Memory error.
 121  *
 122  * `LTTNG_CONDITION_STATUS_INVALID`:
 123  *     * `condition` is `NULL`.
 124  *     * The type of `condition` is not
 125  *       `LTTNG_CONDITION_TYPE_ON_EVENT`.
 126  *     * `expr` is `NULL`.
 127  *     * `expr` is not a locator expression, that is, its type is not
 128  *       one of:
 129  *
 130  *       * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`
 131  *       * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`
 132  *       * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`
 133  *       * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`
 134  *
 135  * `LTTNG_CONDITION_STATUS_UNSUPPORTED`:
 136  *     * The associated event-rule does not support runtime capture.
 137  */
 138 extern enum lttng_condition_status
 139 lttng_condition_on_event_append_capture_descriptor(
 140                 struct lttng_condition *condition,
 141                 struct lttng_event_expr *expr);
 142
 143 /*
 144  * Sets `*count` to the number of capture descriptors in the on event
 145  * condition `condition`.
 146  *
 147  * Returns:
 148  *
 149  * `LTTNG_CONDITION_STATUS_OK`:
 150  *     Success.
 151  *
 152  * `LTTNG_CONDITION_STATUS_INVALID`:
 153  *     * `condition` is `NULL`.
 154  *     * The type of `condition` is not
 155  *       `LTTNG_CONDITION_TYPE_ON_EVENT`.
 156  *     * `count` is `NULL`.
 157  */
 158 extern enum lttng_condition_status
 159 lttng_condition_on_event_get_capture_descriptor_count(
 160                 const struct lttng_condition *condition, unsigned int *count);
 161
 162 /*
 163  * Returns the capture descriptor (borrowed) of the on event condition
 164  * `condition` at the index `index`, or `NULL` if:
 165  *
 166  * * `condition` is `NULL`.
 167  * * The type of `condition` is not
 168  *   `LTTNG_CONDITION_TYPE_ON_EVENT`.
 169  * * `index` is greater than or equal to the number of capture
 170  *   descriptors in `condition` (as returned by
 171  *   lttng_condition_on_event_get_capture_descriptor_count()).
 172  */
 173 extern const struct lttng_event_expr *
 174 lttng_condition_on_event_get_capture_descriptor_at_index(
 175                 const struct lttng_condition *condition, unsigned int index);
 176
 177 #ifdef __cplusplus
 178 }
 179 #endif
 180
 181 #endif /* LTTNG_CONDITION_ON_EVENT_H */