2 * Copyright (C) 2019 Jonathan Rajotte-Julien <jonathan.rajotte-julien@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_TRACKER_H
9 #define LTTNG_TRACKER_H
11 #include <lttng/constant.h>
12 #include <common/macros.h>
13 #include <lttng/session.h>
19 enum lttng_tracker_type
{
20 LTTNG_TRACKER_PID
= 0,
21 LTTNG_TRACKER_VPID
= 1,
22 LTTNG_TRACKER_UID
= 2,
23 LTTNG_TRACKER_GID
= 3,
24 LTTNG_TRACKER_VUID
= 4,
25 LTTNG_TRACKER_VGID
= 5,
28 enum lttng_tracker_id_type
{
29 LTTNG_ID_UNKNOWN
= -1,
35 enum lttng_tracker_id_status
{
36 /* Invalid tracker id parameter. */
37 LTTNG_TRACKER_ID_STATUS_INVALID
= -1,
38 LTTNG_TRACKER_ID_STATUS_OK
= 0,
39 /* Tracker id parameter is unset. */
40 LTTNG_TRACKER_ID_STATUS_UNSET
= 1,
46 struct lttng_tracker_id
;
49 * A collection of tracker id.
51 struct lttng_tracker_ids
;
54 * Create a tracker id for the passed tracker type.
55 * Users must set the tracker id using the matching API call.
57 * On success, the caller is responsible for calling lttng_tracker_id_destroy.
58 * On error, return NULL.
60 extern struct lttng_tracker_id
*lttng_tracker_id_create(void);
63 * Configure the tracker id using the numerical representation of the resource
64 * to be tracked/untracked.
66 * If the tracker id was already configured, calling this function will replace
67 * the previous configuration and free memory as necessary.
69 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
70 * LTTNG_TRACKER_ID_STATUS_INVALID is the passed parameter is invalid.
72 extern enum lttng_tracker_id_status
lttng_tracker_id_set_value(
73 struct lttng_tracker_id
*id
, int value
);
76 * Configure the tracker id using the string representation of the resource to
77 * be tracked/untracked.
79 * If the tracker id was already configured, calling this function will replace
80 * the previous configuration and free memory as necessary.
82 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
83 * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
85 extern enum lttng_tracker_id_status
lttng_tracker_id_set_string(
86 struct lttng_tracker_id
*id
, const char *value
);
89 * Configure the tracker id to track/untrack all resources for the tracker type.
91 * If the tracker id was already configured, calling this function will replace
92 * the previous configuration and free memory as necessary.
94 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
95 * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
97 extern enum lttng_tracker_id_status
lttng_tracker_id_set_all(
98 struct lttng_tracker_id
*id
);
101 * Destroy a tracker id.
103 extern void lttng_tracker_id_destroy(struct lttng_tracker_id
*id
);
106 * Get the type of a tracker id.
108 extern enum lttng_tracker_id_type
lttng_tracker_id_get_type(
109 const struct lttng_tracker_id
*id
);
112 * Get the value of a tracker id.
114 * Returns LTTNG_TRACKER_ID_OK on success,
115 * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
117 * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
119 extern enum lttng_tracker_id_status
lttng_tracker_id_get_value(
120 const struct lttng_tracker_id
*id
, int *value
);
123 * Get the string representation of the tracker id.
125 * Returns LTTNG_TRACKER_ID_OK on success,
126 * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
128 * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
130 extern enum lttng_tracker_id_status
lttng_tracker_id_get_string(
131 const struct lttng_tracker_id
*id
, const char **value
);
134 * Add ID to session tracker.
136 * tracker_type is the type of tracker.
137 * id is the lttng_tracker_type to track.
139 * Returns 0 on success else a negative LTTng error code.
141 extern int lttng_track_id(struct lttng_handle
*handle
,
142 enum lttng_tracker_type tracker_type
,
143 const struct lttng_tracker_id
*id
);
146 * Remove ID from session tracker.
148 * tracker_type is the type of tracker.
149 * id is the lttng_tracker_type to untrack.
150 * Returns 0 on success else a negative LTTng error code.
152 extern int lttng_untrack_id(struct lttng_handle
*handle
,
153 enum lttng_tracker_type tracker_type
,
154 const struct lttng_tracker_id
*id
);
157 * List IDs of a tracker.
159 * On success, ids is allocated.
160 * The ids collection must be freed by the caller with lttng_destroy_ids().
162 * Returns 0 on success, else a negative LTTng error code.
164 extern int lttng_list_tracker_ids(struct lttng_handle
*handle
,
165 enum lttng_tracker_type tracker_type
,
166 struct lttng_tracker_ids
**ids
);
169 * Backward compatibility.
170 * Add PID to session tracker.
172 * A pid argument >= 0 adds the PID to the session tracker.
173 * A pid argument of -1 means "track all PIDs".
175 * Returns 0 on success else a negative LTTng error code.
177 extern int lttng_track_pid(struct lttng_handle
*handle
, int pid
);
180 * Backward compatibility.
181 * Remove PID from session tracker.
183 * A pid argument >= 0 removes the PID from the session tracker.
184 * A pid argument of -1 means "untrack all PIDs".
186 * Returns 0 on success else a negative LTTng error code.
188 extern int lttng_untrack_pid(struct lttng_handle
*handle
, int pid
);
191 * Backward compatibility
192 * List PIDs in the tracker.
194 * enabled is set to whether the PID tracker is enabled.
195 * pids is set to an allocated array of PIDs currently tracked. On
196 * success, pids must be freed by the caller.
197 * nr_pids is set to the number of entries contained by the pids array.
199 * Returns 0 on success, else a negative LTTng error code.
201 extern int lttng_list_tracker_pids(struct lttng_handle
*handle
,
207 * Get a tracker id from the list at a given index.
209 * Note that the list maintains the ownership of the returned tracker id.
210 * It must not be destroyed by the user, nor should it be held beyond the
211 * lifetime of the tracker id list.
213 * Returns a tracker id, or NULL on error.
215 extern const struct lttng_tracker_id
*lttng_tracker_ids_get_at_index(
216 const struct lttng_tracker_ids
*ids
, unsigned int index
);
219 * Get the number of tracker id in a tracker id list.
221 * Return LTTNG_TRACKER_ID_STATUS on sucess,
222 * LTTNG_TRACKER_ID_STATUS_INVALID when passed invalid parameters.
224 extern enum lttng_tracker_id_status
lttng_tracker_ids_get_count(
225 const struct lttng_tracker_ids
*ids
, unsigned int *count
);
228 * Destroy a tracker id list.
230 extern void lttng_tracker_ids_destroy(struct lttng_tracker_ids
*ids
);
236 #endif /* LTTNG_TRACKER_H */