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  * Destroy (frees) a trigger object.
 101  */
 102 extern void lttng_trigger_destroy(struct lttng_trigger *trigger);
 103
 104 /*
 105  * Register a trigger to the session daemon.
 106  *
 107  * The trigger can be destroyed after this call.
 108  *
 109  * Return 0 on success, a negative LTTng error code on error.
 110  */
 111 extern int lttng_register_trigger(struct lttng_trigger *trigger);
 112
 113 /*
 114  * Unregister a trigger from the session daemon.
 115  *
 116  * The trigger can be destroyed after this call.
 117  *
 118  * Return 0 on success, a negative LTTng error code on error.
 119  */
 120 extern int lttng_unregister_trigger(struct lttng_trigger *trigger);
 121
 122 #ifdef __cplusplus
 123 }
 124 #endif
 125
 126 #endif /* LTTNG_TRIGGER_H */