include/lttng/trigger/trigger-internal.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_INTERNAL_H
   9 #define LTTNG_TRIGGER_INTERNAL_H
  10
  11 #include <common/credentials.h>
  12 #include <common/dynamic-array.h>
  13 #include <common/macros.h>
  14 #include <common/optional.h>
  15 #include <lttng/lttng.h>
  16 #include <pthread.h>
  17 #include <stdbool.h>
  18 #include <stdint.h>
  19 #include <sys/types.h>
  20 #include <urcu/ref.h>
  21
  22 struct lttng_payload;
  23 struct lttng_payload_view;
  24 struct mi_writer;
  25 struct mi_lttng_error_query_callbacks;
  26
  27 struct lttng_trigger {
  28         /* Reference counting is only exposed to internal users. */
  29         struct urcu_ref ref;
  30
  31         struct lttng_condition *condition;
  32         struct lttng_action *action;
  33         char *name;
  34         /* For now only the uid portion of the credentials is used. */
  35         struct lttng_credentials creds;
  36         /*
  37          * Internal use only.
  38          * The unique token passed to the tracer to identify an event-rule
  39          * notification.
  40          */
  41         LTTNG_OPTIONAL(uint64_t) tracer_token;
  42
  43         /*
  44          * Is the trigger registered?
  45          *
  46          * This is necessary since a reference holder might be interested in the
  47          * overall state of the trigger from the point of view of its owner.
  48          *
  49          * The main user is the action executor since we want to prevent the
  50          * execution of actions related to a trigger that is unregistered.
  51          *
  52          * Not considered for `is_equal`.
  53          */
  54         bool registered;
  55
  56         /*
  57          * A "hidden" trigger is a trigger that is not externally listed.
  58          * It is used to hide triggers that are used internally by the session
  59          * daemon so that they can't be listed nor unregistered by external
  60          * clients.
  61          *
  62          * This is a property that can only be set internally by the session
  63          * daemon. As such, it is not serialized nor set by a
  64          * "create_from_buffer" constructor.
  65          *
  66          * The hidden property is preserved by copies.
  67          *
  68          * Note that notifications originating from an "hidden" trigger will not
  69          * be sent to clients that are not within the session daemon's process.
  70          */
  71         bool is_hidden;
  72
  73         /*
  74          * The lock is used to protect against concurrent trigger execution and
  75          * trigger removal.
  76          */
  77         pthread_mutex_t lock;
  78 };
  79
  80 struct lttng_triggers {
  81         struct lttng_dynamic_pointer_array array;
  82 };
  83
  84 struct lttng_trigger_comm {
  85         /*
  86          * Credentials, only the uid portion is used for now.
  87          * Used as an override when desired by the root user.
  88          */
  89         uint64_t uid;
  90         /*
  91          * Length of the variable length payload (name, condition, and
  92          * an action).
  93          */
  94         uint32_t length;
  95         /* Includes '\0' terminator. */
  96         uint32_t name_length;
  97         /* A null-terminated name, a condition, and an action follow. */
  98         char payload[];
  99 } LTTNG_PACKED;
 100
 101 struct lttng_triggers_comm {
 102         uint32_t count;
 103         uint32_t length;
 104         /* Count * lttng_trigger_comm structure */
 105         char payload[];
 106 };
 107
 108 ssize_t lttng_trigger_create_from_payload(struct lttng_payload_view *view,
 109                 struct lttng_trigger **trigger);
 110
 111 int lttng_trigger_serialize(const struct lttng_trigger *trigger,
 112                 struct lttng_payload *payload);
 113
 114 bool lttng_trigger_validate(const struct lttng_trigger *trigger);
 115
 116 int lttng_trigger_assign_name(
 117                 struct lttng_trigger *dst, const struct lttng_trigger *src);
 118
 119 void lttng_trigger_set_tracer_token(
 120                 struct lttng_trigger *trigger, uint64_t token);
 121
 122 uint64_t lttng_trigger_get_tracer_token(const struct lttng_trigger *trigger);
 123
 124 int lttng_trigger_generate_name(struct lttng_trigger *trigger,
 125                 uint64_t unique_id);
 126
 127 bool lttng_trigger_is_equal(
 128                 const struct lttng_trigger *a, const struct lttng_trigger *b);
 129
 130 bool lttng_trigger_is_hidden(const struct lttng_trigger *trigger);
 131
 132 void lttng_trigger_set_hidden(struct lttng_trigger *trigger);
 133
 134 void lttng_trigger_get(struct lttng_trigger *trigger);
 135
 136 void lttng_trigger_put(struct lttng_trigger *trigger);
 137
 138 /*
 139  * Serialize a trigger to a mi_writer.
 140  * Return LTTNG_OK in success, other enum lttng_error_code on error.
 141  */
 142 enum lttng_error_code lttng_trigger_mi_serialize(const struct lttng_trigger *trigger,
 143                 struct mi_writer *writer,
 144                 const struct mi_lttng_error_query_callbacks
 145                                 *error_query_callbacks);
 146
 147 /*
 148  * Allocate a new set of triggers.
 149  * The returned object must be freed via lttng_triggers_destroy.
 150  */
 151 struct lttng_triggers *lttng_triggers_create(void);
 152
 153 /*
 154  * Return the a pointer to a mutable element at index "index" of an
 155  * lttng_triggers set.
 156  *
 157  * This differs from the public `lttng_triggers_get_at_index` in that
 158  * the returned pointer to a mutable trigger.
 159  *
 160  * The ownership of the trigger set element is NOT transfered.
 161  * The returned object can NOT be freed via lttng_trigger_destroy.
 162  */
 163 struct lttng_trigger *lttng_triggers_borrow_mutable_at_index(
 164                 const struct lttng_triggers *triggers, unsigned int index);
 165
 166 /*
 167  * Add a trigger to the triggers set.
 168  *
 169  * A reference to the added trigger is acquired on behalf of the trigger set
 170  * on success.
 171  */
 172 int lttng_triggers_add(
 173                 struct lttng_triggers *triggers, struct lttng_trigger *trigger);
 174
 175 /*
 176  * Remove all triggers marked as hidden from the provided trigger set.
 177  */
 178 int lttng_triggers_remove_hidden_triggers(struct lttng_triggers *triggers);
 179
 180 /*
 181  * Serialize a trigger set to an lttng_payload object.
 182  * Return LTTNG_OK on success, negative lttng error code on error.
 183  */
 184 int lttng_triggers_serialize(const struct lttng_triggers *triggers,
 185                 struct lttng_payload *payload);
 186
 187 ssize_t lttng_triggers_create_from_payload(struct lttng_payload_view *view,
 188                 struct lttng_triggers **triggers);
 189
 190 /*
 191  * Serialize a trigger set to a mi_writer.
 192  * Return LTTNG_OK in success, other enum lttng_error_code on error.
 193  */
 194 enum lttng_error_code lttng_triggers_mi_serialize(const struct lttng_triggers *triggers,
 195                 struct mi_writer *writer,
 196                 const struct mi_lttng_error_query_callbacks
 197                                 *error_query_callbacks);
 198
 199 const struct lttng_credentials *lttng_trigger_get_credentials(
 200                 const struct lttng_trigger *trigger);
 201
 202 void lttng_trigger_set_credentials(struct lttng_trigger *trigger,
 203                 const struct lttng_credentials *creds);
 204
 205 /*
 206  * Return the type of any underlying domain restriction. If no particular
 207  * requirement is present, returns LTTNG_DOMAIN_NONE.
 208  */
 209 enum lttng_domain_type lttng_trigger_get_underlying_domain_type_restriction(
 210                 const struct lttng_trigger *trigger);
 211
 212 /*
 213  * Generate any bytecode related to the trigger.
 214  * On success LTTNG_OK. On error, returns lttng_error code.
 215  */
 216 enum lttng_error_code lttng_trigger_generate_bytecode(
 217                 struct lttng_trigger *trigger,
 218                 const struct lttng_credentials *creds);
 219
 220 /*
 221  * Note that the trigger object is not locked by "copy" as it is const and
 222  * used with a number of 'const' triggers. If the trigger could be shared at
 223  * the moment of the copy, it is the caller's responsability to lock it for
 224  * the duration of the copy.
 225  */
 226 struct lttng_trigger *lttng_trigger_copy(const struct lttng_trigger *trigger);
 227
 228 /*
 229  * A given trigger needs a tracer notifier if
 230  *  it has an event-rule condition,
 231  *  AND
 232  *  it has one or more sessiond-execution action.
 233  */
 234 bool lttng_trigger_needs_tracer_notifier(const struct lttng_trigger *trigger);
 235
 236 void lttng_trigger_set_as_registered(struct lttng_trigger *trigger);
 237
 238 void lttng_trigger_set_as_unregistered(struct lttng_trigger *trigger);
 239
 240 /*
 241  * The trigger must be locked before calling lttng_trigger_is_registered.
 242  *
 243  * The lock is necessary since a trigger can be unregistered at any time.
 244  *
 245  * Manipulations requiring that the trigger be registered must always acquire
 246  * the trigger lock for the duration of the manipulation using
 247  * `lttng_trigger_lock` and `lttng_trigger_unlock`.
 248  */
 249 bool lttng_trigger_is_registered(struct lttng_trigger *trigger);
 250
 251 void lttng_trigger_lock(struct lttng_trigger *trigger);
 252
 253 void lttng_trigger_unlock(struct lttng_trigger *trigger);
 254
 255 enum lttng_trigger_status lttng_trigger_add_error_results(
 256                 const struct lttng_trigger *trigger,
 257                 struct lttng_error_query_results *results);
 258
 259 enum lttng_trigger_status lttng_trigger_condition_add_error_results(
 260                 const struct lttng_trigger *trigger,
 261                 struct lttng_error_query_results *results);
 262
 263 enum lttng_trigger_status lttng_trigger_add_action_error_query_results(
 264                 struct lttng_trigger *trigger,
 265                 struct lttng_error_query_results *results);
 266
 267 /*
 268  * Set the trigger name.
 269  *
 270  * A name is optional.
 271  * A name will be assigned on trigger registration if no name is set.
 272  *
 273  * The name is copied.
 274  *
 275  * Return LTTNG_TRIGGER_STATUS_OK on success, LTTNG_TRIGGER_STATUS_INVALID
 276  * if invalid parameters are passed.
 277  */
 278 enum lttng_trigger_status lttng_trigger_set_name(
 279                 struct lttng_trigger *trigger, const char *name);
 280
 281 #endif /* LTTNG_TRIGGER_INTERNAL_H */