.\" -*-nroff-*-
-.\" Copyright (c) 2012, 2013 Petr Machata, Red Hat Inc.
+.\" 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
.\"
.\" Output formatting:
.\"
-[\-F \fIpathlist\fR]
+[[\-F|\-\-config] \fIpathlist\fR]
[\-A \fImaxelts\fR] [\-s \fIstrsize\fR] [\-C|\-\-demangle]
[\-a|\-\-align \fIcolumn\fR] [\-n|\-\-indent \fInr\fR]
[\-o|\-\-output \fIfilename\fR]
this makes C++ function names readable.
.IP "\-D, \-\-debug \fRmask\fI"
Show debugging output of \fBltrace\fR itself. \fImask\fR is a number
-with internal meaning that's not really well defined at all.
-\fImask\fR of 77 shows all debug messages, which is what you usually
-need.
+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.
+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.
-.IP "\-F \fIpathlist"
+.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
.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.
+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
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.
+\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
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 libunwind support was enabled at compile time.
+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.
+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
+\& #pragma once
+\& 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
projects / platform / upstream / ltrace.git / blobdiff