doc/man/lttng-ust-dl.3.txt

   1 // SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
   2 // SPDX-License-Identifier: CC-BY-4.0
   3 //
   4 lttng-ust-dl(3)
   5 ===============
   6 :object-type: library
   7
   8
   9 NAME
  10 ----
  11 lttng-ust-dl - Dynamic linker tracing (LTTng-UST helper)
  12
  13
  14 SYNOPSIS
  15 --------
  16 Launch your application by preloading `liblttng-ust-dl.so`:
  17
  18 [role="term"]
  19 [verse]
  20 $ *LD_PRELOAD=liblttng-ust-dl.so* my-app
  21
  22
  23 DESCRIPTION
  24 -----------
  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
  28 man:lttng-ust(3)).
  29
  30 See man:lttng(1) to learn more about how to control LTTng tracing
  31 sessions.
  32
  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.
  41
  42 The following LTTng-UST events are available when using this library.
  43
  44
  45 `lttng_ust_dl:dlopen`::
  46     Emitted when man:dlopen(3) is called.
  47 +
  48 Fields:
  49 +
  50 [options="header"]
  51 |===
  52 |Field name |Description
  53
  54 |`baddr`
  55 |Base address of loaded library.
  56
  57 |`memsz`
  58 |Size of loaded library in memory.
  59
  60 |`flags`
  61 |Flags passed to man:dlopen(3).
  62
  63 |`path`
  64 |Path to loaded library file.
  65
  66 |`has_build_id`
  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).
  70
  71 |`has_debug_link`
  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).
  75 |===
  76
  77 `lttng_ust_dl:dlmopen`::
  78     Emitted when man:dlmopen(3) is called.
  79 +
  80 Fields:
  81 +
  82 [options="header"]
  83 |===
  84 |Field name |Description
  85
  86 |`baddr`
  87 |Base address of loaded library.
  88
  89 |`memsz`
  90 |Size of loaded library in memory.
  91
  92 |`nsid`
  93 |ID of the namespace in which the library is loaded (as passed
  94 to man:dlmopen(3)).
  95
  96 |`flags`
  97 |Flags passed to man:dlmopen(3).
  98
  99 |`path`
 100 |Path to loaded library file.
 101
 102 |`has_build_id`
 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).
 106
 107 |`has_debug_link`
 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).
 111 |===
 112
 113 `lttng_ust_dl:dlclose`::
 114     Emitted when man:dlclose(3) is called.
 115 +
 116 Fields:
 117 +
 118 [options="header"]
 119 |===
 120 |Field name |Description
 121
 122 |`baddr`
 123 |Base address of loaded library.
 124 |===
 125
 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.
 131 +
 132 Fields:
 133 +
 134 [options="header"]
 135 |===
 136 |Field name |Description
 137
 138 |`baddr`
 139 |Base address of loaded library.
 140
 141 |`filename`
 142 |Debug link file name.
 143
 144 |`crc`
 145 |Debug link file's CRC.
 146 |===
 147
 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.
 153 +
 154 Fields:
 155 +
 156 [options="header"]
 157 |===
 158 |Field name |Description
 159
 160 |`baddr`
 161 |Base address of loaded library.
 162
 163 |`build_id`
 164 |Build ID.
 165 |===
 166
 167
 168 include::common-footer.txt[]
 169
 170 include::common-copyrights.txt[]
 171
 172 include::common-authors.txt[]
 173
 174
 175 SEE ALSO
 176 --------
 177 man:lttng-ust(3),
 178 man:dlopen(3),
 179 man:lttng(1)