1 // SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
2 // SPDX-License-Identifier: CC-BY-4.0
11 lttng-ust-dl - Dynamic linker tracing (LTTng-UST helper)
16 Launch your application by preloading `liblttng-ust-dl.so`:
20 $ *LD_PRELOAD=liblttng-ust-dl.so* my-app
25 When the `liblttng-ust-dl.so` library is preloaded before a given
26 application starts, it causes all calls to man:dlopen(3) and
27 man:dlclose(3) in said application to be traced with LTTng-UST (see
30 See man:lttng(1) to learn more about how to control LTTng tracing
33 IMPORTANT: This LTTng-UST helper can also emit _shared library
34 load/unload_ events (see _Shared library load/unload tracking_ in
35 man:lttng-ust(3)). You should :not: use the event records generated by
36 this LTTng-UST helper (prefixed with `lttng_ust_dl:`) to track the
37 loading and unloading of shared libraries, especially in situations
38 where a dynamically loaded library loads its own dependencies. Instead,
39 do preload `liblttng-ust-dl.so`, but use the shared library load/unload
40 event records, which are more reliable, for your tracking analysis.
42 The following LTTng-UST events are available when using this library.
45 `lttng_ust_dl:dlopen`::
46 Emitted when man:dlopen(3) is called.
52 |Field name |Description
55 |Base address of loaded library.
58 |Size of loaded library in memory.
61 |Flags passed to man:dlopen(3).
64 |Path to loaded library file.
67 |Whether or not the loaded library has a build ID. If this field is 1,
68 you can expect that an `lttng_ust_dl:build_id` event record
69 follows this one (not necessarily immediately after).
72 |Whether or not the loaded library has debug link information. If this
73 field is 1, you can expect that an `lttng_ust_dl:debug_link` event
74 record follows this one (not necessarily immediately after).
77 `lttng_ust_dl:dlmopen`::
78 Emitted when man:dlmopen(3) is called.
84 |Field name |Description
87 |Base address of loaded library.
90 |Size of loaded library in memory.
93 |ID of the namespace in which the library is loaded (as passed
97 |Flags passed to man:dlmopen(3).
100 |Path to loaded library file.
103 |Whether or not the loaded library has a build ID. If this field is 1,
104 you can expect that an `lttng_ust_dl:build_id` event record
105 follows this one (not necessarily immediately after).
108 |Whether or not the loaded library has debug link information. If this
109 field is 1, you can expect that an `lttng_ust_dl:debug_link` event
110 record follows this one (not necessarily immediately after).
113 `lttng_ust_dl:dlclose`::
114 Emitted when man:dlclose(3) is called.
120 |Field name |Description
123 |Base address of loaded library.
126 `lttng_ust_dl:debug_link`::
127 Emitted when debug link information is found when loading a library
128 with man:dlopen(3). See
129 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
130 for more information about debug links.
136 |Field name |Description
139 |Base address of loaded library.
142 |Debug link file name.
145 |Debug link file's CRC.
148 `lttng_ust_dl:build_id`::
149 Emitted when a build ID is found when loading a library
150 with man:dlopen(3). See
151 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
152 for more information about build IDs.
158 |Field name |Description
161 |Base address of loaded library.
168 include::common-footer.txt[]
170 include::common-copyrights.txt[]
172 include::common-authors.txt[]