+.\" -*-nroff-*-
+.\" Copyright (c) 2012, 2013, 2014 Petr Machata, Red Hat Inc.
.\" Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org>
-.\" This file is covered by the GNU GPL
-.TH ltrace 1
+.\"
+.\" 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
-.I "[-CfhiLrStttV] [-a column] [-A maxelts] [-D level] [-e expr] [-l filename] [-n nr] [-o filename] [-p pid] ... [-s strsize] [-u username] [-X extern] [-x extern] ... [--align=column] [--debug=level] [--demangle] [--help] [--indent=nr] [--library=filename] [--output=filename] [--version] [command [arg ...]]"
+.\"
+.\" 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
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
-.TP
-.I \-a, \-\-align column
-Align return values in a specific column (default column is 5/8 of screen width).
-.TP
-.I \-A maxelts
-Maximum number of array elements to print before suppressing the rest with an ellipsis ("...")
-.TP
-.I \-c
-Count time and calls for each library call and report a summary on program exit.
-.TP
-.I \-C, \-\-demangle
+.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.
-.TP
-.I \-D, \-\-debug level
-Show debugging output of
-.B ltrace
-itself.
-.I level
-must be a sum of some of the following numbers:
-.RS
-.TP
-.B 01
-DEBUG_GENERAL. Shows helpful progress information
-.TP
-.B 010
-DEBUG_EVENT. Shows every event received by a traced program
-.TP
-.B 020
-DEBUG_PROCESS. Shows every action
-.B ltrace
-carries upon a traced process
-.TP
-.B 040
-DEBUG_FUNCTION. Shows every entry to internal functions
-.RE
-.TP
-.I \-e expr
-A qualifying expression which modifies which events to trace.
-The format of the expression is:
-.br
-[!]value1[,value2]...
-.br
-where the values are the functions to trace. Using an exclamation
-mark negates the set of values. For example
-.I \-e printf
-means to trace only the printf library call. By contrast,
-.I \-e !printf
-means to trace every library call except printf.
-.IP
-Note that some shells use the exclamation point for history
-expansion; even inside quoted arguments. If so, you must escape
-the exclamation point with a backslash.
-.TP
-.I \-f
+.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 (i.e. calls done
+through PLT slots, which are typically calls from the main binary to a library,
+or inter-library calls) to trace. Usage examples and the syntax description
+appear below in sections \fBFILTER SPECIFICATIONS\fR and \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.
-.TP
-.I \-F
-Load an alternate config file. Normally, /etc/ltrace.conf and
-~/.ltrace.conf will be read (the latter only if it exists).
-Use this option to load the given file or files instead of
-those two default files.
-.TP
-.I \-h, \-\-help
+.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.
-.TP
-.I \-i
+.IP \-i
Print the instruction pointer at the time of the library call.
-.TP
-.I \-l, \-\-library filename
-Display only the symbols included in the library
-.I filename.
-Up to 30 library names can be specified with several instances
-of this option.
-.TP
-.I \-L
-DON'T display library calls (use it with the
-.I \-S
-option).
-.TP
-.I \-n, \-\-indent nr
-Indent trace output by
-.I nr
-number of spaces for each new nested call. Using this option makes
-the program flow visualization easy to follow.
-.TP
-.I \-o, \-\-output filename
-Write the trace output to the file
-.I filename
-rather than to stderr.
-.TP
-.I \-p pid
-Attach to the process with the process ID
-.I pid
-and begin tracing.
-.TP
-.I \-r
-Print a relative timestamp with each line of the trace.
-This records the time difference between the beginning of
-successive lines.
-.TP
-.I \-s strsize
+.IP "\-l, \-\-library \fIlibrary_pattern"
+Display only calls to functions implemented by libraries that match
+.I library_pattern.
+This is as if you specified one \-e for every symbol implemented in a
+library specified by
+.I library_pattern.
+Multiple library patters can be specified with several instances of this option.
+Usage examples and the syntax description of library_pattern appear below in
+sections \fBFILTER SPECIFICATIONS\fR and \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).
-.TP
-.I \-S
+.IP \-S
Display system calls as well as library calls
-.TP
-.I \-t
+.IP \-t
Prefix each line of the trace with the time of day.
-.TP
-.I \-tt
+.IP \-tt
If given twice, the time printed will include the microseconds.
-.TP
-.I \-ttt
+.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.
-.TP
-.I \-T
+.IP \-T
Show the time spent inside each call. This records the time difference
between the beginning and the end of each call.
-.TP
-.I \-u username
+.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.
-.TP
-.I \-X extern
-Some architectures need to know where to set a breakpoint that will be hit
-after the dynamic linker has run. If this flag is used, then the breakpoint
-is set at
-.IR extern ,
-which must be an external function. By default, '_start' is used.
-NOTE: this flag is only available on the architectures that need it.
-.TP
-.I \-x extern
-Trace the external function
-.IR extern .
-This option may be repeated.
-.TP
-.I \-V, \-\-version
+.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
+(those are typically calls inside a library or main binary, though PLT calls,
+traced by \-e, land on entry points as well). Usage examples and the syntax
+description appear below in sections \fBFILTER SPECIFICATIONS\fR and \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 SPECIFICATIONS
+
+Filters are specified with the \-l, \-e and \-x options. In short they mean:
+.IP "\fI\-x\fR is \'show me what calls these symbols (including local calls)\'"
+.IP "\fI\-e\fR is \'show me what calls these symbols (inter-library calls only)\'"
+.IP "\fI\-l\fR is \'show me what calls into this library\'"
+.PP
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+Suppose I have a library defined with this header \fBtstlib.h\fR:
+.PP
+.Vb 6
+\& void func_f_lib(void);
+\& void func_g_lib(void);
+.Ve
+.PP
+and this implementation \fBtstlib.c\fR:
+.PP
+.Vb 6
+\& #include "tstlib.h"
+\& void func_f_lib(void)
+\& {
+\& func_g_lib();
+\& }
+\& void func_g_lib(void)
+\& {
+\& }
+.Ve
+.PP
+Suppose I have an executable that uses this library defined like this \fBtst.c\fR:
+.PP
+.Vb 6
+\& #include "tstlib.h"
+\& void func_f_main(void)
+\& {
+\& }
+\& void main(void)
+\& {
+\& func_f_main();
+\& func_f_lib();
+\& }
+.Ve
+.PP
+If linking without \fB-Bsymbolic\fR, the internal \fBfunc_g_lib()\fR call uses
+the PLT like external calls, and thus ltrace says:
+.PP
+.Vb 6
+\& \fB$ ltrace -x 'func*' -L ./tst\fR
+\& func_f_main() = <void>
+\& func_f_lib@tstlib.so( <unfinished ...>
+\& func_g_lib@tstlib.so() = <void>
+\& <... func_f_lib resumed> ) = <void>
+\& +++ exited (status 163) +++
+.Ve
+
+.Vb 6
+\& \fB$ ltrace -e 'func*' ./tst\fR
+\& tst->func_f_lib( <unfinished ...>
+\& tstlib.so->func_g_lib() = <void>
+\& <... func_f_lib resumed> ) = <void>
+\& +++ exited (status 163) +++
+.Ve
+
+.Vb 6
+\& \fB$ ltrace -l tstlib.so ./tst\fR
+\& tst->func_f_lib( <unfinished ...>
+\& tstlib.so->func_g_lib() = <void>
+\& <... func_f_lib resumed> ) = <void>
+\& +++ exited (status 163) +++
+.Ve
+.PP
+By contrast, if linking with \fB-Bsymbolic\fR, then the internal
+\fBfunc_g_lib()\fR call bypasses the PLT, and ltrace says:
+.PP
+.Vb 6
+\& \fB$ ltrace -x 'func*' -L ./tst\fR
+\& func_f_main() = <void>
+\& func_f_lib@tstlib.so( <unfinished ...>
+\& func_g_lib@tstlib.so() = <void>
+\& <... func_f_lib resumed> ) = <void>
+\& +++ exited (status 163) +++
+.Ve
+
+.Vb 6
+\& \fB$ ltrace -e 'func*' ./tst\fR
+\& tst->func_f_lib() = <void>
+\& +++ exited (status 163) +++
+.Ve
+
+.Vb 6
+\& \fB$ ltrace -l tstlib.so ./tst\fR
+\& tst->func_f_lib() = <void>
+\& +++ exited (status 163) +++
+.Ve
+.PP
+.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
-Manual page and documentation are not very up-to-date.
+It only works on Linux and in some architectures.
.LP
-Option -f sometimes fails to trace some children.
-.LP
-It only works on Linux and in a small subset of architectures.
-.LP
-Only ELF32 binaries are supported.
-.LP
-Calls to dlopen()ed libraries will not be traced.
.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
.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)
-
projects / platform / upstream / ltrace.git / blobdiff