X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=ltrace.1;h=e7facafe24cda64fce7c8afa432dfa65478e036a;hb=0d0ef961855b7aefa4529c49d05e1785c968131f;hp=1d5ee6337f73f9b437a897a22fa6eba647250c47;hpb=3da1b63c19adf0300546d2ead50149dac6126323;p=platform%2Fupstream%2Fltrace.git diff --git a/ltrace.1 b/ltrace.1 index 1d5ee63..e7facaf 100644 --- a/ltrace.1 +++ b/ltrace.1 @@ -1,5 +1,5 @@ .\" -*-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 .\" .\" This program is free software; you can redistribute it and/or @@ -39,7 +39,7 @@ ltrace \- A library call tracer .\" .\" 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] @@ -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 -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 @@ -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. -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 @@ -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 -\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 @@ -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 -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() = +\& func_f_lib@tstlib.so( +\& func_g_lib@tstlib.so() = +\& <... func_f_lib resumed> ) = +\& +++ exited (status 163) +++ +.Ve + +.Vb 6 +\& \fB$ ltrace -e 'func*' ./tst\fR +\& tst->func_f_lib( +\& tstlib.so->func_g_lib() = +\& <... func_f_lib resumed> ) = +\& +++ exited (status 163) +++ +.Ve + +.Vb 6 +\& \fB$ ltrace -l tstlib.so ./tst\fR +\& tst->func_f_lib( +\& tstlib.so->func_g_lib() = +\& <... func_f_lib resumed> ) = +\& +++ 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() = +\& func_f_lib@tstlib.so( +\& func_g_lib@tstlib.so() = +\& <... func_f_lib resumed> ) = +\& +++ exited (status 163) +++ +.Ve + +.Vb 6 +\& \fB$ ltrace -e 'func*' ./tst\fR +\& tst->func_f_lib() = +\& +++ exited (status 163) +++ +.Ve + +.Vb 6 +\& \fB$ ltrace -l tstlib.so ./tst\fR +\& tst->func_f_lib() = +\& +++ exited (status 163) +++ +.Ve +.PP .SH FILTER EXPRESSIONS Filter expression is a chain of glob- or regexp-based rules that are