|
From: Robert W. <rj...@du...> - 2005-03-06 02:08:19
|
CVS commit by rjwalsh: More work-in-progress on the manual page. All the core options are now covered. M +349 -172 valgrind.1 1.2 --- valgrind/docs/valgrind.1 #1.1:1.2 @@ -1,11 +1,14 @@ .TH VALGRIND "1" "" "" + .SH NAME \fBvalgrind \fP- a memory debugger for x86-linux + .SH SYNOPSIS .nf .fam C -\fIvalgrind\fP [\fIvalgrind\fP \fIoptions\fP] \fIyour-prog\fP [\fIyour-prog\fP \fIoptions\fP] +\fIvalgrind\fP [\fIvalgrind\fP \fIoptions\fP] \fIyour-program\fP [\fIyour-program\fP \fIoptions\fP] .fam T .fi + .SH DESCRIPTION \fIvalgrind\fP is a flexible program for debugging and profiling Linux-x86 @@ -14,35 +17,17 @@ 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 usage. -.SH CORE OPTIONS -.TP -.B ---alignment=<number> [default: 8] -By default \fIvalgrind\fP's malloc, realloc, etc, return 8-byte aligned -addresses. These are suitable for any accesses on x86 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 ---branchpred -XXX -.TP -.B ---chain-bb -XXX -.TP -.B ---command-line-only -XXX +html documentation for more comprehensive information. + +.SH COMMON CORE OPTIONS + .TP .B --db-attach=<yes|no> [default: no] -When enabled, Valgrind will pause after every error shown, and print -the line +When enabled, \fIvalgrind\fP will pause after every error shown and +print the line: + .PP .nf @@ -52,48 +37,41 @@ .fam T .fi + .RS -Pressing Ret, or N Ret or n Ret, causes Valgrind not to start a debugger -for this error. +Pressing Ret, or N Ret or n Ret, causes \fIvalgrind\fP not to start a +debugger for this error. + .PP -Y Ret or y Ret causes Valgrind to start the debugger (specified by the -\fI--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. +Pressing Y Ret or y Ret causes \fIvalgrind\fP to start the debugger +(specified by the \fI--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 -C Ret or c Ret causes Valgrind not to start the debugger, and not to -ask again. +Pressing C Ret or c Ret causes \fIvalgrind\fI not to start the debugger +and \fIvalgrind\fP will not ask again. + .PP --db-attach=yes conflicts with --trace-children=yes. You can't use them -together. Valgrind 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. +together. \fIvalgrind\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 valgrind -at runtime. \fI%f\fP is replaced with the executable's file name and -\fI%p\fP is replaced by the process ID of the executable. -.TP -.B ---demangle=<yes|no> [default: yes] -Disable/enable automatic demangling (decoding) of C++ names. Enabled by -default. When enabled, Valgrind will attempt to translate encoded C++ -procedure names back to something approaching the original. The demangler -handles symbols mangled by g++ versions 2.X and 3.X. -.TP -.B ---dump-error=<number> [default: inactive] -After the program has exited, show gory details of the translation of -the basic block containing the <number>'th error context. When used -with --single-step=yes, can show the exact x86 instruction causing -an error. This is all fairly dodgy and doesn't work at all if threads -are involved. +Specify the debugger to use with the --db-attach command. The +default debugger is gdb. This option is a template that is expanded by +\fIvalgrind\fP at runtime. \fI%f\fP is replaced with the executable's +file name and \fI%p\fP is replaced by the process ID of the executable. .TP .B + --error-limit=<yes|no> [default: yes] When enabled, \fIvalgrind\fP stops reporting errors after 30000 in total, @@ -103,10 +81,30 @@ .TP .B ---exec -XXX -.TP -.B ---gen-suppressions -Automatically generate suppressions. + +--gen-suppressions=<yes|no> [default: no] +When enabled, \fIvalgrind\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 +\fIvalgrind\fP will not ask again. +.RE + .TP .B @@ -114,4 +112,5 @@ Show help for all \fIoptions\fP, both for the core and for the selected tool. + .TP .B @@ -119,34 +118,17 @@ Show help for all \fIoptions\fP, both for the core and for the selected tool, including options for debugging \fIvalgrind\fP. -.TP -.B ---input-fd -XXX -.TP -.B ---log-fd=<number> [default: 2, stderr] -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. + .TP .B --log-file=<filename> -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, ".pid" and the process ID, so as to create a file per process. -The specified file name may not be the empty string. -.TP -.B ---log-socket=<ip-address:port-number> -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, \fIvalgrind\fP falls back to writing output to the standard error -(stderr). This option is intended to be used in conjunction with the -\fIvalgrind\fP-listener program. For further details, see section 2.3. +Specifies that \fIvalgrind\fP should send all of its messages to the +specified file. In fact, the file name used is created by concatenating +the text filename, ".pid" and the process ID, so as to create a file +per process. The specified file name may not be the empty string. + .TP .B --num-callers=<number> [default=12] -By default, Valgrind shows four levels of function call names to +By default, \fIvalgrind\fP shows four 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 @@ -155,32 +137,208 @@ and that of its two 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 -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. +\fIvalgrind\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 ---optimise=<yes|no> [default: yes] -When enabled, various improvements are applied to the intermediate code, -mainly aimed at allowing the simulated CPU's registers to be cached in -the real CPU's registers over several simulated instructions. +-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 ---pointercheck -XXX +--suppressions=<filename> [default: $PREFIX/lib/\fIvalgrind\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 ---profile=<yes|no> [default: no] -When enabled, does crude internal profiling of \fIvalgrind\fP itself. This -is not for profiling your programs. Rather it is to allow the developers -to assess where \fIvalgrind\fP is spending its time. The tools must be -built for profiling for this to work. +--tool=<toolname> [default: memcheck] +Specify which tool to use. The default tool is memcheck. The following +tools are available: + +.RS .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. +- addrcheck +\fIaddrcheck\fP is similar to memcheck, but does not perform the same +granularity of memory checking. +.TP +.B +- cachegrind +\fIcachegrind\fP is a cache simulator. +.TP +.B +- helgrind +\fIhelgrind\fP spots potential race conditions in your program. +.TP +.B +- lackey +\fIlackey\fP is a sample tool that can be used as a template for +generating your own tools. +.TP +.B +- massif +\fImassif\fP is a heap profiler. It measures how much heap memory your +program uses. +.TP +.B +- memcheck +\fImemcheck\fP is a fine-grained memory checker. +.TP +.B +- none +\fInone\fP performs no function - it simply runs the program under +\fIvalgrind\fP. +.RE + +.TP +.B +--trace-children=<yes|no> [default: no] +When enabled, \fIvalgrind\fP will trace into child processes. This is +confusing and usually not what you want, so is disabled by default. + +.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 \fIvalgrind\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. + +.SH LESS FREQUENTLY USED CORE OPTIONS +.TP +.B +--alignment=<number> [default: 8] +By default \fIvalgrind\fP's malloc, realloc, etc, return 8-byte aligned +addresses. These are suitable for any accesses on x86 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 +--branchpred=<yes|no> [default: no] +This option enables the generation of static branch prediction hints. +In theory this allows the real CPU to do a better job of running the +generated code, but in practice it makes almost no measurable difference. +It may have a large effect on some x86 implementations. + +.TP +.B +--chain-bb=<yes|no> [default: yes] +Enables basic-block chaining. If basic-block chaining is disabled, +the synthetic CPU returns to the scheduler after interpreting each basic +block. With basic block chaining enabled, it can immediately proceed to +the next basic block. This almost always results in a performance gain, +so it is enabled by default. + +.TP +.B +--command-line-only=<yes|no> [default: no] +Normally, \fIvalgrind\fP will look for command-line options in the +following locations: +.RS +.TP +- The \fIvalgrind\fP command line +.TP +- The \fI\.valgrindrc\fP file in the invocation directory +.TP +- The \fI\.valgrindrc\fP file in users home directory +.TP +- The \fI$VALGRIND_OPTS\fP environment variable +.P + +When this option is enabled, \fIvalgrind\fP will only look at the command +line for options. +.RE + +.TP +.B +--demangle=<yes|no> [default: yes] +Enable or disable automatic demangling (decoding) of C++ names. Enabled by +default. When enabled, \fIvalgrind\fP will attempt to translate encoded +C++ procedure names back to something approaching the original. The +demangler handles symbols mangled by g++ versions 2.X and 3.X. + +.TP +.B +--dump-error=<number> +After the program has exited, show gory details of the translation of +the basic block containing the \fI<number>\fP'th error context. When +used with --single-step=yes, can show the exact x86 instruction causing +an error. This is all fairly dodgy and doesn't work at all if threads +are involved. + +.TP +.B +--exec=<filename> +Specify the executable to run. If this is specified, it takes precedence +over the \fIyour-program\fP executable from the command-line. If this is +not specified, \fIvalgrind\fP searches the path for the \fIyour-program\fP +executable, just like a regular shell would. + +.TP +.B +--input-fd=<number> [default: 0, stdin] +Specify the file descriptor to use for reading input from the user. This +is used whenever \fIvalgrind\fP needs to prompt the user for a decision. + +.TP +.B +--log-fd=<number> [default: 2, stderr] +Specifies that \fIvalgrind\fP should send all of its messages to +the specified file descriptor. The default, 2, is the standard error +channel (stderr). Note that this may interfere with the client's own +use of stderr. + +.TP +.B +--log-socket=<ip-address:port-number> +Specifies that \fIvalgrind\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, \fIvalgrind\fP falls back to writing output to +the standard error (stderr). This option is intended to be used in +conjunction with the \fIvalgrind-listener\fP program. For further details, +see section 2.3 of the user manual. + +.TP +.B +--optimise=<yes|no> [default: yes] +When enabled, various improvements are applied to the intermediate code, +mainly aimed at allowing the simulated CPU's registers to be cached in +the real CPU's registers over several simulated instructions. + +.TP +.B +--pointercheck=<yes|no> [default: yes] +When enabled, enforces client address space limits. If this option is +disabled, the client program has full and unfettered access to the part +of the address space used internally by \fIvalgrind\fP. This can cause +unexplained crashes and false error reports, so it is best left enabled. + .TP .B @@ -191,12 +349,14 @@ 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 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 -__libc_freeres specifically to make glibc release all memory it has -allocated. The MemCheck and AddrCheck tools therefore try and run +such as \fIvalgrind\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 @@ -207,12 +367,13 @@ although at the cost of possibly falsely reporting space leaks in libc.so. .RE + .TP .B ---sanity-level=<number> [default: 1] -Set the level of sanity checking to perform. -.TP -.B ---show-below-main -XXX +--show-below-main=<yes|no> [default: no] +When enabled, this option causes full stack backtraces to be emited, +including the part before \fImain\fP in your program (subject to the +\fI--num-callers\fP option.) When disabled, only the part of the stack +backtrace up to and including main is printed. + .TP .B @@ -220,95 +381,111 @@ When enabled, each x86 insn is translated separately into instrumented code. When disabled, translation is done on a per-basic-block basis, -giving much better translations. +giving much better translations. This is needed when running +\fIvalgrind\fP under \fIvalgrind\fP. + .TP .B ---sloppy-malloc -XXX +--sloppy-malloc=<yes|no> [default: no] +When enabled, \fIvalgrind\fP rounds all memory allocation request sizes +up to 4 bytes. + .TP .B ---suppressions=<filename> [default: $PREFIX/lib/\fIvalgrind\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. +--time-stamp=<yes|no> [default: no] +When enabled, a time-stamp is added to all log messages. + .TP .B ---time-stamp -XXX +--weird-hacks=hack1,hack2,\.\.\. +Pass miscellaneous hints to \fIvalgrind\fP which slightly modify the +simulated behaviour in nonstandard or dangerous ways, possibly to help +the simulation of strange features. By default no hacks are enabled. Use +with caution! Currently known hacks are: + +.RS .TP .B ---tool -XXX +- lax-ioctls +If \fIvalgrind\fP encounters an \fIioctl\fP that it doesn't understand, +it normally prints a warning message before continuing. Specifying the +lax-ioctls hack tells \fIvalgrind\fP to be very lax about ioctl handling +and assume that unknown ioctls just behave correctly. .TP .B ---trace-children=<yes|no> [default: no] -When enabled, Valgrind will trace into child processes. This is confusing -and usually not what you want, so is disabled by default. +- ioctl-mmap +Tell \fIvalgrind\fP to search for new memory mappings after an unknown +\fIioctl\fP call. +.RE + +.SH CORE DEBUGGING OPTIONS + .TP .B ---trace-codegen=<yes|no> [default: no] -XXX +--profile=<yes|no> [default: no] +When enabled, does crude internal profiling of \fIvalgrind\fP itself. This +is not for profiling your programs. Rather it is to allow the developers +to assess where \fIvalgrind\fP is spending its time. The tools must be +built for profiling for this to work. + .TP .B ---trace-malloc=<yes|no> [default: no] -Enable/disable tracing of malloc/free (et al) intercepts. +--sanity-level=<number> [default: 1] +Set the level of sanity checking to perform. This is used for debugging +\fIvalgrind\fP. Setting this to 2 or higher can cause more internal +sanity checks to be performed, but can slow your program down +appreciably. Setting this to 0 disables sanity checks. + .TP .B ---trace-redir=<yes|no> [default: no] -XXX +--trace-codegen=<bitmask> +Produce lots of output showing exactly how \fIvalgrind\fP is translating +each basic block. The argument to this option is a 5-bit wide bitmask. +Each bit refers to a specific feature to trace. If the bit is 1, the +feature is traced. If it is 0, the feature is not traced. + +.RS +The traced features are: .TP -.B ---trace-sched=<yes|no> [default: no] -Enable/disable tracing of thread scheduling events. +Bit 1: basic-block disassembly .TP -.B ---trace-signals=<yes|no> [default: no] -Enable/disable tracing of signal handling. +Bit 2: optimization phase .TP -.B ---trace-syscalls=<yes|no> [default: no] -Enable/disable tracing of system call intercepts. +Bit 3: tool instrumentation .TP -.B ---trace-symtab=<yes|no> [default: no] -Enable/disable tracing of symbol table reading. +Bit 4: register allocation +.TP +Bit 5: final code generation +.RE + .TP .B ---track-fds=<yes|no> [default: no] -XXX +--trace-malloc=<yes|no> [default: no] +Enable or disable tracing of malloc, free and other memory-manager calls. + .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. +--trace-redir=<yes|no> [default: no] +Enable or disable tracing of function redirection. + .TP .B ---version -Show the version number of the \fIvalgrind\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. +--trace-sched=<yes|no> [default: no] +Enable or disable tracing of thread scheduling events. + .TP .B ---weird-hacks=hack1,hack2,\.\.\. -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 hacks are enabled. Use -with caution! Currently known hacks are: -.RS +--trace-signals=<yes|no> [default: no] +Enable or disable tracing of signal handling. + .TP .B -- lax-ioctls -If \fIvalgrind\fP encounters an \fIioctl\fP that it doesn't understand, -it normally prints a warning message before continuing. Specifying the -lax-ioctls hack tells \fIvalgrind\fP to be very lax about ioctl handling -and assume that unknown ioctls just behave correctly. +--trace-syscalls=<yes|no> [default: no] +Enable or disable tracing of system call intercepts. + .TP .B -- ioctl-mmap -Tell \fIvalgrind\fP to search for new memory mappings after an unknown -\fIioctl\fP call. -.RE +--trace-symtab=<yes|no> [default: no] +Enable or disable tracing of symbol table reading. + .SH SEE ALSO /usr/share/doc/\fIvalgrind\fP/html/manual.html |