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