347 lines
14 KiB
Groff
347 lines
14 KiB
Groff
.\" -*-nroff-*-
|
|
.\" Copyright (c) 2012, 2013, 2014 Petr Machata, Red Hat Inc.
|
|
.\" Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org>
|
|
.\"
|
|
.\" This program is free software; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
.\" published by the Free Software Foundation; either version 2 of the
|
|
.\" License, or (at your option) any later version.
|
|
.\"
|
|
.\" This program is distributed in the hope that it will be useful, but
|
|
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
.\" General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public License
|
|
.\" along with this program; if not, write to the Free Software
|
|
.\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
|
|
.\" 02110-1301 USA
|
|
.\"
|
|
.TH LTRACE "1" "January 2013" "" "User Commands"
|
|
.SH NAME
|
|
ltrace \- A library call tracer
|
|
|
|
.SH SYNOPSIS
|
|
.\"
|
|
.\" ---------------------------------------------------------------------------
|
|
.\"
|
|
.PP
|
|
.B ltrace
|
|
.\"
|
|
.\" What events to trace:
|
|
.\"
|
|
[\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR]
|
|
[\-x \fIfilter\fR] [\-S] [\-b|\-\-no-signals]
|
|
.\"
|
|
.\" What to display with each event:
|
|
.\"
|
|
[\-i] [\-w|\-\-where=\fInr\fR] [\-r|\-t|\-tt|\-ttt] [\-T]
|
|
.\"
|
|
.\" Output formatting:
|
|
.\"
|
|
[[\-F|\-\-config] \fIpathlist\fR]
|
|
[\-A \fImaxelts\fR] [\-s \fIstrsize\fR] [\-C|\-\-demangle]
|
|
[\-a|\-\-align \fIcolumn\fR] [\-n|\-\-indent \fInr\fR]
|
|
[\-o|\-\-output \fIfilename\fR]
|
|
.\"
|
|
.\" Various:
|
|
.\"
|
|
[\-D|\-\-debug \fImask\fR] [\-u \fIusername\fR]
|
|
.\"
|
|
.\" What processes to trace:
|
|
.\"
|
|
[\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR]
|
|
.\"
|
|
.\" ---------------------------------------------------------------------------
|
|
.\"
|
|
.PP
|
|
.BR ltrace " \-c"
|
|
.\"
|
|
.\" What events to trace:
|
|
.\"
|
|
[\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR]
|
|
[\-x \fIfilter\fR] [\-S]
|
|
.\"
|
|
.\" Output formatting:
|
|
.\"
|
|
[\-o|\-\-output \fIfilename\fR]
|
|
.\"
|
|
.\" What processes to trace:
|
|
.\"
|
|
[\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR]
|
|
.\"
|
|
.\" ---------------------------------------------------------------------------
|
|
.\"
|
|
.PP
|
|
.BR ltrace " \-V|\-\-version"
|
|
.PP
|
|
.BR ltrace " \-h|\-\-help"
|
|
|
|
.SH DESCRIPTION
|
|
.B ltrace
|
|
is a program that simply runs the specified
|
|
.I command
|
|
until it exits. It intercepts and records the dynamic library calls
|
|
which are called by the executed process and the signals which are
|
|
received by that process.
|
|
It can also intercept and print the system calls executed by the program.
|
|
.PP
|
|
Its use is very similar to
|
|
.BR strace(1) .
|
|
|
|
.B ltrace
|
|
shows parameters of invoked functions and system calls. To determine
|
|
what arguments each function has, it needs external declaration of
|
|
function prototypes. Those are stored in files called \fIprototype
|
|
libraries\fR--see ltrace.conf(5) for details on the syntax of these
|
|
files. See the section \fBPROTOTYPE LIBRARY DISCOVERY\fR to learn how
|
|
\fBltrace\fR finds prototype libraries.
|
|
|
|
.SH OPTIONS
|
|
.PP
|
|
.IP "\-a, \-\-align \fIcolumn"
|
|
Align return values in a specific
|
|
.IR column
|
|
(default column is 5/8 of screen width).
|
|
.IP "\-A \fImaxelts"
|
|
Maximum number of array elements to print before suppressing the rest
|
|
with an ellipsis ("..."). This also limits number of recursive
|
|
structure expansions.
|
|
.IP "\-b, \-\-no-signals"
|
|
Disable printing of signals received by the traced process.
|
|
.IP \-c
|
|
Count time and calls for each library call and report a summary on
|
|
program exit.
|
|
.IP "\-C, \-\-demangle"
|
|
Decode (demangle) low-level symbol names into user-level names.
|
|
Besides removing any initial underscore prefix used by the system,
|
|
this makes C++ function names readable.
|
|
.IP "\-D, \-\-debug \fRmask\fI"
|
|
Show debugging output of \fBltrace\fR itself. \fImask\fR is a number
|
|
describing which debug messages should be displayed. Use the option
|
|
\-Dh to see what can be used, but note that currently the only
|
|
reliable debugmask is 77, which shows all debug messages.
|
|
.IP "\-e \fIfilter"
|
|
A qualifying expression which modifies which library calls to trace.
|
|
The format of the filter expression is described in the section
|
|
\fBFILTER EXPRESSIONS\fR. If more than one \-e option appears on the
|
|
command line, the library calls that match any of them are traced. If
|
|
no \-e is given, \fB@MAIN\fR is assumed as a default.
|
|
.IP \-f
|
|
Trace child processes as they are created by
|
|
currently traced processes as a result of the fork(2)
|
|
or clone(2) system calls.
|
|
The new process is attached immediately.
|
|
.IP "\-F, \-\-config \fIpathlist"
|
|
Contains a colon-separated list of paths. If a path refers to a
|
|
directory, that directory is considered when prototype libraries are
|
|
searched (see the section \fBPROTOTYPE LIBRARY DISCOVERY\fR). If it refers to
|
|
a file, that file is imported implicitly to all loaded prototype
|
|
libraries.
|
|
.IP "\-h, \-\-help"
|
|
Show a summary of the options to ltrace and exit.
|
|
.IP \-i
|
|
Print the instruction pointer at the time of the library call.
|
|
.IP "\-l, \-\-library \fIlibrary_pattern"
|
|
Display only calls to functions implemented by libraries that match
|
|
.I library_pattern.
|
|
Multiple library patters can be specified with several instances of
|
|
this option. Syntax of library_pattern is described in section
|
|
\fBFILTER EXPRESSIONS\fR.
|
|
|
|
Note that while this option selects calls that might be directed to
|
|
the selected libraries, there's no actual guarantee that the call
|
|
won't be directed elsewhere due to e.g. LD_PRELOAD or simply
|
|
dependency ordering. If you want to make sure that symbols in given
|
|
library are actually called, use \fB-x @\fIlibrary_pattern\fR instead.
|
|
.IP \-L
|
|
When no \-e option is given, don't assume the default action of
|
|
\fB@MAIN\fR. In practice this means that library calls will not be
|
|
traced.
|
|
.IP "\-n, \-\-indent \fInr"
|
|
Indent trace output by \fInr\fR spaces for each level of call
|
|
nesting. Using this option makes the program flow visualization easy
|
|
to follow. This indents uselessly also functions that never return,
|
|
such as service functions for throwing exceptions in the C++ runtime.
|
|
.IP "\-o, \-\-output \fIfilename"
|
|
Write the trace output to the file \fIfilename\fR rather than to
|
|
stderr.
|
|
.IP "\-p \fIpid"
|
|
Attach to the process with the process ID \fIpid\fR and begin tracing.
|
|
This option can be used together with passing a command to execute.
|
|
It is possible to attach to several processes by passing more than one
|
|
option \-p.
|
|
.IP \-r
|
|
Print a relative timestamp with each line of the trace. This records
|
|
the time difference between the beginning of successive lines.
|
|
.IP "\-s \fIstrsize"
|
|
Specify the maximum string size to print (the default is 32).
|
|
.IP \-S
|
|
Display system calls as well as library calls
|
|
.IP \-t
|
|
Prefix each line of the trace with the time of day.
|
|
.IP \-tt
|
|
If given twice, the time printed will include the microseconds.
|
|
.IP \-ttt
|
|
If given thrice, the time printed will include the microseconds and
|
|
the leading portion will be printed as the number of seconds since the
|
|
epoch.
|
|
.IP \-T
|
|
Show the time spent inside each call. This records the time difference
|
|
between the beginning and the end of each call.
|
|
.IP "\-u \fIusername"
|
|
Run command with the userid, groupid and supplementary groups of
|
|
.IR username .
|
|
This option is only useful when running as root and enables the
|
|
correct execution of setuid and/or setgid binaries.
|
|
.IP "\-w, \-\-where \fInr"
|
|
Show backtrace of \fInr\fR stack frames for each traced function. This
|
|
option enabled only if elfutils or libunwind support was enabled at compile
|
|
time.
|
|
.IP "\-x \fIfilter"
|
|
A qualifying expression which modifies which symbol table entry points
|
|
to trace. The format of the filter expression is described in the
|
|
section \fBFILTER EXPRESSIONS\fR. If more than one \-x option appears
|
|
on the command line, the symbols that match any of them are traced.
|
|
No entry points are traced if no \-x is given.
|
|
.IP "\-V, \-\-version"
|
|
Show the version number of ltrace and exit.
|
|
|
|
.SH FILTER EXPRESSIONS
|
|
|
|
Filter expression is a chain of glob- or regexp-based rules that are
|
|
used to pick symbols for tracing from libraries that the process uses.
|
|
Most of it is intuitive, so as an example, the following would trace
|
|
calls to malloc and free, except those done by libc:
|
|
|
|
-e malloc+free-@libc.so*
|
|
|
|
This reads: trace malloc and free, but don't trace anything that comes
|
|
from libc. Semi-formally, the syntax of the above example looks
|
|
approximately like this:
|
|
|
|
{[+-][\fIsymbol_pattern\fR][@\fIlibrary_pattern\fR]}
|
|
|
|
\fISymbol_pattern\fR is used to match symbol names,
|
|
\fIlibrary_pattern\fR to match library SONAMEs. Both are implicitly
|
|
globs, but can be regular expressions as well (see below). The glob
|
|
syntax supports meta-characters \fB*\fR and \fB?\fR and character
|
|
classes, similarly to what basic bash globs support. \fB^\fR and
|
|
\fB$\fR are recognized to mean, respectively, start and end of given
|
|
name.
|
|
|
|
Both \fIsymbol_pattern\fR and \fIlibrary_pattern\fR have to match the
|
|
whole name. If you want to match only part of the name, surround it
|
|
with one or two *'s as appropriate. The exception is if the pattern
|
|
is not mentioned at all, in which case it's as if the corresponding
|
|
pattern were \fB*\fR. (So \fBmalloc\fR is really \fBmalloc@*\fR and
|
|
\fB@libc.*\fR is really \fB*@libc.*\fR.)
|
|
|
|
In libraries that don't have an explicit SONAME, basename is taken for
|
|
SONAME. That holds for main binary as well: \fB/bin/echo\fR has an
|
|
implicit SONAME of \fBecho\fR. In addition to that, special library
|
|
pattern \fBMAIN\fR always matches symbols in the main binary and never
|
|
a library with actual SONAME \fBMAIN\fR (use e.g. \fB^MAIN\fR or
|
|
\fB[M]AIN\fR for that).
|
|
|
|
If the symbol or library pattern is surrounded in slashes (/like
|
|
this/), then it is considered a regular expression instead. As a
|
|
shorthand, instead of writing \fB/x/@/y/\fR, you can write
|
|
\fB/x@y/\fR.
|
|
|
|
If the library pattern starts with a slash, it is not a SONAME
|
|
expression, but a path expression, and is matched against the library
|
|
path name.
|
|
|
|
The first rule may lack a sign, in which case \fB+\fR is assumed. If,
|
|
on the other hand, the first rule has a \fB-\fR sign, it is as if
|
|
there was another rule \fB@\fR in front of it, which has the effect of
|
|
tracing complement of given rule.
|
|
|
|
The above rules are used to construct the set of traced symbols. Each
|
|
candidate symbol is passed through the chain of above rules.
|
|
Initially, the symbol is \fIunmarked\fR. If it matches a \fB+\fR
|
|
rule, it becomes \fImarked\fR, if it matches a \fB-\fR rule, it
|
|
becomes \fIunmarked\fR again. If, after applying all rules, the
|
|
symbol is \fImarked\fR, it will be traced.
|
|
|
|
.SH PROTOTYPE LIBRARY DISCOVERY
|
|
|
|
When a library is mapped into the address space of a traced process,
|
|
ltrace needs to know what the prototypes are of functions that this
|
|
library implements. For purposes of ltrace, prototype really is a bit
|
|
more than just type signature: it's also formatting of individual
|
|
parameters and of return value. These prototypes are stored in files
|
|
called prototype libraries.
|
|
|
|
After a library is mapped, ltrace finds out what its SONAME is. It
|
|
then looks for a file named SONAME.conf--e.g. protolib for libc.so.6
|
|
would be in a file called libc.so.6.conf. When such file is found
|
|
(more about where ltrace looks for these files is below), ltrace reads
|
|
all prototypes stored therein. When a symbol table entry point (such
|
|
as those traced by \-x) is hit, the prototype is looked up in a
|
|
prototype library corresponding to the library where the hit occurred.
|
|
When a library call (such as those traced by \-e and \-l) is hit, the
|
|
prototype is looked up in all prototype libraries loaded for given
|
|
process. That is necessary, because a library call is traced in a PLT
|
|
table of a caller library, but the prototype is described at callee
|
|
library.
|
|
|
|
If a library has no SONAME, basename of library file is considered
|
|
instead. For the main program binary, basename is considered as well
|
|
(e.g. protolib for /bin/echo would be called echo.conf). If a name
|
|
corresponding to soname (e.g. libc.so.6.conf) is not found, and the
|
|
module under consideration is a shared library, ltrace also tries
|
|
partial matches. Ltrace snips one period after another, retrying the
|
|
search, until either a protolib is found, or X.so is all that's left.
|
|
Thus libc.so.conf would be considered, but libc.conf not.
|
|
|
|
When looking for a prototype library, ltrace potentially looks into
|
|
several directories. On Linux, those are $XDG_CONFIG_HOME/ltrace,
|
|
$HOME/.ltrace, \fIX\fR/ltrace for each \fIX\fR in $XDG_CONFIG_DIRS and
|
|
/usr/share/ltrace. If the environment variable XDG_CONFIG_HOME is not
|
|
defined, ltrace looks into $HOME/.config/ltrace instead.
|
|
|
|
There's also a mechanism for loading legacy config files. If
|
|
$HOME/.ltrace.conf exists it is imported to every loaded prototype
|
|
library. Similarly for /etc/ltrace.conf. If both exist, both are
|
|
imported, and $HOME/.ltrace.conf is consulted before /etc/ltrace.conf.
|
|
|
|
If \-F contains any directories, those are searched in precedence to
|
|
the above system directories, in the same order in which they are
|
|
mentioned in \-F. Any files passed in \-F are imported similarly to
|
|
above legacy config files, before them.
|
|
|
|
See ltrace.conf(5) for details on the syntax of ltrace prototype
|
|
library files.
|
|
|
|
.SH BUGS
|
|
It has most of the bugs stated in
|
|
.BR strace(1) .
|
|
.LP
|
|
It only works on Linux and in some architectures.
|
|
.LP
|
|
.PP
|
|
If you would like to report a bug, send a message to the mailing list
|
|
(ltrace-devel@lists.alioth.debian.org), or use the
|
|
.BR reportbug(1)
|
|
program if you are under the Debian GNU/Linux distribution.
|
|
|
|
.SH FILES
|
|
.TP
|
|
.I /etc/ltrace.conf
|
|
System configuration file
|
|
.TP
|
|
.I ~/.ltrace.conf
|
|
Personal config file, overrides
|
|
.I /etc/ltrace.conf
|
|
|
|
.SH AUTHOR
|
|
Juan Cespedes <cespedes@debian.org>
|
|
.br
|
|
Petr Machata <pmachata@redhat.com>
|
|
|
|
.SH "SEE ALSO"
|
|
.BR ltrace.conf(5),
|
|
.BR strace(1) ,
|
|
.BR ptrace(2)
|