Clean up command-line args info in the manual and man page for 3.0.0
release.
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@4259 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/docs/valgrind.1 b/docs/valgrind.1
index a6de9cc..d058fd0 100644
--- a/docs/valgrind.1
+++ b/docs/valgrind.1
@@ -1,7 +1,7 @@
.TH VALGRIND "1" "" ""
.SH NAME
-\fBvalgrind \fP- a memory debugger for x86-linux
+\fBvalgrind \fP- a suite of tools for debugging and profiling programs
.SH SYNOPSIS
.nf
@@ -11,8 +11,8 @@
.fi
.SH DESCRIPTION
-\fBvalgrind\fP is a flexible program for debugging and profiling Linux-x86
-executables. It consists of a core, which provides a synthetic x86 CPU
+\fBvalgrind\fP is a flexible program for debugging and profiling Linux
+executables. It consists of a core, which provides a synthetic CPU
in software, and a series of "tools", each of which is a debugging or
profiling tool. The architecture is modular, so that new tools can be
created easily and without disturbing the existing structure.
@@ -125,17 +125,25 @@
default debugger is gdb. This option is a template that is expanded by
\fBvalgrind\fP at runtime. \fB%f\fP is replaced with the executable's
file name and \fB%p\fP is replaced by the process ID of the executable.
+
.TP
.B
+--demangle=<yes|no> [default: yes]
+Enable or disable automatic demangling (decoding) of C++ names. Enabled by
+default. When enabled, \fBvalgrind\fP will attempt to translate encoded
+C++ procedure names back to something approaching the original. The
+demangler handles symbols mangled by g++ versions 2.X and 3.X.
+.TP
+.B
--error-limit=<yes|no> [default: yes]
When enabled, \fBvalgrind\fP stops reporting errors after 30000 in total,
or 300 different ones, have been seen. This is to stop the error tracking
machinery from becoming a huge performance overhead in programs with
many errors.
+
.TP
.B
-
--gen-suppressions=<yes|no> [default: no]
When enabled, \fBvalgrind\fP will pause after every error shown and
print the line:
@@ -174,6 +182,12 @@
.TP
.B
+--input-fd=<number> [default: 0, stdin]
+Specify the file descriptor to use for reading input from the user. This
+is used whenever \fBvalgrind\fP needs to prompt the user for a decision.
+
+.TP
+.B
--log-file=<filename>
Specifies that \fBvalgrind\fP should send all of its messages to the
specified file. In fact, the file name used is created by concatenating
@@ -182,6 +196,39 @@
.TP
.B
+--log-file-exactly=<filename>
+Just like \fB--log-file\fB, but the ".pid" suffix is not added. If you
+trace multiple processes with Valgrind when using this option the log
+file may get all messed up.
+
+.TP
+.B
+--log-fd=<number> [default: 2, stderr]
+Specifies that \fBvalgrind\fP should send all of its messages to
+the specified file descriptor. The default, 2, is the standard error
+channel (stderr). Note that this may interfere with the client's own
+use of stderr.
+
+.TP
+.B
+--log-file-qualifier=<VAR>
+Specifies that \fBvalgrind\fB should send all of its messages to the
+file named by the environment variable \fB$VAR\fB. This is useful when
+running MPI programs.
+
+.TP
+.B
+--log-socket=<ip-address:port-number>
+Specifies that \fBvalgrind\fP should send all of its messages to the
+specified port at the specified IP address. The port may be omitted,
+in which case port 1500 is used. If a connection cannot be made to
+the specified socket, \fBvalgrind\fP falls back to writing output to
+the standard error (stderr). This option is intended to be used in
+conjunction with the \fBvalgrind-listener\fP program. For further details,
+see section 2.3 of the user manual.
+
+.TP
+.B
--num-callers=<number> [default=12]
By default, \fBvalgrind\fP shows 12 levels of function call names to
help you identify program locations. You can change that number with
@@ -206,12 +253,25 @@
.TP
.B
+--show-below-main=<yes|no> [default: no]
+When enabled, this option causes full stack backtraces to be emited,
+including the part before \fBmain\fP in your program (subject to the
+\fB--num-callers\fP option.) When disabled, only the part of the stack
+backtrace up to and including main is printed.
+
+.TP
+.B
--suppressions=<filename> [default: $PREFIX/lib/\fBvalgrind\fP/default.supp]
Specifies an extra file from which to read descriptions of errors to
suppress. You may specify up to 10 additional suppression files.
.TP
.B
+--time-stamp=<yes|no> [default: no]
+When enabled, a time-stamp is added to all log messages.
+
+.TP
+.B
--tool=<toolname> [default: memcheck]
Specify which tool to use. The default tool is memcheck.
@@ -328,14 +388,6 @@
errors to be reported by \fBmemcheck\fP, so it's usually a good idea to
leave this enabled.
-.TP
-.B
---cleanup=<yes|no> [default: yes]
-\fBThis is a flag to help debug valgrind itself. It is of no use to
-end-users\fP. When enabled, various improvments are applied to the
-post-instrumented intermediate code, aimed at removing redundant value
-checks.
-
.SH CACHEGRIND OPTIONS
.TP
@@ -425,7 +477,7 @@
.B
--alignment=<number> [default: 8]
By default \fBvalgrind\fP's malloc, realloc, etc, return 8-byte aligned
-addresses. These are suitable for any accesses on x86 processors. Some
+addresses. These are suitable for any accesses on most processors. Some
programs might however assume that malloc et al return 16- or more
aligned memory. These programs are broken and should be fixed, but if
this is impossible for whatever reason the alignment can be increased
@@ -434,100 +486,6 @@
.TP
.B
---branchpred=<yes|no> [default: no]
-This option enables the generation of static branch prediction hints.
-In theory this allows the real CPU to do a better job of running the
-generated code, but in practice it makes almost no measurable difference.
-It may have a large effect on some x86 implementations.
-
-.TP
-.B
---chain-bb=<yes|no> [default: yes]
-Enables basic-block chaining. If basic-block chaining is disabled,
-the synthetic CPU returns to the scheduler after interpreting each basic
-block. With basic block chaining enabled, it can immediately proceed to
-the next basic block. This almost always results in a performance gain,
-so it is enabled by default.
-
-.TP
-.B
---command-line-only=<yes|no> [default: no]
-Normally, \fBvalgrind\fP will look for command-line options in the
-following locations:
-.RS
-.TP
-- The \fBvalgrind\fP command line
-.TP
-- The \fB\.valgrindrc\fP file in the invocation directory
-.TP
-- The \fB\.valgrindrc\fP file in users home directory
-.TP
-- The \fB$VALGRIND_OPTS\fP environment variable
-.P
-
-When this option is enabled, \fBvalgrind\fP will only look at the command
-line for options.
-.RE
-
-.TP
-.B
---demangle=<yes|no> [default: yes]
-Enable or disable automatic demangling (decoding) of C++ names. Enabled by
-default. When enabled, \fBvalgrind\fP will attempt to translate encoded
-C++ procedure names back to something approaching the original. The
-demangler handles symbols mangled by g++ versions 2.X and 3.X.
-
-.TP
-.B
---dump-error=<number>
-After the program has exited, show gory details of the translation of
-the basic block containing the \fB<number>\fP'th error context. When
-used with --single-step=yes, can show the exact x86 instruction causing
-an error. This is all fairly dodgy and doesn't work at all if threads
-are involved.
-
-.TP
-.B
---exec=<filename>
-Specify the executable to run. If this is specified, it takes precedence
-over the \fByour-program\fP executable from the command-line. If this is
-not specified, \fBvalgrind\fP searches the path for the \fByour-program\fP
-executable, just like a regular shell would.
-
-.TP
-.B
---input-fd=<number> [default: 0, stdin]
-Specify the file descriptor to use for reading input from the user. This
-is used whenever \fBvalgrind\fP needs to prompt the user for a decision.
-
-.TP
-.B
---log-fd=<number> [default: 2, stderr]
-Specifies that \fBvalgrind\fP should send all of its messages to
-the specified file descriptor. The default, 2, is the standard error
-channel (stderr). Note that this may interfere with the client's own
-use of stderr.
-
-.TP
-.B
---log-socket=<ip-address:port-number>
-Specifies that \fBvalgrind\fP should send all of its messages to the
-specified port at the specified IP address. The port may be omitted,
-in which case port 1500 is used. If a connection cannot be made to
-the specified socket, \fBvalgrind\fP falls back to writing output to
-the standard error (stderr). This option is intended to be used in
-conjunction with the \fBvalgrind-listener\fP program. For further details,
-see section 2.3 of the user manual.
-
-.TP
-.B
---optimise=<yes|no> [default: yes]
-When enabled, various improvements are applied to the intermediate code,
-mainly aimed at allowing the simulated CPU's registers to be cached in
-the real CPU's registers over several simulated instructions.
-
-.TP
-.B
--pointercheck=<yes|no> [default: yes]
When enabled, enforces client address space limits. If this option is
disabled, the client program has full and unfettered access to the part
@@ -563,27 +521,6 @@
.TP
.B
---show-below-main=<yes|no> [default: no]
-When enabled, this option causes full stack backtraces to be emited,
-including the part before \fBmain\fP in your program (subject to the
-\fB--num-callers\fP option.) When disabled, only the part of the stack
-backtrace up to and including main is printed.
-
-.TP
-.B
---single-step=<yes|no> [default: no]
-When enabled, each x86 insn is translated separately into instrumented
-code. When disabled, translation is done on a per-basic-block basis,
-giving much better translations. This is needed when running
-\fBvalgrind\fP under \fBvalgrind\fP.
-
-.TP
-.B
---time-stamp=<yes|no> [default: no]
-When enabled, a time-stamp is added to all log messages.
-
-.TP
-.B
--weird-hacks=hack1,hack2,\.\.\.
Pass miscellaneous hints to \fBvalgrind\fP which slightly modify the
simulated behaviour in nonstandard or dangerous ways, possibly to help
@@ -609,71 +546,7 @@
.TP
.B
---profile=<yes|no> [default: no]
-When enabled, does crude internal profiling of \fBvalgrind\fP itself. This
-is not for profiling your programs. Rather it is to allow the developers
-to assess where \fBvalgrind\fP is spending its time. The tools must be
-built for profiling for this to work.
-
-.TP
-.B
---sanity-level=<number> [default: 1]
-Set the level of sanity checking to perform. This is used for debugging
-\fBvalgrind\fP. Setting this to 2 or higher can cause more internal
-sanity checks to be performed, but can slow your program down
-appreciably. Setting this to 0 disables sanity checks.
-
-.TP
-.B
---trace-codegen=<bitmask>
-Produce lots of output showing exactly how \fBvalgrind\fP is translating
-each basic block. The argument to this option is a 5-bit wide bitmask.
-Each bit refers to a specific feature to trace. If the bit is 1, the
-feature is traced. If it is 0, the feature is not traced.
-
-.RS
-The traced features are:
-.TP
-Bit 1: basic-block disassembly
-.TP
-Bit 2: optimization phase
-.TP
-Bit 3: tool instrumentation
-.TP
-Bit 4: register allocation
-.TP
-Bit 5: final code generation
-.RE
-
-.TP
-.B
---trace-malloc=<yes|no> [default: no]
-Enable or disable tracing of malloc, free and other memory-manager calls.
-
-.TP
-.B
---trace-redir=<yes|no> [default: no]
-Enable or disable tracing of function redirection.
-
-.TP
-.B
---trace-sched=<yes|no> [default: no]
-Enable or disable tracing of thread scheduling events.
-
-.TP
-.B
---trace-signals=<yes|no> [default: no]
-Enable or disable tracing of signal handling.
-
-.TP
-.B
---trace-syscalls=<yes|no> [default: no]
-Enable or disable tracing of system call intercepts.
-
-.TP
-.B
---trace-symtab=<yes|no> [default: no]
-Enable or disable tracing of symbol table reading.
+Valgrind has several debugging options that are mostly of use to developers. Use \fB--help-debug\fB to show them.
.SH SEE ALSO
/usr/share/doc/\fBvalgrind\fP/html/manual.html
diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml
index d3b890a..f0123ff 100644
--- a/docs/xml/manual-core.xml
+++ b/docs/xml/manual-core.xml
@@ -610,6 +610,13 @@
</listitem>
<listitem>
+ <para><computeroutput>-q --quiet</computeroutput></para>
+ <para>Run silently, and only print error messages. Useful if
+ you are running regression tests or have some other automated
+ test machinery.</para>
+ </listitem>
+
+ <listitem>
<para><computeroutput>-v --verbose</computeroutput></para>
<para>Be more verbose. Gives extra information on various
aspects of your program, such as: the shared objects loaded,
@@ -619,13 +626,6 @@
</listitem>
<listitem>
- <para><computeroutput>-q --quiet</computeroutput></para>
- <para>Run silently, and only print error messages. Useful if
- you are running regression tests or have some other automated
- test machinery.</para>
- </listitem>
-
- <listitem>
<para><computeroutput>--trace-children=no</computeroutput>
[default]</para>
<para><computeroutput>--trace-children=yes</computeroutput></para>
@@ -635,6 +635,23 @@
</listitem>
<listitem>
+ <para><computeroutput>--track-fds=no</computeroutput> [default]</para>
+ <para><computeroutput>--track-fds=yes</computeroutput></para>
+ <para>When enabled, Valgrind will print out a list of open
+ file descriptors on exit. Along with each file descriptor,
+ Valgrind prints out a stack backtrace of where the file was
+ opened and any details relating to the file descriptor such
+ as the file name or socket details.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--time-stamp=no</computeroutput> [default]</para>
+ <para><computeroutput>--time-stamp=yes</computeroutput></para>
+ <para>When enabled, Valgrind will precede each message with the
+ current time and date.</para>
+ </listitem>
+
+ <listitem>
<para><computeroutput>--log-fd=<number></computeroutput>
[default: 2, stderr]</para>
<para>Specifies that Valgrind should send all of its messages
@@ -696,6 +713,23 @@
<itemizedlist>
<listitem>
+ <para><computeroutput>--xml=no</computeroutput> [default]</para>
+ <para><computeroutput>--xml=yes</computeroutput></para>
+ <para>When enabled, output will be in XML format. This is aimed at
+ making life easier for tools that consume Valgrind's output as input,
+ such as GUI front ends. Currently this option only works with Memcheck
+ and Nulgrind.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--xml-user-comment=<string></computeroutput> [default=""]</para>
+ <para>Embeds an extra user comment string in the XML output. Only works
+ with <computeroutput>--xml=yes</computeroutput> is specified; ignored
+ otherwise.</para>
+ </listitem>
+
+ <listitem>
<para><computeroutput>--demangle=no</computeroutput></para>
<para><computeroutput>--demangle=yes</computeroutput> [default]</para>
<para>Disable/enable automatic demangling (decoding) of C++
@@ -802,48 +836,6 @@
</listitem>
<listitem>
- <para><computeroutput>--track-fds=no</computeroutput> [default]</para>
- <para><computeroutput>--track-fds=yes</computeroutput></para>
- <para>When enabled, Valgrind will print out a list of open
- file descriptors on exit. Along with each file descriptor,
- Valgrind prints out a stack backtrace of where the file was
- opened and any details relating to the file descriptor such
- as the file name or socket details.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--max-stackframe=<number></computeroutput>
- [default=2000000]
- </para>
- <para>You may need to use this option if your program has large
- stack-allocated arrays. Valgrind keeps track of your program's
- stack pointer. If it changes by more than the threshold amount,
- Valgrind assumes your program is switching to a different stack,
- and Memcheck behaves differently than it would for a stack pointer
- change smaller than the threshold. Usually this heuristic works
- well. However, if your program allocates large structures on the
- stack, this heuristic will be fooled, and Memcheck will
- subsequently report large numbers of invalid stack accesses. This
- option allows you to change the threshold to a different value.
- </para>
- <para>
- You should only consider use of this flag if Valgrind's debug output
- directs you to do so. In that case it will tell you the new
- threshold you should specify.
- </para>
- <para>
- In general, allocating large structures on the stack is a bad
- idea, because (1) you can easily run out of stack space,
- especially on systems with limited memory or which expect to
- support large numbers of threads each with a small stack, and (2)
- because the error checking performed by Memcheck is more effective
- for heap-allocated data than for stack-allocated data. If you
- have to use this flag, you may wish to consider rewriting your
- code to allocate on the heap rather than on the stack.
- </para>
- </listitem>
-
- <listitem>
<para><computeroutput>--db-attach=no</computeroutput> [default]</para>
<para><computeroutput>--db-attach=yes</computeroutput></para>
<para>When enabled, Valgrind will pause after every error
@@ -910,6 +902,38 @@
alternative file descriptor from which to read input.</para>
</listitem>
+ <listitem>
+ <para><computeroutput>--max-stackframe=<number></computeroutput>
+ [default=2000000]
+ </para>
+ <para>You may need to use this option if your program has large
+ stack-allocated arrays. Valgrind keeps track of your program's
+ stack pointer. If it changes by more than the threshold amount,
+ Valgrind assumes your program is switching to a different stack,
+ and Memcheck behaves differently than it would for a stack pointer
+ change smaller than the threshold. Usually this heuristic works
+ well. However, if your program allocates large structures on the
+ stack, this heuristic will be fooled, and Memcheck will
+ subsequently report large numbers of invalid stack accesses. This
+ option allows you to change the threshold to a different value.
+ </para>
+ <para>
+ You should only consider use of this flag if Valgrind's debug output
+ directs you to do so. In that case it will tell you the new
+ threshold you should specify.
+ </para>
+ <para>
+ In general, allocating large structures on the stack is a bad
+ idea, because (1) you can easily run out of stack space,
+ especially on systems with limited memory or which expect to
+ support large numbers of threads each with a small stack, and (2)
+ because the error checking performed by Memcheck is more effective
+ for heap-allocated data than for stack-allocated data. If you
+ have to use this flag, you may wish to consider rewriting your
+ code to allocate on the heap rather than on the stack.
+ </para>
+ </listitem>
+
</itemizedlist>
</sect2>
@@ -940,8 +964,8 @@
</sect2>
- <sect2 id="manual-core.rareopts" xreflabel="Rare Options">
- <title>Rare Options</title>
+ <sect2 id="manual-core.rareopts" xreflabel="Uncommon Options">
+ <title>Uncommon Options</title>
<para>These options apply to all tools, as they affect certain
obscure workings of the Valgrind core. Most people won't need
@@ -1027,6 +1051,27 @@
the same functionality.</para>
</listitem>
+ <listitem>
+ <para><computeroutput>--show-emwarns=no</computeroutput> [default]</para>
+ <para><computeroutput>--show-emwarns=yes</computeroutput></para>
+ <para>When enabled, Valgrind will emit warnings about its CPU emulation
+ in certain cases. These are usually not interesting.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--smc-check=none</computeroutput></para>
+ <para><computeroutput>--smc-check=stack</computeroutput> [default]</para>
+ <para><computeroutput>--smc-check=all</computeroutput></para>
+ <para>This option controls Valgrind's detection of self-modifying code.
+ Valgrind can do no detection, detect self-modifying code on the stack,
+ or detect self-modifying code anywhere. Note that the default option
+ will catch the vast majority of cases, as far as we know. Running with
+ <computeroutput>all</computeroutput> will slow Valgrind down greatly
+ (but running with <computeroutput>none</computeroutput> will rarely
+ speed things up, since very little code gets put on the stack for most
+ programs). </para>
+ </listitem>
+
</itemizedlist>
</sect2>
@@ -1035,123 +1080,10 @@
<title>Debugging Valgrind Options</title>
<para>There are also some options for debugging Valgrind itself.
-You shouldn't need to use them in the normal run of things.
-Nevertheless:</para>
+You shouldn't need to use them in the normal run of things. If you
+wish to see the list, use the <computeroutput>--help-debug</computeroutput>
+option.</para>
- <itemizedlist>
-
- <listitem>
- <para><computeroutput>--single-step=no</computeroutput>
- [default]</para>
- <para><computeroutput>--single-step=yes</computeroutput></para>
- <para>When enabled, each instruction is translated separately
- into instrumented code. When disabled, translation is done
- on a per-basic-block basis, giving much better
- translations. This option is very useful if your program expects
- precise exceptions (if it, for example, inspects or modifies register
- state from within a signal handler).
- </para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--optimise=no</computeroutput></para>
- <para><computeroutput>--optimise=yes</computeroutput> [default]</para>
- <para>When enabled, various improvements are applied to the
- intermediate code, mainly aimed at allowing the simulated
- CPU's registers to be cached in the real CPU's registers over
- several simulated instructions.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--profile=no</computeroutput></para>
- <para><computeroutput>--profile=yes</computeroutput> [default]</para>
- <para>When enabled, does crude internal profiling of Valgrind
- itself. This is not for profiling your programs. Rather it
- is to allow the developers to assess where Valgrind is
- spending its time. The tools must be built for profiling for
- this to work.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--trace-syscalls=no</computeroutput>
- [default]</para>
- <para><computeroutput>--trace-syscalls=yes</computeroutput></para>
- <para>Enable/disable tracing of system call intercepts.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--trace-signals=no</computeroutput>
- [default]</para>
- <para><computeroutput>--trace-signals=yes</computeroutput></para>
- <para>Enable/disable tracing of signal handling.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--trace-sched=no</computeroutput>
- [default]</para>
- <para><computeroutput>--trace-sched=yes</computeroutput></para>
- <para>Enable/disable tracing of thread scheduling events.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--trace-pthread=none</computeroutput>
- [default]</para>
- <para><computeroutput>--trace-pthread=some</computeroutput></para>
- <para><computeroutput>--trace-pthread=all</computeroutput></para>
- <para>Specifies amount of trace detail for pthread-related
- events.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--trace-symtab=no</computeroutput>
- [default]</para>
- <para><computeroutput>--trace-symtab=yes</computeroutput></para>
- <para>Enable/disable tracing of symbol table reading and line
- number info reading.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--trace-cfi=no</computeroutput>
- [default]</para>
- <para><computeroutput>--trace-cfi=yes</computeroutput></para>
- <para>Enable/disable tracing of call-frame-info reading.
- Call-frame-info (CFI) is information inserted by compilers
- which describes the relationship between adjacent call frames.
- On architectures which by default do not use a frame pointer,
- such as AMD64, this information is essential for creating stack
- snapshots.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--trace-malloc=no</computeroutput>
- [default]</para>
- <para><computeroutput>--trace-malloc=yes</computeroutput></para>
- <para>Enable/disable tracing of malloc/free (et al)
- intercepts.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--trace-codegen=XXXXX</computeroutput>
- [default: 00000]</para>
- <para>Enable/disable tracing of code generation. Code can be
- printed at five different stages of translation; each
- <computeroutput>X</computeroutput> element must be 0 or
- 1.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--dump-error=<number></computeroutput>
- [default: inactive]</para>
- <para>After the program has exited, show gory details of the
- translation of the basic block containing the <number>'th
- error context. When used with
- <computeroutput>--single-step=yes</computeroutput>, can show
- the exact instruction causing an error. This is all
- fairly dodgy and doesn't work at all if threads are
- involved.</para>
- </listitem>
-
- </itemizedlist>
</sect2>