diff options
Diffstat (limited to 'ltrace.1')
| -rw-r--r-- | ltrace.1 | 267 |
1 files changed, 168 insertions, 99 deletions
@@ -1,5 +1,5 @@ .\" -*-nroff-*- -.\" Copyright (c) 2012 Petr Machata, Red Hat Inc. +.\" Copyright (c) 2012, 2013 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 @@ -17,13 +17,65 @@ .\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA .\" 02110-1301 USA .\" -.TH LTRACE "1" "October 2012" "" "User Commands" +.TH LTRACE "1" "January 2013" "" "User Commands" .SH NAME ltrace \- A library call tracer .SH SYNOPSIS +.\" +.\" --------------------------------------------------------------------------- +.\" +.PP .B ltrace -.I "[-bCfghiLrStttV] [-a column] [-A maxelts] [-D level] [-e expr] [-l library_pattern] [-n nr] [-o filename] [-p pid] ... [-s strsize] [-u username] [-w count] [-x extern] ... [--align=column] [--debug=level] [--demangle] [--help] [--indent=nr] [--library=library_pattern] [--no-signals] [--output=filename] [--version] [--where=NR] [command [arg ...]]" +.\" +.\" What events to trace: +.\" +[\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR] +[\-x \fIfilter\fR] [\-S] [\-b|\-\-no-signals] +.\" +.\" What to display with each event: +.\" +[\-i] [\-w|\-\-where=\fInr\fR] [\-r|\-t|\-tt|\-ttt] [\-T] +.\" +.\" Output formatting: +.\" +[\-F \fIpathlist\fR] +[\-A \fImaxelts\fR] [\-s \fIstrsize\fR] [\-C|\-\-demangle] +[\-a|\-\-align \fIcolumn\fR] [\-n|\-\-indent \fInr\fR] +[\-o|\-\-output \fIfilename\fR] +.\" +.\" Various: +.\" +[\-D|\-\-debug \fImask\fR] [\-u \fIusername\fR] +.\" +.\" What processes to trace: +.\" +[\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR] +.\" +.\" --------------------------------------------------------------------------- +.\" +.PP +.BR ltrace " -c" +.\" +.\" What events to trace: +.\" +[\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR] +[\-x \fIfilter\fR] [\-S] +.\" +.\" Output formatting: +.\" +[\-o|\-\-output \fIfilename\fR] +.\" +.\" What processes to trace: +.\" +[\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR] +.\" +.\" --------------------------------------------------------------------------- +.\" +.PP +.BR ltrace " \-V|\-\-version" +.PP +.BR ltrace " \-h|\-\-help" .SH DESCRIPTION .B ltrace @@ -37,78 +89,60 @@ It can also intercept and print the system calls executed by the program. Its use is very similar to .BR strace(1) . +.B ltrace +shows parameters of invoked functions and system calls. To determine +what arguments each function has, it needs external declaration of +function prototypes. Those are stored in files called \fIprototype +libraries\fR--see ltrace.conf(5) for details on the syntax of these +files. See the section \fBPROTOTYPE LIBRARY DISCOVERY\fR to learn how +\fBltrace\fR finds prototype libraries. + .SH OPTIONS -.TP -.I \-a, \-\-align column +.PP +.IP "\-a, \-\-align \fIcolumn" Align return values in a specific .IR column (default column is 5/8 of screen width). -.TP -.I \-A maxelts +.IP "\-A \fImaxelts" Maximum number of array elements to print before suppressing the rest with an ellipsis ("..."). This also limits number of recursive structure expansions. -.TP -.I \-b, \-\-no-signals +.IP "\-b, \-\-no-signals" Disable printing of signals recieved by the traced process. -.TP -.I \-c -Count time and calls for each library call and report a summary on program exit. -.TP -.I \-C, \-\-demangle +.IP \-c +Count time and calls for each library call and report a summary on +program exit. +.IP "\-C, \-\-demangle" Decode (demangle) low-level symbol names into user-level names. Besides removing any initial underscore prefix used by the system, this makes C++ function names readable. -.TP -.I \-D, \-\-debug level -Show debugging output of -.B ltrace -itself. -.I level -must be a sum of some of the following numbers: -.RS -.TP -.B 01 -DEBUG_GENERAL. Shows helpful progress information -.TP -.B 010 -DEBUG_EVENT. Shows every event received by a traced program -.TP -.B 020 -DEBUG_PROCESS. Shows every action -.B ltrace -carries upon a traced process -.TP -.B 040 -DEBUG_FUNCTION. Shows every entry to internal functions -.RE -.TP -.I \-e filter +.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. +.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. -.TP -.I \-f +.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. -.TP -.I \-F -Load an alternate config file. Normally, /etc/ltrace.conf and -~/.ltrace.conf will be read (the latter only if it exists). -Use this option to load the given file or files instead of -those two default files. -.TP -.I \-h, \-\-help +.IP "\-F \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 +a file, that file is imported implicitly to all loaded prototype +libraries. +.IP "\-h, \-\-help" Show a summary of the options to ltrace and exit. -.TP -.I \-i +.IP \-i Print the instruction pointer at the time of the library call. -.TP -.I \-l, \-\-library 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 @@ -120,71 +154,55 @@ the selected libraries, there's no actual guarantee that the call 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. -.TP -.I \-L +.IP \-L When no -e option is given, don't assume the default action of \fB@MAIN\fR. -.TP -.I \-n, \-\-indent nr -Indent trace output by -.I nr -number of spaces for each new nested call. Using this option makes -the program flow visualization easy to follow. -.TP -.I \-o, \-\-output filename -Write the trace output to the file -.I filename -rather than to stderr. -.TP -.I \-p pid -Attach to the process with the process ID -.I pid -and begin tracing. -.TP -.I \-r -Print a relative timestamp with each line of the trace. -This records the time difference between the beginning of -successive lines. -.TP -.I \-s strsize +.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 +to follow. This indents uselessly also functions that never return, +such as service functions for throwing exceptions in the C++ runtime. +.IP "\-o, \-\-output \fIfilename" +Write the trace output to the file \fIfilename\fR rather than to +stderr. +.IP "\-p \fIpid" +Attach to the process with the process ID \fIpid\fR and begin tracing. +This option can be used together with passing a command to execute. +It is possible to attach to several processes by passing more than one +option \-p. +.IP \-r +Print a relative timestamp with each line of the trace. This records +the time difference between the beginning of successive lines. +.IP "\-s \fIstrsize" Specify the maximum string size to print (the default is 32). -.TP -.I \-S +.IP \-S Display system calls as well as library calls -.TP -.I \-t +.IP \-t Prefix each line of the trace with the time of day. -.TP -.I \-tt +.IP \-tt If given twice, the time printed will include the microseconds. -.TP -.I \-ttt +.IP \-ttt If given thrice, the time printed will include the microseconds and the leading portion will be printed as the number of seconds since the epoch. -.TP -.I \-T +.IP \-T Show the time spent inside each call. This records the time difference between the beginning and the end of each call. -.TP -.I \-u username +.IP "\-u \fIusername" 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. -.TP -.I \-w, --where NR -Show backtrace of NR stack frames for each traced function. This option enabled -only if libunwind support was enabled at compile time. -.TP -.I \-x filter +.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. +.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. -.TP -.I \-V, \-\-version +.IP "\-V, \-\-version" Show the version number of ltrace and exit. .SH FILTER EXPRESSIONS @@ -235,7 +253,8 @@ path name. The first rule may lack a sign, in which case \fB+\fR is assumed. If, on the other hand, the first rule has a \fB-\fR sign, it is as if -there was another rule \fB@*\fR in front of it. +there was another rule \fB@\fR in front of it, which has the effect of +tracing complement of given rule. The above rules are used to construct the set of traced symbols. Each candidate symbol is passed through the chain of above rules. @@ -244,6 +263,56 @@ rule, it becomes \fImarked\fR, if it matches a \fB-\fR rule, it becomes \fIunmarked\fR again. If, after applying all rules, the symbol is \fImarked\fR, it will be traced. +.SH PROTOTYPE LIBRARY DISCOVERY + +When a library is mapped into the address space of a traced process, +ltrace needs to know what the prototypes are of functions that this +library implements. For purposes of ltrace, prototype really is a bit +more than just type signature: it's also formatting of individual +parameters and of return value. These prototypes are stored in files +called prototype libraries. + +After a library is mapped, ltrace finds out what its SONAME is. It +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 +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 +library. + +If a library has no SONAME, basename of library file is considered +instead. For the main program binary, basename is considered as well +(e.g. protolib for /bin/echo would be called echo.conf). If a name +corresponding to soname (e.g. libc.so.6.conf) is not found, and the +module under consideration is a shared library, ltrace also tries +partial matches. Ltrace snips one period after another, retrying the +search, until either a protolib is found, or X.so is all that's left. +Thus libc.so.conf would be considered, but libc.conf not. + +When looking for a prototype library, ltrace potentially looks into +several directories. On Linux, those are $XDG_CONFIG_HOME/ltrace, +$HOME/.ltrace, \fIX\fR/ltrace for each \fIX\fR in $XDG_CONFIG_DIRS and +/usr/share/ltrace. If the environment variable XDG_CONFIG_HOME is not +defined, ltrace looks into $HOME/.config/ltrace instead. + +There's also a mechanism for loading legacy config files. If +$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 +the above system directories, in the same order in which they are +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 +library files. + .SH BUGS It has most of the bugs stated in .BR strace(1) . |