include/lttng/condition/event-rule.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_EVENT_RULE_H
   9 #define LTTNG_CONDITION_EVENT_RULE_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 /**
  20  * Event rule conditions allows an action to be taken whenever an event matching
  21  * the event rule is hit by the tracers.
  22  *
  23  * An event rule condition can also specify a payload to be captured at runtime.
  24  * This is done via the capture descriptor.
  25  *
  26  * Note: the dynamic runtime capture of payload is only available for the
  27  *       trigger notification subsystem.
  28  */
  29
  30 /*
  31  * Create a newly allocated event rule condition.
  32  *
  33  * Returns a new condition on success, NULL on failure. This condition must be
  34  * destroyed using lttng_condition_destroy().
  35  */
  36 extern struct lttng_condition *lttng_condition_event_rule_create(
  37                 struct lttng_event_rule *rule);
  38
  39 /*
  40  * Get the rule property of a event rule condition.
  41  *
  42  * The caller does not assume the ownership of the returned rule. The
  43  * rule shall only be used for the duration of the condition's
  44  * lifetime.
  45  *
  46  * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule
  47  * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
  48  * parameter is passed. */
  49 extern enum lttng_condition_status lttng_condition_event_rule_get_rule(
  50                  const struct lttng_condition *condition,
  51                 const struct lttng_event_rule **rule);
  52
  53 /**
  54  * lttng_evaluation_event_rule_hit are specialised lttng_evaluations which
  55  * allow users to query a number of properties resulting from the evaluation
  56  * of a condition which evaluated to true.
  57  *
  58  * The evaluation of a event rule hit yields two different results:
  59  *    TEMPORARY - The name of the triggers associated with the condition.
  60  *    TODO - The captured event payload if any
  61  */
  62
  63 /*
  64  * Get the trigger name property of a event rule hit evaluation.
  65  *
  66  * Returns LTTNG_EVALUATION_STATUS_OK on success and a trigger name
  67  * or LTTNG_EVALUATION_STATUS_INVALID if
  68  * an invalid parameter is passed.
  69  */
  70 extern enum lttng_evaluation_status
  71 lttng_evaluation_event_rule_get_trigger_name(
  72                 const struct lttng_evaluation *evaluation,
  73                 const char **name);
  74
  75 #ifdef __cplusplus
  76 }
  77 #endif
  78
  79 #endif /* LTTNG_CONDITION_EVENT_RULE_H */