Commit | Line | Data |
---|---|---|
4ddbd0b7 PP |
1 | tracef(3) |
2 | ========= | |
3 | :object-type: macro | |
4 | ||
5 | ||
6 | NAME | |
7 | ---- | |
cfd56ee1 | 8 | tracef, vtracef - LTTng-UST printf(3)-like interface |
4ddbd0b7 PP |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
13 | [verse] | |
14 | *#include <lttng/tracef.h>* | |
15 | ||
16 | [verse] | |
17 | #define *tracef*('fmt', ...) | |
cfd56ee1 | 18 | #define *vtracef*('fmt', 'va_list' ap) |
4ddbd0b7 PP |
19 | |
20 | Link with `-llttng-ust`. | |
21 | ||
22 | ||
23 | DESCRIPTION | |
24 | ----------- | |
25 | The LTTng-UST `tracef()` API allows you to trace your application with | |
26 | the help of a simple man:printf(3)-like macro. The 'fmt' argument is | |
27 | passed directly to the 'fmt' parameter of man:vasprintf(3), as well as | |
28 | the optional parameters following 'fmt'. | |
29 | ||
cfd56ee1 MRB |
30 | To use `tracef()` or `vtracef()`, include `<lttng/tracef.h>` where you need it, |
31 | and link your application with `liblttng-ust`. See the <<example,EXAMPLE>> | |
4ddbd0b7 PP |
32 | section below for a complete usage example. |
33 | ||
cfd56ee1 | 34 | Once your application is instrumented with `tracef()` or `vtracef()` calls and |
4ddbd0b7 PP |
35 | ready to run, use man:lttng-enable-event(1) to enable the |
36 | `lttng_ust_tracef:*` event. | |
37 | ||
38 | The `tracef()` events contain a single field, named `msg`, which is the | |
39 | formatted string output. | |
40 | ||
41 | If you need to attach a specific log level to a `tracef()` call, use | |
42 | man:tracelog(3) instead. | |
43 | ||
44 | See also the <<limitations,LIMITATIONS>> section below for important | |
cfd56ee1 | 45 | limitations to consider when using `tracef()` or `vtracef()`. |
4ddbd0b7 PP |
46 | |
47 | ||
48 | [[example]] | |
49 | EXAMPLE | |
50 | ------- | |
51 | Here's a usage example of `tracef()`: | |
52 | ||
53 | ------------------------------------------------------------------- | |
54 | #include <stdlib.h> | |
55 | #include <lttng/tracef.h> | |
56 | ||
57 | int main(void) | |
58 | { | |
59 | int i; | |
60 | ||
61 | for (i = 0; i < 25; i++) { | |
62 | tracef("my message: %s, this integer: %d", "a message", i); | |
63 | } | |
64 | ||
65 | return EXIT_SUCCESS; | |
66 | } | |
67 | ------------------------------------------------------------------- | |
68 | ||
69 | This C source file, saved as `app.c`, can be compiled into a program | |
70 | like this: | |
71 | ||
72 | [role="term"] | |
636cf2a0 PP |
73 | ---- |
74 | $ cc -o app app.c -llttng-ust | |
75 | ---- | |
4ddbd0b7 PP |
76 | |
77 | You can create an LTTng tracing session, enable the `tracef()` events, | |
78 | and start the created tracing session like this: | |
79 | ||
80 | [role="term"] | |
636cf2a0 PP |
81 | ---- |
82 | $ lttng create my-session | |
83 | $ lttng enable-event --userspace 'lttng_ust_tracef:*' | |
84 | $ lttng start | |
85 | ---- | |
4ddbd0b7 PP |
86 | |
87 | Next, start the program to be traced: | |
88 | ||
89 | [role="term"] | |
636cf2a0 PP |
90 | ---- |
91 | $ ./app | |
92 | ---- | |
4ddbd0b7 PP |
93 | |
94 | Finally, stop the tracing session, and inspect the recorded events: | |
95 | ||
96 | [role="term"] | |
636cf2a0 PP |
97 | ---- |
98 | $ lttng stop | |
99 | $ lttng view | |
100 | ---- | |
4ddbd0b7 PP |
101 | |
102 | ||
103 | [[limitations]] | |
104 | LIMITATIONS | |
105 | ----------- | |
106 | :macro-name: tracef | |
107 | ||
108 | include::tracef-tracelog-limitations.txt[] | |
109 | ||
110 | ||
111 | include::common-footer.txt[] | |
112 | ||
113 | include::common-copyrights.txt[] | |
114 | ||
115 | include::common-authors.txt[] | |
116 | ||
117 | ||
118 | SEE ALSO | |
119 | -------- | |
120 | man:tracelog(3), | |
121 | man:lttng-ust(3), | |
122 | man:lttng(1), | |
123 | man:printf(3) |