Fix: lttng-snapshot: use after free of max size argument
[lttng-tools.git] / include / lttng / trigger / trigger.h
CommitLineData
a58c490f 1/*
ab5be9fa 2 * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
a58c490f 3 *
ab5be9fa 4 * SPDX-License-Identifier: LGPL-2.1-only
a58c490f 5 *
a58c490f
JG
6 */
7
8#ifndef LTTNG_TRIGGER_H
9#define LTTNG_TRIGGER_H
10
64eafdf6 11#include <sys/types.h>
a5c2d2a7 12#include <lttng/constant.h>
5c504c41 13#include <inttypes.h>
7966af57 14#include <lttng/lttng-error.h>
4bd69c5f 15#include <lttng/lttng-export.h>
64eafdf6 16
a58c490f
JG
17struct lttng_action;
18struct lttng_condition;
19struct lttng_trigger;
a02903c0
JR
20/* A set of triggers. */
21struct lttng_triggers;
a58c490f
JG
22
23#ifdef __cplusplus
24extern "C" {
25#endif
26
27enum lttng_register_trigger_status {
28 LTTNG_REGISTER_TRIGGER_STATUS_OK = 0,
29 LTTNG_REGISTER_TRIGGER_STATUS_INVALID = -1,
30};
31
64eafdf6
JR
32enum lttng_trigger_status {
33 LTTNG_TRIGGER_STATUS_OK = 0,
34 LTTNG_TRIGGER_STATUS_ERROR = -1,
35 LTTNG_TRIGGER_STATUS_UNKNOWN = -2,
36 LTTNG_TRIGGER_STATUS_INVALID = -3,
37 LTTNG_TRIGGER_STATUS_UNSET = -4,
38 LTTNG_TRIGGER_STATUS_UNSUPPORTED = -5,
39 LTTNG_TRIGGER_STATUS_PERMISSION_DENIED = -6,
40};
41
75984389
JG
42/*
43 * Create a trigger object associating a condition and an action.
44 *
45 * A trigger associates a condition and an action to take whenever the
46 * condition evaluates to true. Such actions can, for example, consist
47 * in the emission of a notification to clients listening through
48 * notification channels.
49 *
2c302502
JG
50 * Prior to 2.13, the caller had to retain the ownership of both the condition
51 * and action. Both objects had to be kept alive for the lifetime of the trigger
52 * object. This is no longer the case as the condition and action objects are
53 * internally reference counted. It is safe to destroy a condition and an action
54 * after using them to create a trigger. However, they should no longer be used.
75984389 55 *
38114013
PP
56 * If the action is a notification action with capture descriptors,
57 * the condition must be an event rule condition.
58 *
75984389
JG
59 * A trigger must be registered in order to become activate and can
60 * be destroyed after its registration.
61 *
62 * Returns a trigger object on success, NULL on error.
63 * Trigger objects must be destroyed using the lttng_trigger_destroy()
64 * function.
65 */
4bd69c5f 66LTTNG_EXPORT extern struct lttng_trigger *lttng_trigger_create(
a58c490f
JG
67 struct lttng_condition *condition, struct lttng_action *action);
68
64eafdf6
JR
69/*
70 * Set the user identity (uid) of a trigger.
71 *
72 * Only available for the root user (uid 0).
73 *
74 * Returns LTTNG_TRIGGER_STATUS_OK on success,
75 * LTTNG_TRIGGER_STATUS_EPERM if not authorized,
76 * LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed.
77 */
4bd69c5f 78LTTNG_EXPORT extern enum lttng_trigger_status lttng_trigger_set_owner_uid(
64eafdf6
JR
79 struct lttng_trigger *trigger, uid_t uid);
80
81/*
82 * Get the user identity (uid) of a trigger.
83 *
84 * Returns LTTNG_TRIGGER_STATUS_OK on success,
85 * LTTNG_TRIGGER_STATUS_UNSET if unset,
86 * LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed.
87 */
4bd69c5f 88LTTNG_EXPORT extern enum lttng_trigger_status lttng_trigger_get_owner_uid(
64eafdf6
JR
89 const struct lttng_trigger *trigger, uid_t *uid);
90
75984389
JG
91/*
92 * Get the condition of a trigger.
93 *
94 * The caller acquires no ownership of the returned condition.
95 *
96 * Returns a condition on success, NULL on error.
97 */
4bd69c5f 98LTTNG_EXPORT extern struct lttng_condition *lttng_trigger_get_condition(
a58c490f
JG
99 struct lttng_trigger *trigger);
100
4bd69c5f 101LTTNG_EXPORT extern const struct lttng_condition *lttng_trigger_get_const_condition(
0de2479d
SM
102 const struct lttng_trigger *trigger);
103
75984389
JG
104/*
105 * Get the action of a trigger.
106 *
107 * The caller acquires no ownership of the returned action.
108 *
109 * Returns an action on success, NULL on error.
110 */
4bd69c5f 111LTTNG_EXPORT extern struct lttng_action *lttng_trigger_get_action(
a58c490f
JG
112 struct lttng_trigger *trigger);
113
4bd69c5f 114LTTNG_EXPORT extern const struct lttng_action *lttng_trigger_get_const_action(
0de2479d 115 const struct lttng_trigger *trigger);
242388e4
JR
116
117/*
118 * Get the name of a trigger.
119 *
120 * The caller does not assume the ownership of the returned name.
121 * The name shall only only be used for the duration of the trigger's
122 * lifetime, or until a different name is set.
123 *
124 * Returns LTTNG_TRIGGER_STATUS_OK and a pointer to the trigger's name on
125 * success, LTTNG_TRIGGER_STATUS_INVALID if an invalid parameter is passed,
a5c2d2a7 126 * or LTTNG_TRIGGER_STATUS_UNSET if the trigger is unnamed.
242388e4 127 */
4bd69c5f 128LTTNG_EXPORT extern enum lttng_trigger_status lttng_trigger_get_name(
242388e4
JR
129 const struct lttng_trigger *trigger, const char **name);
130
131/*
a5c2d2a7 132 * Destroy (frees) a trigger object.
242388e4 133 */
4bd69c5f 134LTTNG_EXPORT extern void lttng_trigger_destroy(struct lttng_trigger *trigger);
242388e4 135
75984389 136/*
a5c2d2a7
JG
137 * Register a trigger to the session daemon with a given name.
138 *
139 * The trigger object can be destroyed after this call.
140 * On success, this function will set the trigger's name to `name`.
141 *
142 * Returns an LTTng status code.
75984389 143 */
4bd69c5f 144LTTNG_EXPORT extern enum lttng_error_code lttng_register_trigger_with_name(
a5c2d2a7
JG
145 struct lttng_trigger *trigger,
146 const char *name);
a58c490f 147
75984389 148/*
a5c2d2a7
JG
149 * Register a trigger to the session daemon, generating a unique name for its
150 * owner.
75984389
JG
151 *
152 * The trigger can be destroyed after this call.
a5c2d2a7
JG
153 * On success, this function will set the trigger's name to the generated
154 * name.
75984389 155 *
a5c2d2a7 156 * Returns an LTTng status code.
75984389 157 */
4bd69c5f 158LTTNG_EXPORT extern enum lttng_error_code lttng_register_trigger_with_automatic_name(
a5c2d2a7 159 struct lttng_trigger *trigger);
a58c490f 160
75984389
JG
161/*
162 * Unregister a trigger from the session daemon.
163 *
164 * The trigger can be destroyed after this call.
165 *
166 * Return 0 on success, a negative LTTng error code on error.
167 */
4bd69c5f 168LTTNG_EXPORT extern int lttng_unregister_trigger(const struct lttng_trigger *trigger);
a58c490f 169
fbc9f37d
JR
170/*
171 * List triggers for the current user.
172 *
173 * On success, a newly-allocated trigger set is returned.
174 *
175 * The trigger set must be destroyed by the caller (see
176 * lttng_triggers_destroy()).
177 *
178 * Returns LTTNG_OK on success, else a suitable LTTng error code.
179 */
4bd69c5f 180LTTNG_EXPORT extern enum lttng_error_code lttng_list_triggers(
fbc9f37d
JR
181 struct lttng_triggers **triggers);
182
a02903c0
JR
183/*
184 * Get a trigger from the set at a given index.
185 *
186 * Note that the trigger set maintains the ownership of the returned trigger.
187 * It must not be destroyed by the user, nor should a reference to it be held
188 * beyond the lifetime of the trigger set.
189 *
190 * Returns a trigger, or NULL on error.
191 */
4bd69c5f 192LTTNG_EXPORT extern const struct lttng_trigger *lttng_triggers_get_at_index(
a02903c0
JR
193 const struct lttng_triggers *triggers, unsigned int index);
194
195/*
196 * Get the number of triggers in a trigger set.
197 *
198 * Return LTTNG_TRIGGER_STATUS_OK on success,
199 * LTTNG_TRIGGER_STATUS_INVALID when invalid parameters are passed.
200 */
4bd69c5f 201LTTNG_EXPORT extern enum lttng_trigger_status lttng_triggers_get_count(
a02903c0
JR
202 const struct lttng_triggers *triggers, unsigned int *count);
203
204/*
205 * Destroy a trigger set.
206 */
4bd69c5f 207LTTNG_EXPORT extern void lttng_triggers_destroy(struct lttng_triggers *triggers);
a02903c0 208
a5c2d2a7
JG
209/*
210 * Deprecated: invocations should be replaced by
211 * lttng_register_trigger_with_automatic_name().
212 *
213 * Register a trigger to the session daemon.
214 *
215 * The trigger can be destroyed after this call.
216 *
217 * Return 0 on success, a negative LTTng error code on error.
218 */
219LTTNG_DEPRECATED("Use lttng_register_trigger_with_automatic_name")
4bd69c5f 220LTTNG_EXPORT extern int lttng_register_trigger(struct lttng_trigger *trigger);
a02903c0 221
a58c490f
JG
222#ifdef __cplusplus
223}
224#endif
225
226#endif /* LTTNG_TRIGGER_H */
This page took 0.07165 seconds and 5 git commands to generate.