4f813eeb9fdc040e045f1a644928246c9c1b6e50
[lttng-tools.git] / include / lttng / tracker.h
1 /*
2 * Copyright (C) 2019 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
3 *
4 * SPDX-License-Identifier: LGPL-2.1-only
5 *
6 */
7
8 #ifndef LTTNG_TRACKER_H
9 #define LTTNG_TRACKER_H
10
11 #include <lttng/constant.h>
12 #include <lttng/session.h>
13
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17
18 enum lttng_tracker_type {
19 LTTNG_TRACKER_PID = 0,
20 LTTNG_TRACKER_VPID = 1,
21 LTTNG_TRACKER_UID = 2,
22 LTTNG_TRACKER_GID = 3,
23 LTTNG_TRACKER_VUID = 4,
24 LTTNG_TRACKER_VGID = 5,
25 };
26
27 enum lttng_tracker_id_type {
28 LTTNG_ID_UNKNOWN = -1,
29 LTTNG_ID_ALL = 0,
30 LTTNG_ID_VALUE = 1,
31 LTTNG_ID_STRING = 2,
32 };
33
34 enum lttng_tracker_id_status {
35 /* Invalid tracker id parameter. */
36 LTTNG_TRACKER_ID_STATUS_INVALID = -1,
37 LTTNG_TRACKER_ID_STATUS_OK = 0,
38 /* Tracker id parameter is unset. */
39 LTTNG_TRACKER_ID_STATUS_UNSET = 1,
40 };
41
42 /*
43 * A tracker id.
44 */
45 struct lttng_tracker_id;
46
47 /*
48 * A collection of tracker id.
49 */
50 struct lttng_tracker_ids;
51
52 /*
53 * Create a tracker id for the passed tracker type.
54 * Users must set the tracker id using the matching API call.
55 *
56 * On success, the caller is responsible for calling lttng_tracker_id_destroy.
57 * On error, return NULL.
58 */
59 extern struct lttng_tracker_id *lttng_tracker_id_create(void);
60
61 /*
62 * Configure the tracker id using the numerical representation of the resource
63 * to be tracked/untracked.
64 *
65 * If the tracker id was already configured, calling this function will replace
66 * the previous configuration and free memory as necessary.
67 *
68 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
69 * LTTNG_TRACKER_ID_STATUS_INVALID is the passed parameter is invalid.
70 */
71 extern enum lttng_tracker_id_status lttng_tracker_id_set_value(
72 struct lttng_tracker_id *id, int value);
73
74 /*
75 * Configure the tracker id using the string representation of the resource to
76 * be tracked/untracked.
77 *
78 * If the tracker id was already configured, calling this function will replace
79 * the previous configuration and free memory as necessary.
80 *
81 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
82 * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
83 */
84 extern enum lttng_tracker_id_status lttng_tracker_id_set_string(
85 struct lttng_tracker_id *id, const char *value);
86
87 /*
88 * Configure the tracker id to track/untrack all resources for the tracker type.
89 *
90 * If the tracker id was already configured, calling this function will replace
91 * the previous configuration and free memory as necessary.
92 *
93 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
94 * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
95 */
96 extern enum lttng_tracker_id_status lttng_tracker_id_set_all(
97 struct lttng_tracker_id *id);
98
99 /*
100 * Destroy a tracker id.
101 */
102 extern void lttng_tracker_id_destroy(struct lttng_tracker_id *id);
103
104 /*
105 * Get the type of a tracker id.
106 */
107 extern enum lttng_tracker_id_type lttng_tracker_id_get_type(
108 const struct lttng_tracker_id *id);
109
110 /*
111 * Get the value of a tracker id.
112 *
113 * Returns LTTNG_TRACKER_ID_OK on success,
114 * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
115 * LTTNG_ID_VALUE,
116 * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
117 */
118 extern enum lttng_tracker_id_status lttng_tracker_id_get_value(
119 const struct lttng_tracker_id *id, int *value);
120
121 /*
122 * Get the string representation of the tracker id.
123 *
124 * Returns LTTNG_TRACKER_ID_OK on success,
125 * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
126 * LTTNG_ID_STRING,
127 * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
128 */
129 extern enum lttng_tracker_id_status lttng_tracker_id_get_string(
130 const struct lttng_tracker_id *id, const char **value);
131
132 /*
133 * Add ID to session tracker.
134 *
135 * tracker_type is the type of tracker.
136 * id is the lttng_tracker_type to track.
137 *
138 * Returns 0 on success else a negative LTTng error code.
139 */
140 extern int lttng_track_id(struct lttng_handle *handle,
141 enum lttng_tracker_type tracker_type,
142 const struct lttng_tracker_id *id);
143
144 /*
145 * Remove ID from session tracker.
146 *
147 * tracker_type is the type of tracker.
148 * id is the lttng_tracker_type to untrack.
149 * Returns 0 on success else a negative LTTng error code.
150 */
151 extern int lttng_untrack_id(struct lttng_handle *handle,
152 enum lttng_tracker_type tracker_type,
153 const struct lttng_tracker_id *id);
154
155 /*
156 * List IDs of a tracker.
157 *
158 * On success, ids is allocated.
159 * The ids collection must be freed by the caller with lttng_destroy_ids().
160 *
161 * Returns 0 on success, else a negative LTTng error code.
162 */
163 extern int lttng_list_tracker_ids(struct lttng_handle *handle,
164 enum lttng_tracker_type tracker_type,
165 struct lttng_tracker_ids **ids);
166
167 /*
168 * Backward compatibility.
169 * Add PID to session tracker.
170 *
171 * A pid argument >= 0 adds the PID to the session tracker.
172 * A pid argument of -1 means "track all PIDs".
173 *
174 * Returns 0 on success else a negative LTTng error code.
175 */
176 extern int lttng_track_pid(struct lttng_handle *handle, int pid);
177
178 /*
179 * Backward compatibility.
180 * Remove PID from session tracker.
181 *
182 * A pid argument >= 0 removes the PID from the session tracker.
183 * A pid argument of -1 means "untrack all PIDs".
184 *
185 * Returns 0 on success else a negative LTTng error code.
186 */
187 extern int lttng_untrack_pid(struct lttng_handle *handle, int pid);
188
189 /*
190 * Backward compatibility
191 * List PIDs in the tracker.
192 *
193 * enabled is set to whether the PID tracker is enabled.
194 * pids is set to an allocated array of PIDs currently tracked. On
195 * success, pids must be freed by the caller.
196 * nr_pids is set to the number of entries contained by the pids array.
197 *
198 * Returns 0 on success, else a negative LTTng error code.
199 */
200 extern int lttng_list_tracker_pids(struct lttng_handle *handle,
201 int *enabled,
202 int32_t **pids,
203 size_t *nr_pids);
204
205 /*
206 * Get a tracker id from the list at a given index.
207 *
208 * Note that the list maintains the ownership of the returned tracker id.
209 * It must not be destroyed by the user, nor should it be held beyond the
210 * lifetime of the tracker id list.
211 *
212 * Returns a tracker id, or NULL on error.
213 */
214 extern const struct lttng_tracker_id *lttng_tracker_ids_get_at_index(
215 const struct lttng_tracker_ids *ids, unsigned int index);
216
217 /*
218 * Get the number of tracker id in a tracker id list.
219 *
220 * Return LTTNG_TRACKER_ID_STATUS on sucess,
221 * LTTNG_TRACKER_ID_STATUS_INVALID when passed invalid parameters.
222 */
223 extern enum lttng_tracker_id_status lttng_tracker_ids_get_count(
224 const struct lttng_tracker_ids *ids, unsigned int *count);
225
226 /*
227 * Destroy a tracker id list.
228 */
229 extern void lttng_tracker_ids_destroy(struct lttng_tracker_ids *ids);
230
231 #ifdef __cplusplus
232 }
233 #endif
234
235 #endif /* LTTNG_TRACKER_H */
This page took 0.047396 seconds and 3 git commands to generate.