X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=ltrace.1;h=93032f205d3aa196a09605269873a9372ee3bb0d;hb=2b1c30351b63c4cdbd6baefa56d463fc32eb0f74;hp=aeaea76135fc01f190f0f0e7f2c6a2cee4cc079e;hpb=517f5529d7008eba87b8b2fee5ec9ec0a5075f6e;p=platform%2Fupstream%2Fltrace.git diff --git a/ltrace.1 b/ltrace.1 index aeaea76..93032f2 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] @@ -55,7 +55,7 @@ ltrace \- A library call tracer .\" --------------------------------------------------------------------------- .\" .PP -.BR ltrace " -c" +.BR ltrace " \-c" .\" .\" What events to trace: .\" @@ -108,7 +108,7 @@ 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 recieved by the traced process. +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. @@ -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. 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. .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,6 +147,9 @@ 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. +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. Syntax of library_pattern is described in section \fBFILTER EXPRESSIONS\fR. @@ -155,8 +160,9 @@ 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. +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 @@ -193,15 +199,18 @@ 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. -.IP "\-w, --where \fInr" +.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. +to trace (those are typically calls inside a library or main binary, +though PLT calls, traced by \-e, land on entry points as well). 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. .IP "\-V, \-\-version" Show the version number of ltrace and exit. @@ -277,9 +286,9 @@ 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 occured. -When a library call (such as those traced by -e and -l) is hit, the +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 @@ -305,9 +314,9 @@ $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 +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 +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 @@ -317,7 +326,7 @@ library files. It has most of the bugs stated in .BR strace(1) . .LP -It only works on Linux and in a small subset of architectures. +It only works on Linux and in some architectures. .LP .PP If you would like to report a bug, send a message to the mailing list