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