Refactor: lttng-ctl: follow terminology of the tracker documentation
[lttng-tools.git] / include / lttng / tracker.h
1 /*
2 * Copyright (C) 2019 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
3 * Copyright (C) 2020 Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 *
5 * SPDX-License-Identifier: LGPL-2.1-only
6 *
7 */
8
9 #ifndef LTTNG_TRACKER_H
10 #define LTTNG_TRACKER_H
11
12 #include <lttng/constant.h>
13 #include <lttng/domain.h>
14 #include <lttng/lttng-error.h>
15 #include <lttng/session.h>
16
17 #include <sys/types.h>
18
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22
23 /*
24 * Process attribute tracked by a tracker.
25 */
26 enum lttng_process_attr {
27 /* Kernel space domain only. */
28 LTTNG_PROCESS_ATTR_PROCESS_ID = 0,
29 /* Kernel and user space domains. */
30 LTTNG_PROCESS_ATTR_VIRTUAL_PROCESS_ID = 1,
31 /* Kernel space domain only. */
32 LTTNG_PROCESS_ATTR_USER_ID = 2,
33 /* Kernel and user space domains. */
34 LTTNG_PROCESS_ATTR_VIRTUAL_USER_ID = 3,
35 /* Kernel space domain only. */
36 LTTNG_PROCESS_ATTR_GROUP_ID = 4,
37 /* Kernel and user space domains. */
38 LTTNG_PROCESS_ATTR_VIRTUAL_GROUP_ID = 5,
39 };
40
41 /*
42 * Tracking (filtering) policy of a process attribute tracker.
43 */
44 enum lttng_tracking_policy {
45 /*
46 * Track all possible process attribute value of a given type
47 * (i.e. no filtering).
48 * This is the default state of a process attribute tracker.
49 */
50 LTTNG_TRACKING_POLICY_INCLUDE_ALL = 0,
51 /* Exclude all possible process attribute values of a given type. */
52 LTTNG_TRACKING_POLICY_EXCLUDE_ALL = 1,
53 /* Track a set of specific process attribute values. */
54 LTTNG_TRACKING_POLICY_INCLUDE_SET = 2,
55 };
56
57 /*
58 * Type of a process attribute value.
59 *
60 * This allows the use of the matching accessor given the type of a value.
61 */
62 enum lttng_process_attr_value_type {
63 LTTNG_PROCESS_ATTR_VALUE_TYPE_INVALID = -1,
64 LTTNG_PROCESS_ATTR_VALUE_TYPE_PID = 0,
65 LTTNG_PROCESS_ATTR_VALUE_TYPE_UID = 1,
66 LTTNG_PROCESS_ATTR_VALUE_TYPE_USER_NAME = 2,
67 LTTNG_PROCESS_ATTR_VALUE_TYPE_GID = 3,
68 LTTNG_PROCESS_ATTR_VALUE_TYPE_GROUP_NAME = 4,
69 };
70
71 enum lttng_process_attr_tracker_handle_status {
72 LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_GROUP_NOT_FOUND = -7,
73 LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_USER_NOT_FOUND = -6,
74 LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID_TRACKING_POLICY = -5,
75 LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_SESSION_DOES_NOT_EXIST = -4,
76 LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_ERROR = -3,
77 LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_COMMUNICATION_ERROR = -2,
78 LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID = -1,
79 LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK = 0,
80 LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_EXISTS = 1,
81 LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_MISSING = 2,
82 };
83
84 enum lttng_process_attr_values_status {
85 LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE = -2,
86 LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID = -1,
87 LTTNG_PROCESS_ATTR_VALUES_STATUS_OK = 0,
88 };
89
90 /*
91 * A process attribute tracker handle.
92 *
93 * A process attribute tracker is an _inclusion set_ of process
94 * attribute values. Tracked processes are allowed to emit events,
95 * provided those events are targeted by enabled event rules.
96 *
97 * An LTTng session is created with a number of process attribute
98 * trackers by default. The process attributes that can be tracked vary by
99 * domain (see enum lttng_process_attr).
100 *
101 * Trackers are per-domain (user and kernel space) and allow the filtering
102 * of events based on a process's attributes.
103 */
104 struct lttng_process_attr_tracker_handle;
105
106 /* A set of process attribute values. */
107 struct lttng_process_attr_values;
108
109 /*
110 * Get a handle to one of the process attribute trackers of a session's domain.
111 *
112 * Returns LTTNG_OK and a process attribute tracker handle on success,
113 * or an lttng_error_code on error.
114 *
115 * The tracker's ownership is transfered to the caller. Use
116 * lttng_process_attr_tracker_handle_destroy() to dispose of it.
117 */
118 extern enum lttng_error_code lttng_session_get_tracker_handle(
119 const char *session_name,
120 enum lttng_domain_type domain,
121 enum lttng_process_attr process_attr,
122 struct lttng_process_attr_tracker_handle **out_tracker_handle);
123
124 /*
125 * Destroy a process attribute tracker handle.
126 */
127 extern void lttng_process_attr_tracker_handle_destroy(
128 struct lttng_process_attr_tracker_handle *tracker_handle);
129
130 /*
131 * Get the tracking policy of a process attribute tracker.
132 *
133 * Returns the LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK and the tracking
134 * policy of a process attribute tracker on success,
135 * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID on error.
136 */
137 extern enum lttng_process_attr_tracker_handle_status
138 lttng_process_attr_tracker_handle_get_tracking_policy(
139 const struct lttng_process_attr_tracker_handle *tracker_handle,
140 enum lttng_tracking_policy *policy);
141
142 /*
143 * Set the tracking policy of a process attribute tracker.
144 *
145 * Setting the tracking policy to the current tracking policy has no effect.
146 *
147 * Returns the LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK on success,
148 * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID on error.
149 */
150 extern enum lttng_process_attr_tracker_handle_status
151 lttng_process_attr_tracker_handle_set_tracking_policy(
152 const struct lttng_process_attr_tracker_handle *tracker_handle,
153 enum lttng_tracking_policy policy);
154
155 /*
156 * Add a numerical PID to the process ID process attribute tracker inclusion
157 * set.
158 *
159 * Returns LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK on success,
160 * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_EXISTS if it was already
161 * present in the inclusion set, and
162 * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID if an invalid tracker
163 * argument was provided.
164 */
165 extern enum lttng_process_attr_tracker_handle_status
166 lttng_process_attr_process_id_tracker_handle_add_pid(
167 const struct lttng_process_attr_tracker_handle
168 *process_id_tracker,
169 pid_t pid);
170
171 /*
172 * Remove a numerical PID from the process ID process attribute tracker include
173 * set.
174 *
175 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
176 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
177 * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
178 * an invalid tracker argument was provided.
179 */
180 extern enum lttng_process_attr_tracker_handle_status
181 lttng_process_attr_process_id_tracker_handle_remove_pid(
182 const struct lttng_process_attr_tracker_handle
183 *process_id_tracker,
184 pid_t pid);
185
186 /*
187 * Add a numerical PID to the virtual process ID process attribute tracker
188 * inclusion set.
189 *
190 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
191 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
192 * present in the inclusion set, and
193 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
194 * argument was provided.
195 */
196 extern enum lttng_process_attr_tracker_handle_status
197 lttng_process_attr_virtual_process_id_tracker_handle_add_pid(
198 const struct lttng_process_attr_tracker_handle
199 *process_id_tracker,
200 pid_t vpid);
201
202 /*
203 * Remove a numerical PID from the virtual process ID process attribute tracker
204 * inclusion set.
205 *
206 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
207 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
208 * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
209 * an invalid tracker argument was provided.
210 */
211 extern enum lttng_process_attr_tracker_handle_status
212 lttng_process_attr_virtual_process_id_tracker_handle_remove_pid(
213 const struct lttng_process_attr_tracker_handle
214 *process_id_tracker,
215 pid_t vpid);
216
217 /*
218 * Add a numerical UID to the user ID process attribute tracker inclusion set.
219 *
220 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
221 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
222 * present in the inclusion set, and
223 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
224 * argument was provided.
225 */
226 extern enum lttng_process_attr_tracker_handle_status
227 lttng_process_attr_user_id_tracker_handle_add_uid(
228 const struct lttng_process_attr_tracker_handle *user_id_tracker,
229 uid_t uid);
230
231 /*
232 * Remove a numerical UID from the user ID process attribute tracker include
233 * set.
234 *
235 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
236 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
237 * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
238 * an invalid tracker argument was provided.
239 */
240 extern enum lttng_process_attr_tracker_handle_status
241 lttng_process_attr_user_id_tracker_handle_remove_uid(
242 const struct lttng_process_attr_tracker_handle *user_id_tracker,
243 uid_t uid);
244
245 /*
246 * Add a user name to the user ID process attribute tracker inclusion set.
247 *
248 * The user name resolution is performed by the session daemon on addition to
249 * the user ID inclusion set.
250 *
251 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
252 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
253 * present in the inclusion set, and
254 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
255 * argument was provided.
256 */
257 extern enum lttng_process_attr_tracker_handle_status
258 lttng_process_attr_user_id_tracker_handle_add_user_name(
259 const struct lttng_process_attr_tracker_handle *user_id_tracker,
260 const char *user_name);
261
262 /*
263 * Remove a user name from the user ID process attribute tracker include
264 * set.
265 *
266 * No name resolution is performed; the user name will be matched against the
267 * names in the inclusion set.
268 *
269 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
270 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
271 * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
272 * an invalid tracker argument was provided.
273 */
274 extern enum lttng_process_attr_tracker_handle_status
275 lttng_process_attr_user_id_tracker_handle_remove_user_name(
276 const struct lttng_process_attr_tracker_handle *user_id_tracker,
277 const char *user_name);
278
279 /*
280 * Add a numerical UID to the virtual user ID process attribute tracker
281 * inclusion set.
282 *
283 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
284 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
285 * present in the inclusion set, and
286 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
287 * argument was provided.
288 */
289 extern enum lttng_process_attr_tracker_handle_status
290 lttng_process_attr_virtual_user_id_tracker_handle_add_uid(
291 const struct lttng_process_attr_tracker_handle *user_id_tracker,
292 uid_t vuid);
293
294 /*
295 * Remove a numerical UID from the virtual user ID process attribute tracker
296 * inclusion set.
297 *
298 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
299 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
300 * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
301 * an invalid tracker argument was provided.
302 */
303 extern enum lttng_process_attr_tracker_handle_status
304 lttng_process_attr_virtual_user_id_tracker_handle_remove_uid(
305 const struct lttng_process_attr_tracker_handle *user_id_tracker,
306 uid_t vuid);
307
308 /*
309 * Add a user name to the virtual user ID process attribute tracker include
310 * set.
311 *
312 * The user name resolution is performed by the session daemon on addition to
313 * the virtual user ID inclusion set.
314 *
315 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
316 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
317 * present in the inclusion set, and
318 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
319 * argument was provided.
320 */
321 extern enum lttng_process_attr_tracker_handle_status
322 lttng_process_attr_virtual_user_id_tracker_handle_add_user_name(
323 const struct lttng_process_attr_tracker_handle *user_id_tracker,
324 const char *virtual_user_name);
325
326 /*
327 * Remove a user name from the virtual user ID process attribute tracker
328 * inclusion set.
329 *
330 * No name resolution is performed; the user name will be matched against the
331 * names in the inclusion set.
332 *
333 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
334 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
335 * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
336 * an invalid tracker argument was provided.
337 */
338 extern enum lttng_process_attr_tracker_handle_status
339 lttng_process_attr_virtual_user_id_tracker_handle_remove_user_name(
340 const struct lttng_process_attr_tracker_handle *user_id_tracker,
341 const char *virtual_user_name);
342
343 /*
344 * Add a numerical GID to the group ID process attribute tracker inclusion set.
345 *
346 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
347 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
348 * present in the inclusion set, and
349 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
350 * argument was provided.
351 */
352 extern enum lttng_process_attr_tracker_handle_status
353 lttng_process_attr_group_id_tracker_handle_add_gid(
354 const struct lttng_process_attr_tracker_handle *group_id_tracker,
355 gid_t gid);
356
357 /*
358 * Remove a numerical GID from the group ID process attribute tracker include
359 * set.
360 *
361 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
362 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
363 * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
364 * an invalid tracker argument was provided.
365 */
366 extern enum lttng_process_attr_tracker_handle_status
367 lttng_process_attr_group_id_tracker_handle_remove_gid(
368 const struct lttng_process_attr_tracker_handle *group_id_tracker,
369 gid_t gid);
370
371 /*
372 * Add a group name to the group ID process attribute tracker inclusion set.
373 *
374 * The group name resolution is performed by the session daemon on addition to
375 * the group ID inclusion set.
376 *
377 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
378 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
379 * present in the inclusion set, and
380 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
381 * argument was provided.
382 */
383 extern enum lttng_process_attr_tracker_handle_status
384 lttng_process_attr_group_id_tracker_handle_add_group_name(
385 const struct lttng_process_attr_tracker_handle *group_id_tracker,
386 const char *group_name);
387
388 /*
389 * Remove a group name from the group ID process attribute tracker include
390 * set.
391 *
392 * No name resolution is performed; the user name will be matched against the
393 * names in the inclusion set.
394 *
395 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
396 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
397 * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
398 * an invalid tracker argument was provided.
399 */
400 extern enum lttng_process_attr_tracker_handle_status
401 lttng_process_attr_group_id_tracker_handle_remove_group_name(
402 const struct lttng_process_attr_tracker_handle *group_id_tracker,
403 const char *group_name);
404
405 /*
406 * Add a numerical GID to the virtual group ID process attribute tracker
407 * inclusion set.
408 *
409 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
410 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
411 * present in the inclusion set, and
412 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
413 * argument was provided.
414 */
415 extern enum lttng_process_attr_tracker_handle_status
416 lttng_process_attr_virtual_group_id_tracker_handle_add_gid(
417 const struct lttng_process_attr_tracker_handle *group_id_tracker,
418 gid_t vgid);
419
420 /*
421 * Remove a numerical GID from the virtual group ID process attribute tracker
422 * inclusion set.
423 *
424 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
425 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
426 * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
427 * an invalid tracker argument was provided.
428 */
429 extern enum lttng_process_attr_tracker_handle_status
430 lttng_process_attr_virtual_group_id_tracker_handle_remove_gid(
431 const struct lttng_process_attr_tracker_handle *group_id_tracker,
432 gid_t vgid);
433
434 /*
435 * Add a group name to the virtual group ID process attribute tracker include
436 * set.
437 *
438 * The group name resolution is performed by the session daemon on addition to
439 * the virtual group ID inclusion set.
440 *
441 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
442 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
443 * present in the inclusion set, and
444 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
445 * argument was provided.
446 */
447 extern enum lttng_process_attr_tracker_handle_status
448 lttng_process_attr_virtual_group_id_tracker_handle_add_group_name(
449 const struct lttng_process_attr_tracker_handle *group_id_tracker,
450 const char *virtual_group_name);
451
452 /*
453 * Remove a group name from the virtual group ID process attribute tracker
454 * inclusion set.
455 *
456 * No name resolution is performed; the user name will be matched against the
457 * names in the inclusion set.
458 *
459 * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
460 * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
461 * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
462 * an invalid tracker argument was provided.
463 */
464 extern enum lttng_process_attr_tracker_handle_status
465 lttng_process_attr_virtual_group_id_tracker_handle_remove_group_name(
466 const struct lttng_process_attr_tracker_handle *group_id_tracker,
467 const char *virtual_group_name);
468
469 /*
470 * Get the process attribute values that are part of a tracker's inclusion set.
471 *
472 * The values returned are a snapshot of the values that are part of the
473 * tracker's inclusion set at the moment of the invocation; it is not updated
474 * as entries are added or removed.
475 *
476 * The values remain valid until the tracker is destroyed.
477 *
478 * Returns LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK on success,
479 * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID if the tracker's policy is
480 * not LTTNG_POLICY_INCLUDE_SET.
481 */
482 extern enum lttng_process_attr_tracker_handle_status
483 lttng_process_attr_tracker_handle_get_inclusion_set(
484 struct lttng_process_attr_tracker_handle *tracker_handle,
485 const struct lttng_process_attr_values **values);
486
487 /*
488 * Get the count of values within a set of process attribute values.
489 *
490 * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
491 * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID if an invalid argument is provided.
492 */
493 extern enum lttng_process_attr_values_status
494 lttng_process_attr_values_get_count(
495 const struct lttng_process_attr_values *values,
496 unsigned int *count);
497
498 /*
499 * Get the type of a process attribute value at a given index.
500 *
501 * Returns a process attribute value type on success,
502 * LTTNG_PROCESS_ATTR_VALUE_TYPE_INVALID if an invalid argument is provided.
503 */
504 extern enum lttng_process_attr_value_type
505 lttng_process_attr_values_get_type_at_index(
506 const struct lttng_process_attr_values *values,
507 unsigned int index);
508
509 /*
510 * Get a process ID process attribute value.
511 *
512 * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
513 * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
514 * is not a process ID.
515 */
516 extern enum lttng_process_attr_values_status
517 lttng_process_attr_values_get_pid_at_index(
518 const struct lttng_process_attr_values *values,
519 unsigned int index,
520 pid_t *pid);
521
522 /*
523 * Get a user ID process attribute value.
524 *
525 * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
526 * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
527 * is not a user ID.
528 */
529 extern enum lttng_process_attr_values_status
530 lttng_process_attr_values_get_uid_at_index(
531 const struct lttng_process_attr_values *values,
532 unsigned int index,
533 uid_t *uid);
534
535 /*
536 * Get a user name process attribute value.
537 *
538 * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
539 * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
540 * is not a user name.
541 */
542 extern enum lttng_process_attr_values_status
543 lttng_process_attr_values_get_user_name_at_index(
544 const struct lttng_process_attr_values *values,
545 unsigned int index,
546 const char **user_name);
547
548 /*
549 * Get a group ID process attribute value.
550 *
551 * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
552 * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
553 * is not a group ID.
554 */
555 extern enum lttng_process_attr_values_status
556 lttng_process_attr_values_get_gid_at_index(
557 const struct lttng_process_attr_values *values,
558 unsigned int index,
559 gid_t *gid);
560
561 /*
562 * Get a group name process attribute value.
563 *
564 * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
565 * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
566 * is not a group name.
567 */
568 extern enum lttng_process_attr_values_status
569 lttng_process_attr_values_get_group_name_at_index(
570 const struct lttng_process_attr_values *values,
571 unsigned int index,
572 const char **group_name);
573
574 /* The following entry points are deprecated. */
575
576 /*
577 * Deprecated: see `lttng_process_attr_tracker_handle_get_inclusion_set` and
578 * `lttng_process_tracker_handle_get_tracking_policy`.
579 *
580 * List tracked PIDs.
581 *
582 * `enabled` indicates whether or not the PID tracker is enabled.
583 *
584 * `pids` is set to an allocated array of PIDs currently being tracked. On
585 * success, `pids` must be freed by the caller.
586 *
587 * `nr_pids` is set to the number of entries contained in the `pids` array.
588 *
589 * Returns 0 on success, else a negative LTTng error code.
590 */
591 extern int lttng_list_tracker_pids(struct lttng_handle *handle,
592 int *enabled,
593 int32_t **pids,
594 size_t *nr_pids);
595
596 /*
597 * Deprecated: see `lttng_process_attr_process_id_tracker_handle_add_pid`.
598 *
599 * Add PID to session tracker.
600 *
601 * A pid argument >= 0 adds the PID to the session's PID tracker.
602 * A pid argument of -1 means "track all PIDs".
603 *
604 * Note on 'real' PIDs vs 'virtual' VPIDs:
605 * - With the user space domain specified, this function will add a VPID
606 * value to the virtual process ID process attribute tracker's inclusion
607 * set.
608 * - With the kernel space domain specified, this function will add a PID
609 * value to the process ID process attribute tracker's inclusion set.
610 *
611 * Returns 0 on success, else a negative LTTng error code.
612 */
613 extern int lttng_track_pid(struct lttng_handle *handle, int pid);
614
615 /*
616 * Deprecated: see `lttng_process_attr_process_id_tracker_handle_remove_pid`.
617 *
618 * Remove PID from session tracker.
619 *
620 * A pid argument >= 0 removes the PID from the session's PID tracker.
621 * A pid argument of -1 means "untrack all PIDs".
622 *
623 * Note on 'real' PIDs vs 'virtual' VPIDs:
624 * - With the user space domain specified, this function will remove a VPID
625 * value from the virtual process ID process attribute tracker's inclusion
626 * set.
627 * - With the kernel space domain specified, this function will remove a PID
628 * value from the process ID process attribute tracker's inclusion set.
629 *
630 * Returns 0 on success, else a negative LTTng error code.
631 */
632 extern int lttng_untrack_pid(struct lttng_handle *handle, int pid);
633
634 #ifdef __cplusplus
635 }
636 #endif
637
638 #endif /* LTTNG_TRACKER_H */
This page took 0.068081 seconds and 4 git commands to generate.