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