5 The second approach to package the tracepoint providers is to use
6 dynamic linking: the library and its member functions are explicitly
7 sought, loaded and unloaded at runtime using `libdl`.
9 It has to be noted that, for a variety of reasons, the created shared
10 library is be dynamically _loaded_, as opposed to dynamically
11 _linked_. The tracepoint provider shared object is, however, linked
12 with `liblttng-ust`, so that `liblttng-ust` is guaranteed to be loaded
13 as soon as the tracepoint provider is. If the tracepoint provider is
14 not loaded, since the application itself is not linked with
15 `liblttng-ust`, the latter is not loaded at all and the tracepoint calls
18 The process to create the tracepoint provider shared object is pretty
19 much the same as the static library method, except that:
21 * since the tracepoint provider is not part of the application
22 anymore, `TRACEPOINT_DEFINE` _must_ be defined, for each tracepoint
23 provider, in exactly one translation unit (C source file) of the
25 * `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next to
28 Regarding `TRACEPOINT_DEFINE` and `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`,
29 the recommended practice is to use a separate C source file in your
30 application to define them, then include the tracepoint provider
31 header files afterwards. For example:
34 #define TRACEPOINT_DEFINE
35 #define TRACEPOINT_PROBE_DYNAMIC_LINKAGE
37 /* include the header files of one or more tracepoint providers below */
43 `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` makes the macros included afterwards
44 (by including the tracepoint provider header, which itself includes
45 LTTng-UST headers) aware that the tracepoint provider is to be loaded
46 dynamically and not part of the application's executable.
48 The tracepoint provider object file used to create the shared library
49 is built like it is using the static library method, only with the
53 gcc -c <strong>-fpic</strong> -I. tp.c
56 It is then linked as a shared library like this:
59 gcc <strong>-shared -Wl,--no-as-needed -o tp.so -llttng-ust</strong> tp.o
62 As previously stated, this tracepoint provider shared object isn't
63 linked with the user application: it's loaded manually. This is
64 why the application is built with no mention of this tracepoint
65 provider, but still needs `libdl`:
68 gcc -o app other.o files.o of.o your.o app.o <strong>-ldl</strong>
71 Now, to make LTTng-UST tracing available to the application, the
72 `LD_PRELOAD` environment variable is used to preload the tracepoint
73 provider shared library _before_ the application actually starts:
76 <strong>LD_PRELOAD=/path/to/tp.so</strong> ./app
81 <span class="t">Note:</span>It is not safe to use
82 <code>dlclose()</code> on a tracepoint provider shared object that
83 is being actively used for tracing, due to a lack of reference
84 counting from LTTng-UST to the shared object.
88 For example, statically linking a tracepoint provider to a
89 shared object which is to be dynamically loaded by an application
90 (a plugin, for example) is not safe: the shared object, which
91 contains the tracepoint provider, could be dynamically closed
92 (<code>dlclose()</code>) at any time by the application.
96 To instrument a shared object, either:
101 Statically link the tracepoint provider to the
102 <em>application</em>, or
105 Build the tracepoint provider as a shared object (following
106 the procedure shown in this section), and preload it when
107 tracing is needed using the <code>LD_PRELOAD</code>
108 environment variable.
113 Your application will still work without this preloading, albeit without
114 LTTng-UST tracing support: