njn | 74e7012 | 2005-03-12 21:02:52 +0000 | [diff] [blame] | 1 | .TH VALGRIND "1" "" "" |
| 2 | |
| 3 | .SH NAME |
| 4 | \fBvalgrind \fP- a memory debugger for x86-linux |
| 5 | |
| 6 | .SH SYNOPSIS |
| 7 | .nf |
| 8 | .fam C |
| 9 | \fIvalgrind\fP [\fIvalgrind\fP \fIoptions\fP] \fIyour-program\fP [\fIyour-program\fP \fIoptions\fP] |
| 10 | .fam T |
| 11 | .fi |
| 12 | |
| 13 | .SH DESCRIPTION |
| 14 | \fBvalgrind\fP is a flexible program for debugging and profiling Linux-x86 |
| 15 | executables. It consists of a core, which provides a synthetic x86 CPU |
| 16 | in software, and a series of "tools", each of which is a debugging or |
| 17 | profiling tool. The architecture is modular, so that new tools can be |
| 18 | created easily and without disturbing the existing structure. |
| 19 | |
| 20 | .PP |
| 21 | This manual page covers only basic usage and options. Please see the |
| 22 | HTML documentation for more comprehensive information. |
| 23 | |
| 24 | .SH INVOCATION |
| 25 | \fBvalgrind\fP is typically invoked as follows: |
| 26 | |
| 27 | valgrind program args |
| 28 | |
| 29 | This runs \fBprogram\fP (with arguments \fBargs\fP) under valgrind |
| 30 | using the \fBmemcheck\fP tool. \fBmemcheck\fP performs a range of |
| 31 | memory-checking functions, including detecting accesses to uninitialized |
| 32 | memory, misuse of allocated memory (double frees, access after free, |
| 33 | etc.) and detecting memory leaks. |
| 34 | |
| 35 | To use a different tool, use the \fB--tool\fP option: |
| 36 | |
| 37 | valgrind --tool=toolname program args |
| 38 | |
| 39 | The following tools are available: |
| 40 | |
| 41 | .RS |
| 42 | .TP |
| 43 | .B |
| 44 | - addrcheck |
| 45 | \fBaddrcheck\fP is similar to memcheck, but does not perform the same |
| 46 | granularity of memory checking. This will run faster and use less memory, |
| 47 | but may miss some problems that \fBmemcheck\fP would catch. |
| 48 | .TP |
| 49 | .B |
| 50 | - cachegrind |
| 51 | \fBcachegrind\fP is a cache simulator. |
| 52 | ." .TP |
| 53 | ." .B |
| 54 | ." - helgrind |
| 55 | ." \fBhelgrind\fP spots potential race conditions in your program. |
| 56 | .TP |
| 57 | .B |
| 58 | - lackey |
| 59 | \fBlackey\fP is a sample tool that can be used as a template for |
| 60 | generating your own tools. After the program terminates, it prints out |
| 61 | some basic statistics about the program execution. |
| 62 | .TP |
| 63 | .B |
| 64 | - massif |
| 65 | \fBmassif\fP is a heap profiler. It measures how much heap memory your |
| 66 | program uses. |
| 67 | .TP |
| 68 | .B |
| 69 | - memcheck |
| 70 | \fBmemcheck\fP is a fine-grained memory checker. |
| 71 | .TP |
| 72 | .B |
| 73 | - none |
| 74 | \fBnone\fP performs no function - it simply runs the program under |
| 75 | \fBvalgrind\fP. This is typically used for debugging and benchmarking |
| 76 | \fBvalgrind\fP. |
| 77 | .RE |
| 78 | |
| 79 | .SH COMMON CORE OPTIONS |
| 80 | |
| 81 | .TP |
| 82 | .B |
| 83 | --db-attach=<yes|no> [default: no] |
| 84 | When enabled, \fBvalgrind\fP will pause after every error shown and |
| 85 | print the line: |
| 86 | |
| 87 | .PP |
| 88 | .nf |
| 89 | .fam C |
| 90 | ---- Attach to debugger ? --- [Return/N/n/Y/y/C/c] ---- |
| 91 | |
| 92 | .fam T |
| 93 | .fi |
| 94 | |
| 95 | .RS |
| 96 | Pressing Ret, or N Ret or n Ret, causes \fBvalgrind\fP not to start a |
| 97 | debugger for this error. |
| 98 | |
| 99 | .PP |
| 100 | Pressing Y Ret or y Ret causes \fBvalgrind\fP to start the debugger |
| 101 | (specified by the \fB--db-command\fP option) for the program at this |
| 102 | point. When you have finished with the debugger, quit from it, and |
| 103 | the program will continue. Trying to continue from inside the debugger |
| 104 | doesn't work. |
| 105 | |
| 106 | .PP |
| 107 | Pressing C Ret or c Ret causes \fBvalgrind\fP not to start the debugger |
| 108 | and \fBvalgrind\fP will not ask again. |
| 109 | |
| 110 | .PP |
| 111 | --db-attach=yes conflicts with --trace-children=yes. You can't use them |
| 112 | together. \fBvalgrind\fP refuses to start up in this situation. 1 May |
| 113 | 2002: this is a historical relic which could be easily fixed if it gets |
| 114 | in your way. Mail me and complain if this is a problem for you. |
| 115 | |
| 116 | .PP |
| 117 | Nov 2002: if you're sending output to a logfile or to a network socket, |
| 118 | I guess this option doesn't make any sense. Caveat emptor. |
| 119 | .RE |
| 120 | |
| 121 | .TP |
| 122 | .B |
| 123 | --db-command=<command> [default: gdb -nw %f %p] |
| 124 | Specify the debugger to use with the --db-attach command. The |
| 125 | default debugger is gdb. This option is a template that is expanded by |
| 126 | \fBvalgrind\fP at runtime. \fB%f\fP is replaced with the executable's |
| 127 | file name and \fB%p\fP is replaced by the process ID of the executable. |
| 128 | .TP |
| 129 | .B |
| 130 | |
| 131 | --error-limit=<yes|no> [default: yes] |
| 132 | When enabled, \fBvalgrind\fP stops reporting errors after 30000 in total, |
| 133 | or 300 different ones, have been seen. This is to stop the error tracking |
| 134 | machinery from becoming a huge performance overhead in programs with |
| 135 | many errors. |
| 136 | .TP |
| 137 | .B |
| 138 | |
| 139 | --gen-suppressions=<yes|no> [default: no] |
| 140 | When enabled, \fBvalgrind\fP will pause after every error shown and |
| 141 | print the line: |
| 142 | |
| 143 | .PP |
| 144 | .nf |
| 145 | .fam C |
| 146 | ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ---- |
| 147 | |
| 148 | .fam T |
| 149 | .fi |
| 150 | |
| 151 | .RS |
| 152 | Pressing Y Ret or y Ret will cause a suppression for this error to be |
| 153 | printed. This suppression can be cut-and-paste into a custom suppressions |
| 154 | file and used to suppress this error in subsequent runs. |
| 155 | |
| 156 | .P |
| 157 | Pressing Ret or n Ret or N Ret will cause no suppression to be printed. |
| 158 | |
| 159 | .P |
| 160 | Pressing C Ret or c Ret will cause no suppression to be printed and |
| 161 | \fBvalgrind\fP will not ask again. |
| 162 | .RE |
| 163 | |
| 164 | .TP |
| 165 | .B |
| 166 | -h --help |
| 167 | Show help for all options, both for the core and for the selected tool. |
| 168 | |
| 169 | .TP |
| 170 | .B |
| 171 | --help-debug |
| 172 | Show help for all options, both for the core and for the selected tool, |
| 173 | including options for debugging \fBvalgrind\fP. |
| 174 | |
| 175 | .TP |
| 176 | .B |
| 177 | --log-file=<filename> |
| 178 | Specifies that \fBvalgrind\fP should send all of its messages to the |
| 179 | specified file. In fact, the file name used is created by concatenating |
| 180 | the text filename, ".pid" and the process ID, so as to create a file |
| 181 | per process. The specified file name may not be the empty string. |
| 182 | |
| 183 | .TP |
| 184 | .B |
| 185 | --num-callers=<number> [default=12] |
| 186 | By default, \fBvalgrind\fP shows 12 levels of function call names to |
| 187 | help you identify program locations. You can change that number with |
| 188 | this option. This can help in determining the program's location in |
| 189 | deeply-nested call chains. Note that errors are commoned up using only |
| 190 | the top three function locations (the place in the current function, |
| 191 | and that of its two immediate callers). So this doesn't affect the total |
| 192 | number of errors reported. |
| 193 | |
| 194 | .RS |
| 195 | .PP |
| 196 | The maximum value for this is 50. Note that higher settings will make |
| 197 | \fBvalgrind\fP run a bit more slowly and take a bit more memory, but |
| 198 | can be useful when working with programs with deeply-nested call chains. |
| 199 | .RE |
| 200 | |
| 201 | .TP |
| 202 | .B |
| 203 | -q --quiet |
| 204 | Run silently, and only print error messages. Useful if you are running |
| 205 | regression tests or have some other automated test machinery. |
| 206 | |
| 207 | .TP |
| 208 | .B |
| 209 | --suppressions=<filename> [default: $PREFIX/lib/\fBvalgrind\fP/default.supp] |
| 210 | Specifies an extra file from which to read descriptions of errors to |
| 211 | suppress. You may specify up to 10 additional suppression files. |
| 212 | |
| 213 | .TP |
| 214 | .B |
| 215 | --tool=<toolname> [default: memcheck] |
| 216 | Specify which tool to use. The default tool is memcheck. |
| 217 | |
| 218 | .TP |
| 219 | .B |
| 220 | --trace-children=<yes|no> [default: no] |
| 221 | When enabled, \fBvalgrind\fP will trace into child processes. This is |
| 222 | confusing and usually not what you want, so is disabled by default. |
| 223 | |
| 224 | .TP |
| 225 | .B |
| 226 | --track-fds=<yes|no> [default: no] |
| 227 | Track file descriptor creation and deletion and produce a summary at the |
| 228 | end of the program execution of file descriptors that are still in use. |
| 229 | |
| 230 | .TP |
| 231 | .B |
| 232 | -v --verbose |
| 233 | Be more verbose. Gives extra information on various aspects of your |
| 234 | program, such as: the shared objects loaded, the suppressions used, |
| 235 | the progress of the instrumentation and execution engines, and warnings |
| 236 | about unusual behaviour. Repeating the flag increases the verbosity level. |
| 237 | |
| 238 | .TP |
| 239 | .B |
| 240 | --version |
| 241 | Show the version number of the \fBvalgrind\fP core. Tools can have |
| 242 | their own version numbers. There is a scheme in place to ensure that |
| 243 | tools only execute when the core version is one they are known to work |
| 244 | with. This was done to minimise the chances of strange problems arising |
| 245 | from tool-vs-core version incompatibilities. |
| 246 | |
| 247 | .SH ADDRCHECK OPTIONS |
| 248 | |
| 249 | .TP |
| 250 | .B |
| 251 | --freelist-vol=<number> [default: 1000000] |
| 252 | When the client program releases memory using free (in C) or delete |
| 253 | (C++), that memory is not immediately made available for re-allocation. |
| 254 | Instead it is marked inaccessible and placed in a queue of freed blocks. |
| 255 | The purpose is to delay the point at which freed-up memory comes back |
| 256 | into circulation. This increases the chance that \fBaddrcheck\fP will |
| 257 | be able to detect invalid accesses to blocks for some significant period |
| 258 | of time after they have been freed. |
| 259 | |
| 260 | .RS |
| 261 | This flag specifies the maximum total size, in bytes, of the blocks in |
| 262 | the queue. The default value is one million bytes. Increasing this |
| 263 | increases the total amount of memory used by \fBaddrcheck\fP but may |
| 264 | detect invalid uses of freed blocks which would otherwise go undetected. |
| 265 | .RE |
| 266 | |
| 267 | .TP |
| 268 | .B |
| 269 | --leak-check=<yes|no|summary|full> [default: summary] |
| 270 | Enables full, summary or no leak checking. When full (\fBfull\fP or |
| 271 | \fByes\fP options) checking is performed, details on all leaked blocks |
| 272 | are printed after the program finishes executing. When summary checking |
| 273 | is enabled, a summary of all leaked memory is printed. When no leak |
| 274 | checking is performed, no leaked memory details are produced. Disabling |
| 275 | leak checking can speed up your program execution. |
| 276 | |
| 277 | .TP |
| 278 | .B |
| 279 | --leak-resolution=<low|med|high> [default: low] |
| 280 | When doing leak checking, determines how willing \fBaddrcheck\fP is to |
| 281 | consider different backtraces to be the same. When set to \fBlow\fP, |
| 282 | the default, only the first two entries need match. When \fBmed\fP, |
| 283 | four entries have to match. When \fBhigh\fP, all entries need to match. |
| 284 | |
| 285 | .TP |
| 286 | .B |
| 287 | --partial-loads-ok=<yes|no> [default: yes] |
| 288 | Controls how \fBaddrcheck\fP handles word (4-byte) loads from addresses |
| 289 | for which some bytes are addressible and others are not. When enabled, |
| 290 | such loads do not elicit an address error. Instead, \fBaddrcheck\fP |
| 291 | considers the bytes corresponding to the illegal addresses as undefined, |
| 292 | and those corresponding to legal addresses are considered defined. |
| 293 | |
| 294 | .RS |
| 295 | When disabled, loads from partially invalid addresses are treated the |
| 296 | same as loads from completely invalid addresses: an illegal-address error |
| 297 | is issued, and the \fBaddrcheck\fP considers all bytes as invalid data. |
| 298 | .RE |
| 299 | |
| 300 | .TP |
| 301 | .B |
| 302 | --show-reachable=<yes|no> [default: no] |
| 303 | When performing full leak checking, print out details of blocks that are |
| 304 | leaked but still reachable. For details of what a reachable block is, |
| 305 | see the HTML documentation. |
| 306 | |
| 307 | .TP |
| 308 | .B |
| 309 | --workaround-gcc296-bugs=<yes|no> [default: no] |
| 310 | When enabled, assume that reads and writes some small distance below |
| 311 | the stack pointer \fB%esp\fP are due to bugs in gcc 2.96, and does not |
| 312 | report them. The "small distance" is 256 bytes by default. Note that gcc |
| 313 | 2.96 is the default compiler on some older Linux distributions (RedHat |
| 314 | 7.X, Mandrake) and so you may well need to use this flag. Do not use |
| 315 | it if you do not have to, as it can cause real errors to be overlooked. |
| 316 | Another option is to use a gcc/g++ which does not generate accesses below |
| 317 | the stack pointer. 2.95.3 seems to be a good choice in this respect. |
| 318 | |
| 319 | .SH MEMCHECK OPTIONS |
| 320 | \fBmemcheck\fP understands the same options as \fBaddrcheck\fP, along |
| 321 | with the following options: |
| 322 | |
| 323 | .TP |
| 324 | .B |
| 325 | --avoid-strlen-errors=<yes|no> [default: yes] |
| 326 | Enable or disable a heuristic for dealing with highly-optimized versions |
| 327 | of \fBstrlen\fP. These versions of \fBstrlen\fP can cause spurious |
| 328 | errors to be reported by \fBmemcheck\fP, so it's usually a good idea to |
| 329 | leave this enabled. |
| 330 | |
| 331 | .TP |
| 332 | .B |
| 333 | --cleanup=<yes|no> [default: yes] |
| 334 | \fBThis is a flag to help debug valgrind itself. It is of no use to |
| 335 | end-users\fP. When enabled, various improvments are applied to the |
| 336 | post-instrumented intermediate code, aimed at removing redundant value |
| 337 | checks. |
| 338 | |
| 339 | .SH CACHEGRIND OPTIONS |
| 340 | |
| 341 | .TP |
| 342 | .B |
| 343 | --D1=<size>,<associativity>,<line size> |
| 344 | Specify the size, associativity and line size of the level 1 data cache. |
| 345 | All values are measured in bytes. If this options is not specified, |
| 346 | the system value (as retrieved by the \fBCPUID\fP instruction) is used. |
| 347 | |
| 348 | .TP |
| 349 | .B |
| 350 | --I1=<size>,<associativity>,<line size> |
| 351 | Specify the size, associativity and line size of the level 1 instruction |
| 352 | cache. All values are measured in bytes. If this options is not |
| 353 | specified, the system value (as retrieved by the \fBCPUID\fP instruction) |
| 354 | is used. |
| 355 | |
| 356 | .TP |
| 357 | .B |
| 358 | --L2=<size>,<associativity>,<line size> |
| 359 | Specify the size, associativity and line size of the level 2 cache. |
| 360 | All values are measured in bytes. If this options is not specified, |
| 361 | the system value (as retrieved by the \fBCPUID\fP instruction) is used. |
| 362 | |
| 363 | .SH MASSIF OPTIONS |
| 364 | |
| 365 | .TP |
| 366 | .B |
| 367 | --alloc-fn=<name> |
| 368 | Specify a function that allocates memory. This is useful for functions |
| 369 | that are wrappers to \fBmalloc()\fP, which can fill up the context |
| 370 | information uselessly (and give very uninformative bands on the graph). |
| 371 | Functions specified will be ignored in contexts, i.e. treated as though |
| 372 | they were \fBmalloc()\fP. This option can be specified multiple times |
| 373 | on the command line, to name multiple functions. |
| 374 | |
| 375 | .TP |
| 376 | .B |
| 377 | --depth=<number> [default: 3] |
| 378 | Depth of call chains to present in the detailed heap information. |
| 379 | Increasing it will give more information, but \fBmassif\fP will run the |
| 380 | program more slowly, using more memory, and produce a bigger \fB.txt\fP |
| 381 | or \fB.hp\fP file. |
| 382 | |
| 383 | .TP |
| 384 | .B |
| 385 | --format=<text|html> [default: text] |
| 386 | Produce the detailed heap information in text or HTML format. The file |
| 387 | suffix used will be either \fB.txt\fP or \fB.html\fP. |
| 388 | |
| 389 | .TP |
| 390 | .B |
| 391 | --heap=<yes|no> [default: yes] |
| 392 | When enabled, profile heap usage in detail. Without it, the \fB.txt\fP |
| 393 | or \fB.html\fP file will be very short. |
| 394 | |
| 395 | .TP |
| 396 | .B |
| 397 | --heap-admin=<number> [default: 8] |
| 398 | The number of admin bytes per block to use. This can only be an |
| 399 | estimate of the average, since it may vary. The allocator used |
| 400 | by \fBglibc\fP requires somewhere between 4 to 15 bytes per block, |
| 401 | depending on various factors. It also requires admin space for freed |
| 402 | blocks, although \fBmassif\fP does not count this. |
| 403 | |
| 404 | .TP |
| 405 | .B |
| 406 | --stacks=<yes|no> [default: yes] |
| 407 | When enabled, include stack(s) in the profile. Threaded programs can |
| 408 | have multiple stacks. |
| 409 | |
| 410 | ." .SH HELGRIND OPTIONS |
| 411 | |
| 412 | ." .TP |
| 413 | ." .B |
| 414 | ." --private-stacks=<yes|no> [default: no] |
| 415 | ." Assume thread stacks are used privately. |
| 416 | |
| 417 | ." .TP |
| 418 | ." .B |
| 419 | ." --show-last-access=<yes|some|no> [default: no] |
| 420 | ." Show location of last word access on error. |
| 421 | |
| 422 | .SH LESS FREQUENTLY USED CORE OPTIONS |
| 423 | |
| 424 | .TP |
| 425 | .B |
| 426 | --alignment=<number> [default: 8] |
| 427 | By default \fBvalgrind\fP's malloc, realloc, etc, return 8-byte aligned |
| 428 | addresses. These are suitable for any accesses on x86 processors. Some |
| 429 | programs might however assume that malloc et al return 16- or more |
| 430 | aligned memory. These programs are broken and should be fixed, but if |
| 431 | this is impossible for whatever reason the alignment can be increased |
| 432 | using this parameter. The supplied value must be between 8 and 4096 |
| 433 | inclusive, and must be a power of two. |
| 434 | |
| 435 | .TP |
| 436 | .B |
| 437 | --branchpred=<yes|no> [default: no] |
| 438 | This option enables the generation of static branch prediction hints. |
| 439 | In theory this allows the real CPU to do a better job of running the |
| 440 | generated code, but in practice it makes almost no measurable difference. |
| 441 | It may have a large effect on some x86 implementations. |
| 442 | |
| 443 | .TP |
| 444 | .B |
| 445 | --chain-bb=<yes|no> [default: yes] |
| 446 | Enables basic-block chaining. If basic-block chaining is disabled, |
| 447 | the synthetic CPU returns to the scheduler after interpreting each basic |
| 448 | block. With basic block chaining enabled, it can immediately proceed to |
| 449 | the next basic block. This almost always results in a performance gain, |
| 450 | so it is enabled by default. |
| 451 | |
| 452 | .TP |
| 453 | .B |
| 454 | --command-line-only=<yes|no> [default: no] |
| 455 | Normally, \fBvalgrind\fP will look for command-line options in the |
| 456 | following locations: |
| 457 | .RS |
| 458 | .TP |
| 459 | - The \fBvalgrind\fP command line |
| 460 | .TP |
| 461 | - The \fB\.valgrindrc\fP file in the invocation directory |
| 462 | .TP |
| 463 | - The \fB\.valgrindrc\fP file in users home directory |
| 464 | .TP |
| 465 | - The \fB$VALGRIND_OPTS\fP environment variable |
| 466 | .P |
| 467 | |
| 468 | When this option is enabled, \fBvalgrind\fP will only look at the command |
| 469 | line for options. |
| 470 | .RE |
| 471 | |
| 472 | .TP |
| 473 | .B |
| 474 | --demangle=<yes|no> [default: yes] |
| 475 | Enable or disable automatic demangling (decoding) of C++ names. Enabled by |
| 476 | default. When enabled, \fBvalgrind\fP will attempt to translate encoded |
| 477 | C++ procedure names back to something approaching the original. The |
| 478 | demangler handles symbols mangled by g++ versions 2.X and 3.X. |
| 479 | |
| 480 | .TP |
| 481 | .B |
| 482 | --dump-error=<number> |
| 483 | After the program has exited, show gory details of the translation of |
| 484 | the basic block containing the \fB<number>\fP'th error context. When |
| 485 | used with --single-step=yes, can show the exact x86 instruction causing |
| 486 | an error. This is all fairly dodgy and doesn't work at all if threads |
| 487 | are involved. |
| 488 | |
| 489 | .TP |
| 490 | .B |
| 491 | --exec=<filename> |
| 492 | Specify the executable to run. If this is specified, it takes precedence |
| 493 | over the \fByour-program\fP executable from the command-line. If this is |
| 494 | not specified, \fBvalgrind\fP searches the path for the \fByour-program\fP |
| 495 | executable, just like a regular shell would. |
| 496 | |
| 497 | .TP |
| 498 | .B |
| 499 | --input-fd=<number> [default: 0, stdin] |
| 500 | Specify the file descriptor to use for reading input from the user. This |
| 501 | is used whenever \fBvalgrind\fP needs to prompt the user for a decision. |
| 502 | |
| 503 | .TP |
| 504 | .B |
| 505 | --log-fd=<number> [default: 2, stderr] |
| 506 | Specifies that \fBvalgrind\fP should send all of its messages to |
| 507 | the specified file descriptor. The default, 2, is the standard error |
| 508 | channel (stderr). Note that this may interfere with the client's own |
| 509 | use of stderr. |
| 510 | |
| 511 | .TP |
| 512 | .B |
| 513 | --log-socket=<ip-address:port-number> |
| 514 | Specifies that \fBvalgrind\fP should send all of its messages to the |
| 515 | specified port at the specified IP address. The port may be omitted, |
| 516 | in which case port 1500 is used. If a connection cannot be made to |
| 517 | the specified socket, \fBvalgrind\fP falls back to writing output to |
| 518 | the standard error (stderr). This option is intended to be used in |
| 519 | conjunction with the \fBvalgrind-listener\fP program. For further details, |
| 520 | see section 2.3 of the user manual. |
| 521 | |
| 522 | .TP |
| 523 | .B |
| 524 | --optimise=<yes|no> [default: yes] |
| 525 | When enabled, various improvements are applied to the intermediate code, |
| 526 | mainly aimed at allowing the simulated CPU's registers to be cached in |
| 527 | the real CPU's registers over several simulated instructions. |
| 528 | |
| 529 | .TP |
| 530 | .B |
| 531 | --pointercheck=<yes|no> [default: yes] |
| 532 | When enabled, enforces client address space limits. If this option is |
| 533 | disabled, the client program has full and unfettered access to the part |
| 534 | of the address space used internally by \fBvalgrind\fP. This can cause |
| 535 | unexplained crashes and false error reports, so it is best left enabled. |
| 536 | |
| 537 | .TP |
| 538 | .B |
| 539 | --run-libc-freeres=<yes|no> [default: yes] |
| 540 | The GNU C library (libc.so), which is used by all programs, may allocate |
| 541 | memory for its own uses. Usually it doesn't bother to free that memory when |
| 542 | the program ends - there would be no point, since the Linux kernel reclaims |
| 543 | all process resources when a process exits anyway, so it would just slow |
| 544 | things down. |
| 545 | |
| 546 | .RS |
| 547 | .PP |
| 548 | The glibc authors realised that this behaviour causes leak checkers, |
| 549 | such as \fBvalgrind\fP, to falsely report leaks in glibc, when a leak |
| 550 | check is done at exit. In order to avoid this, they provided a routine |
| 551 | called __libc_freeres specifically to make glibc release all memory it |
| 552 | has allocated. The MemCheck and AddrCheck tools therefore try and run |
| 553 | __libc_freeres at exit. |
| 554 | |
| 555 | .PP |
| 556 | Unfortunately, in some versions of glibc, __libc_freeres is sufficiently |
| 557 | buggy to cause segmentation faults. This is particularly noticeable on |
| 558 | Red Hat 7.1. So this flag is provided in order to inhibit the run of |
| 559 | __libc_freeres. If your program seems to run fine on \fBvalgrind\fP, but |
| 560 | segfaults at exit, you may find that --run-libc-freeres=no fixes that, |
| 561 | although at the cost of possibly falsely reporting space leaks in libc.so. |
| 562 | .RE |
| 563 | |
| 564 | .TP |
| 565 | .B |
| 566 | --show-below-main=<yes|no> [default: no] |
| 567 | When enabled, this option causes full stack backtraces to be emited, |
| 568 | including the part before \fBmain\fP in your program (subject to the |
| 569 | \fB--num-callers\fP option.) When disabled, only the part of the stack |
| 570 | backtrace up to and including main is printed. |
| 571 | |
| 572 | .TP |
| 573 | .B |
| 574 | --single-step=<yes|no> [default: no] |
| 575 | When enabled, each x86 insn is translated separately into instrumented |
| 576 | code. When disabled, translation is done on a per-basic-block basis, |
| 577 | giving much better translations. This is needed when running |
| 578 | \fBvalgrind\fP under \fBvalgrind\fP. |
| 579 | |
| 580 | .TP |
| 581 | .B |
njn | 74e7012 | 2005-03-12 21:02:52 +0000 | [diff] [blame] | 582 | --time-stamp=<yes|no> [default: no] |
| 583 | When enabled, a time-stamp is added to all log messages. |
| 584 | |
| 585 | .TP |
| 586 | .B |
| 587 | --weird-hacks=hack1,hack2,\.\.\. |
| 588 | Pass miscellaneous hints to \fBvalgrind\fP which slightly modify the |
| 589 | simulated behaviour in nonstandard or dangerous ways, possibly to help |
| 590 | the simulation of strange features. By default no hacks are enabled. Use |
| 591 | with caution! Currently known hacks are: |
| 592 | |
| 593 | .RS |
| 594 | .TP |
| 595 | .B |
| 596 | - lax-ioctls |
| 597 | If \fBvalgrind\fP encounters an \fBioctl\fP that it doesn't understand, |
| 598 | it normally prints a warning message before continuing. Specifying the |
| 599 | lax-ioctls hack tells \fBvalgrind\fP to be very lax about ioctl handling |
| 600 | and assume that unknown ioctls just behave correctly. |
| 601 | .TP |
| 602 | .B |
| 603 | - ioctl-mmap |
| 604 | Tell \fBvalgrind\fP to search for new memory mappings after an unknown |
| 605 | \fBioctl\fP call. |
| 606 | .RE |
| 607 | |
| 608 | .SH CORE DEBUGGING OPTIONS |
| 609 | |
| 610 | .TP |
| 611 | .B |
| 612 | --profile=<yes|no> [default: no] |
| 613 | When enabled, does crude internal profiling of \fBvalgrind\fP itself. This |
| 614 | is not for profiling your programs. Rather it is to allow the developers |
| 615 | to assess where \fBvalgrind\fP is spending its time. The tools must be |
| 616 | built for profiling for this to work. |
| 617 | |
| 618 | .TP |
| 619 | .B |
| 620 | --sanity-level=<number> [default: 1] |
| 621 | Set the level of sanity checking to perform. This is used for debugging |
| 622 | \fBvalgrind\fP. Setting this to 2 or higher can cause more internal |
| 623 | sanity checks to be performed, but can slow your program down |
| 624 | appreciably. Setting this to 0 disables sanity checks. |
| 625 | |
| 626 | .TP |
| 627 | .B |
| 628 | --trace-codegen=<bitmask> |
| 629 | Produce lots of output showing exactly how \fBvalgrind\fP is translating |
| 630 | each basic block. The argument to this option is a 5-bit wide bitmask. |
| 631 | Each bit refers to a specific feature to trace. If the bit is 1, the |
| 632 | feature is traced. If it is 0, the feature is not traced. |
| 633 | |
| 634 | .RS |
| 635 | The traced features are: |
| 636 | .TP |
| 637 | Bit 1: basic-block disassembly |
| 638 | .TP |
| 639 | Bit 2: optimization phase |
| 640 | .TP |
| 641 | Bit 3: tool instrumentation |
| 642 | .TP |
| 643 | Bit 4: register allocation |
| 644 | .TP |
| 645 | Bit 5: final code generation |
| 646 | .RE |
| 647 | |
| 648 | .TP |
| 649 | .B |
| 650 | --trace-malloc=<yes|no> [default: no] |
| 651 | Enable or disable tracing of malloc, free and other memory-manager calls. |
| 652 | |
| 653 | .TP |
| 654 | .B |
| 655 | --trace-redir=<yes|no> [default: no] |
| 656 | Enable or disable tracing of function redirection. |
| 657 | |
| 658 | .TP |
| 659 | .B |
| 660 | --trace-sched=<yes|no> [default: no] |
| 661 | Enable or disable tracing of thread scheduling events. |
| 662 | |
| 663 | .TP |
| 664 | .B |
| 665 | --trace-signals=<yes|no> [default: no] |
| 666 | Enable or disable tracing of signal handling. |
| 667 | |
| 668 | .TP |
| 669 | .B |
| 670 | --trace-syscalls=<yes|no> [default: no] |
| 671 | Enable or disable tracing of system call intercepts. |
| 672 | |
| 673 | .TP |
| 674 | .B |
| 675 | --trace-symtab=<yes|no> [default: no] |
| 676 | Enable or disable tracing of symbol table reading. |
| 677 | |
| 678 | .SH SEE ALSO |
| 679 | /usr/share/doc/\fBvalgrind\fP/html/manual.html |
| 680 | |
| 681 | .SH AUTHOR |
| 682 | This manpage has been written by Andres Roldan <aroldan@debian.org> |
| 683 | for the Debian Project, but can be used for any other distribution. |
| 684 | Updated, rearranged and expanded by Robert Walsh <rjwalsh@durables.org> |
| 685 | for the 2.4.0 release. |