File: valgrind.1

package info (click to toggle)
valgrind 1%3A2.4.0-2
  • links: PTS
  • area: main
  • in suites: sarge
  • size: 9,384 kB
  • ctags: 8,831
  • sloc: ansic: 67,990; sh: 4,364; perl: 1,833; makefile: 1,125; asm: 978; cpp: 101
file content (358 lines) | stat: -rw-r--r-- 14,579 bytes parent folder | download
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.