2 * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_TRIGGER_H
9 #define LTTNG_TRIGGER_H
11 #include <sys/types.h>
15 struct lttng_condition
;
17 /* A set of triggers. */
18 struct lttng_triggers
;
24 enum lttng_register_trigger_status
{
25 LTTNG_REGISTER_TRIGGER_STATUS_OK
= 0,
26 LTTNG_REGISTER_TRIGGER_STATUS_INVALID
= -1,
29 enum lttng_trigger_status
{
30 LTTNG_TRIGGER_STATUS_OK
= 0,
31 LTTNG_TRIGGER_STATUS_ERROR
= -1,
32 LTTNG_TRIGGER_STATUS_UNKNOWN
= -2,
33 LTTNG_TRIGGER_STATUS_INVALID
= -3,
34 LTTNG_TRIGGER_STATUS_UNSET
= -4,
35 LTTNG_TRIGGER_STATUS_UNSUPPORTED
= -5,
36 LTTNG_TRIGGER_STATUS_PERMISSION_DENIED
= -6,
39 enum lttng_trigger_firing_policy
{
40 LTTNG_TRIGGER_FIRING_POLICY_EVERY_N
= 0,
41 LTTNG_TRIGGER_FIRING_POLICY_ONCE_AFTER_N
= 1,
45 * Create a trigger object associating a condition and an action.
47 * A trigger associates a condition and an action to take whenever the
48 * condition evaluates to true. Such actions can, for example, consist
49 * in the emission of a notification to clients listening through
50 * notification channels.
52 * Prior to 2.13, the caller had to retain the ownership of both the condition
53 * and action. Both objects had to be kept alive for the lifetime of the trigger
54 * object. This is no longer the case as the condition and action objects are
55 * internally reference counted. It is safe to destroy a condition and an action
56 * after using them to create a trigger. However, they should no longer be used.
58 * If the action is a notification action with capture descriptors,
59 * the condition must be an event rule condition.
61 * A trigger must be registered in order to become activate and can
62 * be destroyed after its registration.
64 * Returns a trigger object on success, NULL on error.
65 * Trigger objects must be destroyed using the lttng_trigger_destroy()
68 extern struct lttng_trigger
*lttng_trigger_create(
69 struct lttng_condition
*condition
, struct lttng_action
*action
);
72 * Set the user identity (uid) of a trigger.
74 * Only available for the root user (uid 0).
76 * Returns LTTNG_TRIGGER_STATUS_OK on success,
77 * LTTNG_TRIGGER_STATUS_EPERM if not authorized,
78 * LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed.
80 extern enum lttng_trigger_status
lttng_trigger_set_owner_uid(
81 struct lttng_trigger
*trigger
, uid_t uid
);
84 * Get the user identity (uid) of a trigger.
86 * Returns LTTNG_TRIGGER_STATUS_OK on success,
87 * LTTNG_TRIGGER_STATUS_UNSET if unset,
88 * LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed.
90 extern enum lttng_trigger_status
lttng_trigger_get_owner_uid(
91 const struct lttng_trigger
*trigger
, uid_t
*uid
);
94 * Get the condition of a trigger.
96 * The caller acquires no ownership of the returned condition.
98 * Returns a condition on success, NULL on error.
100 extern struct lttng_condition
*lttng_trigger_get_condition(
101 struct lttng_trigger
*trigger
);
103 const struct lttng_condition
*lttng_trigger_get_const_condition(
104 const struct lttng_trigger
*trigger
);
107 * Get the action of a trigger.
109 * The caller acquires no ownership of the returned action.
111 * Returns an action on success, NULL on error.
113 extern struct lttng_action
*lttng_trigger_get_action(
114 struct lttng_trigger
*trigger
);
116 const struct lttng_action
*lttng_trigger_get_const_action(
117 const struct lttng_trigger
*trigger
);
120 * Get the name of a trigger.
122 * The caller does not assume the ownership of the returned name.
123 * The name shall only only be used for the duration of the trigger's
124 * lifetime, or until a different name is set.
126 * Returns LTTNG_TRIGGER_STATUS_OK and a pointer to the trigger's name on
127 * success, LTTNG_TRIGGER_STATUS_INVALID if an invalid parameter is passed,
128 * or LTTNG_TRIGGER_STATUS_UNSET if a name was not set prior to this call.
130 extern enum lttng_trigger_status
lttng_trigger_get_name(
131 const struct lttng_trigger
*trigger
, const char **name
);
134 * Set the trigger name.
136 * A name is optional.
137 * A name will be assigned on trigger registration if no name is set.
139 * The name is copied.
141 * Return LTTNG_TRIGGER_STATUS_OK on success, LTTNG_TRIGGER_STATUS_INVALID
142 * if invalid parameters are passed.
144 extern enum lttng_trigger_status
lttng_trigger_set_name(
145 struct lttng_trigger
*trigger
, const char *name
);
148 * Set the trigger firing policy.
150 * This is optional. By default a trigger is set to fire each time the
151 * associated condition occurs.
153 * Threshold is the number of times the condition must be hit before the policy
156 * Return LTTNG_TRIGGER_STATUS_OK on success, LTTNG_TRIGGER_STATUS_INVALID
157 * if invalid parameters are passed.
159 extern enum lttng_trigger_status
lttng_trigger_set_firing_policy(
160 struct lttng_trigger
*trigger
,
161 enum lttng_trigger_firing_policy policy_type
,
165 * Get the trigger firing policy.
167 * Threshold is the number of time the condition must be hit before the policy is
170 * Return LTTNG_TRIGGER_STATUS_OK on success, LTTNG_TRIGGER_STATUS_INVALID
171 * if invalid parameters are passed.
173 extern enum lttng_trigger_status
lttng_trigger_get_firing_policy(
174 const struct lttng_trigger
*trigger
,
175 enum lttng_trigger_firing_policy
*policy_type
,
176 uint64_t *threshold
);
179 * Destroy (frees) a trigger object.
181 extern void lttng_trigger_destroy(struct lttng_trigger
*trigger
);
184 * Register a trigger to the session daemon.
186 * The trigger can be destroyed after this call.
188 * Return 0 on success, a negative LTTng error code on error.
190 extern int lttng_register_trigger(struct lttng_trigger
*trigger
);
193 * Unregister a trigger from the session daemon.
195 * The trigger can be destroyed after this call.
197 * Return 0 on success, a negative LTTng error code on error.
199 extern int lttng_unregister_trigger(const struct lttng_trigger
*trigger
);
202 * List triggers for the current user.
204 * On success, a newly-allocated trigger set is returned.
206 * The trigger set must be destroyed by the caller (see
207 * lttng_triggers_destroy()).
209 * Returns LTTNG_OK on success, else a suitable LTTng error code.
211 extern enum lttng_error_code
lttng_list_triggers(
212 struct lttng_triggers
**triggers
);
215 * Get a trigger from the set at a given index.
217 * Note that the trigger set maintains the ownership of the returned trigger.
218 * It must not be destroyed by the user, nor should a reference to it be held
219 * beyond the lifetime of the trigger set.
221 * Returns a trigger, or NULL on error.
223 extern const struct lttng_trigger
*lttng_triggers_get_at_index(
224 const struct lttng_triggers
*triggers
, unsigned int index
);
227 * Get the number of triggers in a trigger set.
229 * Return LTTNG_TRIGGER_STATUS_OK on success,
230 * LTTNG_TRIGGER_STATUS_INVALID when invalid parameters are passed.
232 extern enum lttng_trigger_status
lttng_triggers_get_count(
233 const struct lttng_triggers
*triggers
, unsigned int *count
);
236 * Destroy a trigger set.
238 extern void lttng_triggers_destroy(struct lttng_triggers
*triggers
);
245 #endif /* LTTNG_TRIGGER_H */