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