doc: implement REUSE with SPDX identifiers

[lttng-ust.git] / doc / man / lttng-ust-dl.3.txt

diff --git a/doc/man/lttng-ust-dl.3.txt b/doc/man/lttng-ust-dl.3.txt
index 095eb99dec06621903526bcb874b4f4787f5288f..c5971b92c78f4eeac7c8e7ad3a37cc28598edc1a 100644 (file)
--- a/doc/man/lttng-ust-dl.3.txt
+++ b/doc/man/lttng-ust-dl.3.txt
@@ -1,3 +1,6 @@
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
 lttng-ust-dl(3)
 ===============
 :object-type: library
@@ -14,7 +17,7 @@ Launch your application by preloading `liblttng-ust-dl.so`:
 
 [role="term"]
 [verse]
-*LD_PRELOAD=liblttng-ust-dl.so* my-app
+$ *LD_PRELOAD=liblttng-ust-dl.so* my-app
 
 
 DESCRIPTION
@@ -27,7 +30,17 @@ man:lttng-ust(3)).
 See man:lttng(1) to learn more about how to control LTTng tracing
 sessions.
 
-The following LTTng-UST events are available when using this library:
+IMPORTANT: This LTTng-UST helper can also emit _shared library
+load/unload_ events (see _Shared library load/unload tracking_ in
+man:lttng-ust(3)). You should :not: use the event records generated by
+this LTTng-UST helper (prefixed with `lttng_ust_dl:`) to track the
+loading and unloading of shared libraries, especially in situations
+where a dynamically loaded library loads its own dependencies. Instead,
+do preload `liblttng-ust-dl.so`, but use the shared library load/unload
+event records, which are more reliable, for your tracking analysis.
+
+The following LTTng-UST events are available when using this library.
+
 
 `lttng_ust_dl:dlopen`::
     Emitted when man:dlopen(3) is called.
@@ -39,13 +52,62 @@ Fields:
 |Field name |Description
 
 |`baddr`
-|Base address of loaded library
+|Base address of loaded library.
 
 |`memsz`
-|Size of loaded library in memory
+|Size of loaded library in memory.
+
+|`flags`
+|Flags passed to man:dlopen(3).
 
 |`path`
-|Path to loaded library file
+|Path to loaded library file.
+
+|`has_build_id`
+|Whether or not the loaded library has a build ID. If this field is 1,
+you can expect that an `lttng_ust_dl:build_id` event record
+follows this one (not necessarily immediately after).
+
+|`has_debug_link`
+|Whether or not the loaded library has debug link information. If this
+field is 1, you can expect that an `lttng_ust_dl:debug_link` event
+record follows this one (not necessarily immediately after).
+|===
+
+`lttng_ust_dl:dlmopen`::
+    Emitted when man:dlmopen(3) is called.
++
+Fields:
++
+[options="header"]
+|===
+|Field name |Description
+
+|`baddr`
+|Base address of loaded library.
+
+|`memsz`
+|Size of loaded library in memory.
+
+|`nsid`
+|ID of the namespace in which the library is loaded (as passed
+to man:dlmopen(3)).
+
+|`flags`
+|Flags passed to man:dlmopen(3).
+
+|`path`
+|Path to loaded library file.
+
+|`has_build_id`
+|Whether or not the loaded library has a build ID. If this field is 1,
+you can expect that an `lttng_ust_dl:build_id` event record
+follows this one (not necessarily immediately after).
+
+|`has_debug_link`
+|Whether or not the loaded library has debug link information. If this
+field is 1, you can expect that an `lttng_ust_dl:debug_link` event
+record follows this one (not necessarily immediately after).
 |===
 
 `lttng_ust_dl:dlclose`::
@@ -58,7 +120,7 @@ Fields:
 |Field name |Description
 
 |`baddr`
-|Base address of loaded library
+|Base address of loaded library.
 |===
 
 `lttng_ust_dl:debug_link`::
@@ -74,13 +136,13 @@ Fields:
 |Field name |Description
 
 |`baddr`
-|Base address of loaded library
+|Base address of loaded library.
 
 |`filename`
-|Debug link file name
+|Debug link file name.
 
 |`crc`
-|Debug link file's CRC
+|Debug link file's CRC.
 |===
 
 `lttng_ust_dl:build_id`::
@@ -96,10 +158,10 @@ Fields:
 |Field name |Description
 
 |`baddr`
-|Base address of loaded library
+|Base address of loaded library.
 
 |`build_id`
-|Build ID
+|Build ID.
 |===