1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358
|
." Text automatically generated by txt2man-1.4.7
.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]
.fam T
.fi
.SH DESCRIPTION
\fIvalgrind\fP is a flexible tool for debugging and profiling Linux-x86 executables. The tool consists of a core, which provides a synthetic
x86 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.
.SH OPTIONS
.TP
.B
-h --help
Show help for all \fIoptions\fP, both for the core and for the selected tool.
.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.
.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
-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
--tool=<tool> [In Debian systems, default: memcheck]
Will use the given tool for running \fIvalgrind\fP.
.PP
--track-fds=yes
.TP
.B
--track-fds=no [the default]
Disable/enable tracking of open file descriptors of the debugged
program after exit.
.PP
--demangle=no
.TP
.B
--demangle=yes [the default]
Disable/enable 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.
.RS
.PP
An important fact about demangling is that function names mentioned
in suppressions files should be in their mangled form. \fIvalgrind\fP does
not demangle function names when searching for applicable suppressions,
because to do otherwise would make suppressions file contents dependent
on the state of \fIvalgrind\fP's demangling machinery, and would also be slow
and pointless.
.RE
.TP
.B
--num-callers=<number> [default=4]
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
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.
.RS
.PP
The maximum value for this is 50. Note that higher settings will make
\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
.PP
--db-attach=no [the default]
.TP
.B
--db-attach=yes
When enabled, \fIvalgrind\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 \fIvalgrind\fP not to start a debugger
(by default, will run GDB) for this error.
.PP
Y Ret or y Ret causes \fIvalgrind\fP to start the 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.
.PP
C Ret or c Ret causes \fIvalgrind\fP not to start the debugger, and not to ask
again.
.PP
--db-attach=yes conflicts with --trace-children=yes. You can't use them
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]
Will tell \fIvalgrind\fP to run this debugger when using --db-attach=yes.
.TP
.B
--alignment=<number> [default: 4]
By default \fIvalgrind\fP's malloc, realloc, etc, return 4-byte aligned
addresses. These are suitable for any accesses on x86 processors. Some
programs might however assume that malloc et al return 8- 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 4 and 4096
inclusive, and must be a power of two.
.PP
--sloppy-malloc=no [the default]
.TP
.B
--sloppy-malloc=yes
When enabled, all requests for malloc/calloc are rounded up to a whole
number of machine words -- in other words, made divisible by 4. For
example, a request for 17 bytes of space would result in a 20-byte
area being made available. This works around bugs in sloppy libraries
which assume that they can safely rely on malloc/calloc requests being
rounded up in this fashion. Without the workaround, these libraries tend
to generate large numbers of errors when they access the ends of these
areas.
.RS
.PP
\fIvalgrind\fP snapshots dated 17 Feb 2002 and later are cleverer about this
problem, and you should no longer need to use this flag. To put it
bluntly, if you do need to use this flag, your program violates the
ANSI C semantics defined for malloc and free, even if it appears to
work correctly, and you should fix it, at least if you hope for maximum
portability.
.RE
.PP
--trace-children=no [the default]
.TP
.B
--trace-children=yes
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
--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-file=<filename>
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
--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\fP-listener
program. For further details, see section 2.3.
.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 use as many extra suppressions files as you like.
.PP
--gen-suppressions=no [default]
.TP
.B
--gen-suppressions=yes
When enabled, valgrind will generate a suppression entry for each error found and
print the line
---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----
Pressing Ret, or N Ret or n Ret, causes \fIvalgrind\fP not to show the suppression for this
error.
Y Ret or y Ret causes \fIvalgrind\fP to print the suppression needed to avoid this error using
the --suppressions option.
C Ret or c Ret causes \fIvalgrind\fP not to generate the suppression, and not to ask again.
.TP
.PP
--error-limit=yes [default]
.TP
.B
--error-limit=no
When enabled, \fIvalgrind\fP stops reporting errors after 30000 in total, or 300
different ones, have been seen. This is to stop the error tracking machinery
from becoming a huge performance overhead in programs with many errors.
.PP
--run-libc-freeres=yes [the default]
.TP
.B
--run-libc-freeres=no
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
\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
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 \fIvalgrind\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
--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
- ioctl-VTIME
Use this if you have a program which sets readable file
descriptors to have a timeout by doing ioctl on them with a TCSETA-style
command and a non-zero VTIME timeout value. This is considered potentially
dangerous and therefore is not engaged by default, because it is (remotely)
conceivable that it could cause threads doing read to incorrectly block the
entire process.
You probably want to try this one if you have a program which unexpectedly
blocks in a read from a file descriptor which you know to have been messed
with by ioctl. This could happen, for example, if the descriptor is used to
read input from some kind of screen handling library.
To find out if your program is blocking unexpectedly in the read system call,
run with --trace-syscalls=yes flag.
.TP
.B
- truncate-writes
Use this if you have a threaded program which appears to unexpectedly block whilst writing into a pipe. The effect is to modify all calls to \fBwrite\fP() so that requests to write more than 4096 bytes are treated as if they only requested a write of 4096 bytes. \fIvalgrind\fP does this by changing the count argument of \fBwrite\fP(), as passed to the kernel, so that it is at most 4096. The amount of data written will then be less than the client program asked for, but the client should have a loop around its \fBwrite\fP() call to check whether the requested number of bytes have been written. If not, it should issue further \fBwrite\fP() calls until all the data is written. This all sounds pretty dodgy to me, which is why I've made this behaviour only happen on request. It is not the default behaviour. At the time of writing this (30 June 2002) I have only seen one example where this is necessary, so either the problem is extremely rare or nobody is using \fIvalgrind\fP :-) On experimentation I see that truncate-writes doesn't interact well with ioctl-VTIME, so you probably don't want to try both at once. As above, to find out if your program is blocking unexpectedly in the \fBwrite\fP() system call, you may find the --trace-syscalls=yes --trace-sched=yes flags useful.
.TP
.B
- lax-ioctls
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.
.RE
.PP
There are also some \fIoptions\fP for debugging \fIvalgrind\fP itself. You shouldn't need to use them in the normal run of things. Nevertheless:
.PP
--single-step=no [default]
.TP
.B
--single-step=yes
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.
.PP
--optimise=no
.TP
.B
--optimise=yes [default]
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.
.PP
--profile=no
.TP
.B
--profile=yes [default]
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.
.PP
--trace-syscalls=no [default]
.TP
.B
--trace-syscalls=yes
Enable/disable tracing of system call intercepts.
.PP
--trace-signals=no [default]
.TP
.B
--trace-signals=yes
Enable/disable tracing of signal handling.
.PP
--trace-sched=no [default]
.TP
.B
--trace-sched=yes
Enable/disable tracing of thread scheduling events.
.PP
--trace-pthread=none [default]
--trace-pthread=some
.TP
.B
--trace-pthread=all
Specifies amount of trace detail for pthread-related events.
.PP
--trace-symtab=no [default]
.TP
.B
--trace-symtab=yes
Enable/disable tracing of symbol table reading.
.PP
--trace-malloc=no [default]
.TP
.B
--trace-malloc=yes
Enable/disable tracing of malloc/free (et al) intercepts.
.TP
.B
--stop-after=<number> [default: infinity, more or less]
After <number> basic blocks have been executed, shut down \fIvalgrind\fP and switch
back to running the client on the real CPU.
.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.
.SH SEE ALSO
/usr/share/doc/\fIvalgrind\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.
|