removed needless cast

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

diff --git a/ltrace.1 b/ltrace.1
index aeaea76..93032f2 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]


@@ -55,7 +55,7 @@ ltrace \- A library call tracer
 .\" ---------------------------------------------------------------------------
 .\"
 .PP
 .\" ---------------------------------------------------------------------------
 .\"
 .PP

-.BR ltrace " -c"
+.BR ltrace " \-c"

 .\"
 .\" What events to trace:
 .\"
 .\"
 .\" 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"
 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.
 .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
 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.  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
 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,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.
 .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.
 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
 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
 .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.
 .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
 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
 .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.
 
 .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
 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
 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.
 
 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
 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
 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 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
 .LP
 .PP
 If you would like to report a bug, send a message to the mailing list