include/lttng/trigger/trigger-internal.hpp

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