2d952a6e3f23488e5ca7253dcd14d821d96ad0fd
[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
55 /*
56 * Create a tracker id for the passed tracker type.
57 * Users must set the tracker id using the matching API call.
58 *
59 * On success, the caller is responsible for calling lttng_tracker_id_destroy.
60 * On error, return NULL.
61 */
62 extern struct lttng_tracker_id *lttng_tracker_id_create(void);
63
64 /*
65 * Configure the tracker id using the numerical representation of the resource
66 * to be tracked/untracked.
67 *
68 * If the tracker id was already configured, calling this function will replace
69 * the previous configuration and free memory as necessary.
70 *
71 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
72 * LTTNG_TRACKER_ID_STATUS_INVALID is the passed parameter is invalid.
73 */
74 extern enum lttng_tracker_id_status lttng_tracker_id_set_value(
75 struct lttng_tracker_id *id, int value);
76
77 /*
78 * Configure the tracker id using the string representation of the resource to
79 * be tracked/untracked.
80 *
81 * If the tracker id was already configured, calling this function will replace
82 * the previous configuration and free memory as necessary.
83 *
84 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
85 * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
86 */
87 extern enum lttng_tracker_id_status lttng_tracker_id_set_string(
88 struct lttng_tracker_id *id, const char *value);
89
90 /*
91 * Configure the tracker id to track/untrack all resources for the tracker type.
92 *
93 * If the tracker id was already configured, calling this function will replace
94 * the previous configuration and free memory as necessary.
95 *
96 * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
97 * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
98 */
99 extern enum lttng_tracker_id_status lttng_tracker_id_set_all(
100 struct lttng_tracker_id *id);
101
102 /*
103 * Destroys (frees) a tracker id.
104 */
105 extern void lttng_tracker_id_destroy(struct lttng_tracker_id *id);
106
107 /*
108 * Returns the type of the tracker id.
109 */
110 extern enum lttng_tracker_id_type lttng_tracker_id_get_type(
111 const struct lttng_tracker_id *id);
112
113 /*
114 * Returns the value of the tracker id.
115 *
116 * Returns LTTNG_TRACKER_ID_OK on success,
117 * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
118 * LTTNG_ID_VALUE,
119 * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
120 */
121 extern enum lttng_tracker_id_status lttng_tracker_id_get_value(
122 const struct lttng_tracker_id *id, int *value);
123
124 /*
125 * Returns the string representation of the tracker id.
126 *
127 * Returns LTTNG_TRACKER_ID_OK on success,
128 * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
129 * LTTNG_ID_STRING,
130 * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
131 */
132 extern enum lttng_tracker_id_status lttng_tracker_id_get_string(
133 const struct lttng_tracker_id *id, const char **value);
134
135 /*
136 * Destroys (frees) an array of tracker id.
137 */
138 extern void lttng_tracker_ids_destroy(
139 struct lttng_tracker_id **ids, size_t nr_ids);
140
141 /*
142 * Add ID to session tracker.
143 *
144 * tracker_type is the type of tracker.
145 * id is the lttng_tracker_type to track.
146 *
147 * Returns 0 on success else a negative LTTng error code.
148 */
149 extern int lttng_track_id(struct lttng_handle *handle,
150 enum lttng_tracker_type tracker_type,
151 const struct lttng_tracker_id *id);
152
153 /*
154 * Remove ID from session tracker.
155 *
156 * tracker_type is the type of tracker.
157 * id is the lttng_tracker_type to untrack.
158 * Returns 0 on success else a negative LTTng error code.
159 */
160 extern int lttng_untrack_id(struct lttng_handle *handle,
161 enum lttng_tracker_type tracker_type,
162 const struct lttng_tracker_id *id);
163
164 /*
165 * List IDs in the tracker.
166 *
167 * tracker_type is the type of tracker.
168 * ids is set to an allocated array of IDs currently tracked.
169 * On success, ids must be freed using lttng_tracker_id_destroy on each
170 * constituent of the returned array or using lttng_tracker_ids_destroy.
171 * nr_ids is set to the number of entries contained by the ids array.
172 *
173 * Returns 0 on success, else a negative LTTng error code.
174 */
175 extern int lttng_list_tracker_ids(struct lttng_handle *handle,
176 enum lttng_tracker_type tracker_type,
177 struct lttng_tracker_id ***ids,
178 size_t *nr_ids);
179
180 /*
181 * Backward compatibility.
182 * Add PID to session tracker.
183 *
184 * A pid argument >= 0 adds the PID to the session tracker.
185 * A pid argument of -1 means "track all PIDs".
186 *
187 * Returns 0 on success else a negative LTTng error code.
188 */
189 extern int lttng_track_pid(struct lttng_handle *handle, int pid);
190
191 /*
192 * Backward compatibility.
193 * Remove PID from session tracker.
194 *
195 * A pid argument >= 0 removes the PID from the session tracker.
196 * A pid argument of -1 means "untrack all PIDs".
197 *
198 * Returns 0 on success else a negative LTTng error code.
199 */
200 extern int lttng_untrack_pid(struct lttng_handle *handle, int pid);
201
202 /*
203 * Backward compatibility
204 * List PIDs in the tracker.
205 *
206 * enabled is set to whether the PID tracker is enabled.
207 * pids is set to an allocated array of PIDs currently tracked. On
208 * success, pids must be freed by the caller.
209 * nr_pids is set to the number of entries contained by the pids array.
210 *
211 * Returns 0 on success, else a negative LTTng error code.
212 */
213 extern int lttng_list_tracker_pids(struct lttng_handle *handle,
214 int *enabled,
215 int32_t **pids,
216 size_t *nr_pids);
217
218 #ifdef __cplusplus
219 }
220 #endif
221
222 #endif /* LTTNG_TRACKER_H */
This page took 0.032369 seconds and 3 git commands to generate.