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>
22 #if defined(__cplusplus)
27 struct lttng_payload_view
;
29 struct mi_lttng_error_query_callbacks
;
31 struct lttng_trigger
{
32 /* Reference counting is only exposed to internal users. */
35 struct lttng_condition
*condition
;
36 struct lttng_action
*action
;
38 /* For now only the uid portion of the credentials is used. */
39 struct lttng_credentials creds
;
42 * The unique token passed to the tracer to identify an event-rule
45 LTTNG_OPTIONAL(uint64_t) tracer_token
;
48 * Is the trigger registered?
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.
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.
56 * Not considered for `is_equal`.
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
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.
70 * The hidden property is preserved by copies.
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.
78 * The lock is used to protect against concurrent trigger execution and
84 struct lttng_triggers
{
85 struct lttng_dynamic_pointer_array array
;
88 struct lttng_trigger_comm
{
90 * Credentials, only the uid portion is used for now.
91 * Used as an override when desired by the root user.
95 * Length of the variable length payload (name, condition, and
99 /* Includes '\0' terminator. */
100 uint32_t name_length
;
101 /* A null-terminated name, a condition, and an action follow. */
105 struct lttng_triggers_comm
{
108 /* Count * lttng_trigger_comm structure */
112 ssize_t
lttng_trigger_create_from_payload(struct lttng_payload_view
*view
,
113 struct lttng_trigger
**trigger
);
115 int lttng_trigger_serialize(const struct lttng_trigger
*trigger
,
116 struct lttng_payload
*payload
);
118 bool lttng_trigger_validate(const struct lttng_trigger
*trigger
);
120 int lttng_trigger_assign_name(
121 struct lttng_trigger
*dst
, const struct lttng_trigger
*src
);
123 void lttng_trigger_set_tracer_token(
124 struct lttng_trigger
*trigger
, uint64_t token
);
126 uint64_t lttng_trigger_get_tracer_token(const struct lttng_trigger
*trigger
);
128 int lttng_trigger_generate_name(struct lttng_trigger
*trigger
,
131 bool lttng_trigger_is_equal(
132 const struct lttng_trigger
*a
, const struct lttng_trigger
*b
);
134 bool lttng_trigger_is_hidden(const struct lttng_trigger
*trigger
);
136 void lttng_trigger_set_hidden(struct lttng_trigger
*trigger
);
138 void lttng_trigger_get(struct lttng_trigger
*trigger
);
140 void lttng_trigger_put(struct lttng_trigger
*trigger
);
143 * Serialize a trigger to a mi_writer.
144 * Return LTTNG_OK in success, other enum lttng_error_code on error.
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
);
152 * Allocate a new set of triggers.
153 * The returned object must be freed via lttng_triggers_destroy.
155 struct lttng_triggers
*lttng_triggers_create(void);
158 * Return the a pointer to a mutable element at index "index" of an
159 * lttng_triggers set.
161 * This differs from the public `lttng_triggers_get_at_index` in that
162 * the returned pointer to a mutable trigger.
164 * The ownership of the trigger set element is NOT transfered.
165 * The returned object can NOT be freed via lttng_trigger_destroy.
167 struct lttng_trigger
*lttng_triggers_borrow_mutable_at_index(
168 const struct lttng_triggers
*triggers
, unsigned int index
);
171 * Add a trigger to the triggers set.
173 * A reference to the added trigger is acquired on behalf of the trigger set
176 int lttng_triggers_add(
177 struct lttng_triggers
*triggers
, struct lttng_trigger
*trigger
);
180 * Remove all triggers marked as hidden from the provided trigger set.
182 int lttng_triggers_remove_hidden_triggers(struct lttng_triggers
*triggers
);
185 * Serialize a trigger set to an lttng_payload object.
186 * Return LTTNG_OK on success, negative lttng error code on error.
188 int lttng_triggers_serialize(const struct lttng_triggers
*triggers
,
189 struct lttng_payload
*payload
);
191 ssize_t
lttng_triggers_create_from_payload(struct lttng_payload_view
*view
,
192 struct lttng_triggers
**triggers
);
195 * Serialize a trigger set to a mi_writer.
196 * Return LTTNG_OK in success, other enum lttng_error_code on error.
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
);
203 const struct lttng_credentials
*lttng_trigger_get_credentials(
204 const struct lttng_trigger
*trigger
);
206 void lttng_trigger_set_credentials(struct lttng_trigger
*trigger
,
207 const struct lttng_credentials
*creds
);
210 * Return the type of any underlying domain restriction. If no particular
211 * requirement is present, returns LTTNG_DOMAIN_NONE.
213 enum lttng_domain_type
lttng_trigger_get_underlying_domain_type_restriction(
214 const struct lttng_trigger
*trigger
);
217 * Generate any bytecode related to the trigger.
218 * On success LTTNG_OK. On error, returns lttng_error code.
220 enum lttng_error_code
lttng_trigger_generate_bytecode(
221 struct lttng_trigger
*trigger
,
222 const struct lttng_credentials
*creds
);
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.
230 struct lttng_trigger
*lttng_trigger_copy(const struct lttng_trigger
*trigger
);
233 * A given trigger needs a tracer notifier if
234 * it has an event-rule condition,
236 * it has one or more sessiond-execution action.
238 bool lttng_trigger_needs_tracer_notifier(const struct lttng_trigger
*trigger
);
240 void lttng_trigger_set_as_registered(struct lttng_trigger
*trigger
);
242 void lttng_trigger_set_as_unregistered(struct lttng_trigger
*trigger
);
245 * The trigger must be locked before calling lttng_trigger_is_registered.
247 * The lock is necessary since a trigger can be unregistered at any time.
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`.
253 bool lttng_trigger_is_registered(struct lttng_trigger
*trigger
);
255 void lttng_trigger_lock(struct lttng_trigger
*trigger
);
257 void lttng_trigger_unlock(struct lttng_trigger
*trigger
);
259 enum lttng_trigger_status
lttng_trigger_add_error_results(
260 const struct lttng_trigger
*trigger
,
261 struct lttng_error_query_results
*results
);
263 enum lttng_trigger_status
lttng_trigger_condition_add_error_results(
264 const struct lttng_trigger
*trigger
,
265 struct lttng_error_query_results
*results
);
267 enum lttng_trigger_status
lttng_trigger_add_action_error_query_results(
268 struct lttng_trigger
*trigger
,
269 struct lttng_error_query_results
*results
);
272 * Set the trigger name.
274 * A name is optional.
275 * A name will be assigned on trigger registration if no name is set.
277 * The name is copied.
279 * Return LTTNG_TRIGGER_STATUS_OK on success, LTTNG_TRIGGER_STATUS_INVALID
280 * if invalid parameters are passed.
282 enum lttng_trigger_status
lttng_trigger_set_name(
283 struct lttng_trigger
*trigger
, const char *name
);
285 #if defined(__cplusplus)
289 #endif /* LTTNG_TRIGGER_INTERNAL_H */