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