The valgrind manpage is now auto-generated directly from the
*.xml docs. No more groffly/nroffly editing.
How cool is docbook ?
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@5276 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 2018097..f5367ea 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -43,21 +43,23 @@
# validation stuff
XMLLINT = xmllint
-LINT_FLAGS = --noout --xinclude --noblanks --postvalid
-VALID_FLAGS = --dtdvalid http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd
+LINT_FLAGS = --noblanks --noout --xinclude --postvalid --noent
+# validate with docbook 4.3 'cos it supports xml:base natively
+VALID_FLAGS = --dtdvalid http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd
XMLLINT_FLAGS = $(LINT_FLAGS) $(VALID_FLAGS)
# stylesheet processor
XSLTPROC = xsltproc
-XSLTPROC_FLAGS = --nonet --xinclude
+XSLTPROC_FLAGS = --nonet --xinclude
# stylesheets
XSL_HTML_CHUNK_STYLE = $(mylibdir)/vg-html-chunk.xsl
XSL_FO_STYLE = $(mylibdir)/vg-fo.xsl
XSL_TEXT_STYLE = $(mylibdir)/vg-faq2txt.xsl
XSL_WEBSITE_STYLE = $(mylibdir)/vg-html-website.xsl
+XSL_MAN_STYLE = /usr/share/xml/docbook/stylesheet/nwalsh/1.69.0/manpages/docbook.xsl
-all-docs: FAQ.txt html-docs print-docs
+all-docs: FAQ.txt man-page html-docs print-docs
valid:
$(XMLLINT) $(XMLLINT_FLAGS) $(myxmldir)/index.xml
@@ -68,6 +70,18 @@
export XML_CATALOG_FILES=$(XML_CATALOG_FILES) && \
$(XSLTPROC) $(XSLTPROC_FLAGS) -o ./FAQ.txt $(XSL_TEXT_STYLE) $(myxmldir)/FAQ.xml
+# the valgrind manpage
+man-page:
+ @echo "Generating the valgrind manpage ..."
+ @if test ! -f $(XSL_MAN_STYLE); then \
+ echo "Error: I can't find the file '$(XSL_MAN_STYLE)'"; \
+ echo "Please check where it lives on your system, and" \
+ "amend the line 'XSL_MAN_STYLE = ' in this Makefile."; \
+ exit 1; \
+ fi; \
+ export XML_CATALOG_FILES=$(XML_CATALOG_FILES) && \
+ $(XSLTPROC) $(XSLTPROC_FLAGS) -o ./ $(XSL_MAN_STYLE) $(myxmldir)/valgrind-manpage.xml
+
# chunked html, on a chapter-by-chapter basis
html-docs:
@echo "Generating html files..."
diff --git a/docs/README b/docs/README
index 64ac345..33d01e7 100644
--- a/docs/README
+++ b/docs/README
@@ -22,10 +22,11 @@
valgrind/docs/lib/
Some files of note:
- docs/xml/index.xml: Top-level book-set wrapper
- docs/xml/FAQ.xml: The FAQ
- docs/xml/vg-entities.xml: Various strings, dates etc. used all over
- docs/xml/xml_help.txt: Basic guide to common XML tags.
+ docs/xml/index.xml: Top-level book-set wrapper
+ docs/xml/FAQ.xml: The FAQ
+ docs/valgrind-manpage.xml The valgrind manpage
+ docs/xml/vg-entities.xml: Various strings, dates etc. used all over
+ docs/xml/xml_help.txt: Basic guide to common XML tags.
The docs/internals directory contains some useful high-level stuff about
Valgrind's internals. It's not relevant for the rest of this discussion.
@@ -33,11 +34,12 @@
Overview
---------
-The Documentation Set contains all books, articles,
+The Documentation Set contains all books, articles, manpages,
etc. pertaining to Valgrind, and is designed to be built as:
- chunked html files
- PDF file
- PS file
+- manpage
The whole thing is a "book set", made up of multiple books (the user
manual, the FAQ, the tech-docs, the licenses). Each book could be
@@ -118,11 +120,14 @@
-Notes [Nov. 2004]:
+Notes [Nov. 2005]
-----------------
-- the end of file.xml must have only ONE newline after the last tag:
- </book>
-- pdfxmltex barfs if given a filename with an underscore in it
+After upgrading to Suse 10, found a (known) bug in PassiveTex which
+broke the build, so added a bug-fix to 'docs/lib/vg-fo.xsl'.
+Bug-fix related links:
+http://lists.oasis-open.org/archives/docbook/200509/msg00032.html
+http://www.dpawson.co.uk/docbook/tools.html#d850e300
+http://www.haskell.org/pipermail/glasgow-haskell-bugs/2005-January.txt
Notes [July 2005]
@@ -141,14 +146,11 @@
and that fixed it.
-Notes [Nov. 2005]
+Notes [Nov. 2004]:
-----------------
-After upgrading to Suse 10, found a (known) bug in PassiveTex which
-broke the build, so added a bug-fix to 'docs/lib/vg-fo.xsl'.
-Bug-fix related links:
-http://lists.oasis-open.org/archives/docbook/200509/msg00032.html
-http://www.dpawson.co.uk/docbook/tools.html#d850e300
-http://www.haskell.org/pipermail/glasgow-haskell-bugs/2005-January.txt
+- the end of file.xml must have only ONE newline after the last tag:
+ </book>
+- pdfxmltex barfs if given a filename with an underscore in it
References:
@@ -179,4 +181,4 @@
TODO LESS CRUCIAL:
------------------
- concat titlepage + subtitle page in fo output
-- try and get the QuickStart and FAQ titlepages and tocs onto the same page
+- try and get the QuickStart and FAQ titlepage+toc+content onto one page
diff --git a/docs/lib/vg-html-common.xsl b/docs/lib/vg-html-common.xsl
index cef71d8..283204f 100644
--- a/docs/lib/vg-html-common.xsl
+++ b/docs/lib/vg-html-common.xsl
@@ -7,6 +7,12 @@
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk-code.xsl"/>
+<!-- Note [Dec.1 2005]: the tempate 'chunk-code.xsl' in -->
+<!-- '/usr/share/xml/docbook/stylesheet/nwalsh/1.69.0/html/' -->
+<!-- has been edited to remove 'article' and 'refentry' -->
+<!-- so that separate titlepages don't get generated for them -->
+
+
<!-- use 8859-1 encoding -->
<xsl:output method="html" encoding="ISO-8859-1" indent="yes"/>
diff --git a/docs/lib/vg_basic.css b/docs/lib/vg_basic.css
index 16e6cc2..49367fe 100644
--- a/docs/lib/vg_basic.css
+++ b/docs/lib/vg_basic.css
@@ -16,9 +16,14 @@
h1, h2, h3, h4 { color: #74240f; }
h3 { margin-bottom: 0.4em; }
-code, tt, pre { color: #3366cc; }
code, tt { color: #761596; }
+code a, code a:link, code a:visited, code a:active, code a:hover {
+ color: #761596;
+ text-decoration: none;
+ border-bottom: dashed 1px #761596;
+}
+pre { color: #3366cc; }
pre.programlisting {
color: #000000;
padding: 0.5em;
diff --git a/docs/valgrind.1 b/docs/valgrind.1
deleted file mode 100644
index beb4771..0000000
--- a/docs/valgrind.1
+++ /dev/null
@@ -1,575 +0,0 @@
-.TH VALGRIND "1" "" ""
-
-.SH NAME
-\fBvalgrind \fP- a suite of tools for debugging and profiling programs
-
-.SH SYNOPSIS
-.nf
-.fam C
-\fIvalgrind\fP [\fIvalgrind\fP \fIoptions\fP] \fIyour-program\fP [\fIyour-program\fP \fIoptions\fP]
-.fam T
-.fi
-
-.SH DESCRIPTION
-\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.
-
-.PP
-This manual page covers only basic usage and options. Please see the
-HTML documentation for more comprehensive information.
-
-.SH INVOCATION
-\fBvalgrind\fP is typically invoked as follows:
-
- valgrind program args
-
-This runs \fBprogram\fP (with arguments \fBargs\fP) under valgrind
-using the \fBmemcheck\fP tool. \fBmemcheck\fP performs a range of
-memory-checking functions, including detecting accesses to uninitialized
-memory, misuse of allocated memory (double frees, access after free,
-etc.) and detecting memory leaks.
-
-To use a different tool, use the \fB--tool\fP option:
-
- valgrind --tool=toolname program args
-
-The following tools are available:
-
-.RS
-.TP
-.B
-." - addrcheck
-." \fBaddrcheck\fP is similar to memcheck, but does not perform the same
-." granularity of memory checking. This will run faster and use less memory,
-." but may miss some problems that \fBmemcheck\fP would catch.
-." (\fBaddrcheck\fP is currently not working.)
-.TP
-.B
-- cachegrind
-\fBcachegrind\fP is a cache simulator. It can be used to annotate every
-line of your program with the number of instructions executed and cache
-misses incurred.
-." .TP
-." .B
-." - helgrind
-." \fBhelgrind\fP spots potential race conditions in your program.
-.TP
-.B
-- lackey
-\fBlackey\fP is a sample tool that can be used as a template for
-generating your own tools. After the program terminates, it prints out
-some basic statistics about the program execution.
-.TP
-.B
-- massif
-\fBmassif\fP is a heap profiler. It measures how much heap memory your
-program uses.
-.TP
-.B
-- memcheck
-\fBmemcheck\fP is a fine-grained memory checker.
-.TP
-.B
-- none
-\fBnone\fP performs no function - it simply runs the program under
-\fBvalgrind\fP. This is typically used for debugging and benchmarking
-\fBvalgrind\fP.
-.RE
-
-.SH COMMON CORE OPTIONS
-
-.TP
-.B
---db-attach=<yes|no> [default: no]
-When enabled, \fBvalgrind\fP will pause after every error shown and
-print the line:
-
-.PP
-.nf
-.fam C
- ---- Attach to debugger ? --- [Return/N/n/Y/y/C/c] ----
-
-.fam T
-.fi
-
-.RS
-Pressing Ret, or N Ret or n Ret, causes \fBvalgrind\fP not to start a
-debugger for this error.
-
-.PP
-Pressing Y Ret or y Ret causes \fBvalgrind\fP to start the debugger
-(specified by the \fB--db-command\fP option) for the program at this
-point. When you have finished with the debugger, quit from it, and
-the program will continue. Trying to continue from inside the debugger
-doesn't work.
-
-.PP
-Pressing C Ret or c Ret causes \fBvalgrind\fP not to start the debugger
-and \fBvalgrind\fP will not ask again.
-
-.PP
---db-attach=yes conflicts with --trace-children=yes. You can't use them
-together. \fBvalgrind\fP refuses to start up in this situation. 1 May
-2002: this is a historical relic which could be easily fixed if it gets
-in your way. Mail me and complain if this is a problem for you.
-
-.PP
-Nov 2002: if you're sending output to a logfile or to a network socket,
-I guess this option doesn't make any sense. Caveat emptor.
-.RE
-
-.TP
-.B
---db-command=<command> [default: gdb -nw %f %p]
-Specify the debugger to use with the --db-attach command. The
-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, 3.X and 4.X.
-
-.TP
-.B
---error-limit=<yes|no> [default: yes]
-When enabled, \fBvalgrind\fP stops reporting errors after 100000 in total,
-or 1000 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|all> [default: no]
-When set to \fByes\fP, \fBvalgrind\fP will pause after every error shown and
-print the line:
-
-.PP
-.nf
-.fam C
- ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----
-
-.fam T
-.fi
-
-.RS
-Pressing Y Ret or y Ret will cause a suppression for this error to be
-printed. This suppression can be cut-and-paste into a custom suppressions
-file and used to suppress this error in subsequent runs.
-
-.P
-Pressing Ret or n Ret or N Ret will cause no suppression to be printed.
-
-.P
-Pressing C Ret or c Ret will cause no suppression to be printed and
-\fBvalgrind\fP will not ask again.
-
-.P
-When set to \fall\fP, \fBvalgrind\fP will print suppressions for all
-errors without asking any questions.
-.RE
-
-.TP
-.B
--h --help
-Show help for all options, both for the core and for the selected tool.
-
-.TP
-.B
---help-debug
-Show help for all options, both for the core and for the selected tool,
-including options for debugging \fBvalgrind\fP.
-
-.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 in this case \fBvalgrind\fP's output will be
-interleaved with any output that the client sends to stderr.
-
-.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
-the text filename and the process ID (ie. <filename>.<pid>), so as to create
-a file per process. The specified file name may not be the empty string.
-
-.TP
-.B
---log-file-exactly=<filename>
-Just like \fB--log-file\fP, 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-file-qualifier=<VAR>
-Specifies that \fBvalgrind\fP should send all of its messages to the
-file named by the environment variable \fB$VAR\fP. 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
---max-stackframe=<number> [default: 2000000]
-The maximum size of a stack frame - if the stack pointer moves by more
-than this amount then \fBvalgrind\fP will assume that the program is
-switching to a different stack.
-
-.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
-this option. This can help in determining the program's location in
-deeply-nested call chains. Note that in most cases errors are commoned up
-using only the top four function locations (the place in the current
-function, and that of its three immediate callers). So this doesn't affect
-the total number of errors reported.
-
-.RS
-.PP
-The maximum value for this is 50. Note that higher settings will make
-\fBvalgrind\fP run a bit more slowly and take a bit more memory, but
-can be useful when working with programs with deeply-nested call chains.
-.RE
-
-.TP
-.B
--q --quiet
-Run silently, and only print error messages. Useful if you are running
-regression tests or have some other automated test machinery.
-
-.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 (or similar functions such as glibc's
-\fB__libc_start_main\fP, if \fBmain\fP is not present in the stack trace) in
-your program (subject to the \fB--num-callers\fP option.) When disabled,
-only the part of the stack backtrace up to and including \fBmain\fP 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. It shows how long
-has elapsed since the client program started.
-
-.TP
-.B
---tool=<toolname> [default: memcheck]
-Specify which tool to use. The default tool is memcheck.
-
-.TP
-.B
---trace-children=<yes|no> [default: no]
-When enabled, \fBvalgrind\fP will trace into child processes. This can be
-confusing and usually not what you want, so is disabled by default. But
-it is necessary is some cases, particularly if your program is started
-by a script.
-
-.TP
-.B
---track-fds=<yes|no> [default: no]
-Track file descriptor creation and deletion and produce a summary at the
-end of the program execution of file descriptors that are still in use.
-
-.TP
-.B
--v --verbose
-Be more verbose. Gives extra information on various aspects of your
-program, such as: the shared objects loaded, the suppressions used,
-the progress of the instrumentation and execution engines, and warnings
-about unusual behaviour. Repeating the flag increases the verbosity level.
-
-.TP
-.B
---version
-Show the version number of the \fBvalgrind\fP core. Tools can have
-their own version numbers. There is a scheme in place to ensure that
-tools only execute when the core version is one they are known to work
-with. This was done to minimise the chances of strange problems arising
-from tool-vs-core version incompatibilities.
-
-.TP
-.B
---xml=<yes|no> [default: no]
-Generate output in XML format. Only \fBmemcheck\fP and \fBnulgrind\fP
-currently support this option.
-
-.TP
-.B
---xml-user-comment=<string>
-The specified string will be output at the start of the XML file
-if XML output is requested.
-
-.SH MEMCHECK OPTIONS
-
-.TP
-.B
---freelist-vol=<number> [default: 5000000]
-When the client program releases memory using free (in C) or delete
-(C++), that memory is not immediately made available for re-allocation.
-Instead it is marked inaccessible and placed in a queue of freed blocks.
-The purpose is to delay the point at which freed-up memory comes back
-into circulation. This increases the chance that \fBmemcheck\fP will
-be able to detect invalid accesses to blocks for some significant period
-of time after they have been freed.
-
-.RS
-This flag specifies the maximum total size, in bytes, of the blocks in
-the queue. The default value is one million bytes. Increasing this
-increases the total amount of memory used by \fBmemcheck\fP but may
-detect invalid uses of freed blocks which would otherwise go undetected.
-.RE
-
-.TP
-.B
---leak-check=<yes|no|summary|full> [default: summary]
-Enables full, summary or no leak checking. When full (\fBfull\fP or
-\fByes\fP options) checking is performed, details on all leaked blocks
-are printed after the program finishes executing. When summary checking
-is enabled, a summary of all leaked memory is printed. When no leak
-checking is performed, no leaked memory details are produced. Disabling
-leak checking can speed up your program execution.
-
-.TP
-.B
---leak-resolution=<low|med|high> [default: low]
-When doing leak checking, determines how willing \fBmemcheck\fP is to
-consider different backtraces to be the same. When set to \fBlow\fP,
-the default, only the first two entries need match. When \fBmed\fP,
-four entries have to match. When \fBhigh\fP, all entries need to match.
-
-.TP
-.B
---partial-loads-ok=<yes|no> [default: no]
-Controls how \fBmemcheck\fP handles word (4-byte) loads from addresses
-for which some bytes are addressible and others are not. When enabled,
-such loads do not elicit an address error. Instead, \fBmemcheck\fP
-considers the bytes corresponding to the illegal addresses as undefined,
-and those corresponding to legal addresses are considered defined.
-
-.RS
-When disabled, loads from partially invalid addresses are treated the
-same as loads from completely invalid addresses: an illegal-address error
-is issued, and the \fBmemcheck\fP considers all bytes as invalid data.
-.RE
-
-.TP
-.B
---show-reachable=<yes|no> [default: no]
-When performing full leak checking, print out details of blocks that are
-leaked but still reachable. For details of what a reachable block is,
-see the HTML documentation.
-
-.TP
-.B
---workaround-gcc296-bugs=<yes|no> [default: no]
-When enabled, assume that reads and writes some small distance below
-the stack pointer \fB%esp\fP are due to bugs in gcc 2.96, and does not
-report them. The "small distance" is 256 bytes by default. Note that gcc
-2.96 is the default compiler on some older Linux distributions (RedHat
-7.X, Mandrake) and so you may well need to use this flag. Do not use
-it if you do not have to, as it can cause real errors to be overlooked.
-Another option is to use a gcc/g++ which does not generate accesses below
-the stack pointer. 2.95.3 seems to be a good choice in this respect.
-
-.SH CACHEGRIND OPTIONS
-
-.TP
-.B
---D1=<size>,<associativity>,<line size>
-Specify the size, associativity and line size of the level 1 data cache.
-All values are measured in bytes. If this options is not specified,
-the system value (as retrieved by the \fBCPUID\fP instruction) is used.
-
-.TP
-.B
---I1=<size>,<associativity>,<line size>
-Specify the size, associativity and line size of the level 1 instruction
-cache. All values are measured in bytes. If this options is not
-specified, the system value (as retrieved by the \fBCPUID\fP instruction)
-is used.
-
-.TP
-.B
---L2=<size>,<associativity>,<line size>
-Specify the size, associativity and line size of the level 2 cache.
-All values are measured in bytes. If this options is not specified,
-the system value (as retrieved by the \fBCPUID\fP instruction) is used.
-
-.SH MASSIF OPTIONS
-
-.TP
-.B
---alloc-fn=<name>
-Specify a function that allocates memory. This is useful for functions
-that are wrappers to \fBmalloc()\fP, which can fill up the context
-information uselessly (and give very uninformative bands on the graph).
-Functions specified will be ignored in contexts, i.e. treated as though
-they were \fBmalloc()\fP. This option can be specified multiple times
-on the command line, to name multiple functions.
-
-.TP
-.B
---depth=<number> [default: 3]
-Depth of call chains to present in the detailed heap information.
-Increasing it will give more information, but \fBmassif\fP will run the
-program more slowly, using more memory, and produce a bigger \fB.txt\fP
-or \fB.hp\fP file.
-
-.TP
-.B
---format=<text|html> [default: text]
-Produce the detailed heap information in text or HTML format. The file
-suffix used will be either \fB.txt\fP or \fB.html\fP.
-
-.TP
-.B
---heap=<yes|no> [default: yes]
-When enabled, profile heap usage in detail. Without it, the \fB.txt\fP
-or \fB.html\fP file will be very short.
-
-.TP
-.B
---heap-admin=<number> [default: 8]
-The number of admin bytes per block to use. This can only be an
-estimate of the average, since it may vary. The allocator used
-by \fBglibc\fP requires somewhere between 4 to 15 bytes per block,
-depending on various factors. It also requires admin space for freed
-blocks, although \fBmassif\fP does not count this.
-
-.TP
-.B
---stacks=<yes|no> [default: yes]
-When enabled, include stack(s) in the profile. Threaded programs can
-have multiple stacks.
-
-." .SH HELGRIND OPTIONS
-
-." .TP
-." .B
-." --private-stacks=<yes|no> [default: no]
-." Assume thread stacks are used privately.
-
-." .TP
-." .B
-." --show-last-access=<yes|some|no> [default: no]
-." Show location of last word access on error.
-
-.SH LESS FREQUENTLY USED CORE OPTIONS
-
-.TP
-.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 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
-using this parameter. The supplied value must be between 8 and 4096
-inclusive, and must be a power of two.
-
-.TP
-.B
---run-libc-freeres=<yes|no> [default: yes]
-The GNU C library (libc.so), which is used by all programs, may allocate
-memory for its own uses. Usually it doesn't bother to free that memory when
-the program ends - there would be no point, since the Linux kernel reclaims
-all process resources when a process exits anyway, so it would just slow
-things down.
-
-.RS
-.PP
-The glibc authors realised that this behaviour causes leak checkers,
-such as \fBvalgrind\fP, to falsely report leaks in glibc, when a leak
-check is done at exit. In order to avoid this, they provided a routine
-called __libc_freeres specifically to make glibc release all memory it
-has allocated. The MemCheck and AddrCheck tools therefore try and run
-__libc_freeres at exit.
-
-.PP
-Unfortunately, in some versions of glibc, __libc_freeres is sufficiently
-buggy to cause segmentation faults. This is particularly noticeable on
-Red Hat 7.1. So this flag is provided in order to inhibit the run of
-__libc_freeres. If your program seems to run fine on \fBvalgrind\fP, but
-segfaults at exit, you may find that --run-libc-freeres=no fixes that,
-although at the cost of possibly falsely reporting space leaks in libc.so.
-.RE
-
-.TP
-.B
---sim-hints=hint1,hint2,\.\.\.
-Pass miscellaneous hints to \fBvalgrind\fP which slightly modify the
-simulated behaviour in nonstandard or dangerous ways, possibly to help
-the simulation of strange features. By default no hints are enabled. Use
-with caution! Currently known hints are:
-
-.RS
-.TP
-.B
-- lax-ioctls
-If \fBvalgrind\fP encounters an \fBioctl\fP that it doesn't understand,
-it normally prints a warning message before continuing. Specifying the
-lax-ioctls hack tells \fBvalgrind\fP to be very lax about ioctl handling
-and assume that unknown ioctls just behave correctly.
-.TP
-.B
-- enable-outer
-Enable some special magic needed when the program being run is
-itself \fBvalgrind\fP.
-.RE
-
-.TP
-.B
---smc-check=<none|stack|all> [default: stack]
-Control which areas of memory \fBvalgrind\fP should consider might
-contain self modifying code.
-
-.SH CORE DEBUGGING OPTIONS
-
-.TP
-.B
-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
-
-.SH AUTHOR
-This manpage has been written by Andres Roldan <aroldan@debian.org>
-for the Debian Project, but can be used for any other distribution.
-Updated, rearranged and expanded by Robert Walsh <rjwalsh@durables.org>
-for the 2.4.0 release, and other Valgrind developers subsequently.
diff --git a/docs/xml/FAQ.xml b/docs/xml/FAQ.xml
index 66ff21c..7abd422 100644
--- a/docs/xml/FAQ.xml
+++ b/docs/xml/FAQ.xml
@@ -13,9 +13,9 @@
<year>&vg-lifespan;</year>
<holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
</copyright>
- <author>
- <email><ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></email>
- </author>
+ <legalnotice>
+ <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
+ </legalnotice>
</bookinfo>
@@ -36,11 +36,10 @@
<para>How do you pronounce "Valgrind"?</para>
</question>
<answer id="a-pronounce">
- <para>The "Val" as in the world "value". The "grind" is
- pronounced with a short 'i' -- ie. "grinned" (rhymes with
- "tinned") rather than "grined" (rhymes with "find").</para>
- <para>Don't feel bad: almost everyone gets it wrong at
- first.</para>
+ <para>The "Val" as in the world "value". The "grind" is pronounced
+ with a short 'i' -- ie. "grinned" (rhymes with "tinned") rather than
+ "grined" (rhymes with "find").</para> <para>Don't feel bad: almost
+ everyone gets it wrong at first.</para>
</answer>
</qandaentry>
@@ -49,21 +48,23 @@
<para>Where does the name "Valgrind" come from?</para>
</question>
<answer id="a-whence">
- <para>From Nordic mythology. Originally (before release) the
- project was named Heimdall, after the watchman of the Nordic
- gods. He could "see a hundred miles by day or night, hear the
- grass growing, see the wool growing on a sheep's back" (etc).
- This would have been a great name, but it was already taken by
- a security package "Heimdal".</para> <para>Keeping with the
- Nordic theme, Valgrind was chosen. Valgrind is the name of the
- main entrance to Valhalla (the Hall of the Chosen Slain in
- Asgard). Over this entrance there resides a wolf and over it
- there is the head of a boar and on it perches a huge eagle,
- whose eyes can see to the far regions of the nine worlds. Only
- those judged worthy by the guardians are allowed to pass
- through Valgrind. All others are refused entrance.</para>
- <para>It's not short for "value grinder", although that's not a
- bad guess.</para>
+
+ <para>From Nordic mythology. Originally (before release) the project
+ was named Heimdall, after the watchman of the Nordic gods. He could
+ "see a hundred miles by day or night, hear the grass growing, see the
+ wool growing on a sheep's back" (etc). This would have been a great
+ name, but it was already taken by a security package "Heimdal".</para>
+
+ <para>Keeping with the Nordic theme, Valgrind was chosen. Valgrind is
+ the name of the main entrance to Valhalla (the Hall of the Chosen
+ Slain in Asgard). Over this entrance there resides a wolf and over it
+ there is the head of a boar and on it perches a huge eagle, whose eyes
+ can see to the far regions of the nine worlds. Only those judged
+ worthy by the guardians are allowed to pass through Valgrind. All
+ others are refused entrance.</para>
+
+ <para>It's not short for "value grinder", although that's not a bad
+ guess.</para>
</answer>
</qandaentry>
@@ -85,12 +86,11 @@
</screen>
</question>
<answer id="a-make_dies">
- <para>It's probably a bug in 'make'. Some, but not all,
- instances of version 3.79.1 have this bug, see
- www.mail-archive.com/bug-make@gnu.org/msg01658.html. Try
- upgrading to a more recent version of 'make'. Alternatively,
- we have heard that unsetting the CFLAGS environment variable
- avoids the problem.</para>
+ <para>It's probably a bug in 'make'. Some, but not all, instances of
+ version 3.79.1 have this bug, see
+ www.mail-archive.com/bug-make@gnu.org/msg01658.html. Try upgrading to
+ a more recent version of 'make'. Alternatively, we have heard that
+ unsetting the CFLAGS environment variable avoids the problem.</para>
</answer>
</qandaentry>
@@ -103,98 +103,101 @@
<title>Valgrind aborts unexpectedly</title>
<qandaentry id="faq.exit_errors">
- <question id="q-exit_errors">
- <para>Programs run OK on Valgrind, but at exit produce a bunch
- of errors involving <literal>__libc_freeres()</literal>
- and then die with a segmentation fault.</para>
- </question>
- <answer id="a-exit_errors">
- <para>When the program exits, Valgrind runs the procedure
- <literal>__libc_freeres()</literal> in glibc. This is a hook
- for memory debuggers, so they can ask glibc to free up any
- memory it has used. Doing that is needed to ensure that
- Valgrind doesn't incorrectly report space leaks in glibc.</para>
- <para>Problem is that running
- <literal>__libc_freeres()</literal> in older glibc versions
- causes this crash.</para> <para>WORKAROUND FOR 1.1.X and later
- versions of Valgrind: use the
- <literal>--run-libc-freeres=no</literal> flag. You may then get
- space leak reports for glibc-allocations (please _don't_ report
- these to the glibc people, since they are not real leaks), but
- at least the program runs.</para>
- </answer>
+ <question id="q-exit_errors">
+ <para>Programs run OK on Valgrind, but at exit produce a bunch of
+ errors involving <literal>__libc_freeres()</literal> and then die
+ with a segmentation fault.</para>
+ </question>
+ <answer id="a-exit_errors">
+ <para>When the program exits, Valgrind runs the procedure
+ <function>__libc_freeres()</function> in glibc. This is a hook for
+ memory debuggers, so they can ask glibc to free up any memory it has
+ used. Doing that is needed to ensure that Valgrind doesn't
+ incorrectly report space leaks in glibc.</para>
+
+ <para>Problem is that running <literal>__libc_freeres()</literal> in
+ older glibc versions causes this crash.</para>
+
+ <para>WORKAROUND FOR 1.1.X and later versions of Valgrind: use the
+ <option>--run-libc-freeres=no</option> flag. You may then get space
+ leak reports for glibc-allocations (please _don't_ report these to
+ the glibc people, since they are not real leaks), but at least the
+ program runs.</para>
+ </answer>
</qandaentry>
<qandaentry id="faq.bugdeath">
- <question id="q-bugdeath">
- <para>My (buggy) program dies like this:</para>
+ <question id="q-bugdeath">
+ <para>My (buggy) program dies like this:</para>
<screen>% valgrind: vg_malloc2.c:442 (bszW_to_pszW): Assertion 'pszW >= 0' failed.</screen>
- </question>
- <answer id="a-bugdeath">
- <para>If Memcheck (the memory checker) shows any invalid reads,
- invalid writes and invalid frees in your program, the above may
- happen. Reason is that your program may trash Valgrind's
- low-level memory manager, which then dies with the above
- assertion, or something like this. The cure is to fix your
- program so that it doesn't do any illegal memory accesses. The
- above failure will hopefully go away after that.</para>
- </answer>
+ </question>
+ <answer id="a-bugdeath">
+ <para>If Memcheck (the memory checker) shows any invalid reads,
+ invalid writes and invalid frees in your program, the above may
+ happen. Reason is that your program may trash Valgrind's low-level
+ memory manager, which then dies with the above assertion, or
+ something like this. The cure is to fix your program so that it
+ doesn't do any illegal memory accesses. The above failure will
+ hopefully go away after that.</para>
+ </answer>
</qandaentry>
<qandaentry id="faq.msgdeath">
- <question id="q-msgdeath">
- <para>My program dies, printing a message like this along the
+ <question id="q-msgdeath">
+ <para>My program dies, printing a message like this along the
way:</para>
<screen>% disInstr: unhandled instruction bytes: 0x66 0xF 0x2E 0x5</screen>
- </question>
- <answer id="a-msgdeath">
- <para>Older versions did not support some x86 instructions,
- particularly SSE/SSE2 instructions. Try a newer Valgrind; we
- now support almost all instructions. If it still happens with
- newer versions, if the failing instruction is an SSE/SSE2
- instruction, you might be able to recompile your program
- without it by using the flag
- <computeroutput>-march</computeroutput> to gcc. Either way,
- let us know and we'll try to fix it.</para>
+ </question>
+ <answer id="a-msgdeath">
+ <para>Older versions did not support some x86 instructions,
+ particularly SSE/SSE2 instructions. Try a newer Valgrind; we now
+ support almost all instructions. If it still happens with newer
+ versions, if the failing instruction is an SSE/SSE2 instruction, you
+ might be able to recompile your program without it by using the flag
+ <option>-march</option> to gcc. Either way, let us know and we'll
+ try to fix it.</para>
- <para>Another possibility is that your program has a bug and
- erroneously jumps to a non-code address, in which case you'll
- get a SIGILL signal. Memcheck/Addrcheck may issue a warning
- just before this happens, but they might not if the jump
- happens to land in addressable memory.</para>
- </answer>
+ <para>Another possibility is that your program has a bug and
+ erroneously jumps to a non-code address, in which case you'll get a
+ SIGILL signal. Memcheck/Addrcheck may issue a warning just before
+ this happens, but they might not if the jump happens to land in
+ addressable memory.</para>
+ </answer>
</qandaentry>
<qandaentry id="faq.java">
- <question id="q-java">
- <para>I tried running a Java program (or another program that uses a
- just-in-time compiler) under Valgrind but something went wrong.
- Does Valgrind handle such programs?</para>
- </question>
- <answer id="a-java">
- <para>Valgrind can handle dynamically generated code, so long as none
- of the generated code is later overwritten by other generated code.
- If this happens, though, things will go wrong as Valgrind will continue
- running its translations of the old code (this is true on x86 and AMD64,
- on PPC32 there are explicit cache flush instructions which Valgrind
- detects). You should try running with
- <computeroutput>--smc-check=all</computeroutput> in this case; Valgrind
- will run much more slowly, but should detect the use of the out-of-date
- code.</para>
- <para>Alternativaly, if you have the source code to the JIT compiler you
- can insert calls to the
- <computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput> client
- request to mark out-of-date code, saving you from using
- <computeroutput>--smc-check=all</computeroutput>.</para>
- <para>Apart from this, in theory Valgrind can run any Java program just
- fine, even those that use JNI and are partially implemented in other
- languages like C and C++. In practice, Java implementations tend to do
- nasty things that most programs do not, and Valgrind sometimes falls
- over these corner cases.</para>
- <para>If your Java programs do not run under Valgrind, even with
- <computeroutput>--smc-check=all</computeroutput>, please file a bug
- report and hopefully we'll be able to fix the problem.</para>
- </answer>
+ <question id="q-java">
+ <para>I tried running a Java program (or another program that uses a
+ just-in-time compiler) under Valgrind but something went wrong.
+ Does Valgrind handle such programs?</para>
+ </question>
+ <answer id="a-java">
+ <para>Valgrind can handle dynamically generated code, so long as
+ none of the generated code is later overwritten by other generated
+ code. If this happens, though, things will go wrong as Valgrind
+ will continue running its translations of the old code (this is true
+ on x86 and AMD64, on PPC32 there are explicit cache flush
+ instructions which Valgrind detects). You should try running with
+ <option>--smc-check=all</option> in this case; Valgrind will run
+ much more slowly, but should detect the use of the out-of-date
+ code.</para>
+
+ <para>Alternativaly, if you have the source code to the JIT compiler
+ you can insert calls to the
+ <computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput>
+ client request to mark out-of-date code, saving you from using
+ <option>--smc-check=all</option>.</para>
+
+ <para>Apart from this, in theory Valgrind can run any Java program
+ just fine, even those that use JNI and are partially implemented in
+ other languages like C and C++. In practice, Java implementations
+ tend to do nasty things that most programs do not, and Valgrind
+ sometimes falls over these corner cases.</para>
+
+ <para>If your Java programs do not run under Valgrind, even with
+ <option>--smc-check=all</option>, please file a bug report and
+ hopefully we'll be able to fix the problem.</para>
+ </answer>
</qandaentry>
</qandadiv>
@@ -205,93 +208,89 @@
<title>Valgrind behaves unexpectedly</title>
<qandaentry id="faq.reports">
- <question id="q-reports">
- <para>My program uses the C++ STL and string classes. Valgrind
- reports 'still reachable' memory leaks involving these classes
- at the exit of the program, but there should be none.</para>
- </question>
- <answer id="a-reports">
- <para>First of all: relax, it's probably not a bug, but a
- feature. Many implementations of the C++ standard libraries
- use their own memory pool allocators. Memory for quite a
- number of destructed objects is not immediately freed and given
- back to the OS, but kept in the pool(s) for later re-use. The
- fact that the pools are not freed at the exit() of the program
- cause Valgrind to report this memory as still reachable. The
- behaviour not to free pools at the exit() could be called a bug
- of the library though.</para>
+ <question id="q-reports">
+ <para>My program uses the C++ STL and string classes. Valgrind
+ reports 'still reachable' memory leaks involving these classes at
+ the exit of the program, but there should be none.</para>
+ </question>
+ <answer id="a-reports">
+ <para>First of all: relax, it's probably not a bug, but a feature.
+ Many implementations of the C++ standard libraries use their own
+ memory pool allocators. Memory for quite a number of destructed
+ objects is not immediately freed and given back to the OS, but kept
+ in the pool(s) for later re-use. The fact that the pools are not
+ freed at the exit() of the program cause Valgrind to report this
+ memory as still reachable. The behaviour not to free pools at the
+ exit() could be called a bug of the library though.</para>
- <para>Using gcc, you can force the STL to use malloc and to
- free memory as soon as possible by globally disabling memory
- caching. Beware! Doing so will probably slow down your
- program, sometimes drastically.</para>
- <itemizedlist>
- <listitem>
- <para>With gcc 2.91, 2.95, 3.0 and 3.1, compile all source
- using the STL with <literal>-D__USE_MALLOC</literal>. Beware!
- This is removed from gcc starting with version 3.3.</para>
- </listitem>
- <listitem>
- <para>With gcc 3.2.2 and later, you should export the environment
- variable <literal>GLIBCPP_FORCE_NEW</literal> before running
- your program.</para>
- </listitem>
- <listitem>
- <para>With gcc 3.4 and later, that variable has changed name to
- <literal>GLIBCXX_FORCE_NEW</literal>.</para>
- </listitem>
- </itemizedlist>
+ <para>Using gcc, you can force the STL to use malloc and to free
+ memory as soon as possible by globally disabling memory caching.
+ Beware! Doing so will probably slow down your program, sometimes
+ drastically.</para>
+ <itemizedlist>
+ <listitem>
+ <para>With gcc 2.91, 2.95, 3.0 and 3.1, compile all source using
+ the STL with <literal>-D__USE_MALLOC</literal>. Beware! This is
+ removed from gcc starting with version 3.3.</para>
+ </listitem>
+ <listitem>
+ <para>With gcc 3.2.2 and later, you should export the
+ environment variable <literal>GLIBCPP_FORCE_NEW</literal> before
+ running your program.</para>
+ </listitem>
+ <listitem>
+ <para>With gcc 3.4 and later, that variable has changed name to
+ <literal>GLIBCXX_FORCE_NEW</literal>.</para>
+ </listitem>
+ </itemizedlist>
- <para>There are other ways to disable memory pooling: using the
- <literal>malloc_alloc</literal> template with your objects (not
- portable, but should work for gcc) or even writing your own
- memory allocators. But all this goes beyond the scope of this
- FAQ. Start by reading <ulink
- url="http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3">
- http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3</ulink>
- if you absolutely want to do that. But beware:</para>
+ <para>There are other ways to disable memory pooling: using the
+ <literal>malloc_alloc</literal> template with your objects (not
+ portable, but should work for gcc) or even writing your own memory
+ allocators. But all this goes beyond the scope of this FAQ. Start
+ by reading
+ <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3">
+ http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3</ulink> if
+ you absolutely want to do that. But beware:</para>
- <orderedlist>
- <listitem>
- <para>there are currently changes underway for gcc which are
- not totally reflected in the docs right now ("now" == 26 Apr
- 03)</para>
- </listitem>
- <listitem>
- <para>allocators belong to the more messy parts of the STL
- and people went to great lengths to make it portable across
- platforms. Chances are good that your solution will work on
- your platform, but not on others.</para>
- </listitem>
- </orderedlist>
+ <orderedlist>
+ <listitem>
+ <para>there are currently changes underway for gcc which are not
+ totally reflected in the docs right now ("now" == 26 Apr 03)</para>
+ </listitem>
+ <listitem>
+ <para>allocators belong to the more messy parts of the STL and
+ people went to great lengths to make it portable across
+ platforms. Chances are good that your solution will work on your
+ platform, but not on others.</para>
+ </listitem>
+ </orderedlist>
</answer>
</qandaentry>
<qandaentry id="faq.unhelpful">
- <question id="q-unhelpful">
- <para>The stack traces given by Memcheck (or another tool)
- aren't helpful. How can I improve them?</para>
- </question>
- <answer id="a-unhelpful">
- <para>If they're not long enough, use
- <literal>--num-callers</literal> to make them longer.</para>
- <para>If they're not detailed enough, make sure you are
- compiling with <literal>-g</literal> to add debug information.
- And don't strip symbol tables (programs should be unstripped
- unless you run 'strip' on them; some libraries ship
- stripped).</para>
+ <question id="q-unhelpful">
+ <para>The stack traces given by Memcheck (or another tool) aren't
+ helpful. How can I improve them?</para>
+ </question>
+ <answer id="a-unhelpful">
+ <para>If they're not long enough, use <option>--num-callers</option>
+ to make them longer.</para>
- <para>Also, for leak reports involving shared objects, if the shared
- object is unloaded before the program terminates, Valgrind will discard
- the debug information and the error message will be full of
- <literal>???</literal> entries. The workaround here is to avoid calling
- dlclose() on these shared objects.
- </para>
+ <para>If they're not detailed enough, make sure you are compiling
+ with <option>-g</option> to add debug information. And don't strip
+ symbol tables (programs should be unstripped unless you run 'strip'
+ on them; some libraries ship stripped).</para>
- <para>Also, <literal>-fomit-frame-pointer</literal> and
- <literal>-fstack-check</literal> can make stack traces
- worse.</para>
+ <para>Also, for leak reports involving shared objects, if the shared
+ object is unloaded before the program terminates, Valgrind will
+ discard the debug information and the error message will be full of
+ <literal>???</literal> entries. The workaround here is to avoid
+ calling dlclose() on these shared objects.</para>
+
+ <para>Also, <option>-fomit-frame-pointer</option> and
+ <option>-fstack-check</option> can make stack traces worse.</para>
<para>Some example sub-traces:</para>
@@ -352,18 +351,18 @@
</qandaentry>
<qandaentry id="faq.aliases">
- <question id="q-aliases">
- <para>The stack traces given by Memcheck (or another tool) seem to
- have the wrong function name in them. What's happening?</para>
- </question>
- <answer id="a-aliases">
- <para>Occasionally Valgrind stack traces get the wrong function names.
- This is caused by glibc using aliases to effectively give one function two
- names. Most of the time Valgrind chooses a suitable name, but very
- occasionally it gets it wrong.
- Examples we know of are printing 'bcmp' instead of 'memcmp', 'index'
- instead of 'strchr', and 'rindex' instead of 'strrchr'.</para>
- </answer>
+ <question id="q-aliases">
+ <para>The stack traces given by Memcheck (or another tool) seem to
+ have the wrong function name in them. What's happening?</para>
+ </question>
+ <answer id="a-aliases">
+ <para>Occasionally Valgrind stack traces get the wrong function
+ names. This is caused by glibc using aliases to effectively give
+ one function two names. Most of the time Valgrind chooses a
+ suitable name, but very occasionally it gets it wrong. Examples we
+ know of are printing 'bcmp' instead of 'memcmp', 'index' instead of
+ 'strchr', and 'rindex' instead of 'strrchr'.</para>
+ </answer>
</qandaentry>
</qandadiv>
@@ -375,53 +374,53 @@
<title>Memcheck doesn't find my bug</title>
<qandaentry id="faq.hiddenbug">
- <question id="q-hiddenbug">
- <para>I try running "valgrind --tool=memcheck my_program" and
- get Valgrind's startup message, but I don't get any errors and
- I know my program has errors.</para>
- </question>
- <answer id="a-hiddenbug">
- <para>There are two possible causes of this.</para>
+ <question id="q-hiddenbug">
+ <para>I try running "valgrind --tool=memcheck my_program" and get
+ Valgrind's startup message, but I don't get any errors and I know my
+ program has errors.</para>
+ </question>
+ <answer id="a-hiddenbug">
+ <para>There are two possible causes of this.</para>
- <para>First, by default, Valgrind only traces the top-level process.
- So if your program spawns children, they won't be traced by
- Valgrind by default. Also, if your program is started by a
- shell script, Perl script, or something similar, Valgrind will
- trace the shell, or the Perl interpreter, or equivalent.</para>
+ <para>First, by default, Valgrind only traces the top-level process.
+ So if your program spawns children, they won't be traced by Valgrind
+ by default. Also, if your program is started by a shell script,
+ Perl script, or something similar, Valgrind will trace the shell, or
+ the Perl interpreter, or equivalent.</para>
- <para>To trace child processes, use the
- <literal>--trace-children=yes</literal> option.</para>
+ <para>To trace child processes, use the
+ <option>--trace-children=yes</option> option.</para>
- <para>If you are tracing large trees of processes, it can be
- less disruptive to have the output sent over the network. Give
- Valgrind the flag
- <literal>--log-socket=127.0.0.1:12345</literal> (if you want
- logging output sent to <literal>port 12345</literal> on
- <literal>localhost</literal>). You can use the
- valgrind-listener program to listen on that port:</para>
+ <para>If you are tracing large trees of processes, it can be less
+ disruptive to have the output sent over the network. Give Valgrind
+ the flag <option>--log-socket=127.0.0.1:12345</option> (if you want
+ logging output sent to <literal>port 12345</literal> on
+ <literal>localhost</literal>). You can use the valgrind-listener
+ program to listen on that port:</para>
<programlisting>
valgrind-listener 12345
</programlisting>
- <para>Obviously you have to start the listener process first.
- See the manual for more details.</para>
+ <para>Obviously you have to start the listener process first. See
+ the manual for more details.</para>
- <para>Second, if your program is statically linked, most Valgrind tools
- won't work as well, because they won't be able to replace certain
- functions, such as malloc(), with their own versions. A key indicator of
- this is if Memcheck says:
+ <para>Second, if your program is statically linked, most Valgrind
+ tools won't work as well, because they won't be able to replace
+ certain functions, such as malloc(), with their own versions. A key
+ indicator of this is if Memcheck says:
<programlisting>
No malloc'd blocks -- no leaks are possible
</programlisting>
-when you know your program calls malloc(). The workaround is to avoid
-statically linking your program.</para>
- </answer>
+ when you know your program calls malloc(). The workaround is to
+ avoid statically linking your program.</para>
+ </answer>
</qandaentry>
<qandaentry id="faq.overruns">
- <question id="q-overruns">
- <para>Why doesn't Memcheck find the array overruns in this program?</para>
+ <question id="q-overruns">
+ <para>Why doesn't Memcheck find the array overruns in this
+ program?</para>
<programlisting>
int static[5];
@@ -435,13 +434,12 @@
return 0;
}
</programlisting>
- </question>
- <answer id="a-overruns">
- <para>Unfortunately, Memcheck doesn't do bounds checking on
- static or stack arrays. We'd like to, but it's just not
- possible to do in a reasonable way that fits with how Memcheck
- works. Sorry.</para>
- </answer>
+ </question>
+ <answer id="a-overruns">
+ <para>Unfortunately, Memcheck doesn't do bounds checking on static
+ or stack arrays. We'd like to, but it's just not possible to do in
+ a reasonable way that fits with how Memcheck works. Sorry.</para>
+ </answer>
</qandaentry>
</qandadiv>
@@ -453,59 +451,57 @@
<title>Miscellaneous</title>
<qandaentry id="faq.writesupp">
- <question id="q-writesupp">
- <para>I tried writing a suppression but it didn't work. Can
- you write my suppression for me?</para>
- </question>
- <answer id="a-writesupp">
- <para>Yes! Use the
- <computeroutput>--gen-suppressions=yes</computeroutput> feature
- to spit out suppressions automatically for you. You can then
- edit them if you like, eg. combining similar automatically
- generated suppressions using wildcards like
- <literal>'*'</literal>.</para>
+ <question id="q-writesupp">
+ <para>I tried writing a suppression but it didn't work. Can you
+ write my suppression for me?</para>
+ </question>
+ <answer id="a-writesupp">
+ <para>Yes! Use the <option>--gen-suppressions=yes</option> feature
+ to spit out suppressions automatically for you. You can then edit
+ them if you like, eg. combining similar automatically generated
+ suppressions using wildcards like <literal>'*'</literal>.</para>
- <para>If you really want to write suppressions by hand, read
- the manual carefully. Note particularly that C++ function
- names must be <literal>_mangled_</literal>.</para>
- </answer>
+ <para>If you really want to write suppressions by hand, read the
+ manual carefully. Note particularly that C++ function names must be
+ <literal>_mangled_</literal>.</para>
+ </answer>
</qandaentry>
<qandaentry id="faq.deflost">
- <question id="q=deflost">
- <para>With Memcheck/Addrcheck's memory leak detector, what's
- the difference between "definitely lost", "possibly lost",
- "still reachable", and "suppressed"?</para>
- </question>
- <answer id="a-deflost">
- <para>The details are in the Memcheck section of the user manual.</para>
+ <question id="q-deflost">
+ <para>With Memcheck/Addrcheck's memory leak detector, what's the
+ difference between "definitely lost", "possibly lost", "still
+ reachable", and "suppressed"?</para>
+ </question>
+ <answer id="a-deflost">
+ <para>The details are in the Memcheck section of the user
+ manual.</para>
- <para>In short:</para>
- <itemizedlist>
- <listitem>
- <para>"definitely lost" means your program is leaking memory
- -- fix it!</para>
- </listitem>
- <listitem>
- <para>"possibly lost" means your program is probably leaking
- memory, unless you're doing funny things with
- pointers.</para>
- </listitem>
- <listitem>
- <para>"still reachable" means your program is probably ok --
- it didn't free some memory it could have. This is quite
- common and often reasonable. Don't use
- <computeroutput>--show-reachable=yes</computeroutput> if you
- don't want to see these reports.</para>
- </listitem>
- <listitem>
- <para>"suppressed" means that a leak error has been
- suppressed. There are some suppressions in the default
- suppression files. You can ignore suppressed errors.</para>
- </listitem>
- </itemizedlist>
- </answer>
+ <para>In short:</para>
+ <itemizedlist>
+ <listitem>
+ <para>"definitely lost" means your program is leaking memory --
+ fix it!</para>
+ </listitem>
+ <listitem>
+ <para>"possibly lost" means your program is probably leaking
+ memory, unless you're doing funny things with pointers.</para>
+ </listitem>
+ <listitem>
+ <para>"still reachable" means your program is probably ok -- it
+ didn't free some memory it could have. This is quite common and
+ often reasonable. Don't use
+ <option>--show-reachable=yes</option> if you don't want to see
+ these reports.</para>
+ </listitem>
+ <listitem>
+ <para>"suppressed" means that a leak error has been suppressed.
+ There are some suppressions in the default suppression files.
+ You can ignore suppressed errors.</para>
+ </listitem>
+ </itemizedlist>
+ </answer>
</qandaentry>
</qandadiv>
@@ -517,21 +513,16 @@
<title>How To Get Further Assistance</title>
<qandaentry id="e-help">
-
- <answer id="a-help">
+ <!-- <question><para/></question> -->
+ <answer id="a-help">
<para>Please read all of this section before posting.</para>
<para>If you think an answer is incomplete or inaccurate, please
e-mail <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink>.</para>
-<!--
- <para>Read the appropriate section(s) of the <xref linkend="set-index"/>.</para>
--->
+
<para>Read the appropriate section(s) of the
<ulink url="&vg-bookset;">Valgrind Documentation</ulink>.</para>
-<!--
- <para>Read the <xref linkend="dist"/>.</para>
--->
<para>Read the
<ulink url="&vg-dist-docs;">Distribution Documents</ulink>.</para>
@@ -539,29 +530,30 @@
<ulink url="http://news.gmane.org/gmane.comp.debugging.valgrind">valgrind-users</ulink> mailing list archives, using the group name
<computeroutput>gmane.comp.debugging.valgrind</computeroutput>.</para>
- <para>Only when you have tried all of these things and are still stuck,
- should you post to the <ulink url="&vg-users-list;">valgrind-users
- mailing list</ulink>. In which case, please read the following
- carefully. Making a complete posting will greatly increase the chances
- that an expert or fellow user reading it will have enough information
- and motivation to reply.</para>
+ <para>Only when you have tried all of these things and are still
+ stuck, should you post to the
+ <ulink url="&vg-users-list;">valgrind-users mailing list</ulink>. In
+ which case, please read the following carefully. Making a complete
+ posting will greatly increase the chances that an expert or fellow
+ user reading it will have enough information and motivation to
+ reply.</para>
- <para>Make sure you give full details of the problem,
- including the full output of <computeroutput>valgrind -v</computeroutput>,
- if applicable. Also which Linux distribution you're using (Red Hat, Debian, etc)
- and its version number.</para>
+ <para>Make sure you give full details of the problem, including the
+ full output of <computeroutput>valgrind -v</computeroutput>, if
+ applicable. Also which Linux distribution you're using (Red Hat,
+ Debian, etc) and its version number.</para>
- <para>You are in little danger of making your posting too long
- unless you include large chunks of valgrind's (unsuppressed)
- output, so err on the side of giving too much information.</para>
+ <para>You are in little danger of making your posting too long unless
+ you include large chunks of Valgrind's (unsuppressed) output, so err
+ on the side of giving too much information.</para>
- <para>Clearly written subject lines and message bodies are appreciated,
- too.</para>
+ <para>Clearly written subject lines and message bodies are
+ appreciated, too.</para>
<para>Finally, remember that, despite the fact that most of the
- community are very helpful and responsive to emailed questions,
- you are probably requesting help from unpaid volunteers, so you
- have no guarantee of receiving an answer.</para>
+ community are very helpful and responsive to emailed questions, you
+ are probably requesting help from unpaid volunteers, so you have no
+ guarantee of receiving an answer.</para>
</answer>
</qandaentry>
diff --git a/docs/xml/dist-docs.xml b/docs/xml/dist-docs.xml
index 85302a8..e963adf 100644
--- a/docs/xml/dist-docs.xml
+++ b/docs/xml/dist-docs.xml
@@ -6,17 +6,17 @@
<book id="dist" xreflabel="Distribution Documents">
- <bookinfo>
- <title>Valgrind Distribution Documents</title>
+<bookinfo>
+ <title>Valgrind Distribution Documents</title>
<releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo>
<copyright>
<year>&vg-lifespan;</year>
<holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
</copyright>
- <author>
- <email><ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></email>
- </author>
- </bookinfo>
+ <legalnotice>
+ <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
+ </legalnotice>
+</bookinfo>
<!-- Nb: because these are all text files, we have to wrap -->
<!-- them in suitable XML. Hence the chapter/title stuff -->
diff --git a/docs/xml/index.xml b/docs/xml/index.xml
index 0feec65..475e631 100644
--- a/docs/xml/index.xml
+++ b/docs/xml/index.xml
@@ -1,6 +1,6 @@
<?xml version="1.0"?> <!-- -*- sgml -*- -->
<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml
index 4585812..c825720 100644
--- a/docs/xml/manual-core.xml
+++ b/docs/xml/manual-core.xml
@@ -7,81 +7,77 @@
<chapter id="manual-core" xreflabel="Valgrind's core">
<title>Using and understanding the Valgrind core</title>
-<para>This section describes the Valgrind core services, flags
-and behaviours. That means it is relevant regardless of what
-particular tool you are using. A point of terminology: most
-references to "valgrind" in the rest of this section (Section 2)
-refer to the valgrind core services.</para>
+<para>This section describes the Valgrind core services, flags and
+behaviours. That means it is relevant regardless of what particular
+tool you are using. A point of terminology: most references to
+"valgrind" in the rest of this section (Section 2) refer to the Valgrind
+core services.</para>
<sect1 id="manual-core.whatdoes"
xreflabel="What Valgrind does with your program">
<title>What Valgrind does with your program</title>
-<para>Valgrind is designed to be as non-intrusive as possible. It
-works directly with existing executables. You don't need to
-recompile, relink, or otherwise modify, the program to be
-checked.</para>
+<para>Valgrind is designed to be as non-intrusive as possible. It works
+directly with existing executables. You don't need to recompile, relink,
+or otherwise modify, the program to be checked.</para>
-<para>Simply put <computeroutput>valgrind
---tool=tool_name</computeroutput> at the start of the command
-line normally used to run the program. For example, if want to
-run the command <computeroutput>ls -l</computeroutput> using the
-heavyweight memory-checking tool Memcheck, issue the
-command:</para>
+<para>Simply put
+<computeroutput>valgrind --tool=tool_name</computeroutput>
+at the start of the command line normally used to run the program. For
+example, if want to run the command
+<computeroutput>ls -l</computeroutput> using the heavyweight
+memory-checking tool Memcheck, issue the command:</para>
<programlisting><![CDATA[
valgrind --tool=memcheck ls -l]]></programlisting>
<para>(Memcheck is the default, so if you want to use it you can
-actually omit the <computeroutput>--tool</computeroutput> flag.</para>
+actually omit the <option>--tool</option> flag.</para>
-<para>Regardless of which tool is in use, Valgrind takes control
-of your program before it starts. Debugging information is read
-from the executable and associated libraries, so that error
-messages and other outputs can be phrased in terms of source code
-locations (if that is appropriate).</para>
+<para>Regardless of which tool is in use, Valgrind takes control of your
+program before it starts. Debugging information is read from the
+executable and associated libraries, so that error messages and other
+outputs can be phrased in terms of source code locations (if that is
+appropriate).</para>
-<para>Your program is then run on a synthetic CPU provided by
-the Valgrind core. As new code is executed for the first time,
-the core hands the code to the selected tool. The tool adds its
-own instrumentation code to this and hands the result back to the
-core, which coordinates the continued execution of this
-instrumented code.</para>
+<para>Your program is then run on a synthetic CPU provided by the
+Valgrind core. As new code is executed for the first time, the core
+hands the code to the selected tool. The tool adds its own
+instrumentation code to this and hands the result back to the core,
+which coordinates the continued execution of this instrumented
+code.</para>
-<para>The amount of instrumentation code added varies widely
-between tools. At one end of the scale, Memcheck adds code to
-check every memory access and every value computed, increasing
-the size of the code at least 12 times, and making it run 25-50
-times slower than natively. At the other end of the spectrum,
-the ultra-trivial "none" tool (a.k.a. Nulgrind) adds no
-instrumentation at all and causes in total "only" about a 4 times
-slowdown.</para>
+<para>The amount of instrumentation code added varies widely between
+tools. At one end of the scale, Memcheck adds code to check every
+memory access and every value computed, increasing the size of the code
+at least 12 times, and making it run 25-50 times slower than natively.
+At the other end of the spectrum, the ultra-trivial "none" tool
+(a.k.a. Nulgrind) adds no instrumentation at all and causes in total
+"only" about a 4 times slowdown.</para>
-<para>Valgrind simulates every single instruction your program
-executes. Because of this, the active tool checks, or profiles,
-not only the code in your application but also in all supporting
-dynamically-linked (<computeroutput>.so</computeroutput>-format)
-libraries, including the GNU C library, the X client libraries,
-Qt, if you work with KDE, and so on.</para>
+<para>Valgrind simulates every single instruction your program executes.
+Because of this, the active tool checks, or profiles, not only the code
+in your application but also in all supporting dynamically-linked
+(<computeroutput>.so</computeroutput>-format) libraries, including the
+GNU C library, the X client libraries, Qt, if you work with KDE, and so
+on.</para>
-<para>If you're using one of the error-detection tools, Valgrind
-will often detect errors in libraries, for example the GNU C or
-X11 libraries, which you have to use. You might not be
-interested in these errors, since you probably have no control
-over that code. Therefore, Valgrind allows you to selectively
-suppress errors, by recording them in a suppressions file which
-is read when Valgrind starts up. The build mechanism attempts to
-select suppressions which give reasonable behaviour for the libc
-and XFree86 versions detected on your machine. To make it easier
-to write suppressions, you can use the
-<computeroutput>--gen-suppressions=yes</computeroutput> option
-which tells Valgrind to print out a suppression for each error
-that appears, which you can then copy into a suppressions
-file.</para>
+<para>If you're using one of the error-detection tools, Valgrind will
+often detect errors in libraries, for example the GNU C or X11
+libraries, which you have to use. You might not be interested in these
+errors, since you probably have no control over that code. Therefore,
+Valgrind allows you to selectively suppress errors, by recording them in
+a suppressions file which is read when Valgrind starts up. The build
+mechanism attempts to select suppressions which give reasonable
+behaviour for the libc and XFree86 versions detected on your machine.
+To make it easier to write suppressions, you can use the
+<option>--gen-suppressions=yes</option> option which tells Valgrind to
+print out a suppression for each error that appears, which you can then
+copy into a suppressions file.</para>
-<para>Different error-checking tools report different kinds of
-errors. The suppression mechanism therefore allows you to say
-which tool or tool(s) each suppression applies to.</para>
+<para>Different error-checking tools report different kinds of errors.
+The suppression mechanism therefore allows you to say which tool or
+tool(s) each suppression applies to.</para>
</sect1>
@@ -89,221 +85,199 @@
<sect1 id="manual-core.started" xreflabel="Getting started">
<title>Getting started</title>
-<para>First off, consider whether it might be beneficial to
-recompile your application and supporting libraries with
-debugging info enabled (the <computeroutput>-g</computeroutput>
-flag). Without debugging info, the best Valgrind tools will be
-able to do is guess which function a particular piece of code
-belongs to, which makes both error messages and profiling output
-nearly useless. With <computeroutput>-g</computeroutput>, you'll
-hopefully get messages which point directly to the relevant
-source code lines.</para>
+<para>First off, consider whether it might be beneficial to recompile
+your application and supporting libraries with debugging info enabled
+(the <option>-g</option> flag). Without debugging info, the best
+Valgrind tools will be able to do is guess which function a particular
+piece of code belongs to, which makes both error messages and profiling
+output nearly useless. With <option>-g</option>, you'll hopefully get
+messages which point directly to the relevant source code lines.</para>
-<para>Another flag you might like to consider, if you are working
-with C++, is <computeroutput>-fno-inline</computeroutput>. That
-makes it easier to see the function-call chain, which can help
-reduce confusion when navigating around large C++ apps. For
-whatever it's worth, debugging OpenOffice.org with Memcheck is a
-bit easier when using this flag.
-You don't have to do this, but doing so helps Valgrind
-produce more accurate and less confusing error reports. Chances
-are you're set up like this already, if you intended to debug
-your program with GNU gdb, or some other debugger.</para>
+<para>Another flag you might like to consider, if you are working with
+C++, is <option>-fno-inline</option>. That makes it easier to see the
+function-call chain, which can help reduce confusion when navigating
+around large C++ apps. For whatever it's worth, debugging
+OpenOffice.org with Memcheck is a bit easier when using this flag. You
+don't have to do this, but doing so helps Valgrind produce more accurate
+and less confusing error reports. Chances are you're set up like this
+already, if you intended to debug your program with GNU gdb, or some
+other debugger.</para>
-<para>This paragraph applies only if you plan to use Memcheck: On
-rare occasions, optimisation levels at
-<computeroutput>-O2</computeroutput> and above have been observed
-to generate code which fools Memcheck into wrongly reporting
-uninitialised value errors. We have looked in detail into fixing
-this, and unfortunately the result is that doing so would give a
-further significant slowdown in what is already a slow tool. So
-the best solution is to turn off optimisation altogether. Since
-this often makes things unmanagably slow, a plausible compromise
-is to use <computeroutput>-O</computeroutput>. This gets you the
-majority of the benefits of higher optimisation levels whilst
-keeping relatively small the chances of false complaints from
-Memcheck. All other tools (as far as we know) are unaffected by
-optimisation level.</para>
+<para>This paragraph applies only if you plan to use Memcheck: On rare
+occasions, optimisation levels at <computeroutput>-O2</computeroutput>
+and above have been observed to generate code which fools Memcheck into
+wrongly reporting uninitialised value errors. We have looked in detail
+into fixing this, and unfortunately the result is that doing so would
+give a further significant slowdown in what is already a slow tool. So
+the best solution is to turn off optimisation altogether. Since this
+often makes things unmanagably slow, a plausible compromise is to use
+<computeroutput>-O</computeroutput>. This gets you the majority of the
+benefits of higher optimisation levels whilst keeping relatively small
+the chances of false complaints from Memcheck. All other tools (as far
+as we know) are unaffected by optimisation level.</para>
-<para>Valgrind understands both the older "stabs" debugging
-format, used by gcc versions prior to 3.1, and the newer DWARF2
-format used by gcc 3.1 and later. We continue to refine and
-debug our debug-info readers, although the majority of effort
-will naturally enough go into the newer DWARF2 reader.</para>
+<para>Valgrind understands both the older "stabs" debugging format, used
+by gcc versions prior to 3.1, and the newer DWARF2 format used by gcc
+3.1 and later. We continue to refine and debug our debug-info readers,
+although the majority of effort will naturally enough go into the newer
+DWARF2 reader.</para>
<para>When you're ready to roll, just run your application as you
-would normally, but place <computeroutput>valgrind
---tool=tool_name</computeroutput> in front of your usual
-command-line invocation. Note that you should run the real
-(machine-code) executable here. If your application is started
-by, for example, a shell or perl script, you'll need to modify it
-to invoke Valgrind on the real executables. Running such scripts
-directly under Valgrind will result in you getting error reports
-pertaining to <computeroutput>/bin/sh</computeroutput>,
-<computeroutput>/usr/bin/perl</computeroutput>, or whatever
-interpreter you're using. This may not be what you want and can
-be confusing. You can force the issue by giving the flag
-<computeroutput>--trace-children=yes</computeroutput>, but
-confusion is still likely.</para>
+would normally, but place
+<computeroutput>valgrind --tool=tool_name</computeroutput> in front of
+your usual command-line invocation. Note that you should run the real
+(machine-code) executable here. If your application is started by, for
+example, a shell or perl script, you'll need to modify it to invoke
+Valgrind on the real executables. Running such scripts directly under
+Valgrind will result in you getting error reports pertaining to
+<computeroutput>/bin/sh</computeroutput>,
+<computeroutput>/usr/bin/perl</computeroutput>, or whatever interpreter
+you're using. This may not be what you want and can be confusing. You
+can force the issue by giving the flag
+<option>--trace-children=yes</option>, but confusion is still
+likely.</para>
</sect1>
-<sect1 id="manual-core.comment" xreflabel="The commentary">
-<title>The commentary</title>
+<sect1 id="manual-core.comment" xreflabel="The Commentary">
+<title>The Commentary</title>
-<para>Valgrind tools write a commentary, a stream of text,
-detailing error reports and other significant events. All lines
-in the commentary have following form:
+<para>Valgrind tools write a commentary, a stream of text, detailing
+error reports and other significant events. All lines in the commentary
+have following form:
<programlisting><![CDATA[
==12345== some-message-from-Valgrind]]></programlisting>
</para>
-<para>The <computeroutput>12345</computeroutput> is the process
-ID. This scheme makes it easy to distinguish program output from
-Valgrind commentary, and also easy to differentiate commentaries
-from different processes which have become merged together, for
-whatever reason.</para>
+<para>The <computeroutput>12345</computeroutput> is the process ID.
+This scheme makes it easy to distinguish program output from Valgrind
+commentary, and also easy to differentiate commentaries from different
+processes which have become merged together, for whatever reason.</para>
-<para>By default, Valgrind tools write only essential messages to
-the commentary, so as to avoid flooding you with information of
-secondary importance. If you want more information about what is
-happening, re-run, passing the
-<computeroutput>-v</computeroutput> flag to Valgrind.
-A second <computeroutput>-v</computeroutput> gives yet more detail.
+<para>By default, Valgrind tools write only essential messages to the
+commentary, so as to avoid flooding you with information of secondary
+importance. If you want more information about what is happening,
+re-run, passing the <option>-v</option> flag to Valgrind. A second
+<option>-v</option> gives yet more detail.
</para>
-<para>You can direct the commentary to three different
-places:</para>
+<para>You can direct the commentary to three different places:</para>
<orderedlist>
- <listitem id="manual-core.out2fd" xreflabel="Directing output to fd">
- <para>The default: send it to a file descriptor, which is by
- default 2 (stderr). So, if you give the core no options, it
- will write commentary to the standard error stream. If you
- want to send it to some other file descriptor, for example
- number 9, you can specify
- <computeroutput>--log-fd=9</computeroutput>.</para>
- <para>This is the simplest and most common arrangement, but can
- cause problems when Valgrinding entire trees of
- processes which expect specific file descriptors, particularly
- stdin/stdout/stderr, to be available for their own use.
- </para>
+ <listitem id="manual-core.out2fd" xreflabel="Directing output to fd">
+ <para>The default: send it to a file descriptor, which is by default
+ 2 (stderr). So, if you give the core no options, it will write
+ commentary to the standard error stream. If you want to send it to
+ some other file descriptor, for example number 9, you can specify
+ <option>--log-fd=9</option>.</para>
+
+ <para>This is the simplest and most common arrangement, but can
+ cause problems when valgrinding entire trees of processes which
+ expect specific file descriptors, particularly stdin/stdout/stderr,
+ to be available for their own use.</para>
</listitem>
<listitem id="manual-core.out2file"
- xreflabel="Directing output to file">
- <para>A less intrusive option is to write the commentary to a
- file, which you specify by
- <computeroutput>--log-file=filename</computeroutput>. Note
- carefully that the commentary is <command>not</command>
- written to the file you specify, but instead to one called
- <computeroutput>filename.12345</computeroutput>, if for
- example the pid of the traced process is 12345. This is
- helpful when valgrinding a whole tree of processes at once,
- since it means that each process writes to its own logfile,
- rather than the result being jumbled up in one big
- logfile. If <computeroutput>filename.12345</computeroutput> already
- exists, then it will name new files
- <computeroutput>filename.12345.1</computeroutput> and so on.
- </para>
+ xreflabel="Directing output to file"> <para>A less intrusive
+ option is to write the commentary to a file, which you specify by
+ <option>--log-file=filename</option>. Note carefully that the
+ commentary is <command>not</command> written to the file you
+ specify, but instead to one called
+ <filename>filename.12345</filename>, if for example the pid of the
+ traced process is 12345. This is helpful when valgrinding a whole
+ tree of processes at once, since it means that each process writes
+ to its own logfile, rather than the result being jumbled up in one
+ big logfile. If <filename>filename.12345</filename> already exists,
+ then it will name new files <filename>filename.12345.1</filename>
+ and so on.</para>
- <para>If you want to specify precisely the file name to use,
- without the trailing
- <computeroutput>.12345</computeroutput> part, you can instead use
- <computeroutput>--log-file-exactly=filename</computeroutput>.
- </para>
+ <para>If you want to specify precisely the file name to use, without
+ the trailing <computeroutput>.12345</computeroutput> part, you can
+ instead use <option>--log-file-exactly=filename</option>.</para>
- <para>You can also use the
- <computeroutput>--log-file-qualifier=<VAR></computeroutput> option
- to modify the filename via according to the environment variable
- <computeroutput>VAR</computeroutput>. This is rarely needed, but
- very useful in certain circumstances (eg. when running MPI programs).
- In this case, the trailing <computeroutput>.12345</computeroutput>
- part is replaced by the contents of
- <computeroutput>$VAR</computeroutput>. The idea is that you
- specify a variable which will be set differently for each process
- in the job, for example <computeroutput>BPROC_RANK</computeroutput>
- or whatever is applicable in your MPI setup.
- </para>
+ <para>You can also use the
+ <option>--log-file-qualifier=<VAR></option> option to modify
+ the filename via according to the environment variable
+ <varname>VAR</varname>. This is rarely needed, but very useful in
+ certain circumstances (eg. when running MPI programs). In this
+ case, the trailing <computeroutput>.12345</computeroutput> part is
+ replaced by the contents of <varname>$VAR</varname>. The idea is
+ that you specify a variable which will be set differently for each
+ process in the job, for example
+ <computeroutput>BPROC_RANK</computeroutput> or whatever is
+ applicable in your MPI setup.</para>
</listitem>
<listitem id="manual-core.out2socket"
- xreflabel="Directing output to network socket">
- <para>The least intrusive option is to send the commentary to
- a network socket. The socket is specified as an IP address
- and port number pair, like this:
- <computeroutput>--log-socket=192.168.0.1:12345</computeroutput>
- if you want to send the output to host IP 192.168.0.1 port
- 12345 (I have no idea if 12345 is a port of pre-existing
- significance). You can also omit the port number:
- <computeroutput>--log-socket=192.168.0.1</computeroutput>, in
- which case a default port of 1500 is used. This default is
- defined by the constant
- <computeroutput>VG_CLO_DEFAULT_LOGPORT</computeroutput> in the
- sources.</para>
+ xreflabel="Directing output to network socket"> <para>The
+ least intrusive option is to send the commentary to a network
+ socket. The socket is specified as an IP address and port number
+ pair, like this: <option>--log-socket=192.168.0.1:12345</option> if
+ you want to send the output to host IP 192.168.0.1 port 12345 (I
+ have no idea if 12345 is a port of pre-existing significance). You
+ can also omit the port number:
+ <option>--log-socket=192.168.0.1</option>, in which case a default
+ port of 1500 is used. This default is defined by the constant
+ <computeroutput>VG_CLO_DEFAULT_LOGPORT</computeroutput> in the
+ sources.</para>
- <para>Note, unfortunately, that you have to use an IP address
- here, rather than a hostname.</para>
+ <para>Note, unfortunately, that you have to use an IP address here,
+ rather than a hostname.</para>
- <para>Writing to a network socket is pretty useless if you
- don't have something listening at the other end. We provide a
- simple listener program,
- <computeroutput>valgrind-listener</computeroutput>, which
- accepts connections on the specified port and copies whatever
- it is sent to stdout. Probably someone will tell us this is a
- horrible security risk. It seems likely that people will
- write more sophisticated listeners in the fullness of
- time.</para>
+ <para>Writing to a network socket is pretty useless if you don't
+ have something listening at the other end. We provide a simple
+ listener program,
+ <computeroutput>valgrind-listener</computeroutput>, which accepts
+ connections on the specified port and copies whatever it is sent to
+ stdout. Probably someone will tell us this is a horrible security
+ risk. It seems likely that people will write more sophisticated
+ listeners in the fullness of time.</para>
- <para>valgrind-listener can accept simultaneous connections
- from up to 50 valgrinded processes. In front of each line of
- output it prints the current number of active connections in
- round brackets.</para>
+ <para>valgrind-listener can accept simultaneous connections from up
+ to 50 valgrinded processes. In front of each line of output it
+ prints the current number of active connections in round
+ brackets.</para>
- <para>valgrind-listener accepts two command-line flags:</para>
+ <para>valgrind-listener accepts two command-line flags:</para>
<itemizedlist>
- <listitem>
- <para><computeroutput>-e</computeroutput> or
- <computeroutput>--exit-at-zero</computeroutput>: when the
- number of connected processes falls back to zero, exit.
- Without this, it will run forever, that is, until you send
- it Control-C.</para>
- </listitem>
- <listitem>
- <para><computeroutput>portnumber</computeroutput>: changes
- the port it listens on from the default (1500). The
- specified port must be in the range 1024 to 65535. The
- same restriction applies to port numbers specified by a
- <computeroutput>--log-socket=</computeroutput> to Valgrind
- itself.</para>
- </listitem>
+ <listitem>
+ <para><option>-e</option> or <option>--exit-at-zero</option>:
+ when the number of connected processes falls back to zero,
+ exit. Without this, it will run forever, that is, until you
+ send it Control-C.</para>
+ </listitem>
+ <listitem>
+ <para><option>portnumber</option>: changes the port it listens
+ on from the default (1500). The specified port must be in the
+ range 1024 to 65535. The same restriction applies to port
+ numbers specified by a <option>--log-socket</option> to
+ Valgrind itself.</para>
+ </listitem>
</itemizedlist>
- <para>If a valgrinded process fails to connect to a listener,
- for whatever reason (the listener isn't running, invalid or
- unreachable host or port, etc), Valgrind switches back to
- writing the commentary to stderr. The same goes for any
- process which loses an established connection to a listener.
- In other words, killing the listener doesn't kill the
- processes sending data to it.</para>
+ <para>If a valgrinded process fails to connect to a listener, for
+ whatever reason (the listener isn't running, invalid or unreachable
+ host or port, etc), Valgrind switches back to writing the commentary
+ to stderr. The same goes for any process which loses an established
+ connection to a listener. In other words, killing the listener
+ doesn't kill the processes sending data to it.</para>
</listitem>
- </orderedlist>
-<para>Here is an important point about the relationship between
-the commentary and profiling output from tools. The commentary
-contains a mix of messages from the Valgrind core and the
-selected tool. If the tool reports errors, it will report them
-to the commentary. However, if the tool does profiling, the
-profile data will be written to a file of some kind, depending on
-the tool, and independent of what
-<computeroutput>--log-*</computeroutput> options are in force.
-The commentary is intended to be a low-bandwidth, human-readable
-channel. Profiling data, on the other hand, is usually
-voluminous and not meaningful without further processing, which
-is why we have chosen this arrangement.</para>
+</orderedlist>
+
+<para>Here is an important point about the relationship between the
+commentary and profiling output from tools. The commentary contains a
+mix of messages from the Valgrind core and the selected tool. If the
+tool reports errors, it will report them to the commentary. However, if
+the tool does profiling, the profile data will be written to a file of
+some kind, depending on the tool, and independent of what
+<option>--log-*</option> options are in force. The commentary is
+intended to be a low-bandwidth, human-readable channel. Profiling data,
+on the other hand, is usually voluminous and not meaningful without
+further processing, which is why we have chosen this arrangement.</para>
</sect1>
@@ -312,8 +286,8 @@
<title>Reporting of errors</title>
<para>When one of the error-checking tools (Memcheck, Addrcheck,
-Helgrind) detects something bad happening in the program, an
-error message is written to the commentary. For example:</para>
+Helgrind) detects something bad happening in the program, an error
+message is written to the commentary. For example:</para>
<programlisting><![CDATA[
==25832== Invalid read of size 4
@@ -321,42 +295,39 @@
==25832== by 0x80487AF: main (bogon.cpp:66)
==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd]]></programlisting>
-<para>This message says that the program did an illegal 4-byte
-read of address 0xBFFFF74C, which, as far as Memcheck can tell,
-is not a valid stack address, nor corresponds to any currently
-malloc'd or free'd blocks. The read is happening at line 45 of
-<filename>bogon.cpp</filename>, called from line 66 of the same
-file, etc. For errors associated with an identified
-malloc'd/free'd block, for example reading free'd memory,
-Valgrind reports not only the location where the error happened,
-but also where the associated block was malloc'd/free'd.</para>
+<para>This message says that the program did an illegal 4-byte read of
+address 0xBFFFF74C, which, as far as Memcheck can tell, is not a valid
+stack address, nor corresponds to any currently malloc'd or free'd
+blocks. The read is happening at line 45 of
+<filename>bogon.cpp</filename>, called from line 66 of the same file,
+etc. For errors associated with an identified malloc'd/free'd block,
+for example reading free'd memory, Valgrind reports not only the
+location where the error happened, but also where the associated block
+was malloc'd/free'd.</para>
-<para>Valgrind remembers all error reports. When an error is
-detected, it is compared against old reports, to see if it is a
-duplicate. If so, the error is noted, but no further commentary
-is emitted. This avoids you being swamped with bazillions of
-duplicate error reports.</para>
+<para>Valgrind remembers all error reports. When an error is detected,
+it is compared against old reports, to see if it is a duplicate. If so,
+the error is noted, but no further commentary is emitted. This avoids
+you being swamped with bazillions of duplicate error reports.</para>
-<para>If you want to know how many times each error occurred, run
-with the <computeroutput>-v</computeroutput> option. When
-execution finishes, all the reports are printed out, along with,
-and sorted by, their occurrence counts. This makes it easy to
-see which errors have occurred most frequently.</para>
+<para>If you want to know how many times each error occurred, run with
+the <option>-v</option> option. When execution finishes, all the
+reports are printed out, along with, and sorted by, their occurrence
+counts. This makes it easy to see which errors have occurred most
+frequently.</para>
-<para>Errors are reported before the associated operation
-actually happens. If you're using a tool (Memcheck, Addrcheck)
-which does address checking, and your program attempts to read
-from address zero, the tool will emit a message to this effect,
-and the program will then duly die with a segmentation
-fault.</para>
+<para>Errors are reported before the associated operation actually
+happens. If you're using a tool (Memcheck, Addrcheck) which does
+address checking, and your program attempts to read from address zero,
+the tool will emit a message to this effect, and the program will then
+duly die with a segmentation fault.</para>
-<para>In general, you should try and fix errors in the order that
-they are reported. Not doing so can be confusing. For example,
-a program which copies uninitialised values to several memory
-locations, and later uses them, will generate several error
-messages, when run on Memcheck. The first such error message may
-well give the most direct clue to the root cause of the
-problem.</para>
+<para>In general, you should try and fix errors in the order that they
+are reported. Not doing so can be confusing. For example, a program
+which copies uninitialised values to several memory locations, and later
+uses them, will generate several error messages, when run on Memcheck.
+The first such error message may well give the most direct clue to the
+root cause of the problem.</para>
<para>The process of detecting duplicate errors is quite an
expensive one and can become a significant performance overhead
@@ -371,10 +342,9 @@
if necessary.</para>
<para>To avoid this cutoff you can use the
-<computeroutput>--error-limit=no</computeroutput> flag. Then
-Valgrind will always show errors, regardless of how many there
-are. Use this flag carefully, since it may have a bad effect on
-performance.</para>
+<option>--error-limit=no</option> flag. Then Valgrind will always show
+errors, regardless of how many there are. Use this flag carefully,
+since it may have a bad effect on performance.</para>
</sect1>
@@ -382,136 +352,124 @@
<sect1 id="manual-core.suppress" xreflabel="Suppressing errors">
<title>Suppressing errors</title>
-<para>The error-checking tools detect numerous problems in the
-base libraries, such as the GNU C library, and the XFree86 client
-libraries, which come pre-installed on your GNU/Linux system.
-You can't easily fix these, but you don't want to see these
-errors (and yes, there are many!) So Valgrind reads a list of
-errors to suppress at startup. A default suppression file is
-cooked up by the <computeroutput>./configure</computeroutput>
-script when the system is built.</para>
+<para>The error-checking tools detect numerous problems in the base
+libraries, such as the GNU C library, and the XFree86 client libraries,
+which come pre-installed on your GNU/Linux system. You can't easily fix
+these, but you don't want to see these errors (and yes, there are many!)
+So Valgrind reads a list of errors to suppress at startup. A default
+suppression file is cooked up by the
+<computeroutput>./configure</computeroutput> script when the system is
+built.</para>
-<para>You can modify and add to the suppressions file at your
-leisure, or, better, write your own. Multiple suppression files
-are allowed. This is useful if part of your project contains
-errors you can't or don't want to fix, yet you don't want to
-continuously be reminded of them.</para>
+<para>You can modify and add to the suppressions file at your leisure,
+or, better, write your own. Multiple suppression files are allowed.
+This is useful if part of your project contains errors you can't or
+don't want to fix, yet you don't want to continuously be reminded of
+them.</para>
-<formalpara><title>Note:</title>
-<para>By far the easiest way to add suppressions is to use the
-<computeroutput>--gen-suppressions=yes</computeroutput> flag
+<formalpara><title>Note:</title> <para>By far the easiest way to add
+suppressions is to use the <option>--gen-suppressions=yes</option> flag
described in <xref linkend="manual-core.flags"/>.</para>
</formalpara>
-<para>Each error to be suppressed is described very specifically,
-to minimise the possibility that a suppression-directive
-inadvertantly suppresses a bunch of similar errors which you did
-want to see. The suppression mechanism is designed to allow
-precise yet flexible specification of errors to suppress.</para>
+<para>Each error to be suppressed is described very specifically, to
+minimise the possibility that a suppression-directive inadvertantly
+suppresses a bunch of similar errors which you did want to see. The
+suppression mechanism is designed to allow precise yet flexible
+specification of errors to suppress.</para>
-<para>If you use the <computeroutput>-v</computeroutput> flag, at
-the end of execution, Valgrind prints out one line for each used
-suppression, giving its name and the number of times it got used.
-Here's the suppressions used by a run of <computeroutput>valgrind
---tool=memcheck ls -l</computeroutput>:</para>
+<para>If you use the <option>-v</option> flag, at the end of execution,
+Valgrind prints out one line for each used suppression, giving its name
+and the number of times it got used. Here's the suppressions used by a
+run of <computeroutput>valgrind --tool=memcheck ls l</computeroutput>:</para>
<programlisting><![CDATA[
--27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getgrgid_r
--27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getpwuid_r
--27579-- supp: 6 strrchr/_dl_map_object_from_fd/_dl_map_object]]></programlisting>
-<para>Multiple suppressions files are allowed. By default,
-Valgrind uses
-<computeroutput>$PREFIX/lib/valgrind/default.supp</computeroutput>.
-You can ask to add suppressions from another file, by specifying
-<computeroutput>--suppressions=/path/to/file.supp</computeroutput>.
+<para>Multiple suppressions files are allowed. By default, Valgrind
+uses <filename>$PREFIX/lib/valgrind/default.supp</filename>. You can
+ask to add suppressions from another file, by specifying
+<option>--suppressions=/path/to/file.supp</option>.
</para>
-<para>If you want to understand more about suppressions, look at
-an existing suppressions file whilst reading the following
-documentation. The file
-<computeroutput>glibc-2.2.supp</computeroutput>, in the source
+<para>If you want to understand more about suppressions, look at an
+existing suppressions file whilst reading the following documentation.
+The file <filename>glibc-2.2.supp</filename>, in the source
distribution, provides some good examples.</para>
<para>Each suppression has the following components:</para>
- <itemizedlist>
+<itemizedlist>
<listitem>
- <para>First line: its name. This merely gives a handy name to
- the suppression, by which it is referred to in the summary of
- used suppressions printed out when a program finishes. It's
- not important what the name is; any identifying string will
- do.</para>
+ <para>First line: its name. This merely gives a handy name to the
+ suppression, by which it is referred to in the summary of used
+ suppressions printed out when a program finishes. It's not
+ important what the name is; any identifying string will do.</para>
</listitem>
<listitem>
- <para>Second line: name of the tool(s) that the suppression is
- for (if more than one, comma-separated), and the name of the
- suppression itself, separated by a colon (Nb: no spaces are
- allowed), eg:</para>
-
+ <para>Second line: name of the tool(s) that the suppression is for
+ (if more than one, comma-separated), and the name of the suppression
+ itself, separated by a colon (Nb: no spaces are allowed), eg:</para>
<programlisting><![CDATA[
tool_name1,tool_name2:suppression_name]]></programlisting>
- <para>Recall that Valgrind-2.0.X is a modular system, in which
- different instrumentation tools can observe your program
- whilst it is running. Since different tools detect different
- kinds of errors, it is necessary to say which tool(s) the
- suppression is meaningful to.</para>
+ <para>Recall that valgrind-2.0.X is a modular system, in which
+ different instrumentation tools can observe your program whilst it
+ is running. Since different tools detect different kinds of errors,
+ it is necessary to say which tool(s) the suppression is meaningful
+ to.</para>
- <para>Tools will complain, at startup, if a tool does not
- understand any suppression directed to it. Tools ignore
- suppressions which are not directed to them. As a result, it
- is quite practical to put suppressions for all tools into the
- same suppression file.</para>
+ <para>Tools will complain, at startup, if a tool does not understand
+ any suppression directed to it. Tools ignore suppressions which are
+ not directed to them. As a result, it is quite practical to put
+ suppressions for all tools into the same suppression file.</para>
- <para>Valgrind's core can detect certain PThreads API errors,
- for which this line reads:</para>
+ <para>Valgrind's core can detect certain PThreads API errors, for
+ which this line reads:</para>
<programlisting><![CDATA[
core:PThread]]></programlisting>
</listitem>
<listitem>
- <para>Next line: a small number of suppression types have
- extra information after the second line (eg. the
- <computeroutput>Param</computeroutput> suppression for
- Memcheck)</para>
+ <para>Next line: a small number of suppression types have extra
+ information after the second line (eg. the <varname>Param</varname>
+ suppression for Memcheck)</para>
</listitem>
<listitem>
- <para>Remaining lines: This is the calling context for the
- error -- the chain of function calls that led to it. There
- can be up to four of these lines.</para>
+ <para>Remaining lines: This is the calling context for the error --
+ the chain of function calls that led to it. There can be up to four
+ of these lines.</para>
- <para>Locations may be either names of shared
- objects/executables or wildcards matching function names.
- They begin <computeroutput>obj:</computeroutput> and
- <computeroutput>fun:</computeroutput> respectively. Function
- and object names to match against may use the wildcard
- characters <computeroutput>*</computeroutput> and
- <computeroutput>?</computeroutput>.</para>
+ <para>Locations may be either names of shared objects/executables or
+ wildcards matching function names. They begin
+ <computeroutput>obj:</computeroutput> and
+ <computeroutput>fun:</computeroutput> respectively. Function and
+ object names to match against may use the wildcard characters
+ <computeroutput>*</computeroutput> and
+ <computeroutput>?</computeroutput>.</para>
- <formalpara><title>Important note:</title>
- <para>C++ function names must be <command>mangled</command>.
- If you are writing suppressions by hand, use the
- <computeroutput>--demangle=no</computeroutput> option to get
- the mangled names in your error messages.</para>
- </formalpara>
+ <para><command>Important note: </command> C++ function names must be
+ <command>mangled</command>. If you are writing suppressions by
+ hand, use the <option>--demangle=no</option> option to get the
+ mangled names in your error messages.</para>
</listitem>
<listitem>
- <para>Finally, the entire suppression must be between curly
- braces. Each brace must be the first character on its own
- line.</para>
+ <para>Finally, the entire suppression must be between curly
+ braces. Each brace must be the first character on its own
+ line.</para>
</listitem>
</itemizedlist>
-<para>A suppression only suppresses an error when the error
-matches all the details in the suppression. Here's an
-example:</para>
+<para>A suppression only suppresses an error when the error matches all
+the details in the suppression. Here's an example:</para>
<programlisting><![CDATA[
{
@@ -524,14 +482,14 @@
<para>What it means is: for Memcheck only, suppress a
-use-of-uninitialised-value error, when the data size is 4, when
-it occurs in the function
-<computeroutput>__gconv_transform_ascii_internal</computeroutput>,
-when that is called from any function of name matching
-<computeroutput>__mbr*toc</computeroutput>, when that is called
-from <computeroutput>mbtowc</computeroutput>. It doesn't apply
-under any other circumstances. The string by which this
-suppression is identified to the user is
+use-of-uninitialised-value error, when the data size is 4, when it
+occurs in the function
+<computeroutput>__gconv_transform_ascii_internal</computeroutput>, when
+that is called from any function of name matching
+<computeroutput>__mbr*toc</computeroutput>, when that is called from
+<computeroutput>mbtowc</computeroutput>. It doesn't apply under any
+other circumstances. The string by which this suppression is identified
+to the user is
<computeroutput>__gconv_transform_ascii_internal/__mbrtowc/mbtowc</computeroutput>.</para>
<para>(See <xref linkend="mc-manual.suppfiles"/> for more details
@@ -549,17 +507,17 @@
}]]></programlisting>
<para>Suppress any size 4 uninitialised-value error which occurs
-anywhere in <computeroutput>libX11.so.6.2</computeroutput>, when
-called from anywhere in the same library, when called from
-anywhere in <computeroutput>libXaw.so.7.0</computeroutput>. The
-inexact specification of locations is regrettable, but is about
-all you can hope for, given that the X11 libraries shipped with
-Red Hat 7.2 have had their symbol tables removed.</para>
+anywhere in <filename>libX11.so.6.2</filename>, when called from
+anywhere in the same library, when called from anywhere in
+<filename>libXaw.so.7.0</filename>. The inexact specification of
+locations is regrettable, but is about all you can hope for, given that
+the X11 libraries shipped with Red Hat 7.2 have had their symbol tables
+removed.</para>
-<para>Note: since the above two examples did not make it clear,
-you can freely mix the <computeroutput>obj:</computeroutput> and
-<computeroutput>fun:</computeroutput> styles of description
-within a single suppression record.</para>
+<para>Note: since the above two examples did not make it clear, you can
+freely mix the <computeroutput>obj:</computeroutput> and
+<computeroutput>fun:</computeroutput> styles of description within a
+single suppression record.</para>
</sect1>
@@ -568,170 +526,225 @@
xreflabel="Command-line flags for the Valgrind core">
<title>Command-line flags for the Valgrind core</title>
-<para>As mentioned above, Valgrind's core accepts a common set of
-flags. The tools also accept tool-specific flags, which are
-documented seperately for each tool.</para>
+<para>As mentioned above, Valgrind's core accepts a common set of flags.
+The tools also accept tool-specific flags, which are documented
+seperately for each tool.</para>
<para>You invoke Valgrind like this:</para>
<programlisting><![CDATA[
-valgrind [valgrind-options] your-prog [your-prog options]]]></programlisting>
+valgrind [valgrind-options] your-prog [your-prog-options]]]></programlisting>
-<para>Valgrind's default settings succeed in giving reasonable
-behaviour in most cases. We group the available options by rough
+<para>Valgrind's default settings succeed in giving reasonable behaviour
+in most cases. We group the available options by rough
categories.</para>
<sect2 id="manual-core.toolopts" xreflabel="Tool-selection option">
<title>Tool-selection option</title>
<para>The single most important option.</para>
- <itemizedlist>
- <listitem id="tool_name">
- <para><computeroutput>--tool=<name></computeroutput>
- [default=memcheck]</para>
+
+<itemizedlist>
+ <listitem id="tool_name">
+ <para><option>--tool=<name></option> [default=memcheck]</para>
<para>Run the Valgrind tool called <emphasis>name</emphasis>,
e.g. Memcheck, Addrcheck, Cachegrind, etc.</para>
- </listitem>
- </itemizedlist>
+ </listitem>
+</itemizedlist>
+
</sect2>
+
+
<sect2 id="manual-core.basicopts" xreflabel="Basic Options">
<title>Basic Options</title>
<para>These options work with all tools.</para>
- <itemizedlist>
- <listitem>
- <para><computeroutput>--help</computeroutput></para>
- <para>Show help for all options, both for the core and for
- the selected tool.</para>
- </listitem>
+<variablelist id="basic.opts">
- <listitem>
- <para><computeroutput>--help-debug</computeroutput></para>
- <para>Same as <computeroutput>--help</computeroutput>, but
- also lists debugging options which usually are only of use
- to Valgrind's developers.</para>
- </listitem>
+ <varlistentry id="opt.help" xreflabel="--help">
+ <term><option>-h --help</option></term>
+ <listitem>
+ <para>Show help for all options, both for the core and for the
+ selected tool.</para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para><computeroutput>--version</computeroutput></para>
- <para>Show the version number of the Valgrind core. Tools
- can have their own version numbers. There is a scheme in
- place to ensure that tools only execute when the core version
- is one they are known to work with. This was done to
- minimise the chances of strange problems arising from
- tool-vs-core version incompatibilities.</para>
- </listitem>
+ <varlistentry id="opt.help-debug" xreflabel="--help-debug">
+ <term><option>--help-debug</option></term>
+ <listitem>
+ <para>Same as <option>--help</option>, but also lists debugging
+ options which usually are only of use to Valgrind's
+ developers.</para>
+ </listitem>
+ </varlistentry>
- <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>
+ <varlistentry id="opt.version" xreflabel="--version">
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Show the version number of the Valgrind core. Tools can have
+ their own version numbers. There is a scheme in place to ensure
+ that tools only execute when the core version is one they are
+ known to work with. This was done to minimise the chances of
+ strange problems arising from tool-vs-core version
+ incompatibilities.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="verbosity">
- <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,
- the suppressions used, the progress of the instrumentation
- and execution engines, and warnings about unusual behaviour.
- Repeating the flag increases the verbosity level.</para>
- </listitem>
+ <varlistentry id="opt.quiet" xreflabel="--quiet">
+ <term><option>-q --quiet</option></term>
+ <listitem>
+ <para>Run silently, and only print error messages. Useful if you
+ are running regression tests or have some other automated test
+ machinery.</para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para><computeroutput>-d</computeroutput></para>
- <para>Emit information for debugging Valgrind itself. This
- is usually only of interest to the Valgrind developers.
- Repeating the flag produces more detailed output. If you
- want to send us a bug report, a log of the output
- generated by <computeroutput>-v -v -d -d</computeroutput>
- will make your report more useful.
- </para>
- </listitem>
+ <varlistentry id="opt.verbose" xreflabel="--verbose">
+ <term><option>-v --verbose</option></term>
+ <listitem>
+ <para>Be more verbose. Gives extra information on various aspects
+ of your program, such as: the shared objects loaded, the
+ suppressions used, the progress of the instrumentation and
+ execution engines, and warnings about unusual behaviour. Repeating
+ the flag increases the verbosity level.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="trace_children">
- <para><computeroutput>--trace-children=no</computeroutput>
- [default]</para>
- <para><computeroutput>--trace-children=yes</computeroutput></para>
- <para>When enabled, Valgrind will trace into child processes.
- This is confusing and usually not what you want, so is
- disabled by default.</para>
- </listitem>
+ <varlistentry id="opt.d" xreflabel="-d">
+ <term><option>-d</option></term>
+ <listitem>
+ <para>Emit information for debugging Valgrind itself. This is
+ usually only of interest to the Valgrind developers. Repeating
+ the flag produces more detailed output. If you want to send us a
+ bug report, a log of the output generated by
+ <option>-v -v -d -d</option> will make your report more
+ useful.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="track_fds">
- <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>
+ <varlistentry id="opt.tool" xreflabel="--tool">
+ <term>
+ <option><![CDATA[--tool=<toolname> [default: memcheck] ]]></option>
+ </term>
+ <listitem>
+ <para>Run the Valgrind tool called <varname>toolname</varname>,
+ e.g. Memcheck, Addrcheck, Cachegrind, etc.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="time_stamp">
- <para><computeroutput>--time-stamp=no</computeroutput> [default]</para>
- <para><computeroutput>--time-stamp=yes</computeroutput></para>
- <para>When enabled, Valgrind will precede each message with
- an indication of the elapsed wallclock time since startup,
- expressed as days, hours, minutes, seconds and milliseconds.
- </para>
- </listitem>
+ <varlistentry id="opt.trace-children" xreflabel="--trace-children">
+ <term>
+ <option><![CDATA[--trace-children=<yes|no> [default: no] ]]></option>
+ </term>
+ <listitem>
+ <para>When enabled, Valgrind will trace into child processes.
+ This can be confusing and isn't usually what you want, so it is
+ disabled by default.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="log2fd">
- <para><computeroutput>--log-fd=<number></computeroutput>
- [default: 2, stderr]</para>
- <para>Specifies that Valgrind 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.</para>
- </listitem>
+ <varlistentry id="opt.track-fds" xreflabel="--track-fds">
+ <term>
+ <option><![CDATA[--track-fds=<yes|no> [default: no] ]]></option>
+ </term>
+ <listitem>
+ <para>When enabled, Valgrind will print out a list of open file
+ descriptors on exit. Along with each file descriptor is printed 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>
+ </varlistentry>
- <listitem id="log2file_pid">
- <para><computeroutput>--log-file=<filename></computeroutput></para>
- <para>Specifies that Valgrind should send all of its messages
- to the specified file. In fact, the file name used is
- created by concatenating the text
- <computeroutput>filename</computeroutput>, "." and the
- process ID, so as to create a file per process. The
- specified file name may not be the empty string.</para>
- </listitem>
+ <varlistentry id="opt.time-stamp" xreflabel="--time-stamp">
+ <term>
+ <option><![CDATA[--time-stamp=<yes|no> [default: no] ]]></option>
+ </term>
+ <listitem>
+ <para>When enabled, each message is preceded with an indication of
+ the elapsed wallclock time since startup, expressed as days,
+ hours, minutes, seconds and milliseconds.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="log2file">
- <para><computeroutput>--log-file-exactly=<filename></computeroutput></para>
- <para>Just like <computeroutput>--log-file</computeroutput>, but
- the "." suffix is not added. If you trace multiple processes
- with Valgrind when using this option the log file may get all messed
- up.
- </para>
- </listitem>
+ <varlistentry id="opt.log-fd" xreflabel="--log-fd">
+ <term>
+ <option><![CDATA[--log-fd=<number> [default: 2, stderr] ]]></option>
+ </term>
+ <listitem>
+ <para>Specifies that Valgrind 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, as Valgrind's output will be
+ interleaved with any output that the client sends to
+ stderr.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="log2file_qualifier">
- <para><computeroutput>--log-file-qualifer=<VAR></computeroutput></para>
- <para>When used in conjunction with
- <computeroutput>--log-file=</computeroutput>, causes the log file
- name to be qualified using the contents of environment variable
- <computeroutput>VAR</computeroutput>. This is useful when running
- MPI programs.
- For further details, see <xref linkend="manual-core.comment"/>.
- </para>
- </listitem>
+ <varlistentry id="opt.log-file" xreflabel="--log-file">
+ <term>
+ <option><![CDATA[--log-file=<filename> ]]></option>
+ </term>
+ <listitem>
+ <para>Specifies that Valgrind should send all of its messages to
+ the specified file. In fact, the file name used is created by
+ concatenating the text <filename>filename</filename>, "." and the
+ process ID, (ie. <![CDATA[<filename>.<pid>]]>), so as to create a
+ file per process. The specified file name may not be the empty
+ string.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="log2socket">
- <para><computeroutput>--log-socket=<ip-address:port-number></computeroutput></para>
- <para>Specifies that Valgrind 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, Valgrind
- falls back to writing output to the standard error (stderr).
- This option is intended to be used in conjunction with the
- <computeroutput>valgrind-listener</computeroutput> program.
- For further details, see <xref linkend="manual-core.comment"/>.</para>
- </listitem>
+ <varlistentry id="opt.log-file-exactly" xreflabel="--log-file-exactly">
+ <term>
+ <option><![CDATA[--log-file-exactly=<filename> ]]></option>
+ </term>
+ <listitem>
+ <para>Just like <option>--log-file</option>, but the suffix
+ <computeroutput>".pid"</computeroutput> is not added. If you
+ trace multiple processes with Valgrind when using this option the
+ log file may get all messed up.</para>
+ </listitem>
+ </varlistentry>
- </itemizedlist>
- </sect2>
+ <varlistentry id="opt.log-file-qualifier" xreflabel="--log-file-qualifier">
+ <term>
+ <option><![CDATA[--log-file-qualifier=<VAR> ]]></option>
+ </term>
+ <listitem>
+ <para>When used in conjunction with <option>--log-file</option>,
+ causes the log file name to be qualified using the contents of the
+ environment variable <computeroutput>$VAR</computeroutput>. This
+ is useful when running MPI programs. For further details, see
+ <link linkend="manual-core.comment">Section 2.3 "The Commentary"</link>
+ in the manual.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="opt.log-socket" xreflabel="--log-socket">
+ <term>
+ <option><![CDATA[--log-socket=<ip-address:port-number> ]]></option>
+ </term>
+ <listitem>
+ <para>Specifies that Valgrind 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, Valgrind falls back to writing
+ output to the standard error (stderr). This option is intended to
+ be used in conjunction with the
+ <computeroutput>valgrind-listener</computeroutput> program. For
+ further details, see
+ <link linkend="manual-core.comment">Section 2.3 "The Commentary"</link>
+ in the manual.</para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+
+</sect2>
<sect2 id="manual-core.erropts" xreflabel="Error-related Options">
@@ -740,235 +753,268 @@
<para>These options are used by all tools that can report
errors, e.g. Memcheck, but not Cachegrind.</para>
- <itemizedlist>
+<variablelist id="error-related.opts">
- <listitem id="xml_output">
- <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 id="xml_user_comment">
- <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 id="auto_demangle">
- <para><computeroutput>--demangle=no</computeroutput></para>
- <para><computeroutput>--demangle=yes</computeroutput> [default]</para>
- <para>Disable/enable automatic demangling (decoding) of C++
- names. Enabled by default. When enabled, Valgrind will
- attempt to translate encoded C++ names back to
- something approaching the original. The demangler handles
- symbols mangled by g++ versions 2.X and 3.X.</para>
+ <varlistentry id="opt.xml" xreflabel="--xml">
+ <term>
+ <option><![CDATA[--xml=<yes|no> [default: no] ]]></option>
+ </term>
+ <listitem>
+ <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>
+ </varlistentry>
- <para>An important fact about demangling is that function
- names mentioned in suppressions files should be in their
- mangled form. Valgrind does not demangle function names when
- searching for applicable suppressions, because to do
- otherwise would make suppressions file contents dependent on
- the state of Valgrind's demangling machinery, and would also
- be slow and pointless.</para>
- </listitem>
+ <varlistentry id="opt.xml-user-comment" xreflabel="--xml-user-comment">
+ <term>
+ <option><![CDATA[--xml-user-comment=<string> ]]></option>
+ </term>
+ <listitem>
+ <para>Embeds an extra user comment string at the start of the XML
+ output. Only works when <option>--xml=yes</option> is specified;
+ ignored otherwise.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="num_callers">
- <para><computeroutput>--num-callers=<number></computeroutput> [default=12]</para>
- <para>By default, Valgrind shows twelve levels of function call
- names to help you identify program locations. You can change
- that number with this option. This can help in determining
- the program's location in deeply-nested call chains. Note
- that errors are commoned up using only the top three function
- locations (the place in the current function, and that of its
- two immediate callers). So this doesn't affect the total
- number of errors reported.</para>
+ <varlistentry id="opt.demangle" xreflabel="--demangle">
+ <term>
+ <option><![CDATA[--demangle=<yes|no> [default: yes] ]]></option>
+ </term>
+ <listitem>
+ <para>Enable/disable automatic demangling (decoding) of C++ names.
+ Enabled by default. When enabled, Valgrind will attempt to
+ translate encoded C++ names back to something approaching the
+ original. The demangler handles symbols mangled by g++ versions
+ 2.X, 3.X and 4.X.</para>
- <para>The maximum value for this is 50. Note that higher
- settings will make Valgrind run a bit more slowly and take a
- bit more memory, but can be useful when working with programs
- with deeply-nested call chains.</para>
- </listitem>
+ <para>An important fact about demangling is that function names
+ mentioned in suppressions files should be in their mangled form.
+ Valgrind does not demangle function names when searching for
+ applicable suppressions, because to do otherwise would make
+ suppressions file contents dependent on the state of Valgrind's
+ demangling machinery, and would also be slow and pointless.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="error_limit">
- <para><computeroutput>--error-limit=yes</computeroutput>
- [default]</para>
- <para><computeroutput>--error-limit=no</computeroutput></para>
- <para>When enabled, Valgrind stops reporting errors after
- 100000 in total, or 1000 different ones, have been seen. This
- is to stop the error tracking machinery from becoming a huge
- performance overhead in programs with many errors.</para>
- </listitem>
+ <varlistentry id="opt.num-callers" xreflabel="--num-callers">
+ <term>
+ <option><![CDATA[--num-callers=<number> [default: 12] ]]></option>
+ </term>
+ <listitem>
+ <para>By default, Valgrind shows twelve levels of function call
+ names to help you identify program locations. You can change that
+ number with this option. This can help in determining the
+ program's location in deeply-nested call chains. Note that errors
+ are commoned up using only the top four function locations (the
+ place in the current function, and that of its three immediate
+ callers). So this doesn't affect the total number of errors
+ reported.</para>
- <listitem id="stack_traces">
- <para><computeroutput>--show-below-main=yes</computeroutput></para>
- <para><computeroutput>--show-below-main=no</computeroutput>
- [default]</para>
- <para>By default, stack traces for errors do not show any
- functions that appear beneath
- <computeroutput>main()</computeroutput> (or similar functions
- such as glibc's <computeroutput>__libc_start_main()</computeroutput>, if
- <computeroutput>main()</computeroutput> is not present in the stack
- trace); most of the time it's uninteresting C library stuff. If this
- option is enabled, these entries below
- <computeroutput>main()</computeroutput> will be shown.</para>
- </listitem>
+ <para>The maximum value for this is 50. Note that higher settings
+ will make Valgrind run a bit more slowly and take a bit more
+ memory, but can be useful when working with programs with
+ deeply-nested call chains.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="supps_files">
- <para><computeroutput>--suppressions=<filename></computeroutput>
- [default: $PREFIX/lib/valgrind/default.supp]</para>
- <para>Specifies an extra file from which to read descriptions
- of errors to suppress. You may use as many extra
- suppressions files as you like.</para>
- </listitem>
+ <varlistentry id="opt.error-limit" xreflabel="--error-limit">
+ <term>
+ <option><![CDATA[--error-limit=<yes|no> [default: yes] ]]></option>
+ </term>
+ <listitem>
+ <para>When enabled, Valgrind stops reporting errors after 100,000
+ in total, or 1,000 different ones, have been seen. This is to
+ stop the error tracking machinery from becoming a huge performance
+ overhead in programs with many errors.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="gen_supps">
- <para><computeroutput>--gen-suppressions=no</computeroutput>
- [default]</para>
- <para><computeroutput>--gen-suppressions=yes</computeroutput></para>
- <para><computeroutput>--gen-suppressions=all</computeroutput></para>
+ <varlistentry id="opt.stack-traces" xreflabel="--show-below-main">
+ <term>
+ <option><![CDATA[--show-below-main=<yes|no> [default: no] ]]></option>
+ </term>
+ <listitem>
+ <para>By default, stack traces for errors do not show any
+ functions that appear beneath <function>main()</function>
+ (or similar functions such as glibc's
+ <function>__libc_start_main()</function>, if
+ <function>main()</function> is not present in the stack trace);
+ most of the time it's uninteresting C library stuff. If this
+ option is enabled, those entries below <function>main()</function>
+ will be shown.</para>
+ </listitem>
+ </varlistentry>
- <para>When set to <computeroutput>yes</computeroutput>, Valgrind
- will pause after every error shown, and print the line:
- <computeroutput>---- Print suppression ? --- [Return/N/n/Y/y/C/c]
- ----</computeroutput></para>
+ <varlistentry id="opt.suppressions" xreflabel="--suppressions">
+ <term>
+ <option><![CDATA[--suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp] ]]></option>
+ </term>
+ <listitem>
+ <para>Specifies an extra file from which to read descriptions of
+ errors to suppress. You may use as many extra suppressions files
+ as you like.</para>
+ </listitem>
+ </varlistentry>
- <para>The prompt's behaviour is the same as for the
- <computeroutput>--db-attach</computeroutput> option.</para>
+ <varlistentry id="opt.gen-suppressions" xreflabel="--gen-supressions">
+ <term>
+ <option><![CDATA[--gen-suppressions=<yes|no|all> [default: no] ]]></option>
+ </term>
+ <listitem>
+ <para>When set to <varname>yes</varname>, Valgrind will pause
+ after every error shown and print the line:
+ <literallayout> ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----</literallayout>
- <para>If you choose to, Valgrind will print out a suppression
- for this error. You can then cut and paste it into a
- suppression file if you don't want to hear about the error in
- the future.</para>
+ The prompt's behaviour is the same as for the
+ <option>--db-attach</option> option (see below).</para>
- <para>When set to <computeroutput>all</computeroutput>, Valgrind
- will print a suppression for every reported error, without
- querying the user.</para>
+ <para>If you choose to, Valgrind will print out a suppression for
+ this error. You can then cut and paste it into a suppression file
+ if you don't want to hear about the error in the future.</para>
- <para>This option is particularly useful with C++ programs,
- as it prints out the suppressions with mangled names, as
- required.</para>
+ <para>When set to <varname>all</varname>, Valgrind will print a
+ suppression for every reported error, without querying the
+ user.</para>
- <para>Note that the suppressions printed are as specific as
- possible. You may want to common up similar ones, eg. by
- adding wildcards to function names. Also, sometimes two
- different errors are suppressed by the same suppression, in
- which case Valgrind will output the suppression more than
- once, but you only need to have one copy in your suppression
- file (but having more than one won't cause problems). Also,
- the suppression name is given as <computeroutput><insert a
- suppression name here></computeroutput>; the name doesn't
- really matter, it's only used with the
- <computeroutput>-v</computeroutput> option which prints out
- all used suppression records.</para>
- </listitem>
+ <para>This option is particularly useful with C++ programs, as it
+ prints out the suppressions with mangled names, as
+ required.</para>
- <listitem id="attach_debugger">
- <para><computeroutput>--db-attach=no</computeroutput> [default]</para>
- <para><computeroutput>--db-attach=yes</computeroutput></para>
- <para>When enabled, Valgrind will pause after every error
- shown, and print the line: <computeroutput>---- Attach to
- debugger ? --- [Return/N/n/Y/y/C/c] ----</computeroutput></para>
+ <para>Note that the suppressions printed are as specific as
+ possible. You may want to common up similar ones, eg. by adding
+ wildcards to function names. Also, sometimes two different errors
+ are suppressed by the same suppression, in which case Valgrind
+ will output the suppression more than once, but you only need to
+ have one copy in your suppression file (but having more than one
+ won't cause problems). Also, the suppression name is given as
+ <computeroutput><insert a suppression name
+ here></computeroutput>; the name doesn't really matter, it's
+ only used with the <option>-v</option> option which prints out all
+ used suppression records.</para>
+ </listitem>
+ </varlistentry>
- <para>Pressing <literal>Ret</literal>, or
- <literal>N Ret</literal> or <literal>n Ret</literal>, causes
- Valgrind not to start a debugger for this error.</para>
+ <varlistentry id="opt.db-attach" xreflabel="--db-attach">
+ <term>
+ <option><![CDATA[--db-attach=<yes|no> [default: no] ]]></option>
+ </term>
+ <listitem>
+ <para>When enabled, Valgrind will pause after every error shown
+ and print the line:
+ <literallayout> ---- Attach to debugger ? --- [Return/N/n/Y/y/C/c] ----</literallayout>
- <para><literal>Y Ret</literal> or <literal>y Ret</literal>
- causes Valgrind to start a debugger, for the program at this
- point. When you have finished with the debugger, quit from
- it, and the program will continue. Trying to continue from
- inside the debugger doesn't work.</para>
+ Pressing <varname>Ret</varname>, or <varname>N Ret</varname> or
+ <varname>n Ret</varname>, causes Valgrind not to start a debugger
+ for this error.</para>
- <para><literal>C Ret</literal> or <literal>c Ret</literal>
- causes Valgrind not to start a debugger, and not to ask
- again.</para>
+ <para>Pressing <varname>Y Ret</varname> or
+ <varname>y Ret</varname> causes Valgrind to start a debugger for
+ the program at this point. When you have finished with the
+ debugger, quit from it, and the program will continue. Trying to
+ continue from inside the debugger doesn't work.</para>
- <formalpara>
- <title>Note:</title>
- <para><computeroutput>--db-attach=yes</computeroutput>
- conflicts with
- <computeroutput>--trace-children=yes</computeroutput>. You
- can't use them together. Valgrind refuses to start up in
- this situation.</para>
- </formalpara>
- <para>1 May 2002: this is a historical relic which could be
- easily fixed if it gets in your way. Mail us and complain if
- this is a problem for you.</para> <para>Nov 2002: if you're
- sending output to a logfile or to a network socket, I guess
- this option doesn't make any sense. Caveat emptor.</para>
- </listitem>
+ <para><varname>C Ret</varname> or <varname>c Ret</varname> causes
+ Valgrind not to start a debugger, and not to ask again.</para>
- <listitem id="which_debugger">
- <para><computeroutput>--db-command=<command></computeroutput>
- [default: gdb -nw %f %p]</para>
- <para>This specifies how Valgrind will invoke the debugger.
- By default it will use whatever GDB is detected at build
- time, which is usually
- <computeroutput>/usr/bin/gdb</computeroutput>. Using this
- command, you can specify some alternative command to invoke
- the debugger you want to use.</para>
+ <para><command>Note:</command> <option>--db-attach=yes</option>
+ conflicts with <option>--trace-children=yes</option>. You can't
+ use them together. Valgrind refuses to start up in this
+ situation.</para>
- <para>The command string given can include one or instances
- of the <literal>%p</literal> and <literal>%f</literal>
- expansions. Each instance of <literal>%p</literal> expands to
- the PID of the process to be debugged and each instance of
- <literal>%f</literal> expands to the path to the executable
- for the process to be debugged.</para>
- </listitem>
+ <para>May 2002: this is a historical relic which could be easily
+ fixed if it gets in your way. Mail us and complain if this is a
+ problem for you.</para>
+ <para>Nov 2002: if you're sending output to a logfile or to a
+ network socket, I guess this option doesn't make any sense.
+ Caveat emptor.</para>
+ </listitem>
+ </varlistentry>
- <listitem id="input_fd">
- <para><computeroutput>--input-fd=<number></computeroutput>
- [default=0, stdin]</para>
- <para>When using
- <computeroutput>--db-attach=yes</computeroutput> and
- <computeroutput>--gen-suppressions=yes</computeroutput>,
- Valgrind will stop so as to read keyboard input from you,
- when each error occurs. By default it reads from the
- standard input (stdin), which is problematic for programs
- which close stdin. This option allows you to specify an
- alternative file descriptor from which to read input.</para>
- </listitem>
+ <varlistentry id="opt.db-command" xreflabel="--db-command">
+ <term>
+ <option><![CDATA[--db-command=<command> [default: gdb -nw %f %p] ]]></option>
+ </term>
+ <listitem>
+ <para>Specify the debugger to use with the
+ <option>--db-attach</option> command. The default debugger is
+ gdb. This option is a template that is expanded by Valgrind at
+ runtime. <literal>%f</literal> is replaced with the executable's
+ file name and <literal>%p</literal> is replaced by the process ID
+ of the executable.</para>
- <listitem id="max_frames">
- <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>
+ <para>This specifies how Valgrind will invoke the debugger. By
+ default it will use whatever GDB is detected at build time, which
+ is usually <computeroutput>/usr/bin/gdb</computeroutput>. Using
+ this command, you can specify some alternative command to invoke
+ the debugger you want to use.</para>
- </itemizedlist>
+ <para>The command string given can include one or instances of the
+ <literal>%p</literal> and <literal>%f</literal> expansions. Each
+ instance of <literal>%p</literal> expands to the PID of the
+ process to be debugged and each instance of <literal>%f</literal>
+ expands to the path to the executable for the process to be
+ debugged.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="opt.input-fd" xreflabel="--input-fd">
+ <term>
+ <option><![CDATA[--input-fd=<number> [default: 0, stdin] ]]></option>
+ </term>
+ <listitem>
+ <para>When using <option>--db-attach=yes</option> and
+ <option>--gen-suppressions=yes</option>, Valgrind will stop so as
+ to read keyboard input from you, when each error occurs. By
+ default it reads from the standard input (stdin), which is
+ problematic for programs which close stdin. This option allows
+ you to specify an alternative file descriptor from which to read
+ input.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="opt.max-stackframe" xreflabel="--max-stackframe">
+ <term>
+ <option><![CDATA[--max-stackframe=<number> [default: 2000000] ]]></option>
+ </term>
+ <listitem>
+ <para>The maximum size of a stack frame - if the stack pointer moves by
+ more than this amount then Valgrind will assume that
+ the program is switching to a different stack.</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>
+ </varlistentry>
+
+</variablelist>
+
</sect2>
+
<sect2 id="manual-core.mallocopts" xreflabel="malloc()-related Options">
<title><computeroutput>malloc()</computeroutput>-related Options</title>
@@ -976,138 +1022,146 @@
<computeroutput>malloc()</computeroutput> (e.g. Memcheck and
Addrcheck), the following options apply.</para>
- <itemizedlist>
+<variablelist id="malloc-related.opts">
- <listitem id="alignment">
- <para><computeroutput>--alignment=<number></computeroutput>
- [default: 8]</para>
- <para>By default Valgrind's
- <computeroutput>malloc</computeroutput>,
- <computeroutput>realloc</computeroutput>, etc, return 8-byte
- aligned addresses. This is standard for
- most processors. Some programs might however assume that
- <computeroutput>malloc</computeroutput> et al return 16- or
- more aligned memory. The supplied value must be between 4
- and 4096 inclusive, and must be a power of two.</para>
- </listitem>
-
- </itemizedlist>
-
- </sect2>
-
-
- <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
- to use these.</para>
-
- <itemizedlist>
-
- <listitem id="free_glibc">
- <para><computeroutput>--run-libc-freeres=yes</computeroutput>
- [default]</para>
- <para><computeroutput>--run-libc-freeres=no</computeroutput></para>
- <para>The GNU C library
- (<computeroutput>libc.so</computeroutput>), which is used by
- all programs, may allocate memory for its own uses. Usually
- it doesn't bother to free that memory when the program ends -
- there would be no point, since the Linux kernel reclaims all
- process resources when a process exits anyway, so it would
- just slow things down.</para>
-
- <para>The glibc authors realised that this behaviour causes
- leak checkers, such as Valgrind, to falsely report leaks in
- glibc, when a leak check is done at exit. In order to avoid
- this, they provided a routine called
- <computeroutput>__libc_freeres</computeroutput> specifically
- to make glibc release all memory it has allocated. Memcheck
- and Addrcheck therefore try and run
- <computeroutput>__libc_freeres</computeroutput> at
- exit.</para>
-
- <para>Unfortunately, in some versions of glibc,
- <computeroutput>__libc_freeres</computeroutput> is
- sufficiently buggy to cause segmentation faults. This is
- particularly noticeable on Red Hat 7.1. So this flag is
- provided in order to inhibit the run of
- <computeroutput>__libc_freeres</computeroutput>. If your
- program seems to run fine on Valgrind, but segfaults at exit,
- you may find that
- <computeroutput>--run-libc-freeres=no</computeroutput> fixes
- that, although at the cost of possibly falsely reporting
- space leaks in
- <computeroutput>libc.so</computeroutput>.</para>
- </listitem>
-
- <listitem id="simulation_hints">
- <para><computeroutput>--sim-hints=hint1,hint2,...</computeroutput></para>
- <para>Pass miscellaneous hints to Valgrind which slightly
- modify the simulated behaviour in nonstandard or dangerous
- ways, possibly to help the simulation of strange features.
- By default no hints are enabled. Use with caution!
- Currently known hints are:</para>
- <itemizedlist>
- <listitem><para><computeroutput>lax-ioctls</computeroutput></para>
- <para>Be very lax about ioctl handling; the only assumption
- is that the size is correct. Doesn't require the full
- buffer to be initialized when writing. Without this, using
- some device drivers with a large number of strange ioctl
- commands becomes very tiresome.</para>
- </listitem>
-
- <listitem><para><computeroutput>enable-inner</computeroutput></para>
- <para>Enable some special magic needed when the program being
- run is itself Valgrind.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem id="kernel_variant">
- <para><computeroutput>--kernel-variant=variant1,variant2,...</computeroutput>
- </para>
- <para>Handle system calls and ioctls arising from minor variants
- of the default kernel for this platform. This is useful for
- running on hacked kernels or with kernel modules which support
- nonstandard ioctls, for example. Use with caution. If you don't
- understand what this option does then you almost certainly don't
- need it.
- Currently known variants are:</para>
- <itemizedlist>
- <listitem><para><computeroutput>bproc</computeroutput></para>
- <para>Support the sys_broc system call on x86. This is for
- running on BProc, which is a minor variant of standard Linux
- which is sometimes used for building clusters.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem id="show_emwarns">
- <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 id="smc_support">
- <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>
+ <varlistentry id="opt.alignment" xreflabel="--alignment">
+ <term>
+ <option><![CDATA[--alignment=<number> [default: 8] ]]></option>
+ </term>
+ <listitem>
+ <para>By default Valgrind's <function>malloc()</function>,
+ <function>realloc()</function>, etc, return 8-byte aligned
+ addresses. This is standard for most processors. However, some
+ programs might assume that <function>malloc()</function> et al
+ return 16-byte or more aligned memory. The supplied value must be
+ between 8 and 4096 inclusive, and must be a power of two.</para>
</listitem>
+ </varlistentry>
- </itemizedlist>
+</variablelist>
+
+</sect2>
+
+
+<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 to use
+these.</para>
+
+<variablelist id="uncommon.opts">
+
+ <varlistentry id="opt.run-libc-freeres" xreflabel="--run-libc-freeres">
+ <term>
+ <option><![CDATA[--run-libc-freeres=<yes|no> [default: yes] ]]></option>
+ </term>
+ <listitem>
+ <para>The GNU C library (<function>libc.so</function>), which is
+ used by all programs, may allocate memory for its own uses.
+ Usually it doesn't bother to free that memory when the program
+ ends - there would be no point, since the Linux kernel reclaims
+ all process resources when a process exits anyway, so it would
+ just slow things down.</para>
+
+ <para>The glibc authors realised that this behaviour causes leak
+ checkers, such as Valgrind, to falsely report leaks in glibc, when
+ a leak check is done at exit. In order to avoid this, they
+ provided a routine called <function>__libc_freeres</function>
+ specifically to make glibc release all memory it has allocated.
+ Memcheck and Addrcheck therefore try and run
+ <function>__libc_freeres</function> at exit.</para>
+
+ <para>Unfortunately, in some versions of glibc,
+ <function>__libc_freeres</function> is sufficiently buggy to cause
+ segmentation faults. This is particularly noticeable on Red Hat
+ 7.1. So this flag is provided in order to inhibit the run of
+ <function>__libc_freeres</function>. If your program seems to run
+ fine on Valgrind, but segfaults at exit, you may find that
+ <option>--run-libc-freeres=no</option> fixes that, although at the
+ cost of possibly falsely reporting space leaks in
+ <filename>libc.so</filename>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="opt.sim-hints" xreflabel="--sim-hints">
+ <term>
+ <option><![CDATA[--sim-hints=hint1,hint2,... ]]></option>
+ </term>
+ <listitem>
+ <para>Pass miscellaneous hints to Valgrind which slightly modify
+ the simulated behaviour in nonstandard or dangerous ways, possibly
+ to help the simulation of strange features. By default no hints
+ are enabled. Use with caution! Currently known hints are:</para>
+ <itemizedlist>
+ <listitem>
+ <para><option>lax-ioctls: </option> Be very lax about ioctl
+ handling; the only assumption is that the size is
+ correct. Doesn't require the full buffer to be initialized
+ when writing. Without this, using some device drivers with a
+ large number of strange ioctl commands becomes very
+ tiresome.</para>
+ </listitem>
+ <listitem>
+ <para><option>enable-inner: </option> Enable some special
+ magic needed when the program being run is itself
+ Valgrind.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="opt.kernel-variant" xreflabel="--kernel-variant">
+ <term>
+ <option>--kernel-variant=variant1,variant2,...</option>
+ </term>
+ <listitem>
+ <para>Handle system calls and ioctls arising from minor variants
+ of the default kernel for this platform. This is useful for
+ running on hacked kernels or with kernel modules which support
+ nonstandard ioctls, for example. Use with caution. If you don't
+ understand what this option does then you almost certainly don't
+ need it. Currently known variants are:</para>
+ <itemizedlist>
+ <listitem>
+ <para><option>bproc: </option> Support the sys_broc system
+ call on x86. This is for running on BProc, which is a minor
+ variant of standard Linux which is sometimes used for building
+ clusters.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="opt.show-emwarns" xreflabel="--show-emwarns">
+ <term>
+ <option><![CDATA[--show-emwarns=<yes|no> [default: no] ]]></option>
+ </term>
+ <listitem>
+ <para>When enabled, Valgrind will emit warnings about its CPU
+ emulation in certain cases. These are usually not
+ interesting.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="opt.smc-check" xreflabel="--smc-check">
+ <term>
+ <option><![CDATA[--smc-check=<none|stack|all> [default: stack] ]]></option>
+ </term>
+ <listitem>
+ <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 <varname>all</varname> will slow Valgrind down
+ greatly (but running with <varname>none</varname> will rarely
+ speed things up, since very little code gets put on the stack for
+ most programs).</para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+
</sect2>
@@ -1264,14 +1318,13 @@
<varlistentry>
<term><command><computeroutput>VALGRIND_COUNT_ERRORS</computeroutput>:</command></term>
<listitem>
- <para>returns the number of errors found so far by Valgrind.
- Can be useful in test harness code when combined with the
- <computeroutput>--log-fd=-1</computeroutput> option; this
- runs Valgrind silently, but the client program can detect
- when errors occur. Only useful for tools that report errors,
- e.g. it's useful for Memcheck, but for Cachegrind it will
- always return zero because Cachegrind doesn't report
- errors.</para>
+ <para>returns the number of errors found so far by Valgrind. Can be
+ useful in test harness code when combined with the
+ <option>--log-fd=-1</option> option; this runs Valgrind silently,
+ but the client program can detect when errors occur. Only useful
+ for tools that report errors, e.g. it's useful for Memcheck, but for
+ Cachegrind it will always return zero because Cachegrind doesn't
+ report errors.</para>
</listitem>
</varlistentry>
@@ -1350,10 +1403,10 @@
program on the <emphasis>real</emphasis> CPU, not the virtual
CPU that Valgrind normally runs code on. These are used in
various ways internally to Valgrind. They might be useful to
- client programs.</para> <formalpara><title>Warning:</title>
- <para>Only use these if you <emphasis>really</emphasis> know
- what you are doing.</para>
- </formalpara>
+ client programs.</para>
+
+ <para><command>Warning:</command> Only use these if you
+ <emphasis>really</emphasis> know what you are doing.</para>
</listitem>
</varlistentry>
@@ -1507,33 +1560,34 @@
</para>
<para>There are three options (in addition to the usual
-<computeroutput>--prefix=</computeroutput> which affect how Valgrind is built:
+<option>--prefix=</option> which affect how Valgrind is built:
<itemizedlist>
- <listitem>
- <para><computeroutput>--enable-inner</computeroutput></para>
- <para>This builds Valgrind with some special magic hacks which
- make it possible to run it on a standard build of Valgrind
- (what the developers call "self-hosting"). Ordinarily you
- should not use this flag as various kinds of safety checks
- are disabled.
- </para>
- </listitem>
- <listitem>
- <para><computeroutput>--enable-tls</computeroutput></para>
- <para>TLS (Thread Local Storage) is a relatively new mechanism which
- requires compiler, linker and kernel support. Valgrind automatically test
- if TLS is supported and enable this option. Sometimes it cannot test for
- TLS, so this option allows you to override the automatic test.</para>
- </listitem>
-
- <listitem>
- <para><computeroutput>--with-vex=</computeroutput></para>
- <para>Specifies the path to the underlying VEX dynamic-translation
- library. By default this is taken to be in the VEX directory
- off the root of the source tree.
+ <listitem>
+ <para><option>--enable-inner</option></para>
+ <para>This builds Valgrind with some special magic hacks which make
+ it possible to run it on a standard build of Valgrind (what the
+ developers call "self-hosting"). Ordinarily you should not use
+ this flag as various kinds of safety checks are disabled.
</para>
- </listitem>
+ </listitem>
+
+ <listitem>
+ <para><option>--enable-tls</option></para>
+ <para>TLS (Thread Local Storage) is a relatively new mechanism which
+ requires compiler, linker and kernel support. Valgrind
+ automatically test if TLS is supported and enable this option.
+ Sometimes it cannot test for TLS, so this option allows you to
+ override the automatic test.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>--with-vex=</option></para>
+ <para>Specifies the path to the underlying VEX dynamic-translation
+ library. By default this is taken to be in the VEX directory off
+ the root of the source tree.
+ </para>
+ </listitem>
</itemizedlist>
</para>
@@ -1589,83 +1643,79 @@
<sect1 id="manual-core.limits" xreflabel="Limitations">
<title>Limitations</title>
-<para>The following list of limitations seems long.
-However, most programs actually work fine.</para>
+<para>The following list of limitations seems long. However, most
+programs actually work fine.</para>
-<para>Valgrind will run Linux ELF
-binaries, on a kernel 2.4.X or 2.6.X system, on the x86, amd64
-and ppc32 architectures, subject to
-the following constraints:</para>
+<para>Valgrind will run Linux ELF binaries, on a kernel 2.4.X or 2.6.X
+system, on the x86, amd64 and ppc32 architectures, subject to the
+following constraints:</para>
<itemizedlist>
<listitem>
- <para>On x86 and amd64, there is no support for 3DNow! instructions. If
- the translator encounters these, Valgrind will generate a SIGILL when the
- instruction is executed. Apart from that, on x86 and amd64,
+ <para>On x86 and amd64, there is no support for 3DNow! instructions.
+ If the translator encounters these, Valgrind will generate a SIGILL
+ when the instruction is executed. Apart from that, on x86 and amd64,
essentially all instructions are supported, up to and including SSE2.
- Version 3.1.0 includes limited support for SSE3 on x86. This could be
- improved
- if necessary.</para>
- <para>On ppc32, almost all integer, floating point and Altivec instructions
- are supported.</para>
+ Version 3.1.0 includes limited support for SSE3 on x86. This could
+ be improved if necessary.</para>
+
+ <para>On ppc32, almost all integer, floating point and Altivec
+ instructions are supported.</para>
</listitem>
<listitem>
<para>Atomic instruction sequences are not properly supported, in the
- sense that their atomicity is not preserved. This will affect
- any use of synchronization via memory shared between processes. They
+ sense that their atomicity is not preserved. This will affect any
+ use of synchronization via memory shared between processes. They
will appear to work, but fail sporadically.</para>
</listitem>
<listitem>
- <para>If your program does its own memory management, rather
- than using malloc/new/free/delete, it should still work, but
- Valgrind's error checking won't be so effective. If you
- describe your program's memory management scheme using "client
- requests" (see <xref linkend="manual-core.clientreq"/>),
- Memcheck can do
- better. Nevertheless, using malloc/new and free/delete is
- still the best approach.</para>
+ <para>If your program does its own memory management, rather than
+ using malloc/new/free/delete, it should still work, but Valgrind's
+ error checking won't be so effective. If you describe your program's
+ memory management scheme using "client requests"
+ (see <xref linkend="manual-core.clientreq"/>), Memcheck can do
+ better. Nevertheless, using malloc/new and free/delete is still the
+ best approach.</para>
</listitem>
<listitem>
- <para>Valgrind's signal simulation is not as robust as it
- could be. Basic POSIX-compliant sigaction and sigprocmask
- functionality is supplied, but it's conceivable that things
- could go badly awry if you do weird things with signals.
- Workaround: don't. Programs that do non-POSIX signal tricks
- are in any case inherently unportable, so should be avoided if
- possible.</para>
+ <para>Valgrind's signal simulation is not as robust as it could be.
+ Basic POSIX-compliant sigaction and sigprocmask functionality is
+ supplied, but it's conceivable that things could go badly awry if you
+ do weird things with signals. Workaround: don't. Programs that do
+ non-POSIX signal tricks are in any case inherently unportable, so
+ should be avoided if possible.</para>
</listitem>
<listitem>
- <para>Machine instructions, and system calls, have been
- implemented on demand. So it's possible, although unlikely,
- that a program will fall over with a message to that effect.
- If this happens, please report ALL the details printed out, so
- we can try and implement the missing feature.</para>
+ <para>Machine instructions, and system calls, have been implemented
+ on demand. So it's possible, although unlikely, that a program will
+ fall over with a message to that effect. If this happens, please
+ report ALL the details printed out, so we can try and implement the
+ missing feature.</para>
</listitem>
<listitem>
- <para>Memory consumption of your program is majorly increased
- whilst running under Valgrind. This is due to the large
- amount of administrative information maintained behind the
- scenes. Another cause is that Valgrind dynamically translates
- the original executable. Translated, instrumented code is
- 12-18 times larger than the original so you can easily end
- up with 50+ MB of translations when running (eg) a web
- browser.</para>
+ <para>Memory consumption of your program is majorly increased whilst
+ running under Valgrind. This is due to the large amount of
+ administrative information maintained behind the scenes. Another
+ cause is that Valgrind dynamically translates the original
+ executable. Translated, instrumented code is 12-18 times larger than
+ the original so you can easily end up with 50+ MB of translations
+ when running (eg) a web browser.</para>
</listitem>
<listitem>
- <para>Valgrind can handle dynamically-generated code just
- fine. If you regenerate code over the top of old code
- (ie. at the same memory addresses), if the code is on the stack Valgrind
- will realise the code has changed, and work correctly. This is necessary
- to handle the trampolines GCC uses to implemented nested functions.
- If you regenerate code somewhere other than the stack, you will need to
- use the <computeroutput>--smc-check=all</computeroutput> flag, and
- Valgrind will run more slowly than normal.</para>
+ <para>Valgrind can handle dynamically-generated code just fine. If
+ you regenerate code over the top of old code (ie. at the same memory
+ addresses), if the code is on the stack Valgrind will realise the
+ code has changed, and work correctly. This is necessary to handle
+ the trampolines GCC uses to implemented nested functions. If you
+ regenerate code somewhere other than the stack, you will need to use
+ the <option>--smc-check=all</option> flag, and Valgrind will run more
+ slowly than normal.</para>
</listitem>
<listitem>
@@ -1674,26 +1724,25 @@
the IEEE754 standard.</para>
<para>Precision: There is no support for 80 bit arithmetic.
- Internally, Valgrind represents all such "long double"
- numbers in 64 bits, and so
- there may be some differences in results. Whether or not this is
- critical remains to be seen. Note, the x86/amd64 fldt/fstpt
- instructions (read/write 80-bit numbers) are correctly simulated,
- using conversions to/from 64 bits, so that in-memory images of
- 80-bit numbers look correct if anyone wants to see.</para>
+ Internally, Valgrind represents all such "long double" numbers in 64
+ bits, and so there may be some differences in results. Whether or
+ not this is critical remains to be seen. Note, the x86/amd64
+ fldt/fstpt instructions (read/write 80-bit numbers) are correctly
+ simulated, using conversions to/from 64 bits, so that in-memory
+ images of 80-bit numbers look correct if anyone wants to see.</para>
<para>The impression observed from many FP regression tests is that
the accuracy differences aren't significant. Generally speaking, if
a program relies on 80-bit precision, there may be difficulties
porting it to non x86/amd64 platforms which only support 64-bit FP
precision. Even on x86/amd64, the program may get different results
- depending on whether it is compiled to use SSE2 instructions
- (64-bits only), or x87 instructions (80-bit). The net effect is to
- make FP programs behave as if they had been run on a machine with
- 64-bit IEEE floats, for example PowerPC. On amd64 FP arithmetic is
- done by default on SSE2, so amd64 looks more like PowerPC than x86
- from an FP perspective, and there are far fewer noticable accuracy
- differences than with x86.</para>
+ depending on whether it is compiled to use SSE2 instructions (64-bits
+ only), or x87 instructions (80-bit). The net effect is to make FP
+ programs behave as if they had been run on a machine with 64-bit IEEE
+ floats, for example PowerPC. On amd64 FP arithmetic is done by
+ default on SSE2, so amd64 looks more like PowerPC than x86 from an FP
+ perspective, and there are far fewer noticable accuracy differences
+ than with x86.</para>
<para>Rounding: Valgrind does observe the 4 IEEE-mandated rounding
modes (to nearest, to +infinity, to -infinity, to zero) for the
@@ -1719,10 +1768,9 @@
<para>When Valgrind detects that the program is trying to exceed any
of these limitations (setting exception handlers, rounding mode, or
precision control), it can print a message giving a traceback of
- where this has happened, and continue execution. This behaviour
- used to be the default, but the messages are annoying and so showing
- them is now optional. Use
- <computeroutput>--show-emwarns=yes</computeroutput> to see
+ where this has happened, and continue execution. This behaviour used
+ to be the default, but the messages are annoying and so showing them
+ is now optional. Use <option>--show-emwarns=yes</option> to see
them.</para>
<para>The above limitations define precisely the IEEE754 'default'
@@ -1731,15 +1779,15 @@
</listitem>
<listitem>
- <para>As of version 3.0.0, Valgrind has the following limitations
- in its implementation of x86/AMD64 SSE2 FP arithmetic.</para>
+ <para>As of version 3.0.0, Valgrind has the following limitations in
+ its implementation of x86/AMD64 SSE2 FP arithmetic.</para>
- <para>Essentially the same: no exceptions, and limited observance
- of rounding mode. Also, SSE2 has control bits which make it treat
+ <para>Essentially the same: no exceptions, and limited observance of
+ rounding mode. Also, SSE2 has control bits which make it treat
denormalised numbers as zero (DAZ) and a related action, flush
denormals to zero (FTZ). Both of these cause SSE2 arithmetic to be
- less accurate than IEEE requires. Valgrind detects, ignores, and
- can warn about, attempts to enable either mode.</para>
+ less accurate than IEEE requires. Valgrind detects, ignores, and can
+ warn about, attempts to enable either mode.</para>
</listitem>
<listitem>
@@ -1824,71 +1872,75 @@
<itemizedlist>
<listitem>
- <para><computeroutput>More than 100 errors detected.
- Subsequent errors will still be recorded, but in less detail
- than before.</computeroutput></para>
- <para>After 100 different errors have been shown, Valgrind
- becomes more conservative about collecting them. It then
- requires only the program counters in the top two stack frames
- to match when deciding whether or not two errors are really
- the same one. Prior to this point, the PCs in the top four
- frames are required to match. This hack has the effect of
- slowing down the appearance of new errors after the first 100.
- The 100 constant can be changed by recompiling Valgrind.</para>
+ <para><computeroutput>More than 100 errors detected. Subsequent
+ errors will still be recorded, but in less detail than
+ before.</computeroutput></para>
+
+ <para>After 100 different errors have been shown, Valgrind becomes
+ more conservative about collecting them. It then requires only the
+ program counters in the top two stack frames to match when deciding
+ whether or not two errors are really the same one. Prior to this
+ point, the PCs in the top four frames are required to match. This
+ hack has the effect of slowing down the appearance of new errors
+ after the first 100. The 100 constant can be changed by recompiling
+ Valgrind.</para>
</listitem>
<listitem>
- <para><computeroutput>More than 1000 errors detected. I'm not
- reporting any more. Final error counts may be inaccurate. Go
- fix your program!</computeroutput></para>
- <para>After 1000 different errors have been detected, Valgrind
- ignores any more. It seems unlikely that collecting even more
- different ones would be of practical help to anybody, and it
- avoids the danger that Valgrind spends more and more of its
- time comparing new errors against an ever-growing collection.
- As above, the 1000 number is a compile-time constant.</para>
+ <para><computeroutput>More than 1000 errors detected. I'm not
+ reporting any more. Final error counts may be inaccurate. Go fix
+ your program!</computeroutput></para>
+
+ <para>After 1000 different errors have been detected, Valgrind
+ ignores any more. It seems unlikely that collecting even more
+ different ones would be of practical help to anybody, and it avoids
+ the danger that Valgrind spends more and more of its time comparing
+ new errors against an ever-growing collection. As above, the 1000
+ number is a compile-time constant.</para>
</listitem>
<listitem>
- <para><computeroutput>Warning: client switching
- stacks?</computeroutput></para>
- <para>Valgrind spotted such a large change in the stack
- pointer, <literal>%esp</literal>, that it guesses the client
- is switching to a different stack. At this point it makes a
- kludgey guess where the base of the new stack is, and sets
- memory permissions accordingly. You may get many bogus error
- messages following this, if Valgrind guesses wrong. At the
- moment "large change" is defined as a change of more that
- 2000000 in the value of the <literal>%esp</literal> (stack
- pointer) register.</para>
+ <para><computeroutput>Warning: client switching stacks?</computeroutput></para>
+
+ <para>Valgrind spotted such a large change in the stack pointer,
+ <literal>%esp</literal>, that it guesses the client is switching to
+ a different stack. At this point it makes a kludgey guess where the
+ base of the new stack is, and sets memory permissions accordingly.
+ You may get many bogus error messages following this, if Valgrind
+ guesses wrong. At the moment "large change" is defined as a change
+ of more that 2000000 in the value of the <literal>%esp</literal>
+ (stack pointer) register.</para>
</listitem>
<listitem>
- <para><computeroutput>Warning: client attempted to close
- Valgrind's logfile fd <number></computeroutput></para>
- <para>Valgrind doesn't allow the client to close the logfile,
- because you'd never see any diagnostic information after that
- point. If you see this message, you may want to use the
- <computeroutput>--log-fd=<number></computeroutput> option
- to specify a different logfile file-descriptor number.</para>
+ <para><computeroutput>Warning: client attempted to close Valgrind's
+ logfile fd <number></computeroutput></para>
+
+ <para>Valgrind doesn't allow the client to close the logfile,
+ because you'd never see any diagnostic information after that point.
+ If you see this message, you may want to use the
+ <option>--log-fd=<number></option> option to specify a
+ different logfile file-descriptor number.</para>
</listitem>
<listitem>
- <para><computeroutput>Warning: noted but unhandled ioctl
- <number></computeroutput></para>
- <para>Valgrind observed a call to one of the vast family of
- <computeroutput>ioctl</computeroutput> system calls, but did
- not modify its memory status info (because I have not yet got
- round to it). The call will still have gone through, but you
- may get spurious errors after this as a result of the
- non-update of the memory info.</para>
+ <para><computeroutput>Warning: noted but unhandled ioctl
+ <number></computeroutput></para>
+
+ <para>Valgrind observed a call to one of the vast family of
+ <computeroutput>ioctl</computeroutput> system calls, but did not
+ modify its memory status info (because I have not yet got round to
+ it). The call will still have gone through, but you may get
+ spurious errors after this as a result of the non-update of the
+ memory info.</para>
</listitem>
<listitem>
- <para><computeroutput>Warning: set address range perms: large
- range <number></computeroutput></para>
- <para>Diagnostic message, mostly for benefit of the valgrind
- developers, to do with memory permissions.</para>
+ <para><computeroutput>Warning: set address range perms: large range
+ <number></computeroutput></para>
+
+ <para>Diagnostic message, mostly for benefit of the Valgrind
+ developers, to do with memory permissions.</para>
</listitem>
</itemizedlist>
diff --git a/docs/xml/manual-intro.xml b/docs/xml/manual-intro.xml
index c7080d0..35e4a85 100644
--- a/docs/xml/manual-intro.xml
+++ b/docs/xml/manual-intro.xml
@@ -8,13 +8,12 @@
<sect1 id="manual-intro.overview" xreflabel="An Overview of Valgrind">
<title>An Overview of Valgrind</title>
-<para>Valgrind is a suite of simulation-based debugging and
-profiling tools for programs running on Linux (x86, amd64 and ppc32).
-The system consists of a core, which
-provides a synthetic CPU in software, and a series of tools,
-each of which performs some kind of debugging, profiling, or
-similar task. The architecture is modular, so that new tools can
-be created easily and without disturbing the existing
+<para>Valgrind is a suite of simulation-based debugging and profiling
+tools for programs running on Linux (x86, amd64 and ppc32). The system
+consists of a core, which provides a synthetic CPU in software, and a
+series of tools, each of which performs some kind of debugging,
+profiling, or similar task. The architecture is modular, so that new
+tools can be created easily and without disturbing the existing
structure.</para>
<para>A number of useful tools are supplied as standard. In
@@ -23,11 +22,10 @@
<orderedlist>
<listitem>
- <para><command>Memcheck</command> detects memory-management
- problems in your programs. All reads and writes of memory
- are checked, and calls to malloc/new/free/delete are
- intercepted. As a result, Memcheck can detect the following
- problems:</para>
+ <para><command>Memcheck</command> detects memory-management problems
+ in your programs. All reads and writes of memory are checked, and
+ calls to malloc/new/free/delete are intercepted. As a result,
+ Memcheck can detect the following problems:</para>
<itemizedlist>
<listitem>
@@ -60,124 +58,118 @@
functions</para></listitem>
</itemizedlist>
- <para>Problems like these can be difficult to find by other
- means, often lying undetected for long periods, then causing
- occasional, difficult-to-diagnose crashes.</para>
+ <para>Problems like these can be difficult to find by other means,
+ often lying undetected for long periods, then causing occasional,
+ difficult-to-diagnose crashes.</para>
</listitem>
<listitem>
- <para><command>Addrcheck</command> is a lightweight version
- of Memcheck. It is identical to Memcheck except for the
- single detail that it does not do any uninitialised-value
- checks. All of the other checks -- primarily the
- fine-grained address checking -- are still done. The
- downside of this is that you don't catch the
+ <para><command>Addrcheck</command> is a lightweight version of
+ Memcheck. It is identical to Memcheck except for the single detail
+ that it does not do any uninitialised-value checks. All of the
+ other checks -- primarily the fine-grained address checking -- are
+ still done. The downside of this is that you don't catch the
uninitialised-value errors that Memcheck can find.</para>
- <para>But the upside is significant: programs run about twice
- as fast as they do on Memcheck, and a lot less memory is
- used. It still finds reads/writes of freed memory, memory
- off the end of blocks and in other invalid places, bugs which
- you really want to find before release!</para>
+ <para>But the upside is significant: programs run about twice as
+ fast as they do on Memcheck, and a lot less memory is used. It
+ still finds reads/writes of freed memory, memory off the end of
+ blocks and in other invalid places, bugs which you really want to
+ find before release!</para>
- <para>Because Addrcheck is lighter and faster than Memcheck,
- you can run more programs for longer, and so you may be able
- to cover more test scenarios. Addrcheck was created because
- one of us (Julian) wanted to be able to run a complete KDE
- desktop session with checking. As of early November 2002, we
- have been able to run KDE-3.0.3 on a 1.7 GHz P4 with 512 MB
- of memory, using Addrcheck. Although the result is not
- stellar, it's quite usable, and it seems plausible to run KDE
- for long periods at a time like this, collecting up all the
- addressing errors that appear.</para>
+ <para>Because Addrcheck is lighter and faster than Memcheck, you can
+ run more programs for longer, and so you may be able to cover more
+ test scenarios. Addrcheck was created because one of us (Julian)
+ wanted to be able to run a complete KDE desktop session with
+ checking. As of early November 2002, we have been able to run
+ KDE-3.0.3 on a 1.7 GHz P4 with 512 MB of memory, using Addrcheck.
+ Although the result is not stellar, it's quite usable, and it seems
+ plausible to run KDE for long periods at a time like this,
+ collecting up all the addressing errors that appear.</para>
<para>NOTE: Addrcheck is not available in Valgrind 3.1.X. We hope
- to reinstate its functionality in later releases. For now, use
+ to reinstate its functionality in later releases. For now, use
Memcheck instead.</para>
</listitem>
<listitem>
<para><command>Cachegrind</command> is a cache profiler. It
- performs detailed simulation of the I1, D1 and L2 caches in
- your CPU and so can accurately pinpoint the sources of cache
- misses in your code. If you desire, it will show the number
- of cache misses, memory references and instructions accruing
- to each line of source code, with per-function, per-module
- and whole-program summaries. If you ask really nicely it
- will even show counts for each individual machine
- instruction.</para>
+ performs detailed simulation of the I1, D1 and L2 caches in your CPU
+ and so can accurately pinpoint the sources of cache misses in your
+ code. If you desire, it will show the number of cache misses,
+ memory references and instructions accruing to each line of source
+ code, with per-function, per-module and whole-program summaries. If
+ you ask really nicely it will even show counts for each individual
+ machine instruction.</para>
<para>On x86 and AMD64, Cachegrind auto-detects your machine's cache
- configuration using the
- <computeroutput>CPUID</computeroutput> instruction, and so
- needs no further configuration info, in most cases.</para>
+ configuration using the <computeroutput>CPUID</computeroutput>
+ instruction, and so needs no further configuration info, in most
+ cases.</para>
- <para>Cachegrind is nicely complemented by Josef
- Weidendorfer's amazing KCacheGrind visualisation tool
+ <para>Cachegrind is nicely complemented by Josef Weidendorfer's
+ amazing KCacheGrind visualisation tool
(<ulink url="http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindIndex">http://kcachegrind.sourceforge.net</ulink>),
a KDE application which presents these profiling results in a
graphical and easier-to-understand form.</para>
</listitem>
<listitem>
- <para><command>Helgrind</command> finds data races in
- multithreaded programs. Helgrind looks for memory locations
- which are accessed by more than one (POSIX p-)thread, but for
- which no consistently used (pthread_mutex_)lock can be found.
- Such locations are indicative of missing synchronisation
- between threads, and could cause hard-to-find
- timing-dependent problems.</para>
+ <para><command>Helgrind</command> finds data races in multithreaded
+ programs. Helgrind looks for memory locations which are accessed by
+ more than one (POSIX p-)thread, but for which no consistently used
+ (pthread_mutex_)lock can be found. Such locations are indicative of
+ missing synchronisation between threads, and could cause
+ hard-to-find timing-dependent problems.</para>
- <para>Helgrind ("Hell's Gate", in Norse mythology) implements
- the so-called "Eraser" data-race-detection algorithm, along
- with various refinements (thread-segment lifetimes) which
- reduce the number of false errors it reports. It is as yet
- somewhat of an experimental tool, so your feedback is
- especially welcomed here.</para>
+ <para>Helgrind ("Hell's Gate", in Norse mythology) implements the
+ so-called "Eraser" data-race-detection algorithm, along with various
+ refinements (thread-segment lifetimes) which reduce the number of
+ false errors it reports. It is as yet somewhat of an experimental
+ tool, so your feedback is especially welcomed here.</para>
<para>Helgrind has been hacked on extensively by Jeremy
Fitzhardinge, and we have him to thank for getting it to a
releasable state.</para>
- <para>NOTE: Helgrind is, unfortunately, not available in Valgrind 3.1.X,
- as a result of threading changes that happened in the 2.4.0 release.
- We hope to reinstate its functionality in a future 3.2.0 release.</para>
+ <para>NOTE: Helgrind is, unfortunately, not available in Valgrind
+ 3.1.X, as a result of threading changes that happened in the 2.4.0
+ release. We hope to reinstate its functionality in a future 3.2.0
+ release.</para>
</listitem>
</orderedlist>
-<para>A couple of minor tools (<command>Lackey</command>
-and <command>Nulgrind</command>) are
-also supplied. These aren't particularly useful -- they exist to
-illustrate how to create simple tools and to help the valgrind
-developers in various ways. Nulgrind is the null tool -- it adds
-no instrumentation. Lackey is a simple example tool
-which counts instructions, memory accesses, and the number of
+<para>A couple of minor tools (<command>Lackey</command> and
+<command>Nulgrind</command>) are also supplied. These aren't
+particularly useful -- they exist to illustrate how to create simple
+tools and to help the valgrind developers in various ways. Nulgrind is
+the null tool -- it adds no instrumentation. Lackey is a simple example
+tool which counts instructions, memory accesses, and the number of
integer and floating point operations your program does.</para>
<para>Valgrind is closely tied to details of the CPU and operating
system, and to a lesser extent, the compiler and basic C libraries.
-Nonetheless, as of version 3.1.0 it supports several platforms: x86/Linux
-(mature), AMD64/Linux (maturing), and PPC32/Linux (immature but works well).
-Valgrind uses the standard Unix
+Nonetheless, as of version 3.1.0 it supports several platforms:
+x86/Linux (mature), AMD64/Linux (maturing), and PPC32/Linux (immature
+but works well). Valgrind uses the standard Unix
<computeroutput>./configure</computeroutput>,
<computeroutput>make</computeroutput>, <computeroutput>make
-install</computeroutput> mechanism, and we have attempted to
-ensure that it works on machines with kernel 2.4 or 2.6 and glibc
+install</computeroutput> mechanism, and we have attempted to ensure that
+it works on machines with kernel 2.4 or 2.6 and glibc
2.2.X--2.3.X.</para>
<para>Valgrind is licensed under the <xref linkend="license.gpl"/>,
-version 2. The <computeroutput>valgrind/*.h</computeroutput> headers that
-you may wish to include in your code (eg.
-<computeroutput>valgrind.h</computeroutput>,
-<computeroutput>memcheck.h</computeroutput>) are
-distributed under a BSD-style license, so you may include them in your code
-without worrying about license conflicts. Some of the PThreads test cases,
-<computeroutput>pth_*.c</computeroutput>, are taken from
-"Pthreads Programming" by Bradford Nichols, Dick Buttlar &
-Jacqueline Proulx Farrell, ISBN 1-56592-115-1, published by
-O'Reilly & Associates, Inc.</para>
+version 2. The <computeroutput>valgrind/*.h</computeroutput> headers
+that you may wish to include in your code (eg.
+<filename>valgrind.h</filename>, <filename>memcheck.h</filename>) are
+distributed under a BSD-style license, so you may include them in your
+code without worrying about license conflicts. Some of the PThreads
+test cases, <filename>pth_*.c</filename>, are taken from "Pthreads
+Programming" by Bradford Nichols, Dick Buttlar & Jacqueline Proulx
+Farrell, ISBN 1-56592-115-1, published by O'Reilly & Associates,
+Inc.</para>
</sect1>
@@ -185,26 +177,23 @@
<sect1 id="manual-intro.navigation" xreflabel="How to navigate this manual">
<title>How to navigate this manual</title>
-<para>The Valgrind distribution consists of the Valgrind core,
-upon which are built Valgrind tools, which do different kinds of
-debugging and profiling. This manual is structured
-similarly.</para>
+<para>The Valgrind distribution consists of the Valgrind core, upon
+which are built Valgrind tools, which do different kinds of debugging
+and profiling. This manual is structured similarly.</para>
-<para>First, we describe the Valgrind core, how to use it, and
-the flags it supports. Then, each tool has its own chapter in
-this manual. You only need to read the documentation for the
-core and for the tool(s) you actually use, although you may find
-it helpful to be at least a little bit familar with what all
-tools do. If you're new to all this, you probably want to run
-the Memcheck tool. If you want to write a new tool, read
-<xref linkend="writing-tools"/>.</para>
+<para>First, we describe the Valgrind core, how to use it, and the flags
+it supports. Then, each tool has its own chapter in this manual. You
+only need to read the documentation for the core and for the tool(s) you
+actually use, although you may find it helpful to be at least a little
+bit familar with what all tools do. If you're new to all this, you
+probably want to run the Memcheck tool. If you want to write a new
+tool, read <xref linkend="writing-tools"/>.</para>
-<para>Be aware that the core understands some command line flags,
-and the tools have their own flags which they know about. This
-means there is no central place describing all the flags that are
-accepted -- you have to read the flags documentation both for
-<xref linkend="manual-core"/> and for the tool you want to
-use.</para>
+<para>Be aware that the core understands some command line flags, and
+the tools have their own flags which they know about. This means there
+is no central place describing all the flags that are accepted -- you
+have to read the flags documentation both for
+<xref linkend="manual-core"/> and for the tool you want to use.</para>
</sect1>
diff --git a/docs/xml/manual.xml b/docs/xml/manual.xml
index aa2f8c1..1599aed 100644
--- a/docs/xml/manual.xml
+++ b/docs/xml/manual.xml
@@ -1,6 +1,6 @@
<?xml version="1.0"?> <!-- -*- sgml -*- -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
@@ -13,9 +13,9 @@
<year>&vg-lifespan;</year>
<holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
</copyright>
- <author>
- <email><ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></email>
- </author>
+ <legalnotice>
+ <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
+ </legalnotice>
</bookinfo>
<xi:include href="manual-intro.xml" parse="xml"
diff --git a/docs/xml/quick-start-guide.xml b/docs/xml/quick-start-guide.xml
index d4daf27..771e063 100644
--- a/docs/xml/quick-start-guide.xml
+++ b/docs/xml/quick-start-guide.xml
@@ -12,9 +12,9 @@
<year>&vg-lifespan;</year>
<holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
</copyright>
- <author>
- <email><ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></email>
- </author>
+ <legalnotice>
+ <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
+ </legalnotice>
</bookinfo>
@@ -25,27 +25,31 @@
<sect1 id="quick-start.intro" xreflabel="Introduction">
<title>Introduction</title>
-<para>The Valgrind distribution has multiple tools. The most popular is the
-memory checking tool (called Memcheck) which can detect many common memory
-errors such as:</para>
+<para>The Valgrind distribution has multiple tools. The most popular is
+the memory checking tool (called Memcheck) which can detect many common
+memory errors such as:</para>
<itemizedlist>
- <listitem><para>touching memory you shouldn't (eg. overrunning heap block
+ <listitem>
+ <para>touching memory you shouldn't (eg. overrunning heap block
boundaries);</para>
- </listitem>
- <listitem><para>using values before they have been initialized;</para>
- </listitem>
- <listitem><para>incorrect freeing of memory, such as double-freeing heap
- blocks;</para>
- </listitem>
- <listitem><para>memory leaks.</para>
- </listitem>
+ </listitem>
+ <listitem>
+ <para>using values before they have been initialized;</para>
+ </listitem>
+ <listitem>
+ <para>incorrect freeing of memory, such as double-freeing heap
+ blocks;</para>
+ </listitem>
+ <listitem>
+ <para>memory leaks.</para>
+ </listitem>
</itemizedlist>
-<para>What follows is the minimum information you need to start detecting
-memory errors in your program with Memcheck. Note that this guide applies
-to Valgrind version 2.4.0 and later; some of the information is not quite
-right for earlier versions.</para>
+<para>What follows is the minimum information you need to start
+detecting memory errors in your program with Memcheck. Note that this
+guide applies to Valgrind version 2.4.0 and later; some of the
+information is not quite right for earlier versions.</para>
</sect1>
@@ -53,15 +57,17 @@
<sect1 id="quick-start.prepare" xreflabel="Preparing your program">
<title>Preparing your program</title>
-<para>Compile your program with <computeroutput>-g</computeroutput> to include
-debugging information so that Memcheck's error messages include exact line
-numbers. Using <computeroutput>-O0</computeroutput> is also a good idea, if
-you can tolerate the slowdown. With <computeroutput>-O1</computeroutput>
-line numbers in error messages can be inaccurate, although generally speaking
-Memchecking code compiled at <computeroutput>-O1</computeroutput> works
-fairly well. Use of <computeroutput>-O2</computeroutput> and above is
-not recommended as Memcheck occasionally reports uninitialised-value
-errors which don't really exist.</para>
+<para>Compile your program with <option>-g</option> to include debugging
+information so that Memcheck's error messages include exact line
+numbers. Using <computeroutput>-O0</computeroutput> is also a good
+idea, if you can tolerate the slowdown. With
+<computeroutput>-O1</computeroutput> line numbers in error messages can
+be inaccurate, although generally speaking Memchecking code compiled at
+<computeroutput>-O1</computeroutput> works fairly well. Use of
+<computeroutput>-O2</computeroutput> and above is not recommended as
+Memcheck occasionally reports uninitialised-value errors which don't
+really exist.</para>
+
</sect1>
@@ -69,24 +75,20 @@
<title>Running your program under Memcheck</title>
<para>If you normally run your program like this:
-
-<programlisting>
- myprog arg1 arg2
+<programlisting> myprog arg1 arg2
</programlisting>
Use this command line:
-
-<programlisting>
- valgrind --leak-check=yes myprog arg1 arg2
+<programlisting> valgrind --leak-check=yes myprog arg1 arg2
</programlisting>
-Memcheck is the default tool. The
-<computeroutput>--leak-check</computeroutput> option turns on the detailed
-memory leak detector.</para>
+Memcheck is the default tool. The <option>--leak-check</option> option
+turns on the detailed memory leak detector.</para>
-<para>Your program will run much slower (eg. 20 to 30 times) than normal,
-and use a lot more memory. Memcheck will issue messages about memory errors
-and leaks that it detects.</para>
+<para>Your program will run much slower (eg. 20 to 30 times) than
+normal, and use a lot more memory. Memcheck will issue messages about
+memory errors and leaks that it detects.</para>
+
</sect1>
@@ -111,8 +113,8 @@
}
</programlisting>
-Most error messages look like the following, which describes problem 1, the
-heap block overrun:
+Most error messages look like the following, which describes problem 1,
+the heap block overrun:
<programlisting>
==19182== Invalid write of size 4
@@ -127,44 +129,40 @@
Things to notice:
<itemizedlist>
- <listitem>
- <para>There is a lot of information in each error message; read it
- carefully.</para>
- </listitem>
-
- <listitem>
- <para>The 19182 is the process ID; it's usually unimportant.</para>
- </listitem>
-
- <listitem>
- <para>The first line ("Invalid write...") tells you what kind of error it
- is. Here, the program wrote to some memory it should not have due to a
- heap block overrun.</para>
- </listitem>
-
- <listitem>
- <para>Below the first line is a stack trace telling you where the problem
- occurred. Stack traces can get quite large, and be confusing, especially
- if you are using the C++ STL. Reading them from the bottom up can help.
- If the stack trace is not big enough, use the
- <computeroutput>--num-callers</computeroutput> option to make it
- bigger.</para>
- </listitem>
-
- <listitem>
- <para>The code addresses (eg. 0x804838F) are usually unimportant, but
- occasionally crucial for tracking down weirder bugs.</para>
- </listitem>
-
- <listitem>
- <para>Some error messages have a second component which describes the memory
- address involved. This one shows that the written memory is just past
- the end of a block allocated with malloc() on line 5 of example.c.</para>
- </listitem>
+ <listitem>
+ <para>There is a lot of information in each error message; read it
+ carefully.</para>
+ </listitem>
+ <listitem>
+ <para>The 19182 is the process ID; it's usually unimportant.</para>
+ </listitem>
+ <listitem>
+ <para>The first line ("Invalid write...") tells you what kind of
+ error it is. Here, the program wrote to some memory it should not
+ have due to a heap block overrun.</para>
+ </listitem>
+ <listitem>
+ <para>Below the first line is a stack trace telling you where the
+ problem occurred. Stack traces can get quite large, and be
+ confusing, especially if you are using the C++ STL. Reading them
+ from the bottom up can help. If the stack trace is not big enough,
+ use the <option>--num-callers</option> option to make it
+ bigger.</para>
+ </listitem>
+ <listitem>
+ <para>The code addresses (eg. 0x804838F) are usually unimportant, but
+ occasionally crucial for tracking down weirder bugs.</para>
+ </listitem>
+ <listitem>
+ <para>Some error messages have a second component which describes
+ the memory address involved. This one shows that the written memory
+ is just past the end of a block allocated with malloc() on line 5 of
+ example.c.</para>
+ </listitem>
</itemizedlist>
-It's worth fixing errors in the order they are reported, as later
-errors can be caused by earlier errors.</para>
+It's worth fixing errors in the order they are reported, as later errors
+can be caused by earlier errors.</para>
<para>Memory leak messages look like this:
@@ -176,25 +174,28 @@
</programlisting>
The stack trace tells you where the leaked memory was allocated.
-Memcheck cannot tell you why the memory leaked, unfortunately. (Ignore the
-"vg_replace_malloc.c", that's an implementation detail.)</para>
+Memcheck cannot tell you why the memory leaked, unfortunately. (Ignore
+the "vg_replace_malloc.c", that's an implementation detail.)</para>
-<para>There are several kinds of leaks; the two most important categories are:
+<para>There are several kinds of leaks; the two most important
+categories are:
<itemizedlist>
- <listitem><para>"definitely lost": your program is leaking memory -- fix
- it!</para>
- </listitem>
-
- <listitem><para>"probably lost": your program is leaking memory, unless
- you're doing funny things with pointers (such as moving them to point to
- the middle of a heap block).</para>
- </listitem>
+ <listitem>
+ <para>"definitely lost": your program is leaking memory -- fix
+ it!</para>
+ </listitem>
+ <listitem>
+ <para>"probably lost": your program is leaking memory, unless you're
+ doing funny things with pointers (such as moving them to point to
+ the middle of a heap block).</para>
+ </listitem>
</itemizedlist>
If you don't understand an error message, please consult
-<xref linkend="mc-manual.errormsgs"/> in the <xref linkend="manual"/> which has
-examples of all the error messages Memcheck produces.</para>
+<xref linkend="mc-manual.errormsgs"/> in the <xref linkend="manual"/>
+which has examples of all the error messages Memcheck produces.</para>
+
</sect1>
@@ -206,25 +207,28 @@
<xref linkend="manual-core.suppress"/> in the <xref linkend="manual"/>).
However, it is typically right 99% of the time, so you should be wary of
ignoring its error messages. After all, you wouldn't ignore warning
-messages produced by a compiler, right? The suppression mechanism is also
-useful if Memcheck is reporting errors in library code that you cannot
-change; the default suppression set hides a lot of these, but you may
-come across more.</para>
+messages produced by a compiler, right? The suppression mechanism is
+also useful if Memcheck is reporting errors in library code that you
+cannot change; the default suppression set hides a lot of these, but you
+may come across more.</para>
-<para>Memcheck also cannot detect every memory error your program has. For
-example, it can't detect if you overrun the bounds of an array that is
-allocated statically or on the stack. But it should detect every error that
-could crash your program (eg. cause a segmentation fault).</para>
+<para>Memcheck also cannot detect every memory error your program has.
+For example, it can't detect if you overrun the bounds of an array that
+is allocated statically or on the stack. But it should detect every
+error that could crash your program (eg. cause a segmentation
+fault).</para>
+
</sect1>
<sect1 id="quick-start.info" xreflabel="More Information">
<title>More information</title>
-<para>Please consult the <xref linkend="FAQ"/> and the
-<xref linkend="manual"/>, which have much more information. Note that the
-other tools in the Valgrind distribution can be invoked with the
-<computeroutput>--tool</computeroutput> option.</para>
+<para>Please consult the <xref linkend="FAQ"/> and the
+<xref linkend="manual"/>, which have much more information. Note that
+the other tools in the Valgrind distribution can be invoked with the
+<option>--tool</option> option.</para>
+
</sect1>
diff --git a/docs/xml/tech-docs.xml b/docs/xml/tech-docs.xml
index 050db3d..825c8e1 100644
--- a/docs/xml/tech-docs.xml
+++ b/docs/xml/tech-docs.xml
@@ -5,17 +5,17 @@
<book id="tech-docs" xreflabel="Valgrind Technical Documentation">
- <bookinfo>
- <title>Valgrind Technical Documentation</title>
- <releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo>
+<bookinfo>
+ <title>Valgrind Technical Documentation</title>
+ <releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo>
<copyright>
<year>&vg-lifespan;</year>
<holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
</copyright>
- <author>
- <email><ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></email>
- </author>
- </bookinfo>
+ <legalnotice>
+ <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
+ </legalnotice>
+</bookinfo>
<xi:include href="../../memcheck/docs/mc-tech-docs.xml" parse="xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
diff --git a/docs/xml/valgrind-manpage.xml b/docs/xml/valgrind-manpage.xml
new file mode 100644
index 0000000..4ea3ac0
--- /dev/null
+++ b/docs/xml/valgrind-manpage.xml
@@ -0,0 +1,255 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
+
+
+<refentry id="valgrind">
+
+<refmeta>
+ <refentrytitle>VALGRIND</refentrytitle>
+ <manvolnum>1</manvolnum>
+ <refmiscinfo>Release &rel-version;</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname>valgrind</refname>
+ <refpurpose>a suite of tools for debugging and profiling programs</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+ <command>valgrind</command>
+ <arg>
+ <arg><replaceable>valgrind</replaceable></arg>
+ <arg><replaceable>options</replaceable></arg>
+ </arg>
+ <arg><replaceable>your-program</replaceable></arg>
+ <arg>
+ <arg><replaceable>your-program-options</replaceable></arg>
+ </arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsect1 id="description">
+<title>Description</title>
+
+<para><command>Valgrind</command> 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.</para>
+
+<para>This manual page covers only basic usage and options. For more
+comprehensive information, please see the HTML documentation on your
+system: <filename>&vg-doc-path;</filename>, or online:
+<filename>&vg-bookset;</filename>.</para>
+
+</refsect1>
+
+
+<refsect1 id="invocation">
+<title>Invocation</title>
+
+<para><command>Valgrind</command> is typically invoked as follows:
+<literallayout> valgrind program args</literallayout>
+
+This runs <command>program</command> (with arguments
+<command>args</command>) under Valgrind using the Memcheck tool.
+Memcheck performs a range of memory-checking functions, including
+detecting accesses to uninitialised memory, misuse of allocated memory
+(double frees, access after free, etc.) and detecting memory
+leaks.</para>
+
+<para>To use a different tool, use the <option>--tool</option> option:
+<literallayout> valgrind --tool=toolname program args</literallayout></para>
+
+<para>The following tools are available:</para>
+
+<itemizedlist>
+
+ <listitem>
+ <para><option>cachegrind</option> is a cache simulator. It can be
+ used to annotate every line of your program with the number of
+ instructions executed and cache misses incurred.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>helgrind</option> spots potential race conditions in
+ your program.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>lackey</option> is a sample tool that can be used as a
+ template for generating your own tools. After the program
+ terminates, it prints out some basic statistics about the program
+ execution.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>massif</option> is a heap profiler. It measures how
+ much heap memory your program uses.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>memcheck</option> is a fine-grained memory checker.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>none</option> performs no function - it simply runs
+ the program under Valgrind. This is typically used for debugging
+ and benchmarking Valgrind.</para>
+ </listitem>
+
+</itemizedlist>
+
+</refsect1>
+
+
+
+<refsect1 id="basic-options">
+<title>Basic Options</title>
+
+<para>These options work with all tools.</para>
+
+<xi:include href="manual-core.xml" xpointer="basic.opts"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="error-related-options">
+<title>Error-Related Options</title>
+
+<para>These options are used by all tools that can report errors,
+e.g. Memcheck, but not Cachegrind.</para>
+
+<xi:include href="manual-core.xml" xpointer="error-related.opts"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="malloc-related-options">
+<title>malloc()-related Options</title>
+
+<para>For tools that use their own version of
+<function>malloc()</function> (e.g. Memcheck and Addrcheck), the
+following options apply.</para>
+
+<xi:include href="manual-core.xml" xpointer="malloc-related.opts"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="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 to use
+these.</para>
+
+<xi:include href="manual-core.xml" xpointer="uncommon.opts"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="debugging-valgrind-options">
+<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. If you wish to
+see the list, use the <option>--help-debug</option> option.</para>
+
+</refsect1>
+
+
+
+<refsect1 id="memcheck-options">
+<title>Memcheck Options</title>
+
+<xi:include href="../../memcheck/docs/mc-manual.xml" xpointer="mc.opts"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="cachegrind-options">
+<title>Cachegrind Options</title>
+
+<xi:include href="../../cachegrind/docs/cg-manual.xml" xpointer="cg.opts.p1"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+<xi:include href="../../cachegrind/docs/cg-manual.xml" xpointer="cg.opts"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="massif-options">
+<title>Massif Options</title>
+
+<xi:include href="../../massif/docs/ms-manual.xml" xpointer="ms.opts"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="helgrind-options">
+<title>Helgrind Options</title>
+
+<xi:include href="../../helgrind/docs/hg-manual.xml" xpointer="hg.opts"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="lackey-options">
+<title>Lackey Options</title>
+
+<xi:include href="../../lackey/docs/lk-manual.xml" xpointer="lk.opts"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+<refsect1 id="see_also">
+<title>See Also</title>
+
+<para>
+<filename>&vg-doc-path;</filename>,
+and/or
+<filename>&vg-bookset;</filename>.
+</para>
+
+</refsect1>
+
+
+<refsect1 id="author">
+<title>Author</title>
+
+<para>This manpage has been written by Andres Roldan <aroldan@debian.org>
+for the Debian Project, but can be used for any other distribution.</para>
+
+<para>Updated, rearranged and expanded by Robert Walsh
+<rjwalsh@durables.org> for the 2.4.0 release, and by other
+Valgrind developers subsequently.</para>
+
+</refsect1>
+
+
+</refentry>
+
diff --git a/docs/xml/vg-entities.xml b/docs/xml/vg-entities.xml
index c8045d3..305c5dd 100644
--- a/docs/xml/vg-entities.xml
+++ b/docs/xml/vg-entities.xml
@@ -4,17 +4,20 @@
<!ENTITY vg-vemail "valgrind@valgrind.org">
<!ENTITY vg-lifespan "2000-2005">
<!ENTITY vg-users-list "http://lists.sourceforge.net/lists/listinfo/valgrind-users">
-<!ENTITY vg-developers "http://www.valgrind.org/info/developers.html">
-<!ENTITY vg-svn-repo "http://www.valgrind.org/downloads/repository.html">
-<!ENTITY vg-bookset "http://www.valgrind.org/docs/manual/index.html">
-<!ENTITY vg-dist-docs "http://www.valgrind.org/docs/manual/dist.html">
-
<!-- valgrind release + version stuff -->
<!ENTITY rel-type "Release">
<!ENTITY rel-version "3.1.0">
<!ENTITY rel-date "November 25 2005">
+<!-- where the docs are installed -->
+<!ENTITY vg-doc-path "/usr/share/doc/valgrind/html/index.html">
+
<!-- valgrind website links used in lots of places in the docs -->
<!-- kept in here 'cos everytime the website gets changed, it`s -->
<!-- a real pain tracking the links down in the docs -->
+<!ENTITY vg-developers "http://www.valgrind.org/info/developers.html">
+<!ENTITY vg-svn-repo "http://www.valgrind.org/downloads/repository.html">
+<!ENTITY vg-bookset "http://www.valgrind.org/docs/manual/index.html">
+<!ENTITY vg-dist-docs "http://www.valgrind.org/docs/manual/dist.html">
+<!ENTITY vg-commentary "http://www.valgrind.org/docs/manual/manual-core.html#manual-core.comment">
diff --git a/docs/xml/writing-tools.xml b/docs/xml/writing-tools.xml
index 0c3068c..0ef1648 100644
--- a/docs/xml/writing-tools.xml
+++ b/docs/xml/writing-tools.xml
@@ -3,6 +3,7 @@
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
+
<chapter id="writing-tools" xreflabel="Writing a New Valgrind Tool">
<title>Writing a New Valgrind Tool</title>
@@ -279,18 +280,16 @@
<sect2 id="writing-tools.howtoolswork" xreflabel="How tools work">
<title>How tools work</title>
-<para>Tools must define various functions for instrumenting
-programs that are called by Valgrind's core. They are then linked
-against the coregrind library
-(<computeroutput>libcoregrind.a</computeroutput>) that valgrind
-provides as well as the VEX library
-(<computeroutput>libvex.a</computeroutput>) that also comes with
-valgrind and provides the JIT engine.</para>
+<para>Tools must define various functions for instrumenting programs
+that are called by Valgrind's core. They are then linked against the
+coregrind library (<filename>libcoregrind.a</filename>) that valgrind
+provides as well as the VEX library (<filename>libvex.a</filename>) that
+also comes with valgrind and provides the JIT engine.</para>
-<para>Each tool is linked as a statically linked program and placed
-in the valgrind library directory from where valgrind will load it
-automatically when the <computeroutput>--tool</computeroutput> option
-is used to select it.</para>
+<para>Each tool is linked as a statically linked program and placed in
+the valgrind library directory from where valgrind will load it
+automatically when the <option>--tool</option> option is used to select
+it.</para>
</sect2>
@@ -298,11 +297,11 @@
<sect2 id="writing-tools.gettingcode" xreflabel="Getting the code">
<title>Getting the code</title>
-<para>To write your own tool, you'll need the Valgrind source code.
-A normal source distribution should do, although you might want to
-check out the latest code from the Subversion repository. See the
-information about how to do so at
-<ulink url="&vg-svn-repo;">the Valgrind website</ulink>.</para>
+<para>To write your own tool, you'll need the Valgrind source code. A
+normal source distribution should do, although you might want to check
+out the latest code from the Subversion repository. See the information
+about how to do so at <ulink url="&vg-svn-repo;">the Valgrind
+website</ulink>.</para>
</sect2>
@@ -310,68 +309,59 @@
<sect2 id="writing-tools.gettingstarted" xreflabel="Getting started">
<title>Getting started</title>
-<para>Valgrind uses GNU <computeroutput>automake</computeroutput>
-and <computeroutput>autoconf</computeroutput> for the creation of
-Makefiles and configuration. But don't worry, these instructions
-should be enough to get you started even if you know nothing
-about those tools.</para>
+<para>Valgrind uses GNU <computeroutput>automake</computeroutput> and
+<computeroutput>autoconf</computeroutput> for the creation of Makefiles
+and configuration. But don't worry, these instructions should be enough
+to get you started even if you know nothing about those tools.</para>
<para>In what follows, all filenames are relative to Valgrind's
top-level directory <computeroutput>valgrind/</computeroutput>.</para>
<orderedlist>
<listitem>
- <para>Choose a name for the tool, and an abbreviation that can
- be used as a short prefix. We'll use
- <computeroutput>foobar</computeroutput> and
- <computeroutput>fb</computeroutput> as an example.</para>
+ <para>Choose a name for the tool, and an abbreviation that can be used
+ as a short prefix. We'll use <computeroutput>foobar</computeroutput>
+ and <computeroutput>fb</computeroutput> as an example.</para>
</listitem>
<listitem>
- <para>Make a new directory
- <computeroutput>foobar/</computeroutput> which will hold the
- tool.</para>
+ <para>Make a new directory <computeroutput>foobar/</computeroutput>
+ which will hold the tool.</para>
</listitem>
<listitem>
- <para>Copy <computeroutput>none/Makefile.am</computeroutput>
- into <computeroutput>foobar/</computeroutput>. Edit it by
- replacing all occurrences of the string
- <computeroutput>"none"</computeroutput> with
- <computeroutput>"foobar"</computeroutput> and the one
- occurrence of the string <computeroutput>"nl_"</computeroutput>
- with <computeroutput>"fb_"</computeroutput>. It might be worth
- trying to understand this file, at least a little; you might
- have to do more complicated things with it later on. In
- particular, the name of the
- <computeroutput>foobar_SOURCES</computeroutput>
- variable determines the name of the tool, which
- determines what name must be passed to the
- <computeroutput>--tool</computeroutput> option to use the
- tool.</para>
+ <para>Copy <filename>none/Makefile.am</filename> into
+ <computeroutput>foobar/</computeroutput>. Edit it by replacing all
+ occurrences of the string <computeroutput>"none"</computeroutput> with
+ <computeroutput>"foobar"</computeroutput> and the one occurrence of
+ the string <computeroutput>"nl_"</computeroutput> with
+ <computeroutput>"fb_"</computeroutput>. It might be worth trying to
+ understand this file, at least a little; you might have to do more
+ complicated things with it later on. In particular, the name of the
+ <computeroutput>foobar_SOURCES</computeroutput> variable determines
+ the name of the tool, which determines what name must be passed to the
+ <option>--tool</option> option to use the tool.</para>
</listitem>
<listitem>
<para>Copy <filename>none/nl_main.c</filename> into
<computeroutput>foobar/</computeroutput>, renaming it as
- <filename>fb_main.c</filename>. Edit it by changing the lines
- in <computeroutput>pre_clo_init()</computeroutput> to
- something appropriate for the tool. These fields are used in
- the startup message, except for
- <computeroutput>bug_reports_to</computeroutput> which is used
- if a tool assertion fails.</para>
+ <filename>fb_main.c</filename>. Edit it by changing the lines in
+ <function>pre_clo_init()</function> to something appropriate for the
+ tool. These fields are used in the startup message, except for
+ <computeroutput>bug_reports_to</computeroutput> which is used if a
+ tool assertion fails.</para>
</listitem>
<listitem>
- <para>Edit <computeroutput>Makefile.am</computeroutput>,
- adding the new directory
+ <para>Edit <filename>Makefile.am</filename>, adding the new directory
<computeroutput>foobar</computeroutput> to the
<computeroutput>SUBDIRS</computeroutput> variable.</para>
</listitem>
<listitem>
- <para>Edit <computeroutput>configure.in</computeroutput>,
- adding <computeroutput>foobar/Makefile</computeroutput> to the
+ <para>Edit <filename>configure.in</filename>, adding
+ <filename>foobar/Makefile</filename> to the
<computeroutput>AC_OUTPUT</computeroutput> list.</para>
</listitem>
@@ -382,8 +372,8 @@
./configure --prefix=`pwd`/inst
make install]]></programlisting>
- <para>It should automake, configure and compile without
- errors, putting copies of the tool in
+ <para>It should automake, configure and compile without errors,
+ putting copies of the tool in
<computeroutput>foobar/</computeroutput> and
<computeroutput>inst/lib/valgrind/</computeroutput>.</para>
</listitem>
@@ -412,13 +402,13 @@
</orderedlist>
-<para>These steps don't have to be followed exactly - you can
-choose different names for your source files, and use a different
-<computeroutput>--prefix</computeroutput> for
+<para>These steps don't have to be followed exactly - you can choose
+different names for your source files, and use a different
+<option>--prefix</option> for
<computeroutput>./configure</computeroutput>.</para>
-<para>Now that we've setup, built and tested the simplest
-possible tool, onto the interesting stuff...</para>
+<para>Now that we've setup, built and tested the simplest possible tool,
+onto the interesting stuff...</para>
</sect2>
@@ -435,16 +425,15 @@
fini()]]></programlisting>
<para>Also, it must use the macro
-<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput>
-exactly once in its source code. If it doesn't, you will get a
-link error involving
-<computeroutput>VG_(tool_interface_version)</computeroutput>.
-This macro is used to ensure the core/tool interface used by the
-core and a plugged-in tool are binary compatible.</para>
+<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput> exactly
+once in its source code. If it doesn't, you will get a link error
+involving <computeroutput>VG_(tool_interface_version)</computeroutput>.
+This macro is used to ensure the core/tool interface used by the core
+and a plugged-in tool are binary compatible.</para>
-<para>In addition, if a tool wants to use some of the optional
-services provided by the core, it may have to define other
-functions and tell the code about them.</para>
+<para>In addition, if a tool wants to use some of the optional services
+provided by the core, it may have to define other functions and tell the
+code about them.</para>
</sect2>
@@ -454,58 +443,52 @@
<title>Initialisation</title>
<para>Most of the initialisation should be done in
-<computeroutput>pre_clo_init()</computeroutput>. Only use
-<computeroutput>post_clo_init()</computeroutput> if a tool
-provides command line options and must do some initialisation
-after option processing takes place
-(<computeroutput>"clo"</computeroutput> stands for "command line
+<function>pre_clo_init()</function>. Only use
+<function>post_clo_init()</function> if a tool provides command line
+options and must do some initialisation after option processing takes
+place (<computeroutput>"clo"</computeroutput> stands for "command line
options").</para>
-<para>First of all, various "details" need to be set for a tool,
-using the functions
-<computeroutput>VG_(details_*)()</computeroutput>. Some are all
-compulsory, some aren't. Some are used when constructing the
-startup message,
-<computeroutput>detail_bug_reports_to</computeroutput> is used if
-<computeroutput>VG_(tool_panic)()</computeroutput> is ever
-called, or a tool assertion fails. Others have other uses.</para>
+<para>First of all, various "details" need to be set for a tool, using
+the functions <function>VG_(details_*)()</function>. Some are all
+compulsory, some aren't. Some are used when constructing the startup
+message, <computeroutput>detail_bug_reports_to</computeroutput> is used
+if <computeroutput>VG_(tool_panic)()</computeroutput> is ever called, or
+a tool assertion fails. Others have other uses.</para>
-<para>Second, various "needs" can be set for a tool, using the
-functions <computeroutput>VG_(needs_*)()</computeroutput>. They
-are mostly booleans, and can be left untouched (they default to
-<computeroutput>False</computeroutput>). They determine whether
-a tool can do various things such as: record, report and suppress
-errors; process command line options; wrap system calls; record
-extra information about malloc'd blocks, etc.</para>
+<para>Second, various "needs" can be set for a tool, using the functions
+<function>VG_(needs_*)()</function>. They are mostly booleans, and can
+be left untouched (they default to <varname>False</varname>). They
+determine whether a tool can do various things such as: record, report
+and suppress errors; process command line options; wrap system calls;
+record extra information about malloc'd blocks, etc.</para>
-<para>For example, if a tool wants the core's help in recording
-and reporting errors, it must call
-<computeroutput>VG_(needs_tool_errors)</computeroutput> and provide
-definitions of eight functions for comparing errors, printing out
-errors, reading suppressions from a suppressions file, etc.
-While writing these functions requires some work, it's much less
-than doing error handling from scratch because the core is doing
-most of the work. See the function
-<computeroutput>VG_(needs_tool_errors)</computeroutput> in
-<filename>include/pub_tool_tooliface.h</filename> for full details of all
-the needs.</para>
+<para>For example, if a tool wants the core's help in recording and
+reporting errors, it must call
+<function>VG_(needs_tool_errors)</function> and provide definitions of
+eight functions for comparing errors, printing out errors, reading
+suppressions from a suppressions file, etc. While writing these
+functions requires some work, it's much less than doing error handling
+from scratch because the core is doing most of the work. See the
+function <function>VG_(needs_tool_errors)</function> in
+<filename>include/pub_tool_tooliface.h</filename> for full details of
+all the needs.</para>
-<para>Third, the tool can indicate which events in core it wants
-to be notified about, using the functions
-<computeroutput>VG_(track_*)()</computeroutput>. These include
-things such as blocks of memory being malloc'd, the stack pointer
-changing, a mutex being locked, etc. If a tool wants to know
-about this, it should provide a pointer to a function, which will
-be called when that event happens.</para>
+<para>Third, the tool can indicate which events in core it wants to be
+notified about, using the functions <function>VG_(track_*)()</function>.
+These include things such as blocks of memory being malloc'd, the stack
+pointer changing, a mutex being locked, etc. If a tool wants to know
+about this, it should provide a pointer to a function, which will be
+called when that event happens.</para>
-<para>For example, if the tool want to be notified when a new
-block of memory is malloc'd, it should call
-<computeroutput>VG_(track_new_mem_heap)()</computeroutput> with
-an appropriate function pointer, and the assigned function will
-be called each time this happens.</para>
+<para>For example, if the tool want to be notified when a new block of
+memory is malloc'd, it should call
+<function>VG_(track_new_mem_heap)()</function> with an appropriate
+function pointer, and the assigned function will be called each time
+this happens.</para>
-<para>More information about "details", "needs" and "trackable
-events" can be found in
+<para>More information about "details", "needs" and "trackable events"
+can be found in
<filename>include/pub_tool_tooliface.h</filename>.</para>
</sect2>
@@ -515,17 +498,16 @@
<sect2 id="writing-tools.instr" xreflabel="Instrumentation">
<title>Instrumentation</title>
-<para><computeroutput>instrument()</computeroutput> is the
-interesting one. It allows you to instrument
-<emphasis>VEX IR</emphasis>, which is Valgrind's RISC-like
-intermediate language. VEX IR is described in
+<para><function>instrument()</function> is the interesting one. It
+allows you to instrument <emphasis>VEX IR</emphasis>, which is
+Valgrind's RISC-like intermediate language. VEX IR is described in
<xref linkend="mc-tech-docs.ucode"/>.</para>
<para>The easiest way to instrument VEX IR is to insert calls to C
functions when interesting things happen. See the tool "Lackey"
-(<filename>lackey/lk_main.c</filename>) for a simple example of
-this, or Cachegrind (<filename>cachegrind/cg_main.c</filename>)
-for a more complex example.</para>
+(<filename>lackey/lk_main.c</filename>) for a simple example of this, or
+Cachegrind (<filename>cachegrind/cg_main.c</filename>) for a more
+complex example.</para>
</sect2>
@@ -534,9 +516,9 @@
<sect2 id="writing-tools.fini" xreflabel="Finalisation">
<title>Finalisation</title>
-<para>This is where you can present the final results, such as a
-summary of the information collected. Any log files should be
-written out at this point.</para>
+<para>This is where you can present the final results, such as a summary
+of the information collected. Any log files should be written out at
+this point.</para>
</sect2>
@@ -545,36 +527,34 @@
<sect2 id="writing-tools.otherinfo" xreflabel="Other Important Information">
<title>Other Important Information</title>
-<para>Please note that the core/tool split infrastructure is
-quite complex and not brilliantly documented. Here are some
-important points, but there are undoubtedly many others that I
-should note but haven't thought of.</para>
+<para>Please note that the core/tool split infrastructure is quite
+complex and not brilliantly documented. Here are some important points,
+but there are undoubtedly many others that I should note but haven't
+thought of.</para>
-<para>The files <filename>include/pub_tool_*.h</filename> contain
-all the types, macros, functions, etc. that a tool should
-(hopefully) need, and are the only <filename>.h</filename> files
-a tool should need to
+<para>The files <filename>include/pub_tool_*.h</filename> contain all
+the types, macros, functions, etc. that a tool should (hopefully) need,
+and are the only <filename>.h</filename> files a tool should need to
<computeroutput>#include</computeroutput>.</para>
-<para>In particular, you can't use anything from the
-C library (there are deep reasons for this, trust us). Valgrind
-provides an implementation of a reasonable subset of the C
-library, details of which are in
-<filename>pub_tool_libc*.h</filename>.</para>
+<para>In particular, you can't use anything from the C library (there
+are deep reasons for this, trust us). Valgrind provides an
+implementation of a reasonable subset of the C library, details of which
+are in <filename>pub_tool_libc*.h</filename>.</para>
-<para>Similarly, when writing a tool, you shouldn't need to look
-at any of the code in Valgrind's core. Although it might be
-useful sometimes to help understand something.</para>
+<para>Similarly, when writing a tool, you shouldn't need to look at any
+of the code in Valgrind's core. Although it might be useful sometimes
+to help understand something.</para>
<para>The <filename>pub_tool_*.h</filename> files have a reasonable
-amount of documentation in it that should hopefully be enough to get
-you going. But ultimately, the tools distributed (Memcheck,
-Addrcheck, Cachegrind, Lackey, etc.) are probably the best
-documentation of all, for the moment.</para>
+amount of documentation in it that should hopefully be enough to get you
+going. But ultimately, the tools distributed (Memcheck, Addrcheck,
+Cachegrind, Lackey, etc.) are probably the best documentation of all,
+for the moment.</para>
<para>Note that the <computeroutput>VG_</computeroutput> macro is used
-heavily. This just prepends a longer string in front of names to
-avoid potential namespace clashes.</para>
+heavily. This just prepends a longer string in front of names to avoid
+potential namespace clashes.</para>
</sect2>
@@ -589,8 +569,9 @@
<sect3 id="writing-tools.segfaults">
<title>Segmentation Faults</title>
-<para>If you are getting segmentation faults in C functions used
-by your tool, the usual GDB command:</para>
+<para>If you are getting segmentation faults in C functions used by your
+tool, the usual GDB command:</para>
+
<screen><![CDATA[
gdb <prog> core]]></screen>
<para>usually gives the location of the segmentation fault.</para>
@@ -601,49 +582,51 @@
<sect3 id="writing-tools.debugfns">
<title>Debugging C functions</title>
-<para>If you want to debug C functions used by your tool, you can
+<para>If you want to debug C functions used by your tool, you can
achieve this by following these steps:</para>
<orderedlist>
- <listitem>
- <para>Set <computeroutput>VALGRIND_LAUNCHER</computeroutput> to
- <computeroutput><![CDATA[<prefix>/bin/valgrind]]></computeroutput>:</para>
+ <listitem>
+ <para>Set <computeroutput>VALGRIND_LAUNCHER</computeroutput> to
+ <computeroutput><![CDATA[<prefix>/bin/valgrind]]></computeroutput>:</para>
<programlisting>
export VALGRIND_LAUNCHER=/usr/local/bin/valgrind</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>Then run <computeroutput><![CDATA[ gdb <prefix>/lib/valgrind/<platform>/<tool>:]]></computeroutput></para>
+ <listitem>
+ <para>Then run <computeroutput><![CDATA[ gdb <prefix>/lib/valgrind/<platform>/<tool>:]]></computeroutput></para>
<programlisting>
gdb /usr/local/lib/valgrind/ppc32-linux/lackey</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>Do <computeroutput>handle SIGSEGV SIGILL nostop noprint</computeroutput> in
- GDB to prevent GDB from stopping on a SIGSEGV or SIGILL:</para>
+ <listitem>
+ <para>Do <computeroutput>handle SIGSEGV SIGILL nostop
+ noprint</computeroutput> in GDB to prevent GDB from stopping on a
+ SIGSEGV or SIGILL:</para>
<programlisting>
(gdb) handle SIGILL SIGSEGV nostop noprint</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>Set any breakpoints you want and proceed as normal for GDB:</para>
+ <listitem>
+ <para>Set any breakpoints you want and proceed as normal for GDB:</para>
<programlisting>
(gdb) b vgPlain_do_exec</programlisting>
- <para>The macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you
- want to set a breakpoint VG_(do_exec), you could do like this in GDB.</para>
- </listitem>
+ <para>The macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you
+ want to set a breakpoint VG_(do_exec), you could do like this in
+ GDB.</para>
+ </listitem>
- <listitem>
- <para>Run the tool with required options:</para>
+ <listitem>
+ <para>Run the tool with required options:</para>
<programlisting>
(gdb) run `pwd`</programlisting>
- </listitem>
+ </listitem>
</orderedlist>
-<para>GDB may be able to give you useful information. Note that
-by default most of the system is built with
-<computeroutput>-fomit-frame-pointer</computeroutput>, and you'll
-need to get rid of this to extract useful tracebacks from GDB.</para>
+<para>GDB may be able to give you useful information. Note that by
+default most of the system is built with
+<option>-fomit-frame-pointer</option>, and you'll need to get rid of
+this to extract useful tracebacks from GDB.</para>
</sect3>
@@ -651,11 +634,10 @@
<sect3 id="writing-tools.ucode-probs">
<title>UCode Instrumentation Problems</title>
-<para>If you are having problems with your VEX UIR instrumentation,
-it's likely that GDB won't be able to help at all. In this case,
-Valgrind's <computeroutput>--trace-flags</computeroutput>
-option is invaluable for observing the results of
-instrumentation.</para>
+<para>If you are having problems with your VEX UIR instrumentation, it's
+likely that GDB won't be able to help at all. In this case, Valgrind's
+<option>--trace-flags</option> option is invaluable for observing the
+results of instrumentation.</para>
</sect3>
@@ -663,13 +645,13 @@
<sect3 id="writing-tools.misc">
<title>Miscellaneous</title>
-<para>If you just want to know whether a program point has been
-reached, using the <computeroutput>OINK</computeroutput> macro
-(in <filename>include/pub_tool_libcprint.h</filename>) can be easier
-than using GDB.</para>
+<para>If you just want to know whether a program point has been reached,
+using the <computeroutput>OINK</computeroutput> macro (in
+<filename>include/pub_tool_libcprint.h</filename>) can be easier than
+using GDB.</para>
-<para>The other debugging command line options can be useful too
-(run <computeroutput>valgrind --help-debug</computeroutput> for the
+<para>The other debugging command line options can be useful too (run
+<computeroutput>valgrind --help-debug</computeroutput> for the
list).</para>
</sect3>
@@ -689,30 +671,27 @@
<sect2 id="writing-tools.suppressions" xreflabel="Suppressions">
<title>Suppressions</title>
-<para>If your tool reports errors and you want to suppress some
-common ones, you can add suppressions to the suppression files.
-The relevant files are
-<computeroutput>valgrind/*.supp</computeroutput>; the final
-suppression file is aggregated from these files by combining the
-relevant <computeroutput>.supp</computeroutput> files depending
-on the versions of linux, X and glibc on a system.</para>
+<para>If your tool reports errors and you want to suppress some common
+ones, you can add suppressions to the suppression files. The relevant
+files are <filename>valgrind/*.supp</filename>; the final suppression
+file is aggregated from these files by combining the relevant
+<filename>.supp</filename> files depending on the versions of linux, X
+and glibc on a system.</para>
<para>Suppression types have the form
<computeroutput>tool_name:suppression_name</computeroutput>. The
-<computeroutput>tool_name</computeroutput> here is the name you
-specify for the tool during initialisation with
-<computeroutput>VG_(details_name)()</computeroutput>.</para>
+<computeroutput>tool_name</computeroutput> here is the name you specify
+for the tool during initialisation with
+<function>VG_(details_name)()</function>.</para>
</sect2>
-<!--
<sect2 id="writing-tools.docs" xreflabel="Documentation">
<title>Documentation</title>
-<para>As of version &rel-version;, Valgrind documentation has
-been converted to XML. Why?
-See <ulink url="http://www.ucc.ie/xml/">The XML FAQ</ulink>.
+<para>As of version 3.0.0, Valgrind documentation has been converted to
+XML. Why? See <ulink url="http://www.ucc.ie/xml/">The XML FAQ</ulink>.
</para>
@@ -743,186 +722,14 @@
<computeroutput>valgrind/docs/lib/</computeroutput>. You
shouldn't need to modify these in any way.</para>
-<para><command>Catalogs:</command> Assuming that you have the
-various tools listed above installed, you will probably need to
-modify
-<computeroutput>valgrind/docs/lib/vg-catalog.xml</computeroutput>
-so that the parser can find your DocBook installation. Catalogs
-provide a mapping from generic addresses to specific local
-directories on a given machine. Just add another
-<computeroutput>group</computeroutput> to this file, reflecting
-your local installation.</para>
-
-</sect3>
-
-
-<sect3 id="writing-tools.writing" xreflabel="Writing the Documentation">
-<title>Writing the Documentation</title>
-
-<para>If you aren't confident using XML, or you have problems
-with the toolchain, then write your documentation in text format,
-email it to
-<computeroutput>&vg-vemail;</computeroutput>, and
-someone will convert it to XML for you. Otherwise, follow these
-steps (using <computeroutput>foobar</computeroutput> as the
-example tool name again):</para>
-
-<orderedlist>
-
- <listitem>
- <para>Make a directory
- <computeroutput>valgrind/foobar/docs/</computeroutput>.</para>
- </listitem>
-
- <listitem>
- <para>Copy the xml tool documentation template file
- <computeroutput>valgrind/docs/xml/tool-template.xml</computeroutput>
- to <computeroutput>foobar/docs/</computeroutput>, and rename it
- to
- <computeroutput>foobar/docs/fb-manual.xml</computeroutput>.</para>
- <para><command>Note</command>: there is a *really stupid* tetex
- bug with underscores in filenames, so don't use '_'.</para>
- </listitem>
-
- <listitem>
- <para>Write the documentation. There are some helpful bits and
- pieces on using xml markup in
- <filename>valgrind/docs/xml/xml_help.txt</filename>.</para>
- </listitem>
-
- <listitem>
- <para>Validate <computeroutput>foobar/docs/fb-manual.xml</computeroutput>
- using the shell script
- <filename>valgrind/docs/lib/xmlproc.sh</filename>.</para>
-<screen><![CDATA[
-% cd valgrind/docs/lib/
-% ./xmlproc.sh -valid ../../foobar/docs/fb-manual.xml
-]]></screen>
-
- <para>If you have linked to other documents in the Valgrind
- Documentation Set, you will get errors of the form:</para>
-
-<screen><![CDATA[
-fb-manual.xml:1632: element xref: validity error :
- IDREF attribute linkend references an unknown ID "mc-tech-docs"
-]]></screen>
-
- <para>Ignore (only) these - they will disappear when
- <filename>fb-manual.xml</filename> is integrated into the
- Set.</para>
-
- <para>Because the xml toolchain is fragile, it is important to
- ensure that <computeroutput>fb-manual.xml</computeroutput> won't
- break the documentation set build. Note that just because an
- xml file happily transforms to html does not necessarily mean
- the same holds true for pdf/ps.</para>
- </listitem>
-
- <listitem>
- <para>You can (re-)generate <filename>fb-manual.html</filename>
- while you are writing <filename>fb-manual.xml</filename> to help
- you see how it's looking. The generated file
- <filename>fb-manual.html</filename> will be output in
- <computeroutput>foobar/docs/</computeroutput>.</para>
-
-<screen><![CDATA[
-% ./xmlproc.sh -html ../../foobar/docs/fb-manual.xml
-]]></screen>
- </listitem>
-
- <listitem>
- <para>When you have finished, generate html, pdf and ps output
- to check all is well:</para>
-
-<screen><![CDATA[
-% cp ../../foobar/fb-manual.xml .
-% ./xmlproc.sh -test fb-manual.xml
-]]></screen>
-
- <para>Check the output files (<filename>index.html,
- fb-manual.pdf, fb-manual.ps</filename>) in
- <computeroutput>/lib/test/</computeroutput> with the relevant
- viewers. When you are happy and have finished tinkering with
- <computeroutput>fb-manual.xml</computeroutput>:</para>
-
-<screen><![CDATA[
-% ./xmlproc.sh -clean fb-manual.xml
-]]></screen>
-</listitem>
-
- <listitem>
- <para>In order for your documentation to be included in the
- User Manual, the relevant entries must be made in
- <filename>/valgrind/docs/xml/vg-bookset.xml</filename> in this
- format (hopefully, it should be pretty obvious):</para>
-
-<programlisting><![CDATA[
-<!ENTITY fb-manual SYSTEM "../../foobar/docs/fb-manual.xml">
-... ...
-&fb-manual;
-]]></programlisting>
-
- <para>Send a patch for this to
- <computeroutput>&vg-vemail;</computeroutput>.</para>
-
- <para>To achieve true anality, try for a full doc-set build:</para>
-<screen><![CDATA[
-% cd valgrind/docs/
-% make all
-]]></screen>
- </listitem>
-
-</orderedlist>
-
-</sect3>
-
-</sect2>
--->
-<sect2 id="writing-tools.docs" xreflabel="Documentation">
-<title>Documentation</title>
-
-<para>As of version &rel-version;, Valgrind documentation has
-been converted to XML. Why?
-See <ulink url="http://www.ucc.ie/xml/">The XML FAQ</ulink>.
-</para>
-
-
-<sect3 id="writing-tools.xml" xreflabel="The XML Toolchain">
-<title>The XML Toolchain</title>
-
-<para>If you are feeling conscientious and want to write some
-documentation for your tool, please use XML. The Valgrind
-Docs use the following toolchain and versions:</para>
-
-<programlisting>
- xmllint: using libxml version 20607
- xsltproc: using libxml 20607, libxslt 10102 and libexslt 802
- pdfxmltex: pdfTeX (Web2C 7.4.5) 3.14159-1.10b
- pdftops: version 3.00
- DocBook: version 4.2
-</programlisting>
-
-<para><command>Latency:</command> you should note that latency is
-a big problem: DocBook is constantly being updated, but the tools
-tend to lag behind somewhat. It is important that the versions
-get on with each other, so if you decide to upgrade something,
-then you need to ascertain whether things still work nicely -
-this *cannot* be assumed.</para>
-
-<para><command>Stylesheets:</command> The Valgrind docs use
-various custom stylesheet layers, all of which are in
-<computeroutput>valgrind/docs/lib/</computeroutput>. You
-shouldn't need to modify these in any way.</para>
-
-<para><command>Catalogs:</command> Assuming that you have the
-various tools listed above installed, you will probably need to
-modify
-<computeroutput>valgrind/docs/lib/vg-catalog.xml</computeroutput>
-so that the parser can find your DocBook installation. Catalogs
-provide a mapping from generic addresses to specific local
-directories on a given machine. Just add another
-<computeroutput>group</computeroutput> to this file, reflecting
-your local installation.</para>
+<para><command>Catalogs:</command> Catalogs provide a mapping from
+generic addresses to specific local directories on a given machine.
+Most recent Linux distributions have adopted a common place for storing
+catalogs (<filename>/etc/xml/</filename>). Assuming that you have the
+various tools listed above installed, you probably won't need to modify
+your catalogs. But if you do, then just add another
+<computeroutput>group</computeroutput> to this file, reflecting your
+local installation.</para>
</sect3>
@@ -937,34 +744,34 @@
<listitem>
<para>Make a directory
- <computeroutput>valgrind/foobar/docs/</computeroutput>.</para>
- </listitem>
+ <computeroutput>valgrind/foobar/docs/</computeroutput>.</para>
+ </listitem>
- <listitem>
- <para>Copy the XML documentation file for the tool Nulgrind from
- <computeroutput>valgrind/none/docs/nl-manual.xml</computeroutput>
- to <computeroutput>foobar/docs/</computeroutput>, and rename it
- to
- <computeroutput>foobar/docs/fb-manual.xml</computeroutput>.</para>
- <para><command>Note</command>: there is a *really stupid* tetex
- bug with underscores in filenames, so don't use '_'.</para>
- </listitem>
+ <listitem>
+ <para>Copy the XML documentation file for the tool Nulgrind from
+ <filename>valgrind/none/docs/nl-manual.xml</filename> to
+ <computeroutput>foobar/docs/</computeroutput>, and rename it to
+ <filename>foobar/docs/fb-manual.xml</filename>.</para>
- <listitem>
- <para>Write the documentation. There are some helpful bits and
- pieces on using xml markup in
- <filename>valgrind/docs/xml/xml_help.txt</filename>.</para>
- </listitem>
+ <para><command>Note</command>: there is a *really stupid* tetex bug
+ with underscores in filenames, so don't use '_'.</para>
+ </listitem>
- <listitem>
- <para>Include it in the User Manual by adding the relevant entry must
- be added to <filename>valgrind/docs/xml/manual.xml</filename>. Copy
- and edit an existing entry.</para>
- </listitem>
+ <listitem>
+ <para>Write the documentation. There are some helpful bits and
+ pieces on using xml markup in
+ <filename>valgrind/docs/xml/xml_help.txt</filename>.</para>
+ </listitem>
- <listitem>
- <para>Validate <computeroutput>foobar/docs/fb-manual.xml</computeroutput>
- using the following command from within <filename>valgrind/docs/</filename>:
+ <listitem>
+ <para>Include it in the User Manual by adding the relevant entry to
+ <filename>valgrind/docs/xml/manual.xml</filename>. Copy and edit an
+ existing entry.</para>
+ </listitem>
+
+ <listitem>
+ <para>Validate <filename>foobar/docs/fb-manual.xml</filename> using
+ the following command from within <filename>valgrind/docs/</filename>:
</para>
<screen><![CDATA[
% make valid
@@ -977,41 +784,37 @@
attribute base of element chapter
]]></screen>
- <para>Ignore (only) these -- they're not important.</para>
+ <para>Ignore (only) these -- they're not important.</para>
- <para>Because the xml toolchain is fragile, it is important to
- ensure that <filename>fb-manual.xml</filename> won't
- break the documentation set build. Note that just because an
- xml file happily transforms to html does not necessarily mean
- the same holds true for pdf/ps.</para>
- </listitem>
+ <para>Because the xml toolchain is fragile, it is important to ensure
+ that <filename>fb-manual.xml</filename> won't break the documentation
+ set build. Note that just because an xml file happily transforms to
+ html does not necessarily mean the same holds true for pdf/ps.</para>
+ </listitem>
- <listitem>
- <para>You can (re-)generate the HTML docs
- while you are writing <filename>fb-manual.xml</filename> to help
- you see how it's looking. The generated files end up in
- <filename>valgrind/docs/html/</filename>. Use the following
- command, within <filename>valgrind/docs/</filename>:</para>
-
+ <listitem>
+ <para>You can (re-)generate the HTML docs while you are writing
+ <filename>fb-manual.xml</filename> to help you see how it's looking.
+ The generated files end up in
+ <filename>valgrind/docs/html/</filename>. Use the following
+ command, within <filename>valgrind/docs/</filename>:</para>
<screen><![CDATA[
% make html-docs
]]></screen>
- </listitem>
+ </listitem>
- <listitem>
- <para>When you have finished, also generate pdf and ps output
- to check all is well, from within <filename>valgrind/docs/</filename>:
+ <listitem>
+ <para>When you have finished, also generate pdf and ps output to
+ check all is well, from within <filename>valgrind/docs/</filename>:
</para>
-
<screen><![CDATA[
% make print-docs
]]></screen>
- <para>Check the output <filename>.pdf</filename> and
- <filename>.ps</filename> files in
- <computeroutput>valgrind/docs/print/</computeroutput>.
- </para>
-</listitem>
+ <para>Check the output <filename>.pdf</filename> and
+ <filename>.ps</filename> files in
+ <computeroutput>valgrind/docs/print/</computeroutput>.</para>
+ </listitem>
</orderedlist>
@@ -1023,52 +826,50 @@
<sect2 id="writing-tools.regtests" xreflabel="Regression Tests">
<title>Regression Tests</title>
-<para>Valgrind has some support for regression tests. If you
-want to write regression tests for your tool:</para>
+<para>Valgrind has some support for regression tests. If you want to
+write regression tests for your tool:</para>
<orderedlist>
- <listitem>
- <para>Make a directory
- <computeroutput>foobar/tests/</computeroutput>. Make sure the name
- of the directory is <computeroutput>tests/</computeroutput> as the
- build system assumes that any tests for the tool will be in a
- directory by that name.</para>
- </listitem>
+ <listitem>
+ <para>Make a directory
+ <computeroutput>foobar/tests/</computeroutput>. Make sure the name
+ of the directory is <computeroutput>tests/</computeroutput> as the
+ build system assumes that any tests for the tool will be in a
+ directory by that name.</para>
+ </listitem>
- <listitem>
- <para>Edit <computeroutput>configure.in</computeroutput>,
- adding <computeroutput>foobar/tests/Makefile</computeroutput>
- to the <computeroutput>AC_OUTPUT</computeroutput> list.</para>
- </listitem>
+ <listitem>
+ <para>Edit <filename>configure.in</filename>, adding
+ <filename>foobar/tests/Makefile</filename> to the
+ <computeroutput>AC_OUTPUT</computeroutput> list.</para>
+ </listitem>
- <listitem>
- <para>Write
- <computeroutput>foobar/tests/Makefile.am</computeroutput>. Use
- <computeroutput>memcheck/tests/Makefile.am</computeroutput> as
- an example.</para>
- </listitem>
+ <listitem>
+ <para>Write <filename>foobar/tests/Makefile.am</filename>. Use
+ <filename>memcheck/tests/Makefile.am</filename> as an
+ example.</para>
+ </listitem>
- <listitem>
- <para>Write the tests, <computeroutput>.vgtest</computeroutput>
- test description files,
- <computeroutput>.stdout.exp</computeroutput> and
- <computeroutput>.stderr.exp</computeroutput> expected output
- files. (Note that Valgrind's output goes to stderr.) Some
- details on writing and running tests are given in the comments
- at the top of the testing script
- <computeroutput>tests/vg_regtest</computeroutput>.</para>
- </listitem>
+ <listitem>
+ <para>Write the tests, <computeroutput>.vgtest</computeroutput> test
+ description files, <computeroutput>.stdout.exp</computeroutput> and
+ <computeroutput>.stderr.exp</computeroutput> expected output files.
+ (Note that Valgrind's output goes to stderr.) Some details on
+ writing and running tests are given in the comments at the top of
+ the testing script
+ <computeroutput>tests/vg_regtest</computeroutput>.</para>
+ </listitem>
- <listitem>
- <para>Write a filter for stderr results
- <computeroutput>foobar/tests/filter_stderr</computeroutput>.
- It can call the existing filters in
- <computeroutput>tests/</computeroutput>. See
- <computeroutput>memcheck/tests/filter_stderr</computeroutput>
- for an example; in particular note the
- <computeroutput>$dir</computeroutput> trick that ensures the
- filter works correctly from any directory.</para>
- </listitem>
+ <listitem>
+ <para>Write a filter for stderr results
+ <computeroutput>foobar/tests/filter_stderr</computeroutput>. It can
+ call the existing filters in
+ <computeroutput>tests/</computeroutput>. See
+ <computeroutput>memcheck/tests/filter_stderr</computeroutput> for an
+ example; in particular note the
+ <computeroutput>$dir</computeroutput> trick that ensures the filter
+ works correctly from any directory.</para>
+ </listitem>
</orderedlist>
@@ -1079,27 +880,26 @@
<sect2 id="writing-tools.profiling" xreflabel="Profiling">
<title>Profiling</title>
-<para>Nb: as of 25-Mar-2005, the profiling is broken, and has been
-for a long time...</para>
+<para>Nb: as of 25-Mar-2005, the profiling is broken, and has been for a
+long time...</para>
<para>To do simple tick-based profiling of a tool, include the
line:</para>
<programlisting><![CDATA[
#include "vg_profile.c"]]></programlisting>
-<para>in the tool somewhere, and rebuild (you may have to
-<computeroutput>make clean</computeroutput> first). Then run
-Valgrind with the <computeroutput>--profile=yes</computeroutput>
-option.</para>
-<para>The profiler is stack-based; you can register a profiling
-event with
-<computeroutput>VG_(register_profile_event)()</computeroutput>
-and then use the <computeroutput>VGP_PUSHCC</computeroutput> and
-<computeroutput>VGP_POPCC</computeroutput> macros to record time
-spent doing certain things. New profiling event numbers must not
-overlap with the core profiling event numbers. See
-<filename>include/pub_tool_profile.h</filename> for details and
-Memcheck for an example.</para>
+<para>in the tool somewhere, and rebuild (you may have to
+<computeroutput>make clean</computeroutput> first). Then run Valgrind
+with the <option>--profile=yes</option> option.</para>
+
+<para>The profiler is stack-based; you can register a profiling event
+with <function>VG_(register_profile_event)()</function> and then use the
+<computeroutput>VGP_PUSHCC</computeroutput> and
+<computeroutput>VGP_POPCC</computeroutput> macros to record time spent
+doing certain things. New profiling event numbers must not overlap with
+the core profiling event numbers. See
+<filename>include/pub_tool_profile.h</filename> for details and Memcheck
+for an example.</para>
</sect2>
@@ -1109,11 +909,10 @@
<title>Other Makefile Hackery</title>
<para>If you add any directories under
-<computeroutput>valgrind/foobar/</computeroutput>, you will need
-to add an appropriate <filename>Makefile.am</filename> to it, and
-add a corresponding entry to the
-<computeroutput>AC_OUTPUT</computeroutput> list in
-<filename>valgrind/configure.in</filename>.</para>
+<computeroutput>valgrind/foobar/</computeroutput>, you will need to add
+an appropriate <filename>Makefile.am</filename> to it, and add a
+corresponding entry to the <computeroutput>AC_OUTPUT</computeroutput>
+list in <filename>valgrind/configure.in</filename>.</para>
<para>If you add any scripts to your tool (see Cachegrind for an
example) you need to add them to the
@@ -1127,26 +926,24 @@
<sect2 id="writing-tools.ifacever" xreflabel="Core/tool Interface Versions">
<title>Core/tool Interface Versions</title>
-<para>In order to allow for the core/tool interface to evolve
-over time, Valgrind uses a basic interface versioning system.
-All a tool has to do is use the
-<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput>
-macro exactly once in its code. If not, a link error will occur
-when the tool is built.</para>
+<para>In order to allow for the core/tool interface to evolve over time,
+Valgrind uses a basic interface versioning system. All a tool has to do
+is use the
+<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput> macro
+exactly once in its code. If not, a link error will occur when the tool
+is built.</para>
-<para>The interface version number has the form X.Y. Changes in
-Y indicate binary compatible changes. Changes in X indicate
-binary incompatible changes. If the core and tool has the same
-major version number X they should work together. If X doesn't
-match, Valgrind will abort execution with an explanation of the
-problem.</para>
+<para>The interface version number has the form X.Y. Changes in Y
+indicate binary compatible changes. Changes in X indicate binary
+incompatible changes. If the core and tool has the same major version
+number X they should work together. If X doesn't match, Valgrind will
+abort execution with an explanation of the problem.</para>
-<para>This approach was chosen so that if the interface changes
-in the future, old tools won't work and the reason will be
-clearly explained, instead of possibly crashing mysteriously. We
-have attempted to minimise the potential for binary incompatible
-changes by means such as minimising the use of naked structs in
-the interface.</para>
+<para>This approach was chosen so that if the interface changes in the
+future, old tools won't work and the reason will be clearly explained,
+instead of possibly crashing mysteriously. We have attempted to
+minimise the potential for binary incompatible changes by means such as
+minimising the use of naked structs in the interface.</para>
</sect2>
@@ -1160,45 +957,44 @@
<para>This whole core/tool business is under active development,
although it's slowly maturing.</para>
-<para>The first consequence of this is that the core/tool
-interface will continue to change in the future; we have no
-intention of freezing it and then regretting the inevitable
-stupidities. Hopefully most of the future changes will be to add
-new features, hooks, functions, etc, rather than to change old
-ones, which should cause a minimum of trouble for existing tools,
-and we've put some effort into future-proofing the interface to
-avoid binary incompatibility. But we can't guarantee anything.
-The versioning system should catch any incompatibilities. Just
-something to be aware of.</para>
+<para>The first consequence of this is that the core/tool interface will
+continue to change in the future; we have no intention of freezing it
+and then regretting the inevitable stupidities. Hopefully most of the
+future changes will be to add new features, hooks, functions, etc,
+rather than to change old ones, which should cause a minimum of trouble
+for existing tools, and we've put some effort into future-proofing the
+interface to avoid binary incompatibility. But we can't guarantee
+anything. The versioning system should catch any incompatibilities.
+Just something to be aware of.</para>
-<para>The second consequence of this is that we'd love to hear
-your feedback about it:</para>
+<para>The second consequence of this is that we'd love to hear your
+feedback about it:</para>
<itemizedlist>
- <listitem>
- <para>If you love it or hate it</para>
- </listitem>
- <listitem>
- <para>If you find bugs</para>
- </listitem>
- <listitem>
- <para>If you write a tool</para>
- </listitem>
- <listitem>
- <para>If you have suggestions for new features, needs,
- trackable events, functions</para>
- </listitem>
- <listitem>
- <para>If you have suggestions for making tools easier to
- write</para>
- </listitem>
- <listitem>
- <para>If you have suggestions for improving this
- documentation</para>
- </listitem>
- <listitem>
- <para>If you don't understand something</para>
- </listitem>
+ <listitem>
+ <para>If you love it or hate it</para>
+ </listitem>
+ <listitem>
+ <para>If you find bugs</para>
+ </listitem>
+ <listitem>
+ <para>If you write a tool</para>
+ </listitem>
+ <listitem>
+ <para>If you have suggestions for new features, needs, trackable
+ events, functions</para>
+ </listitem>
+ <listitem>
+ <para>If you have suggestions for making tools easier to
+ write</para>
+ </listitem>
+ <listitem>
+ <para>If you have suggestions for improving this
+ documentation</para>
+ </listitem>
+ <listitem>
+ <para>If you don't understand something</para>
+ </listitem>
</itemizedlist>
<para>or anything else!</para>
diff --git a/docs/xml/xml_help.txt b/docs/xml/xml_help.txt
index 41d5ed7..ae71a6f 100644
--- a/docs/xml/xml_help.txt
+++ b/docs/xml/xml_help.txt
@@ -27,7 +27,7 @@
Important: inside <screen> and <programlisting> blocks, do NOT
use 'html entities' in your markup, eg. '<' If you *do* use
them, they will be output verbatim, which is not what you want.
-
+Instead, wrap the content with CDATA tags (see below).
----------------------------------------------
@@ -83,6 +83,8 @@
</listitem>
</itemizedlist>
+<para>and this is some more text after the list.</para>
+
----------------------------------------------
To achieve this:
@@ -116,12 +118,12 @@
----------------------------------------------
To achieve this:
-<p>It uses the Eraser algorithm described in:<br />
-<br />
- Eraser: A Dynamic Data Race Detector for Multithreaded Programs<br />
- Stefan Savage, Michael Burrows, Patrick Sobalvarro and Thomas Anderson<br />
- ACM Transactions on Computer Systems, 15(4):391-411<br />
- November 1997.<br />
+<p>It uses the Eraser algorithm described in:<br/>
+<br/>
+ Eraser: A Dynamic Data Race Detector for Multithreaded Programs<br/>
+ Stefan Savage, Michael Burrows, Patrick Sobalvarro and Thomas Anderson<br/>
+ ACM Transactions on Computer Systems, 15(4):391-411<br/>
+ November 1997.<br/>
</p>
Do this:
@@ -171,4 +173,4 @@
----------------------------------------------
-Any other helpful hints? Please tell us.
+Any other helpful hints? Please add to this.