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

   1 lttng-ust-dl(3)
   2 ===============
   3 :object-type: library
   4
   5
   6 NAME
   7 ----
   8 lttng-ust-dl - Dynamic linker tracing (LTTng-UST helper)
   9
  10
  11 SYNOPSIS
  12 --------
  13 Launch your application by preloading `liblttng-ust-dl.so`:
  14
  15 [role="term"]
  16 [verse]
  17 $ *LD_PRELOAD=liblttng-ust-dl.so* my-app
  18
  19
  20 DESCRIPTION
  21 -----------
  22 When the `liblttng-ust-dl.so` library is preloaded before a given
  23 application starts, it causes all calls to man:dlopen(3) and
  24 man:dlclose(3) in said application to be traced with LTTng-UST (see
  25 man:lttng-ust(3)).
  26
  27 See man:lttng(1) to learn more about how to control LTTng tracing
  28 sessions.
  29
  30 IMPORTANT: This LTTng-UST helper can also emit _shared library
  31 load/unload_ events (see _Shared library load/unload tracking_ in
  32 man:lttng-ust(3)). You should :not: use the event records generated by
  33 this LTTng-UST helper (prefixed with `lttng_ust_dl:`) to track the
  34 loading and unloading of shared libraries, especially in situations
  35 where a dynamically loaded library loads its own dependencies. Instead,
  36 do preload `liblttng-ust-dl.so`, but use the shared library load/unload
  37 event records, which are more reliable, for your tracking analysis.
  38
  39 The following LTTng-UST events are available when using this library.
  40
  41
  42 `lttng_ust_dl:dlopen`::
  43     Emitted when man:dlopen(3) is called.
  44 +
  45 Fields:
  46 +
  47 [options="header"]
  48 |===
  49 |Field name |Description
  50
  51 |`baddr`
  52 |Base address of loaded library.
  53
  54 |`memsz`
  55 |Size of loaded library in memory.
  56
  57 |`flags`
  58 |Flags passed to man:dlopen(3).
  59
  60 |`path`
  61 |Path to loaded library file.
  62
  63 |`has_build_id`
  64 |Whether or not the loaded library has a build ID. If this field is 1,
  65 you can expect that an `lttng_ust_dl:build_id` event record
  66 follows this one (not necessarily immediately after).
  67
  68 |`has_debug_link`
  69 |Whether or not the loaded library has debug link information. If this
  70 field is 1, you can expect that an `lttng_ust_dl:debug_link` event
  71 record follows this one (not necessarily immediately after).
  72 |===
  73
  74 `lttng_ust_dl:dlmopen`::
  75     Emitted when man:dlmopen(3) is called.
  76 +
  77 Fields:
  78 +
  79 [options="header"]
  80 |===
  81 |Field name |Description
  82
  83 |`baddr`
  84 |Base address of loaded library.
  85
  86 |`memsz`
  87 |Size of loaded library in memory.
  88
  89 |`nsid`
  90 |ID of the namespace in which the library is loaded (as passed
  91 to man:dlmopen(3)).
  92
  93 |`flags`
  94 |Flags passed to man:dlmopen(3).
  95
  96 |`path`
  97 |Path to loaded library file.
  98
  99 |`has_build_id`
 100 |Whether or not the loaded library has a build ID. If this field is 1,
 101 you can expect that an `lttng_ust_dl:build_id` event record
 102 follows this one (not necessarily immediately after).
 103
 104 |`has_debug_link`
 105 |Whether or not the loaded library has debug link information. If this
 106 field is 1, you can expect that an `lttng_ust_dl:debug_link` event
 107 record follows this one (not necessarily immediately after).
 108 |===
 109
 110 `lttng_ust_dl:dlclose`::
 111     Emitted when man:dlclose(3) is called.
 112 +
 113 Fields:
 114 +
 115 [options="header"]
 116 |===
 117 |Field name |Description
 118
 119 |`baddr`
 120 |Base address of loaded library.
 121 |===
 122
 123 `lttng_ust_dl:debug_link`::
 124     Emitted when debug link information is found when loading a library
 125     with man:dlopen(3). See
 126     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
 127     for more information about debug links.
 128 +
 129 Fields:
 130 +
 131 [options="header"]
 132 |===
 133 |Field name |Description
 134
 135 |`baddr`
 136 |Base address of loaded library.
 137
 138 |`filename`
 139 |Debug link file name.
 140
 141 |`crc`
 142 |Debug link file's CRC.
 143 |===
 144
 145 `lttng_ust_dl:build_id`::
 146     Emitted when a build ID is found when loading a library
 147     with man:dlopen(3). See
 148     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
 149     for more information about build IDs.
 150 +
 151 Fields:
 152 +
 153 [options="header"]
 154 |===
 155 |Field name |Description
 156
 157 |`baddr`
 158 |Base address of loaded library.
 159
 160 |`build_id`
 161 |Build ID.
 162 |===
 163
 164
 165 include::common-footer.txt[]
 166
 167 include::common-copyrights.txt[]
 168
 169 include::common-authors.txt[]
 170
 171
 172 SEE ALSO
 173 --------
 174 man:lttng-ust(3),
 175 man:dlopen(3),
 176 man:lttng(1)