include/lttng/trigger/trigger.h

   1 /*
   2  * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_TRIGGER_H
   9 #define LTTNG_TRIGGER_H
  10
  11 #include <sys/types.h>
  12
  13 struct lttng_action;
  14 struct lttng_condition;
  15 struct lttng_trigger;
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 enum lttng_register_trigger_status {
  22         LTTNG_REGISTER_TRIGGER_STATUS_OK = 0,
  23         LTTNG_REGISTER_TRIGGER_STATUS_INVALID = -1,
  24 };
  25
  26 enum lttng_trigger_status {
  27         LTTNG_TRIGGER_STATUS_OK = 0,
  28         LTTNG_TRIGGER_STATUS_ERROR = -1,
  29         LTTNG_TRIGGER_STATUS_UNKNOWN = -2,
  30         LTTNG_TRIGGER_STATUS_INVALID = -3,
  31         LTTNG_TRIGGER_STATUS_UNSET = -4,
  32         LTTNG_TRIGGER_STATUS_UNSUPPORTED = -5,
  33         LTTNG_TRIGGER_STATUS_PERMISSION_DENIED = -6,
  34 };
  35
  36 /*
  37  * Create a trigger object associating a condition and an action.
  38  *
  39  * A trigger associates a condition and an action to take whenever the
  40  * condition evaluates to true. Such actions can, for example, consist
  41  * in the emission of a notification to clients listening through
  42  * notification channels.
  43  *
  44  * The caller retains the ownership of both the condition and action
  45  * and both must be kept alive for the lifetime of the trigger object.
  46  *
  47  * A trigger must be registered in order to become activate and can
  48  * be destroyed after its registration.
  49  *
  50  * Returns a trigger object on success, NULL on error.
  51  * Trigger objects must be destroyed using the lttng_trigger_destroy()
  52  * function.
  53  */
  54 extern struct lttng_trigger *lttng_trigger_create(
  55                 struct lttng_condition *condition, struct lttng_action *action);
  56
  57 /*
  58  * Set the user identity (uid) of a trigger.
  59  *
  60  * Only available for the root user (uid 0).
  61  *
  62  * Returns LTTNG_TRIGGER_STATUS_OK on success,
  63  * LTTNG_TRIGGER_STATUS_EPERM if not authorized,
  64  * LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed.
  65  */
  66 extern enum lttng_trigger_status lttng_trigger_set_owner_uid(
  67                 struct lttng_trigger *trigger, uid_t uid);
  68
  69 /*
  70  * Get the user identity (uid) of a trigger.
  71  *
  72  * Returns LTTNG_TRIGGER_STATUS_OK on success,
  73  * LTTNG_TRIGGER_STATUS_UNSET if unset,
  74  * LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed.
  75  */
  76 extern enum lttng_trigger_status lttng_trigger_get_owner_uid(
  77                 const struct lttng_trigger *trigger, uid_t *uid);
  78
  79 /*
  80  * Get the condition of a trigger.
  81  *
  82  * The caller acquires no ownership of the returned condition.
  83  *
  84  * Returns a condition on success, NULL on error.
  85  */
  86 extern struct lttng_condition *lttng_trigger_get_condition(
  87                 struct lttng_trigger *trigger);
  88
  89 /*
  90  * Get the action of a trigger.
  91  *
  92  * The caller acquires no ownership of the returned action.
  93  *
  94  * Returns an action on success, NULL on error.
  95  */
  96 extern struct lttng_action *lttng_trigger_get_action(
  97                 struct lttng_trigger *trigger);
  98
  99
 100 /*
 101  * Get the name of a trigger.
 102  *
 103  * The caller does not assume the ownership of the returned name.
 104  * The name shall only only be used for the duration of the trigger's
 105  * lifetime, or until a different name is set.
 106  *
 107  * Returns LTTNG_TRIGGER_STATUS_OK and a pointer to the trigger's name on
 108  * success, LTTNG_TRIGGER_STATUS_INVALID if an invalid parameter is passed,
 109  * or LTTNG_TRIGGER_STATUS_UNSET if a name was not set prior to this call.
 110  */
 111 extern enum lttng_trigger_status lttng_trigger_get_name(
 112                 const struct lttng_trigger *trigger, const char **name);
 113
 114 /*
 115  * Set the trigger name.
 116  *
 117  * A name is optional.
 118  * A name will be assigned on trigger registration if no name is set.
 119  *
 120  * The name is copied.
 121  *
 122  * Return LTTNG_TRIGGER_STATUS_OK on success, LTTNG_TRIGGER_STATUS_INVALID
 123  * if invalid parameters are passed.
 124  */
 125 extern enum lttng_trigger_status lttng_trigger_set_name(
 126                 struct lttng_trigger *trigger, const char *name);
 127
 128 /*
 129  * Destroy (frees) a trigger object.
 130  */
 131 extern void lttng_trigger_destroy(struct lttng_trigger *trigger);
 132
 133 /*
 134  * Register a trigger to the session daemon.
 135  *
 136  * The trigger can be destroyed after this call.
 137  *
 138  * Return 0 on success, a negative LTTng error code on error.
 139  */
 140 extern int lttng_register_trigger(struct lttng_trigger *trigger);
 141
 142 /*
 143  * Unregister a trigger from the session daemon.
 144  *
 145  * The trigger can be destroyed after this call.
 146  *
 147  * Return 0 on success, a negative LTTng error code on error.
 148  */
 149 extern int lttng_unregister_trigger(struct lttng_trigger *trigger);
 150
 151 #ifdef __cplusplus
 152 }
 153 #endif
 154
 155 #endif /* LTTNG_TRIGGER_H */