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 LTTNG_HIDDEN
 109 ssize_t lttng_trigger_create_from_payload(struct lttng_payload_view *view,
 110                 struct lttng_trigger **trigger);
 111
 112 LTTNG_HIDDEN
 113 int lttng_trigger_serialize(const struct lttng_trigger *trigger,
 114                 struct lttng_payload *payload);
 115
 116 LTTNG_HIDDEN
 117 bool lttng_trigger_validate(const struct lttng_trigger *trigger);
 118
 119 LTTNG_HIDDEN
 120 int lttng_trigger_assign_name(
 121                 struct lttng_trigger *dst, const struct lttng_trigger *src);
 122
 123 LTTNG_HIDDEN
 124 void lttng_trigger_set_tracer_token(
 125                 struct lttng_trigger *trigger, uint64_t token);
 126
 127 LTTNG_HIDDEN
 128 uint64_t lttng_trigger_get_tracer_token(const struct lttng_trigger *trigger);
 129
 130 LTTNG_HIDDEN
 131 int lttng_trigger_generate_name(struct lttng_trigger *trigger,
 132                 uint64_t unique_id);
 133
 134 LTTNG_HIDDEN
 135 bool lttng_trigger_is_equal(
 136                 const struct lttng_trigger *a, const struct lttng_trigger *b);
 137
 138 LTTNG_HIDDEN
 139 bool lttng_trigger_is_hidden(const struct lttng_trigger *trigger);
 140
 141 LTTNG_HIDDEN
 142 void lttng_trigger_set_hidden(struct lttng_trigger *trigger);
 143
 144 LTTNG_HIDDEN
 145 void lttng_trigger_get(struct lttng_trigger *trigger);
 146
 147 LTTNG_HIDDEN
 148 void lttng_trigger_put(struct lttng_trigger *trigger);
 149
 150 /*
 151  * Serialize a trigger to a mi_writer.
 152  * Return LTTNG_OK in success, other enum lttng_error_code on error.
 153  */
 154 LTTNG_HIDDEN
 155 enum lttng_error_code lttng_trigger_mi_serialize(const struct lttng_trigger *trigger,
 156                 struct mi_writer *writer,
 157                 const struct mi_lttng_error_query_callbacks
 158                                 *error_query_callbacks);
 159
 160 /*
 161  * Allocate a new set of triggers.
 162  * The returned object must be freed via lttng_triggers_destroy.
 163  */
 164 LTTNG_HIDDEN
 165 struct lttng_triggers *lttng_triggers_create(void);
 166
 167 /*
 168  * Return the a pointer to a mutable element at index "index" of an
 169  * lttng_triggers set.
 170  *
 171  * This differs from the public `lttng_triggers_get_at_index` in that
 172  * the returned pointer to a mutable trigger.
 173  *
 174  * The ownership of the trigger set element is NOT transfered.
 175  * The returned object can NOT be freed via lttng_trigger_destroy.
 176  */
 177 LTTNG_HIDDEN
 178 struct lttng_trigger *lttng_triggers_borrow_mutable_at_index(
 179                 const struct lttng_triggers *triggers, unsigned int index);
 180
 181 /*
 182  * Add a trigger to the triggers set.
 183  *
 184  * A reference to the added trigger is acquired on behalf of the trigger set
 185  * on success.
 186  */
 187 LTTNG_HIDDEN
 188 int lttng_triggers_add(
 189                 struct lttng_triggers *triggers, struct lttng_trigger *trigger);
 190
 191 /*
 192  * Remove all triggers marked as hidden from the provided trigger set.
 193  */
 194 LTTNG_HIDDEN
 195 int lttng_triggers_remove_hidden_triggers(struct lttng_triggers *triggers);
 196
 197 /*
 198  * Serialize a trigger set to an lttng_payload object.
 199  * Return LTTNG_OK on success, negative lttng error code on error.
 200  */
 201 LTTNG_HIDDEN
 202 int lttng_triggers_serialize(const struct lttng_triggers *triggers,
 203                 struct lttng_payload *payload);
 204
 205 LTTNG_HIDDEN
 206 ssize_t lttng_triggers_create_from_payload(struct lttng_payload_view *view,
 207                 struct lttng_triggers **triggers);
 208
 209 /*
 210  * Serialize a trigger set to a mi_writer.
 211  * Return LTTNG_OK in success, other enum lttng_error_code on error.
 212  */
 213 LTTNG_HIDDEN
 214 enum lttng_error_code lttng_triggers_mi_serialize(const struct lttng_triggers *triggers,
 215                 struct mi_writer *writer,
 216                 const struct mi_lttng_error_query_callbacks
 217                                 *error_query_callbacks);
 218
 219 LTTNG_HIDDEN
 220 const struct lttng_credentials *lttng_trigger_get_credentials(
 221                 const struct lttng_trigger *trigger);
 222
 223 LTTNG_HIDDEN
 224 void lttng_trigger_set_credentials(struct lttng_trigger *trigger,
 225                 const struct lttng_credentials *creds);
 226
 227 /*
 228  * Return the type of any underlying domain restriction. If no particular
 229  * requirement is present, returns LTTNG_DOMAIN_NONE.
 230  */
 231 LTTNG_HIDDEN
 232 enum lttng_domain_type lttng_trigger_get_underlying_domain_type_restriction(
 233                 const struct lttng_trigger *trigger);
 234
 235 /*
 236  * Generate any bytecode related to the trigger.
 237  * On success LTTNG_OK. On error, returns lttng_error code.
 238  */
 239 LTTNG_HIDDEN
 240 enum lttng_error_code lttng_trigger_generate_bytecode(
 241                 struct lttng_trigger *trigger,
 242                 const struct lttng_credentials *creds);
 243
 244 /*
 245  * Note that the trigger object is not locked by "copy" as it is const and
 246  * used with a number of 'const' triggers. If the trigger could be shared at
 247  * the moment of the copy, it is the caller's responsability to lock it for
 248  * the duration of the copy.
 249  */
 250 LTTNG_HIDDEN
 251 struct lttng_trigger *lttng_trigger_copy(const struct lttng_trigger *trigger);
 252
 253 /*
 254  * A given trigger needs a tracer notifier if
 255  *  it has an event-rule condition,
 256  *  AND
 257  *  it has one or more sessiond-execution action.
 258  */
 259 LTTNG_HIDDEN
 260 bool lttng_trigger_needs_tracer_notifier(const struct lttng_trigger *trigger);
 261
 262 LTTNG_HIDDEN
 263 void lttng_trigger_set_as_registered(struct lttng_trigger *trigger);
 264
 265 LTTNG_HIDDEN
 266 void lttng_trigger_set_as_unregistered(struct lttng_trigger *trigger);
 267
 268 /*
 269  * The trigger must be locked before calling lttng_trigger_is_registered.
 270  *
 271  * The lock is necessary since a trigger can be unregistered at any time.
 272  *
 273  * Manipulations requiring that the trigger be registered must always acquire
 274  * the trigger lock for the duration of the manipulation using
 275  * `lttng_trigger_lock` and `lttng_trigger_unlock`.
 276  */
 277 LTTNG_HIDDEN
 278 bool lttng_trigger_is_registered(struct lttng_trigger *trigger);
 279
 280 LTTNG_HIDDEN
 281 void lttng_trigger_lock(struct lttng_trigger *trigger);
 282
 283 LTTNG_HIDDEN
 284 void lttng_trigger_unlock(struct lttng_trigger *trigger);
 285
 286 LTTNG_HIDDEN
 287 enum lttng_trigger_status lttng_trigger_add_error_results(
 288                 const struct lttng_trigger *trigger,
 289                 struct lttng_error_query_results *results);
 290
 291 LTTNG_HIDDEN
 292 enum lttng_trigger_status lttng_trigger_condition_add_error_results(
 293                 const struct lttng_trigger *trigger,
 294                 struct lttng_error_query_results *results);
 295
 296 LTTNG_HIDDEN
 297 enum lttng_trigger_status lttng_trigger_add_action_error_query_results(
 298                 struct lttng_trigger *trigger,
 299                 struct lttng_error_query_results *results);
 300
 301 /*
 302  * Set the trigger name.
 303  *
 304  * A name is optional.
 305  * A name will be assigned on trigger registration if no name is set.
 306  *
 307  * The name is copied.
 308  *
 309  * Return LTTNG_TRIGGER_STATUS_OK on success, LTTNG_TRIGGER_STATUS_INVALID
 310  * if invalid parameters are passed.
 311  */
 312 LTTNG_HIDDEN
 313 enum lttng_trigger_status lttng_trigger_set_name(
 314                 struct lttng_trigger *trigger, const char *name);
 315
 316 #endif /* LTTNG_TRIGGER_INTERNAL_H */