'\" t
.\"     Title: lttng-ust-dl
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/19/2024
.\"    Manual: LTTng Manual
.\"    Source: LTTng 2.13.8
.\"  Language: English
.\"
.TH "LTTNG\-UST\-DL" "3" "04/19/2024" "LTTng 2\&.13\&.8" "LTTng Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
lttng-ust-dl \- Dynamic linker tracing (LTTng\-UST helper)
.SH "SYNOPSIS"
.sp
Launch your application by preloading \fBliblttng-ust-dl.so\fR:
.sp
.nf
$ \fBLD_PRELOAD=liblttng\-ust\-dl\&.so\fR my\-app
.fi
.SH "DESCRIPTION"
.sp
When the \fBliblttng-ust-dl.so\fR library is preloaded before a given application starts, it causes all calls to \fBdlopen\fR(3) and \fBdlclose\fR(3) in said application to be traced with LTTng\-UST (see \fBlttng-ust\fR(3))\&.
.sp
See \fBlttng\fR(1) to learn more about how to control LTTng tracing sessions\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.sp
This LTTng\-UST helper can also emit \fIshared library load/unload\fR events (see \fIShared library load/unload tracking\fR in \fBlttng-ust\fR(3))\&. You should NOT use the event records generated by this LTTng\-UST helper (prefixed with \fBlttng_ust_dl:\fR) to track the loading and unloading of shared libraries, especially in situations where a dynamically loaded library loads its own dependencies\&. Instead, do preload \fBliblttng-ust-dl.so\fR, but use the shared library load/unload event records, which are more reliable, for your tracking analysis\&.
.sp .5v
.RE
.sp
The following LTTng\-UST events are available when using this library\&.
.PP
\fBlttng_ust_dl:dlopen\fR
.RS 4
Emitted when
\fBdlopen\fR(3)
is called\&.
.sp
Fields:
.TS
allbox tab(:);
ltB ltB.
T{
Field name
T}:T{
Description
T}
.T&
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt.
T{
\fBbaddr\fR
T}:T{
Base address of loaded library\&.
T}
T{
\fBmemsz\fR
T}:T{
Size of loaded library in memory\&.
T}
T{
\fBflags\fR
T}:T{
Flags passed to
\fBdlopen\fR(3)\&.
T}
T{
\fBpath\fR
T}:T{
Path to loaded library file\&.
T}
T{
\fBhas_build_id\fR
T}:T{
Whether or not the loaded library has a build ID\&. If this field is 1, you can expect that an
\fBlttng_ust_dl:build_id\fR
event record follows this one (not necessarily immediately after)\&.
T}
T{
\fBhas_debug_link\fR
T}:T{
Whether or not the loaded library has debug link information\&. If this field is 1, you can expect that an
\fBlttng_ust_dl:debug_link\fR
event record follows this one (not necessarily immediately after)\&.
T}
.TE
.sp 1
.RE
.PP
\fBlttng_ust_dl:dlmopen\fR
.RS 4
Emitted when
\fBdlmopen\fR(3)
is called\&.
.sp
Fields:
.TS
allbox tab(:);
ltB ltB.
T{
Field name
T}:T{
Description
T}
.T&
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt.
T{
\fBbaddr\fR
T}:T{
Base address of loaded library\&.
T}
T{
\fBmemsz\fR
T}:T{
Size of loaded library in memory\&.
T}
T{
\fBnsid\fR
T}:T{
ID of the namespace in which the library is loaded (as passed to
\fBdlmopen\fR(3))\&.
T}
T{
\fBflags\fR
T}:T{
Flags passed to
\fBdlmopen\fR(3)\&.
T}
T{
\fBpath\fR
T}:T{
Path to loaded library file\&.
T}
T{
\fBhas_build_id\fR
T}:T{
Whether or not the loaded library has a build ID\&. If this field is 1, you can expect that an
\fBlttng_ust_dl:build_id\fR
event record follows this one (not necessarily immediately after)\&.
T}
T{
\fBhas_debug_link\fR
T}:T{
Whether or not the loaded library has debug link information\&. If this field is 1, you can expect that an
\fBlttng_ust_dl:debug_link\fR
event record follows this one (not necessarily immediately after)\&.
T}
.TE
.sp 1
.RE
.PP
\fBlttng_ust_dl:dlclose\fR
.RS 4
Emitted when
\fBdlclose\fR(3)
is called\&.
.sp
Fields:
.TS
allbox tab(:);
ltB ltB.
T{
Field name
T}:T{
Description
T}
.T&
lt lt.
T{
\fBbaddr\fR
T}:T{
Base address of loaded library\&.
T}
.TE
.sp 1
.RE
.PP
\fBlttng_ust_dl:debug_link\fR
.RS 4
Emitted when debug link information is found when loading a library with
\fBdlopen\fR(3)\&. See
Debugging Information in Separate Files <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html>
for more information about debug links\&.
.sp
Fields:
.TS
allbox tab(:);
ltB ltB.
T{
Field name
T}:T{
Description
T}
.T&
lt lt
lt lt
lt lt.
T{
\fBbaddr\fR
T}:T{
Base address of loaded library\&.
T}
T{
\fBfilename\fR
T}:T{
Debug link file name\&.
T}
T{
\fBcrc\fR
T}:T{
Debug link file\(cqs CRC\&.
T}
.TE
.sp 1
.RE
.PP
\fBlttng_ust_dl:build_id\fR
.RS 4
Emitted when a build ID is found when loading a library with
\fBdlopen\fR(3)\&. See
Debugging Information in Separate Files <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html>
for more information about build IDs\&.
.sp
Fields:
.TS
allbox tab(:);
ltB ltB.
T{
Field name
T}:T{
Description
T}
.T&
lt lt
lt lt.
T{
\fBbaddr\fR
T}:T{
Base address of loaded library\&.
T}
T{
\fBbuild_id\fR
T}:T{
Build ID\&.
T}
.TE
.sp 1
.RE
.SH "BUGS"
.sp
If you encounter any issue or usability problem, please report it on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>\&.
.SH "RESOURCES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
LTTng project website <http://lttng.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
LTTng documentation <http://lttng.org/docs>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Git repositories <http://git.lttng.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GitHub organization <http://github.com/lttng>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Continuous integration <http://ci.lttng.org/>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Mailing list <http://lists.lttng.org>
for support and development:
\fBlttng-dev@lists.lttng.org\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
IRC channel <irc://irc.oftc.net/lttng>:
\fB#lttng\fR
on
\fBirc.oftc.net\fR
.RE
.SH "COPYRIGHTS"
.sp
This library is part of the LTTng\-UST project\&.
.sp
This library is distributed under the GNU Lesser General Public License, version 2\&.1 <http://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html>\&. See the for more details\&.
.SH "THANKS"
.sp
Thanks to Ericsson for funding this work, providing real\-life use cases, and testing\&.
.sp
Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> at \('Ecole Polytechnique de Montr\('eal for the LTTng journey\&.
.SH "AUTHORS"
.sp
LTTng\-UST was originally written by Mathieu Desnoyers, with additional contributions from various other people\&. It is currently maintained by Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>\&.
.SH "SEE ALSO"
.sp
\fBlttng-ust\fR(3), \fBdlopen\fR(3), \fBlttng\fR(1)