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