added forgotten free(), forgotten return

[platform/upstream/ltrace.git] / ltrace.1

diff --git a/ltrace.1 b/ltrace.1
index 1d5ee63..e7facaf 100644 (file)
--- a/ltrace.1
+++ b/ltrace.1
@@ -1,5 +1,5 @@
 .\" -*-nroff-*-
 .\" -*-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
 .\" Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org>
 .\"
 .\" This program is free software; you can redistribute it and/or


@@ -39,7 +39,7 @@ ltrace \- A library call tracer
 .\"
 .\" Output formatting:
 .\"
 .\"
 .\" 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]
 [\-A \fImaxelts\fR] [\-s \fIstrsize\fR] [\-C|\-\-demangle]
 [\-a|\-\-align \fIcolumn\fR] [\-n|\-\-indent \fInr\fR]
 [\-o|\-\-output \fIfilename\fR]


@@ -118,21 +118,23 @@ 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
 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"
 .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
 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
 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


@@ -145,9 +147,12 @@ 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.
 .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
 
 Note that while this option selects calls that might be directed to
 the selected libraries, there's no actual guarantee that the call


@@ -156,7 +161,8 @@ 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
 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
 .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


@@ -195,16 +201,123 @@ 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
 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"
 .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.
 
 .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
 .SH FILTER EXPRESSIONS
 
 Filter expression is a chain of glob- or regexp-based rules that are