Fix uninitialized ret value
[lttng-tools.git] / include / lttng / lttng.h
CommitLineData
826d496d 1/*
b7384347
DG
2 * lttng.h
3 *
4 * Linux Trace Toolkit Control Library Header File
5 *
826d496d 6 * Copyright (C) 2011 - David Goulet <david.goulet@polymtl.ca>
fac6795d 7 *
1e46a50f
TD
8 * This library is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU Lesser General Public License as published by the
10 * Free Software Foundation; only version 2.1 of the License.
82a3637f 11 *
1e46a50f
TD
12 * This library is distributed in the hope that it will be useful, but WITHOUT
13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
15 * for more details.
82a3637f 16 *
1e46a50f
TD
17 * You should have received a copy of the GNU Lesser General Public License
18 * along with this library; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
fac6795d
DG
20 */
21
b7384347
DG
22#ifndef _LTTNG_H
23#define _LTTNG_H
fac6795d 24
57167058 25#include <limits.h>
1e307fab
DG
26#include <stdint.h>
27#include <sys/types.h>
57167058 28
b7384347 29/*
e6ddca71 30 * Event symbol length. Copied from LTTng kernel ABI.
1657e9bb 31 */
8d326ab9 32#define LTTNG_SYMBOL_NAME_LEN 256
f3ed775e 33
e6ddca71
DG
34/*
35 * Every lttng_event_* structure both apply to kernel event and user-space
36 * event.
e6ddca71
DG
37 */
38
7d29a247 39/*
1e46a50f 40 * Domain types: the different possible tracers.
7d29a247
DG
41 */
42enum lttng_domain_type {
0d0c377a
DG
43 LTTNG_DOMAIN_KERNEL = 1,
44 LTTNG_DOMAIN_UST = 2,
d78d6610
DG
45
46 /*
47 * For now, the domains below are not implemented. However, we keep them
48 * here in order to retain their enum values for future development. Note
49 * that it is on the roadmap to implement them.
50 *
0d0c377a
DG
51 LTTNG_DOMAIN_UST_EXEC_NAME = 3,
52 LTTNG_DOMAIN_UST_PID = 4,
53 LTTNG_DOMAIN_UST_PID_FOLLOW_CHILDREN = 5,
d78d6610 54 */
7d29a247
DG
55};
56
7d29a247
DG
57/*
58 * Instrumentation type of tracing event.
59 */
f3ed775e 60enum lttng_event_type {
7a3d1328
MD
61 LTTNG_EVENT_ALL = -1,
62 LTTNG_EVENT_TRACEPOINT = 0,
63 LTTNG_EVENT_PROBE = 1,
64 LTTNG_EVENT_FUNCTION = 2,
65 LTTNG_EVENT_FUNCTION_ENTRY = 3,
66 LTTNG_EVENT_NOOP = 4,
67 LTTNG_EVENT_SYSCALL = 5,
0cda4f28
MD
68};
69
70/*
71 * Loglevel information.
72 */
73enum lttng_loglevel_type {
8005f29a
MD
74 LTTNG_EVENT_LOGLEVEL_ALL = 0,
75 LTTNG_EVENT_LOGLEVEL_RANGE = 1,
76 LTTNG_EVENT_LOGLEVEL_SINGLE = 2,
1657e9bb
DG
77};
78
e6ddca71
DG
79/*
80 * LTTng consumer mode
81 */
82enum lttng_event_output {
d78d6610
DG
83 LTTNG_EVENT_SPLICE = 0,
84 LTTNG_EVENT_MMAP = 1,
e6ddca71
DG
85};
86
7d29a247
DG
87/* Event context possible type */
88enum lttng_event_context_type {
d78d6610
DG
89 LTTNG_EVENT_CONTEXT_PID = 0,
90 LTTNG_EVENT_CONTEXT_PERF_COUNTER = 1,
9197c5c4 91 LTTNG_EVENT_CONTEXT_PROCNAME = 2,
d78d6610
DG
92 LTTNG_EVENT_CONTEXT_PRIO = 3,
93 LTTNG_EVENT_CONTEXT_NICE = 4,
94 LTTNG_EVENT_CONTEXT_VPID = 5,
95 LTTNG_EVENT_CONTEXT_TID = 6,
96 LTTNG_EVENT_CONTEXT_VTID = 7,
97 LTTNG_EVENT_CONTEXT_PPID = 8,
98 LTTNG_EVENT_CONTEXT_VPPID = 9,
9197c5c4 99 LTTNG_EVENT_CONTEXT_PTHREAD_ID = 10,
d65106b1
DG
100};
101
d0254c7c 102enum lttng_calibrate_type {
d78d6610 103 LTTNG_CALIBRATE_FUNCTION = 0,
d0254c7c
MD
104};
105
8d326ab9
DG
106#define LTTNG_DOMAIN_PADDING1 16
107#define LTTNG_DOMAIN_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
9f19cc17
DG
108struct lttng_domain {
109 enum lttng_domain_type type;
8d326ab9
DG
110 char padding[LTTNG_DOMAIN_PADDING1];
111
9f19cc17
DG
112 union {
113 pid_t pid;
114 char exec_name[NAME_MAX];
8d326ab9 115 char padding[LTTNG_DOMAIN_PADDING2];
9f19cc17
DG
116 } attr;
117};
118
d65106b1 119/* Perf counter attributes */
8d326ab9 120#define LTTNG_PERF_EVENT_PADDING1 16
7d29a247 121struct lttng_event_perf_counter_ctx {
d65106b1
DG
122 uint32_t type;
123 uint64_t config;
124 char name[LTTNG_SYMBOL_NAME_LEN];
8d326ab9
DG
125
126 char padding[LTTNG_PERF_EVENT_PADDING1];
d65106b1
DG
127};
128
129/* Event/Channel context */
8d326ab9
DG
130#define LTTNG_EVENT_CONTEXT_PADDING1 16
131#define LTTNG_EVENT_CONTEXT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
7d29a247
DG
132struct lttng_event_context {
133 enum lttng_event_context_type ctx;
8d326ab9
DG
134 char padding[LTTNG_EVENT_CONTEXT_PADDING1];
135
d65106b1 136 union {
7d29a247 137 struct lttng_event_perf_counter_ctx perf_counter;
8d326ab9 138 char padding[LTTNG_EVENT_CONTEXT_PADDING2];
d65106b1
DG
139 } u;
140};
141
b7384347 142/*
7d29a247
DG
143 * Event probe.
144 *
145 * Either addr is used or symbol_name and offset.
57167058 146 */
8d326ab9 147#define LTTNG_EVENT_PROBE_PADDING1 16
7d29a247 148struct lttng_event_probe_attr {
f3ed775e
DG
149 uint64_t addr;
150
151 uint64_t offset;
152 char symbol_name[LTTNG_SYMBOL_NAME_LEN];
8d326ab9
DG
153
154 char padding[LTTNG_EVENT_PROBE_PADDING1];
57167058
DG
155};
156
b7384347 157/*
f3ed775e
DG
158 * Function tracer
159 */
8d326ab9 160#define LTTNG_EVENT_FUNCTION_PADDING1 16
f3ed775e
DG
161struct lttng_event_function_attr {
162 char symbol_name[LTTNG_SYMBOL_NAME_LEN];
8d326ab9
DG
163
164 char padding[LTTNG_EVENT_FUNCTION_PADDING1];
f3ed775e
DG
165};
166
167/*
168 * Generic lttng event
169 */
8d326ab9
DG
170#define LTTNG_EVENT_PADDING1 16
171#define LTTNG_EVENT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
f3ed775e 172struct lttng_event {
0cda4f28 173 enum lttng_event_type type;
f3ed775e 174 char name[LTTNG_SYMBOL_NAME_LEN];
0cda4f28
MD
175
176 enum lttng_loglevel_type loglevel_type;
8005f29a 177 int loglevel;
0cda4f28 178
9f19cc17 179 uint32_t enabled;
b551a063 180 pid_t pid;
8d326ab9
DG
181
182 char padding[LTTNG_EVENT_PADDING1];
183
f3ed775e
DG
184 /* Per event type configuration */
185 union {
7d29a247 186 struct lttng_event_probe_attr probe;
f3ed775e 187 struct lttng_event_function_attr ftrace;
8d326ab9
DG
188
189 char padding[LTTNG_EVENT_PADDING2];
f3ed775e
DG
190 } attr;
191};
192
e6ddca71
DG
193/*
194 * Tracer channel attributes. For both kernel and user-space.
195 */
8d326ab9 196#define LTTNG_CHANNEL_ATTR_PADDING1 LTTNG_SYMBOL_NAME_LEN + 32
f3ed775e 197struct lttng_channel_attr {
8ce37aa5
DG
198 int overwrite; /* 1: overwrite, 0: discard */
199 uint64_t subbuf_size; /* bytes */
200 uint64_t num_subbuf; /* power of 2 */
201 unsigned int switch_timer_interval; /* usec */
202 unsigned int read_timer_interval; /* usec */
f05b5f07 203 enum lttng_event_output output; /* splice, mmap */
8d326ab9
DG
204
205 char padding[LTTNG_CHANNEL_ATTR_PADDING1];
f3ed775e
DG
206};
207
208/*
e6ddca71 209 * Channel information structure. For both kernel and user-space.
1657e9bb 210 */
8d326ab9 211#define LTTNG_CHANNEL_PADDING1 16
e6ddca71 212struct lttng_channel {
045e5491 213 char name[LTTNG_SYMBOL_NAME_LEN];
9f19cc17 214 uint32_t enabled;
e6ddca71 215 struct lttng_channel_attr attr;
8d326ab9
DG
216
217 char padding[LTTNG_CHANNEL_PADDING1];
f3ed775e
DG
218};
219
8d326ab9 220#define LTTNG_CALIBRATE_PADDING1 16
d0254c7c
MD
221struct lttng_calibrate {
222 enum lttng_calibrate_type type;
8d326ab9
DG
223
224 char padding[LTTNG_CALIBRATE_PADDING1];
d0254c7c
MD
225};
226
e6ddca71
DG
227/*
228 * Basic session information.
229 *
230 * This is an 'output data' meaning that it only comes *from* the session
231 * daemon *to* the lttng client. It's basically a 'human' representation of
232 * tracing entities (here a session).
233 */
8d326ab9 234#define LTTNG_SESSION_PADDING1 16
e6ddca71 235struct lttng_session {
f3ed775e 236 char name[NAME_MAX];
e6ddca71
DG
237 /* The path where traces are written */
238 char path[PATH_MAX];
464dd62d 239 uint32_t enabled; /* enabled/started: 1, disabled/stopped: 0 */
8d326ab9
DG
240
241 char padding[LTTNG_SESSION_PADDING1];
1657e9bb
DG
242};
243
cd80958d
DG
244/*
245 * Handle used as a context for commands.
246 */
8d326ab9 247#define LTTNG_HANDLE_PADDING1 16
cd80958d
DG
248struct lttng_handle {
249 char session_name[NAME_MAX];
250 struct lttng_domain domain;
8d326ab9
DG
251
252 char padding[LTTNG_HANDLE_PADDING1];
cd80958d
DG
253};
254
7d29a247
DG
255/*
256 * Public LTTng control API
257 *
1e46a50f 258 * For functions having an lttng domain type as parameter, if a bad value is
7d29a247
DG
259 * given, NO default is applied and an error is returned.
260 *
261 * On success, all functions of the API return 0 or the size of the allocated
1e46a50f 262 * array (in bytes).
7d29a247
DG
263 *
264 * On error, a negative value is returned being a specific lttng-tools error
9a745bc7 265 * code which can be humanly interpreted with lttng_strerror(err).
1e46a50f
TD
266 *
267 * Exceptions to this are noted below.
7d29a247
DG
268 */
269
b7384347 270/*
1e46a50f 271 * Create a handle used as a context for every request made to the library.
cd80958d
DG
272 *
273 * This handle contains the session name and lttng domain on which the command
1e46a50f
TD
274 * will be executed.
275 * The returned pointer will be NULL in case of malloc() error.
cd80958d
DG
276 */
277extern struct lttng_handle *lttng_create_handle(const char *session_name,
278 struct lttng_domain *domain);
279
280/*
1e46a50f
TD
281 * Destroy a handle. This will simply free(3) the data pointer returned by
282 * lttng_create_handle(), rendering it unusable.
b7384347 283 */
cd80958d 284extern void lttng_destroy_handle(struct lttng_handle *handle);
7d29a247
DG
285
286/*
1e46a50f
TD
287 * Create a tracing session using a name and a path where the trace will be
288 * written.
7d29a247 289 */
38057ed1 290extern int lttng_create_session(const char *name, const char *path);
f3ed775e 291
7d29a247 292/*
1e46a50f 293 * Destroy a tracing session.
7d29a247 294 *
1e46a50f
TD
295 * The session will not be usable anymore, tracing will be stopped for all
296 * registered traces, and the tracing buffers will be flushed.
7d29a247 297 */
843f5df9 298extern int lttng_destroy_session(const char *name);
f3ed775e 299
e6ddca71 300/*
1e46a50f 301 * List all the tracing sessions.
7d29a247 302 *
1e46a50f
TD
303 * Return the size (number of entries) of the "lttng_session" array. Caller
304 * must free(3).
e6ddca71 305 */
ca95a216 306extern int lttng_list_sessions(struct lttng_session **sessions);
f3ed775e 307
9f19cc17 308/*
1e46a50f 309 * List the registered domain(s) of a session.
9f19cc17 310 *
1e46a50f
TD
311 * Return the size (number of entries) of the "lttng_domain" array. Caller
312 * must free(3).
9f19cc17 313 */
330be774 314extern int lttng_list_domains(const char *session_name,
9f19cc17
DG
315 struct lttng_domain **domains);
316
317/*
1e46a50f 318 * List the channel(s) of a session.
9f19cc17 319 *
1e46a50f
TD
320 * Return the size (number of entries) of the "lttng_channel" array. Caller
321 * must free(3).
9f19cc17 322 */
cd80958d
DG
323extern int lttng_list_channels(struct lttng_handle *handle,
324 struct lttng_channel **channels);
9f19cc17
DG
325
326/*
1e46a50f 327 * List the event(s) of a session channel.
9f19cc17 328 *
1e46a50f
TD
329 * Return the size (number of entries) of the "lttng_event" array.
330 * Caller must free(3).
9f19cc17 331 */
cd80958d
DG
332extern int lttng_list_events(struct lttng_handle *handle,
333 const char *channel_name, struct lttng_event **events);
9f19cc17
DG
334
335/*
1e46a50f 336 * List the available tracepoints of a specific lttng domain.
9f19cc17 337 *
1e46a50f
TD
338 * Return the size (number of entries) of the "lttng_event" array.
339 * Caller must free(3).
9f19cc17 340 */
cd80958d 341extern int lttng_list_tracepoints(struct lttng_handle *handle,
2a71efd5 342 struct lttng_event **events);
9f19cc17 343
7d29a247
DG
344/*
345 * Check if a session daemon is alive.
1e46a50f
TD
346 *
347 * Return 1 if alive or 0 if not. On error returns a negative value.
7d29a247 348 */
947308c4 349extern int lttng_session_daemon_alive(void);
f3ed775e 350
7d29a247 351/*
1e46a50f
TD
352 * Set the tracing group for the *current* flow of execution.
353 *
354 * On success, returns 0, on error, returns -1 (null name) or -ENOMEM.
7d29a247 355 */
b7384347 356extern int lttng_set_tracing_group(const char *name);
f3ed775e 357
7d29a247 358/*
1e46a50f 359 * Return a human-readable error message for an lttng-tools error code.
7d29a247
DG
360 *
361 * Parameter MUST be a negative value or else you'll get a generic message.
362 */
9a745bc7 363extern const char *lttng_strerror(int code);
b7384347 364
d9800920 365/*
1e46a50f
TD
366 * This call registers an "outside consumer" for a session and an lttng domain.
367 * No consumer will be spawned and all fds/commands will go through the socket
368 * path given (socket_path).
d9800920 369 *
3bd1e081 370 * NOTE: At the moment, if you use the liblttng-kconsumer, you can only use the
d9800920
DG
371 * command socket. The error socket is not supported yet for roaming consumers.
372 */
373extern int lttng_register_consumer(struct lttng_handle *handle,
374 const char *socket_path);
375
7d29a247 376/*
1e46a50f 377 * Start tracing for *all* registered traces (kernel and user-space).
7d29a247 378 */
6a4f824d 379extern int lttng_start_tracing(const char *session_name);
f3ed775e 380
7d29a247 381/*
1e46a50f 382 * Stop tracing for *all* registered traces (kernel and user-space).
7d29a247 383 */
6a4f824d 384extern int lttng_stop_tracing(const char *session_name);
f3ed775e 385
b7384347 386/*
1e46a50f 387 * Add context to event(s) for a specific channel (or for all).
7d29a247 388 *
1e46a50f 389 * If event_name is NULL, the context is applied to all events of the channel.
7d29a247 390 * If channel_name is NULL, a lookup of the event's channel is done.
1e46a50f 391 * If both are NULL, the context is applied to all events of all channels.
b7384347 392 */
cd80958d 393extern int lttng_add_context(struct lttng_handle *handle,
38057ed1
DG
394 struct lttng_event_context *ctx, const char *event_name,
395 const char *channel_name);
f3ed775e 396
7d29a247 397/*
1e46a50f 398 * Create or enable a kernel event (or events) for a channel.
7d29a247
DG
399 *
400 * If the event you are trying to enable does not exist, it will be created,
401 * else it is enabled.
1e46a50f 402 * If event_name is NULL, all events are enabled.
7d29a247
DG
403 * If channel_name is NULL, the default channel is used (channel0).
404 */
cd80958d
DG
405extern int lttng_enable_event(struct lttng_handle *handle,
406 struct lttng_event *ev, const char *channel_name);
f3ed775e 407
7d29a247
DG
408/*
409 * Create or enable a kernel channel.
1e46a50f 410 * The channel name cannot be NULL.
7d29a247 411 */
cd80958d 412extern int lttng_enable_channel(struct lttng_handle *handle,
38057ed1 413 struct lttng_channel *chan);
f3ed775e 414
7d29a247 415/*
1e46a50f 416 * Disable kernel event(s) of a channel and domain.
7d29a247 417 *
1e46a50f 418 * If event_name is NULL, all events are disabled.
7d29a247
DG
419 * If channel_name is NULL, the default channel is used (channel0).
420 */
cd80958d
DG
421extern int lttng_disable_event(struct lttng_handle *handle,
422 const char *name, const char *channel_name);
fac6795d 423
1df4dedd 424/*
7d29a247
DG
425 * Disable kernel channel.
426 *
1e46a50f 427 * The channel name cannot be NULL.
1df4dedd 428 */
cd80958d 429extern int lttng_disable_channel(struct lttng_handle *handle,
38057ed1 430 const char *name);
1df4dedd 431
d0254c7c
MD
432/*
433 * Calibrate LTTng overhead.
434 */
cd80958d 435extern int lttng_calibrate(struct lttng_handle *handle,
d0254c7c
MD
436 struct lttng_calibrate *calibrate);
437
5edd7e09
DG
438/*
439 * Set the default channel attributes for a specific domain and an allocated
440 * lttng_channel_attr pointer.
1e46a50f
TD
441 *
442 * If either or both of the arguments are NULL, nothing happens.
5edd7e09
DG
443 */
444extern void lttng_channel_set_default_attr(struct lttng_domain *domain,
445 struct lttng_channel_attr *attr);
446
b7384347 447#endif /* _LTTNG_H */
This page took 0.076202 seconds and 4 git commands to generate.