2 * Copyright (C) 2019 - Jonathan Rajotte-Julien <jonathan.rajotte-julien@efficios.com>
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.
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
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
18 #ifndef LTTNG_TRACKER_H
19 #define LTTNG_TRACKER_H
21 #include <lttng/constant.h>
22 #include <common/macros.h>
23 #include <lttng/session.h>
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,
38 enum lttng_tracker_id_type
{
39 LTTNG_ID_UNKNOWN
= -1,
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,
56 struct lttng_tracker_id
;
59 * A collection of tracker id.
61 struct lttng_tracker_ids
;
64 * Create a tracker id for the passed tracker type.
65 * Users must set the tracker id using the matching API call.
67 * On success, the caller is responsible for calling lttng_tracker_id_destroy.
68 * On error, return NULL.
70 extern struct lttng_tracker_id
*lttng_tracker_id_create(void);
73 * Configure the tracker id using the numerical representation of the resource
74 * to be tracked/untracked.
76 * If the tracker id was already configured, calling this function will replace
77 * the previous configuration and free memory as necessary.
79 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
80 * LTTNG_TRACKER_ID_STATUS_INVALID is the passed parameter is invalid.
82 extern enum lttng_tracker_id_status
lttng_tracker_id_set_value(
83 struct lttng_tracker_id
*id
, int value
);
86 * Configure the tracker id using the string representation of the resource to
87 * be tracked/untracked.
89 * If the tracker id was already configured, calling this function will replace
90 * the previous configuration and free memory as necessary.
92 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
93 * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
95 extern enum lttng_tracker_id_status
lttng_tracker_id_set_string(
96 struct lttng_tracker_id
*id
, const char *value
);
99 * Configure the tracker id to track/untrack all resources for the tracker type.
101 * If the tracker id was already configured, calling this function will replace
102 * the previous configuration and free memory as necessary.
104 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
105 * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
107 extern enum lttng_tracker_id_status
lttng_tracker_id_set_all(
108 struct lttng_tracker_id
*id
);
111 * Destroy a tracker id.
113 extern void lttng_tracker_id_destroy(struct lttng_tracker_id
*id
);
116 * Get the type of a tracker id.
118 extern enum lttng_tracker_id_type
lttng_tracker_id_get_type(
119 const struct lttng_tracker_id
*id
);
122 * Get the value of a tracker id.
124 * Returns LTTNG_TRACKER_ID_OK on success,
125 * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
127 * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
129 extern enum lttng_tracker_id_status
lttng_tracker_id_get_value(
130 const struct lttng_tracker_id
*id
, int *value
);
133 * Get the string representation of the tracker id.
135 * Returns LTTNG_TRACKER_ID_OK on success,
136 * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
138 * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
140 extern enum lttng_tracker_id_status
lttng_tracker_id_get_string(
141 const struct lttng_tracker_id
*id
, const char **value
);
144 * Add ID to session tracker.
146 * tracker_type is the type of tracker.
147 * id is the lttng_tracker_type to track.
149 * Returns 0 on success else a negative LTTng error code.
151 extern int lttng_track_id(struct lttng_handle
*handle
,
152 enum lttng_tracker_type tracker_type
,
153 const struct lttng_tracker_id
*id
);
156 * Remove ID from session tracker.
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.
162 extern int lttng_untrack_id(struct lttng_handle
*handle
,
163 enum lttng_tracker_type tracker_type
,
164 const struct lttng_tracker_id
*id
);
167 * List IDs of a tracker.
169 * On success, ids is allocated.
170 * The ids collection must be freed by the caller with lttng_destroy_ids().
172 * Returns 0 on success, else a negative LTTng error code.
174 extern int lttng_list_tracker_ids(struct lttng_handle
*handle
,
175 enum lttng_tracker_type tracker_type
,
176 struct lttng_tracker_ids
**ids
);
179 * Backward compatibility.
180 * Add PID to session tracker.
182 * A pid argument >= 0 adds the PID to the session tracker.
183 * A pid argument of -1 means "track all PIDs".
185 * Returns 0 on success else a negative LTTng error code.
187 extern int lttng_track_pid(struct lttng_handle
*handle
, int pid
);
190 * Backward compatibility.
191 * Remove PID from session tracker.
193 * A pid argument >= 0 removes the PID from the session tracker.
194 * A pid argument of -1 means "untrack all PIDs".
196 * Returns 0 on success else a negative LTTng error code.
198 extern int lttng_untrack_pid(struct lttng_handle
*handle
, int pid
);
201 * Backward compatibility
202 * List PIDs in the tracker.
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.
209 * Returns 0 on success, else a negative LTTng error code.
211 extern int lttng_list_tracker_pids(struct lttng_handle
*handle
,
217 * Get a tracker id from the list at a given index.
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.
223 * Returns a tracker id, or NULL on error.
225 extern const struct lttng_tracker_id
*lttng_tracker_ids_get_at_index(
226 const struct lttng_tracker_ids
*ids
, unsigned int index
);
229 * Get the number of tracker id in a tracker id list.
231 * Return LTTNG_TRACKER_ID_STATUS on sucess,
232 * LTTNG_TRACKER_ID_STATUS_INVALID when passed invalid parameters.
234 extern enum lttng_tracker_id_status
lttng_tracker_ids_get_count(
235 const struct lttng_tracker_ids
*ids
, unsigned int *count
);
238 * Destroy a tracker id list.
240 extern void lttng_tracker_ids_destroy(struct lttng_tracker_ids
*ids
);
246 #endif /* LTTNG_TRACKER_H */