# lttng-ust-dl

## NAME



           lttng-ust-dl - Dynamic linker tracing (LTTng-UST helper)
    


## SYNOPSIS



           Launch your application by preloading **liblttng-ust-dl.so** :
    
           $ **LD_PRELOAD=liblttng-ust-dl.so** my-app
    


## DESCRIPTION



           When the **liblttng-ust-dl.so** library is preloaded before a given
           application starts, it causes all calls to dlopen(3) and
           dlclose(3) in said application to be traced with LTTng-UST (see
           lttng-ust(3)).
    
           See lttng(1) to learn more about how to control LTTng tracing
           sessions.
    
               **Important**
    
               This LTTng-UST helper can also emit _shared library load/unload_
               events (see _Shared library load/unload tracking_ in
               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 dlopen(3) is called.
    
               Fields:
               ┌────────────────┬──────────────────────────┐
               │ **Field name** │ **Description** │
               ├────────────────┼──────────────────────────┤
               │ **baddr** │ Base address of loaded   │
               │                │ library.                 │
               ├────────────────┼──────────────────────────┤
               │ **memsz** │ Size of loaded library   │
               │                │ in memory.               │
               ├────────────────┼──────────────────────────┤
               │ **flags** │ Flags passed to          │
               │                │ dlopen(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:dlmopen**
               Emitted when dlmopen(3) is called.
    
               Fields:
               ┌────────────────┬──────────────────────────┐
               │ **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     │
               │                │ dlmopen(3)).             │
               ├────────────────┼──────────────────────────┤
               │ **flags** │ Flags passed to          │
               │                │ 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**
               Emitted when dlclose(3) is called.
    
               Fields:
               ┌────────────┬────────────────────────┐
               │ **Field name** │ **Description** │
               ├────────────┼────────────────────────┤
               │ **baddr** │ Base address of loaded │
               │            │ library.               │
               └────────────┴────────────────────────┘
    
           **lttng_ust_dl:debug_link**
               Emitted when debug link information is found when loading a
               library with dlopen(3). See Debugging Information in Separate
               Files <https://sourceware.org/gdb/onlinedocs/gdb/Separate-
               Debug-Files.html> for more information about debug links.
    
               Fields:
               ┌────────────┬────────────────────────┐
               │ **Field name** │ **Description** │
               ├────────────┼────────────────────────┤
               │ **baddr** │ Base address of loaded │
               │            │ library.               │
               ├────────────┼────────────────────────┤
               │ **filename** │ Debug link file name.  │
               ├────────────┼────────────────────────┤
               │ **crc** │ Debug link file’s CRC. │
               └────────────┴────────────────────────┘
    
           **lttng_ust_dl:build_id**
               Emitted when a build ID is found when loading a library with
               dlopen(3). See Debugging Information in Separate Files
               <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
               Files.html> for more information about build IDs.
    
               Fields:
               ┌────────────┬────────────────────────┐
               │ **Field name** │ **Description** │
               ├────────────┼────────────────────────┤
               │ **baddr** │ Base address of loaded │
               │            │ library.               │
               ├────────────┼────────────────────────┤
               │ **build_id** │ Build ID.              │
               └────────────┴────────────────────────┘
    


## BUGS



           If you encounter any issue or usability problem, please report it
           on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-
           ust>.
    


## RESOURCES



           •   LTTng project website <http://lttng.org>
    
           •   LTTng documentation <http://lttng.org/docs>
    
           •   Git repositories <http://git.lttng.org>
    
           •   GitHub organization <http://github.com/lttng>
    
           •   Continuous integration <http://ci.lttng.org/>
    
           •   Mailing list <http://lists.lttng.org> for support and
               development: **lttng-dev@lists.lttng.org**
    
           •   IRC channel <irc://irc.oftc.net/lttng>: **#lttng** on **irc.oftc.net**
    


## THANKS



           Thanks to Ericsson for funding this work, providing real-life use
           cases, and testing.
    
           Special thanks to Michel Dagenais and the DORSAL laboratory
           <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal
           for the LTTng journey.
    


* * *