.\" -*-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
.\"
.\" 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]
.\" ---------------------------------------------------------------------------
.\"
.PP
-.BR ltrace " -c"
+.BR ltrace " \-c"
.\"
.\" What events to trace:
.\"
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.
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
.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.
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
.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.
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
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
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
projects / platform / upstream / ltrace.git / blobdiff