2 * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_TRIGGER_INTERNAL_H
9 #define LTTNG_TRIGGER_INTERNAL_H
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>
19 #include <sys/types.h>
23 struct lttng_payload_view
;
25 struct mi_lttng_error_query_callbacks
;
27 struct lttng_trigger
{
28 /* Reference counting is only exposed to internal users. */
31 struct lttng_condition
*condition
;
32 struct lttng_action
*action
;
34 /* For now only the uid portion of the credentials is used. */
35 struct lttng_credentials creds
;
38 * The unique token passed to the tracer to identify an event-rule
41 LTTNG_OPTIONAL(uint64_t) tracer_token
;
44 * Is the trigger registered?
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.
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.
52 * Not considered for `is_equal`.
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
62 * This is a property that can only be set internally by the session
65 * The hidden property is preserved by copies.
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.
73 * The lock is used to protect against concurrent trigger execution and
79 struct lttng_triggers
{
80 struct lttng_dynamic_pointer_array array
;
83 struct lttng_trigger_comm
{
85 * Credentials, only the uid portion is used for now.
86 * Used as an override when desired by the root user.
90 * Length of the variable length payload (name, condition, and
94 /* Includes '\0' terminator. */
96 /* Hidden property. */
98 /* A null-terminated name, a condition, and an action follow. */
102 struct lttng_triggers_comm
{
105 /* Count * lttng_trigger_comm structure */
110 ssize_t
lttng_trigger_create_from_payload(struct lttng_payload_view
*view
,
111 struct lttng_trigger
**trigger
);
114 int lttng_trigger_serialize(const struct lttng_trigger
*trigger
,
115 struct lttng_payload
*payload
);
118 bool lttng_trigger_validate(const struct lttng_trigger
*trigger
);
121 int lttng_trigger_assign_name(
122 struct lttng_trigger
*dst
, const struct lttng_trigger
*src
);
125 void lttng_trigger_set_tracer_token(
126 struct lttng_trigger
*trigger
, uint64_t token
);
129 uint64_t lttng_trigger_get_tracer_token(const struct lttng_trigger
*trigger
);
132 int lttng_trigger_generate_name(struct lttng_trigger
*trigger
,
136 bool lttng_trigger_is_equal(
137 const struct lttng_trigger
*a
, const struct lttng_trigger
*b
);
140 bool lttng_trigger_is_hidden(const struct lttng_trigger
*trigger
);
143 void lttng_trigger_set_hidden(struct lttng_trigger
*trigger
);
146 void lttng_trigger_get(struct lttng_trigger
*trigger
);
149 void lttng_trigger_put(struct lttng_trigger
*trigger
);
152 * Serialize a trigger to a mi_writer.
153 * Return LTTNG_OK in success, other enum lttng_error_code on error.
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
);
162 * Allocate a new set of triggers.
163 * The returned object must be freed via lttng_triggers_destroy.
166 struct lttng_triggers
*lttng_triggers_create(void);
169 * Return the a pointer to a mutable element at index "index" of an
170 * lttng_triggers set.
172 * This differs from the public `lttng_triggers_get_at_index` in that
173 * the returned pointer to a mutable trigger.
175 * The ownership of the trigger set element is NOT transfered.
176 * The returned object can NOT be freed via lttng_trigger_destroy.
179 struct lttng_trigger
*lttng_triggers_borrow_mutable_at_index(
180 const struct lttng_triggers
*triggers
, unsigned int index
);
183 * Add a trigger to the triggers set.
185 * A reference to the added trigger is acquired on behalf of the trigger set
189 int lttng_triggers_add(
190 struct lttng_triggers
*triggers
, struct lttng_trigger
*trigger
);
193 * Remove all triggers marked as hidden from the provided trigger set.
196 int lttng_triggers_remove_hidden_triggers(struct lttng_triggers
*triggers
);
199 * Serialize a trigger set to an lttng_payload object.
200 * Return LTTNG_OK on success, negative lttng error code on error.
203 int lttng_triggers_serialize(const struct lttng_triggers
*triggers
,
204 struct lttng_payload
*payload
);
207 ssize_t
lttng_triggers_create_from_payload(struct lttng_payload_view
*view
,
208 struct lttng_triggers
**triggers
);
211 * Serialize a trigger set to a mi_writer.
212 * Return LTTNG_OK in success, other enum lttng_error_code on error.
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
);
221 const struct lttng_credentials
*lttng_trigger_get_credentials(
222 const struct lttng_trigger
*trigger
);
225 void lttng_trigger_set_credentials(struct lttng_trigger
*trigger
,
226 const struct lttng_credentials
*creds
);
229 * Return the type of any underlying domain restriction. If no particular
230 * requirement is present, returns LTTNG_DOMAIN_NONE.
233 enum lttng_domain_type
lttng_trigger_get_underlying_domain_type_restriction(
234 const struct lttng_trigger
*trigger
);
237 * Generate any bytecode related to the trigger.
238 * On success LTTNG_OK. On error, returns lttng_error code.
241 enum lttng_error_code
lttng_trigger_generate_bytecode(
242 struct lttng_trigger
*trigger
,
243 const struct lttng_credentials
*creds
);
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.
252 struct lttng_trigger
*lttng_trigger_copy(const struct lttng_trigger
*trigger
);
255 * A given trigger needs a tracer notifier if
256 * it has an event-rule condition,
258 * it has one or more sessiond-execution action.
261 bool lttng_trigger_needs_tracer_notifier(const struct lttng_trigger
*trigger
);
264 void lttng_trigger_set_as_registered(struct lttng_trigger
*trigger
);
267 void lttng_trigger_set_as_unregistered(struct lttng_trigger
*trigger
);
270 * The trigger must be locked before calling lttng_trigger_is_registered.
272 * The lock is necessary since a trigger can be unregistered at any time.
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`.
279 bool lttng_trigger_is_registered(struct lttng_trigger
*trigger
);
282 void lttng_trigger_lock(struct lttng_trigger
*trigger
);
285 void lttng_trigger_unlock(struct lttng_trigger
*trigger
);
288 enum lttng_trigger_status
lttng_trigger_add_error_results(
289 const struct lttng_trigger
*trigger
,
290 struct lttng_error_query_results
*results
);
293 enum lttng_trigger_status
lttng_trigger_condition_add_error_results(
294 const struct lttng_trigger
*trigger
,
295 struct lttng_error_query_results
*results
);
298 enum lttng_trigger_status
lttng_trigger_add_action_error_query_results(
299 struct lttng_trigger
*trigger
,
300 struct lttng_error_query_results
*results
);
303 * Set the trigger name.
305 * A name is optional.
306 * A name will be assigned on trigger registration if no name is set.
308 * The name is copied.
310 * Return LTTNG_TRIGGER_STATUS_OK on success, LTTNG_TRIGGER_STATUS_INVALID
311 * if invalid parameters are passed.
314 enum lttng_trigger_status
lttng_trigger_set_name(
315 struct lttng_trigger
*trigger
, const char *name
);
317 #endif /* LTTNG_TRIGGER_INTERNAL_H */