\-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)
.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
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
+\& 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