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