47
47
<dt><span class="sect1"><a href="mc-manual.html#mc-manual.clientreqs">3.6. Client Requests</a></span></dt>
50
<p>To use this tool, you may specify
51
<code class="computeroutput">--tool=memcheck</code> on the Valgrind
52
command line. You don't have to, though, since Memcheck is the default
50
<p>To use this tool, you may specify <code class="option">--tool=memcheck</code>
51
on the Valgrind command line. You don't have to, though, since Memcheck
52
is the default tool.</p>
54
53
<div class="sect1" lang="en">
55
54
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
56
55
<a name="mc-manual.bugs"></a>3.1.�Kinds of bugs that Memcheck can find</h2></div></div></div>
57
<p>Memcheck is Valgrind's heavyweight memory checking
58
tool. All reads and writes of memory are checked, and
59
calls to malloc/new/free/delete are intercepted. As a result,
60
Memcheck can detect the following problems:</p>
56
<p>Memcheck is Valgrind's heavyweight memory checking tool. All
57
reads and writes of memory are checked, and calls to
58
malloc/new/free/delete are intercepted. As a result, Memcheck can detect
59
the following problems:</p>
61
60
<div class="itemizedlist"><ul type="disc">
62
61
<li><p>Use of uninitialised memory</p></li>
63
62
<li><p>Reading/writing memory after it has been free'd</p></li>
64
63
<li><p>Reading/writing off the end of malloc'd blocks</p></li>
65
64
<li><p>Reading/writing inappropriate areas on the stack</p></li>
66
<li><p>Memory leaks -- where pointers to malloc'd blocks are
65
<li><p>Memory leaks - where pointers to malloc'd blocks are
67
66
lost forever</p></li>
68
67
<li><p>Mismatched use of malloc/new/new [] vs
69
68
free/delete/delete []</p></li>
70
69
<li><p>Overlapping <code class="computeroutput">src</code> and
71
70
<code class="computeroutput">dst</code> pointers in
72
<code class="computeroutput">memcpy()</code> and related
71
<code class="function">memcpy()</code> and related
76
75
<div class="sect1" lang="en">
77
76
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
78
77
<a name="mc-manual.flags"></a>3.2.�Command-line flags specific to Memcheck</h2></div></div></div>
79
<div class="itemizedlist">
80
<a name="leakcheck"></a><ul type="disc">
82
<p><code class="computeroutput">--leak-check=no</code></p>
83
<p><code class="computeroutput">--leak-check=summary</code> [default]</p>
84
<p><code class="computeroutput">--leak-check=full</code></p>
85
<p>When enabled, search for memory leaks when the client
86
program finishes. A memory leak means a malloc'd block,
87
which has not yet been free'd, but to which no pointer can be
88
found. Such a block can never be free'd by the program,
89
since no pointer to it exists. If set to
90
<code class="computeroutput">summary</code>, it says how many leaks occurred.
91
If set to <code class="computeroutput">all</code>, it gives details of each
95
<p><a name="showreach"></a><code class="computeroutput">--show-reachable=no</code>
97
<p><code class="computeroutput">--show-reachable=yes</code></p>
98
<p>When disabled, the memory leak detector only shows
99
blocks for which it cannot find a pointer to at all, or it
100
can only find a pointer to the middle of. These blocks are
101
prime candidates for memory leaks. When enabled, the leak
102
detector also reports on blocks which it could find a pointer
103
to. Your program could, at least in principle, have freed
104
such blocks before exit. Contrast this to blocks for which
105
no pointer, or only an interior pointer could be found: they
106
are more likely to indicate memory leaks, because you do not
107
actually have a pointer to the start of the block which you
108
can hand to <code class="computeroutput">free</code>, even if
112
<p><a name="leakres"></a><code class="computeroutput">--leak-resolution=low</code>
114
<p><code class="computeroutput">--leak-resolution=med</code></p>
115
<p><code class="computeroutput">--leak-resolution=high</code></p>
78
<div class="variablelist">
79
<a name="mc.opts.list"></a><dl>
81
<a name="opt.leak-check"></a><span class="term">
82
<code class="option">--leak-check=<no|summary|yes|full> [default: summary] </code>
85
<dd><p>When enabled, search for memory leaks when the client
86
program finishes. A memory leak means a malloc'd block, which has
87
not yet been free'd, but to which no pointer can be found. Such a
88
block can never be free'd by the program, since no pointer to it
89
exists. If set to <code class="varname">summary</code>, it says how many
90
leaks occurred. If set to <code class="varname">full</code> or
91
<code class="varname">yes</code>, it gives details of each individual
94
<a name="opt.show-reachable"></a><span class="term">
95
<code class="option">--show-reachable=<yes|no> [default: no] </code>
98
<dd><p>When disabled, the memory leak detector only shows blocks
99
for which it cannot find a pointer to at all, or it can only find
100
a pointer to the middle of. These blocks are prime candidates for
101
memory leaks. When enabled, the leak detector also reports on
102
blocks which it could find a pointer to. Your program could, at
103
least in principle, have freed such blocks before exit. Contrast
104
this to blocks for which no pointer, or only an interior pointer
105
could be found: they are more likely to indicate memory leaks,
106
because you do not actually have a pointer to the start of the
107
block which you can hand to <code class="function">free</code>, even if you
110
<a name="opt.leak-resolution"></a><span class="term">
111
<code class="option">--leak-resolution=<low|med|high> [default: low] </code>
116
115
<p>When doing leak checking, determines how willing
117
Memcheck is to consider different backtraces to be the same.
118
When set to <code class="computeroutput">low</code>, the
119
default, only the first two entries need match. When
120
<code class="computeroutput">med</code>, four entries have to
121
match. When <code class="computeroutput">high</code>, all
122
entries need to match.</p>
116
<code class="constant">memcheck</code> is to consider different backtraces to
117
be the same. When set to <code class="varname">low</code>, only the first
118
two entries need match. When <code class="varname">med</code>, four entries
119
have to match. When <code class="varname">high</code>, all entries need to
123
121
<p>For hardcore leak debugging, you probably want to use
124
<code class="computeroutput">--leak-resolution=high</code>
126
<code class="computeroutput">--num-callers=40</code> or some
127
such large number. Note however that this can give an
128
overwhelming amount of information, which is why the defaults
129
are 4 callers and low-resolution matching.</p>
131
<code class="computeroutput">--leak-resolution=</code> setting
132
does not affect Memcheck's ability to find leaks. It only
133
changes how the results are presented.</p>
136
<p><a name="freelist"></a><code class="computeroutput">--freelist-vol=<number></code>
137
[default: 5000000]</p>
138
<p>When the client program releases memory using free (in
139
<code class="literal">C</code>) or delete (<code class="literal">C++</code>),
140
that memory is not immediately made available for
141
re-allocation. Instead it is marked inaccessible and placed
142
in a queue of freed blocks. The purpose is to defer
143
as long as possible the point at which freed-up memory comes back
144
into circulation. This increases the chance that Memcheck will be
145
able to detect invalid accesses to blocks for some significant period
146
of time after they have been freed.</p>
147
<p>This flag specifies the maximum total size, in bytes,
148
of the blocks in the queue. The default value is five million
149
bytes. Increasing this increases the total amount of memory
150
used by Memcheck but may detect invalid uses of freed blocks
151
which would otherwise go undetected.</p>
154
<p><a name="gcc296"></a><code class="computeroutput">--workaround-gcc296-bugs=no</code>
156
<p><code class="computeroutput">--workaround-gcc296-bugs=yes</code></p>
157
<p>When enabled, assume that reads and writes some small
158
distance below the stack pointer are due to bugs in gcc
159
2.96, and does not report them. The "small distance" is 256
160
bytes by default. Note that gcc 2.96 is the default compiler
161
on some older Linux distributions (RedHat 7.X) and so you may need to use
162
this flag. Do not use it if you do not have to, as it can cause real errors
163
to be overlooked. A better alternative is to use a more recent gcc/g++ in
164
which this bug is fixed.</p>
167
<p><a name="partial"></a><code class="computeroutput">--partial-loads-ok=yes</code>
169
<p><code class="computeroutput">--partial-loads-ok=no</code>[default]
171
<p>Controls how Memcheck handles word-sized, word-aligned loads from
172
addresses for which some bytes are addressible and others are
173
not. When <code class="computeroutput">yes</code>,
174
such loads do not elicit an address error.
175
Instead, the loaded V bytes corresponding to the illegal
176
addresses indicate Undefined, and those corresponding to
177
legal addresses are loaded from shadow memory, as usual.</p>
178
<p>When <code class="computeroutput">no</code>(the default),
179
loads from partially invalid addresses are treated the same as
180
loads from completely invalid addresses: an illegal-address error
181
is issued, and the resulting V bytes indicate valid data.</p>
122
<code class="option">--leak-resolution=high</code> together with
123
<code class="option">--num-callers=40</code> or some such large number. Note
124
however that this can give an overwhelming amount of information,
125
which is why the defaults are 4 callers and low-resolution
127
<p>Note that the <code class="option">--leak-resolution=</code> setting
128
does not affect <code class="constant">memcheck's</code> ability to find
129
leaks. It only changes how the results are presented.</p>
132
<a name="opt.freelist-vol"></a><span class="term">
133
<code class="option">--freelist-vol=<number> [default: 5000000] </code>
137
<p>When the client program releases memory using
138
<code class="function">free</code> (in <code class="literal">C</code>) or delete
139
(<code class="literal">C++</code>), that memory is not immediately made
140
available for re-allocation. Instead, it is marked inaccessible
141
and placed in a queue of freed blocks. The purpose is to defer as
142
long as possible the point at which freed-up memory comes back
143
into circulation. This increases the chance that
144
<code class="constant">memcheck</code> will be able to detect invalid
145
accesses to blocks for some significant period of time after they
147
<p>This flag specifies the maximum total size, in bytes, of the
148
blocks in the queue. The default value is five million bytes.
149
Increasing this increases the total amount of memory used by
150
<code class="constant">memcheck</code> but may detect invalid uses of freed
151
blocks which would otherwise go undetected.</p>
154
<a name="opt.workaround-gcc296-bugs"></a><span class="term">
155
<code class="option">--workaround-gcc296-bugs=<yes|no> [default: no] </code>
158
<dd><p>When enabled, assume that reads and writes some small
159
distance below the stack pointer are due to bugs in gcc 2.96, and
160
does not report them. The "small distance" is 256 bytes by
161
default. Note that gcc 2.96 is the default compiler on some older
162
Linux distributions (RedHat 7.X) and so you may need to use this
163
flag. Do not use it if you do not have to, as it can cause real
164
errors to be overlooked. A better alternative is to use a more
165
recent gcc/g++ in which this bug is fixed.</p></dd>
167
<a name="opt.partial-loads-ok"></a><span class="term">
168
<code class="option">--partial-loads-ok=<yes|no> [default: no] </code>
172
<p>Controls how <code class="constant">memcheck</code> handles word-sized,
173
word-aligned loads from addresses for which some bytes are
174
addressible and others are not. When <code class="varname">yes</code>, such
175
loads do not elicit an address error. Instead, the loaded V bytes
176
corresponding to the illegal addresses indicate Undefined, and
177
those corresponding to legal addresses are loaded from shadow
178
memory, as usual.</p>
179
<p>When <code class="varname">no</code>, loads from partially invalid
180
addresses are treated the same as loads from completely invalid
181
addresses: an illegal-address error is issued, and the resulting V
182
bytes indicate valid data.</p>
182
183
<p>Note that code that behaves in this way is in violation of
183
the the ISO C/C++ standards, and should be considered broken.
184
If at all possible, such code should be fixed. This flag should
185
be used only as a last resort.
184
the the ISO C/C++ standards, and should be considered broken. If
185
at all possible, such code should be fixed. This flag should be
186
used only as a last resort.</p>
189
<a name="opt.undef-value-errors"></a><span class="term">
190
<code class="option">--undef-value-errors=<yes|no> [default: yes] </code>
193
<dd><p>Controls whether <code class="constant">memcheck</code> detects
194
dangerous uses of undefined value errors. When
195
<code class="varname">yes</code>, Memcheck behaves like Addrcheck, a lightweight
196
memory-checking tool that used to be part of Valgrind, which didn't
197
detect undefined value errors. Use this option if you don't like
198
seeing undefined value errors.
191
203
<div class="sect1" lang="en">
192
204
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
193
205
<a name="mc-manual.errormsgs"></a>3.3.�Explanation of error messages from Memcheck</h2></div></div></div>
194
<p>Despite considerable sophistication under the hood,
195
Memcheck can only really detect two kinds of errors: use of
196
illegal addresses, and use of undefined values. Nevertheless,
197
this is enough to help you discover all sorts of
198
memory-management nasties in your code. This section presents a
199
quick summary of what error messages mean. The precise behaviour
200
of the error-checking machinery is described in <a href="mc-manual.html#mc-manual.machine">Details of Memcheck's checking machinery</a>.</p>
206
<p>Despite considerable sophistication under the hood, Memcheck can
207
only really detect two kinds of errors: use of illegal addresses, and
208
use of undefined values. Nevertheless, this is enough to help you
209
discover all sorts of memory-management nasties in your code. This
210
section presents a quick summary of what error messages mean. The
211
precise behaviour of the error-checking machinery is described in
212
<a href="mc-manual.html#mc-manual.machine">Details of Memcheck's checking machinery</a>.</p>
201
213
<div class="sect2" lang="en">
202
214
<div class="titlepage"><div><div><h3 class="title">
203
215
<a name="mc-manual.badrw"></a>3.3.1.�Illegal read / Illegal write errors</h3></div></div></div>
210
222
by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
211
223
Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd
213
<p>This happens when your program reads or writes memory at a
214
place which Memcheck reckons it shouldn't. In this example, the
215
program did a 4-byte read at address 0xBFFFF0E0, somewhere within
216
the system-supplied library libpng.so.2.1.0.9, which was called
217
from somewhere else in the same library, called from line 326 of
218
<code class="filename">qpngio.cpp</code>, and so on.</p>
219
<p>Memcheck tries to establish what the illegal address might
220
relate to, since that's often useful. So, if it points into a
221
block of memory which has already been freed, you'll be informed
222
of this, and also where the block was free'd at. Likewise, if it
223
should turn out to be just off the end of a malloc'd block, a
224
common result of off-by-one-errors in array subscripting, you'll
225
be informed of this fact, and also where the block was
227
<p>In this example, Memcheck can't identify the address.
228
Actually the address is on the stack, but, for some reason, this
229
is not a valid stack address -- it is below the stack pointer
230
and that isn't allowed. In this
231
particular case it's probably caused by gcc generating invalid
225
<p>This happens when your program reads or writes memory at a place
226
which Memcheck reckons it shouldn't. In this example, the program did a
227
4-byte read at address 0xBFFFF0E0, somewhere within the system-supplied
228
library libpng.so.2.1.0.9, which was called from somewhere else in the
229
same library, called from line 326 of <code class="filename">qpngio.cpp</code>,
231
<p>Memcheck tries to establish what the illegal address might relate
232
to, since that's often useful. So, if it points into a block of memory
233
which has already been freed, you'll be informed of this, and also where
234
the block was free'd at. Likewise, if it should turn out to be just off
235
the end of a malloc'd block, a common result of off-by-one-errors in
236
array subscripting, you'll be informed of this fact, and also where the
237
block was malloc'd.</p>
238
<p>In this example, Memcheck can't identify the address. Actually
239
the address is on the stack, but, for some reason, this is not a valid
240
stack address -- it is below the stack pointer and that isn't allowed.
241
In this particular case it's probably caused by gcc generating invalid
232
242
code, a known bug in some ancient versions of gcc.</p>
233
<p>Note that Memcheck only tells you that your program is
234
about to access memory at an illegal address. It can't stop the
235
access from happening. So, if your program makes an access which
236
normally would result in a segmentation fault, you program will
237
still suffer the same fate -- but you will get a message from
238
Memcheck immediately prior to this. In this particular example,
239
reading junk on the stack is non-fatal, and the program stays
243
<p>Note that Memcheck only tells you that your program is about to
244
access memory at an illegal address. It can't stop the access from
245
happening. So, if your program makes an access which normally would
246
result in a segmentation fault, you program will still suffer the same
247
fate -- but you will get a message from Memcheck immediately prior to
248
this. In this particular example, reading junk on the stack is
249
non-fatal, and the program stays alive.</p>
242
251
<div class="sect2" lang="en">
243
252
<div class="titlepage"><div><div><h3 class="title">
249
258
by 0x402E8476: _IO_printf (printf.c:36)
250
259
by 0x8048472: main (tests/manuel1.c:8)
252
<p>An uninitialised-value use error is reported when your
253
program uses a value which hasn't been initialised -- in other
254
words, is undefined. Here, the undefined value is used somewhere
255
inside the printf() machinery of the C library. This error was
256
reported when running the following small program:</p>
261
<p>An uninitialised-value use error is reported when your program
262
uses a value which hasn't been initialised -- in other words, is
263
undefined. Here, the undefined value is used somewhere inside the
264
printf() machinery of the C library. This error was reported when
265
running the following small program:</p>
257
266
<pre class="programlisting">
261
270
printf ("x = %d\n", x);
263
<p>It is important to understand that your program can copy
264
around junk (uninitialised) data as much as it likes.
265
Memcheck observes this and keeps track of the data, but does not
266
complain. A complaint is issued only when your program attempts
267
to make use of uninitialised data. In this example, x is
268
uninitialised. Memcheck observes the value being passed to
269
<code class="literal">_IO_printf</code> and thence to
272
<p>It is important to understand that your program can copy around
273
junk (uninitialised) data as much as it likes. Memcheck observes this
274
and keeps track of the data, but does not complain. A complaint is
275
issued only when your program attempts to make use of uninitialised
276
data. In this example, x is uninitialised. Memcheck observes the value
277
being passed to <code class="literal">_IO_printf</code> and thence to
270
278
<code class="literal">_IO_vfprintf</code>, but makes no comment. However,
271
_IO_vfprintf has to examine the value of x so it can turn it into
272
the corresponding ASCII string, and it is at this point that
273
Memcheck complains.</p>
279
_IO_vfprintf has to examine the value of x so it can turn it into the
280
corresponding ASCII string, and it is at this point that Memcheck
274
282
<p>Sources of uninitialised data tend to be:</p>
275
283
<div class="itemizedlist"><ul type="disc">
276
<li><p>Local variables in procedures which have not been
277
initialised, as in the example above.</p></li>
278
<li><p>The contents of malloc'd blocks, before you write
279
something there. In C++, the new operator is a wrapper round
280
malloc, so if you create an object with new, its fields will
281
be uninitialised until you (or the constructor) fill them in,
282
which is only Right and Proper.</p></li>
284
<li><p>Local variables in procedures which have not been initialised,
285
as in the example above.</p></li>
286
<li><p>The contents of malloc'd blocks, before you write something
287
there. In C++, the new operator is a wrapper round malloc, so if
288
you create an object with new, its fields will be uninitialised
289
until you (or the constructor) fill them in, which is only Right and
285
293
<div class="sect2" lang="en">
322
329
by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
323
330
by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)
325
<p>In <code class="literal">C++</code> it's important to deallocate
326
memory in a way compatible with how it was allocated. The deal
332
<p>In <code class="literal">C++</code> it's important to deallocate memory in a
333
way compatible with how it was allocated. The deal is:</p>
328
334
<div class="itemizedlist"><ul type="disc">
329
335
<li><p>If allocated with
330
<code class="computeroutput">malloc</code>,
331
<code class="computeroutput">calloc</code>,
332
<code class="computeroutput">realloc</code>,
333
<code class="computeroutput">valloc</code> or
334
<code class="computeroutput">memalign</code>, you must
335
deallocate with <code class="computeroutput">free</code>.</p></li>
336
<li><p>If allocated with
337
<code class="computeroutput">new[]</code>, you must deallocate
338
with <code class="computeroutput">delete[]</code>.</p></li>
339
<li><p>If allocated with <code class="computeroutput">new</code>,
340
you must deallocate with
341
<code class="computeroutput">delete</code>.</p></li>
336
<code class="function">malloc</code>,
337
<code class="function">calloc</code>,
338
<code class="function">realloc</code>,
339
<code class="function">valloc</code> or
340
<code class="function">memalign</code>, you must
341
deallocate with <code class="function">free</code>.</p></li>
342
<li><p>If allocated with <code class="function">new[]</code>, you must
343
deallocate with <code class="function">delete[]</code>.</p></li>
344
<li><p>If allocated with <code class="function">new</code>, you must deallocate
345
with <code class="function">delete</code>.</p></li>
343
<p>The worst thing is that on Linux apparently it doesn't
344
matter if you do muddle these up, and it all seems to work ok,
345
but the same program may then crash on a different platform,
346
Solaris for example. So it's best to fix it properly. According
347
to the KDE folks "it's amazing how many C++ programmers don't
347
<p>The worst thing is that on Linux apparently it doesn't matter if
348
you do muddle these up, and it all seems to work ok, but the same
349
program may then crash on a different platform, Solaris for example. So
350
it's best to fix it properly. According to the KDE folks "it's amazing
351
how many C++ programmers don't know this".</p>
349
352
<p>Pascal Massimino adds the following clarification:
350
<code class="computeroutput">delete[]</code> must be used for
351
objects allocated by <code class="computeroutput">new[]</code> because
352
the compiler stores the size of the array and the
353
pointer-to-member to the destructor of the array's content just
354
before the pointer actually returned. This implies a
355
variable-sized overhead in what's returned by
356
<code class="computeroutput">new</code> or
357
<code class="computeroutput">new[]</code>.</p>
353
<code class="function">delete[]</code> must be used for objects allocated by
354
<code class="function">new[]</code> because the compiler stores the size of the
355
array and the pointer-to-member to the destructor of the array's content
356
just before the pointer actually returned. This implies a
357
variable-sized overhead in what's returned by <code class="function">new</code>
358
or <code class="function">new[]</code>.</p>
359
360
<div class="sect2" lang="en">
360
361
<div class="titlepage"><div><div><h3 class="title">
430
431
==27492== by 0x804865A: main (overlap.c:40)
433
<p>You don't want the two blocks to overlap because one of
434
them could get partially trashed by the copying.</p>
434
<p>You don't want the two blocks to overlap because one of them could
435
get partially trashed by the copying.</p>
435
436
<p>You might think that Memcheck is being overly pedantic reporting
436
this in the case where <code class="computeroutput">dst</code> is less
437
than <code class="computeroutput">src</code>. For example, the obvious way
438
to implement <code class="computeroutput">memcpy()</code> is by copying
439
from the first byte to the last. However, the optimisation guides of
440
some architectures recommend copying from the last byte down to the first.
441
Also, some implementations of <code class="computeroutput">memcpy()</code>
442
zero <code class="computeroutput">dst</code> before copying, because zeroing
443
the destination's cache line(s) can improve performance.</p>
444
<p>The moral of the story is: if you want to write truly portable code,
445
don't make any assumptions about the language implementation.</p>
437
this in the case where <code class="computeroutput">dst</code> is less than
438
<code class="computeroutput">src</code>. For example, the obvious way to
439
implement <code class="function">memcpy()</code> is by copying from the first
440
byte to the last. However, the optimisation guides of some
441
architectures recommend copying from the last byte down to the first.
442
Also, some implementations of <code class="function">memcpy()</code> zero
443
<code class="computeroutput">dst</code> before copying, because zeroing the
444
destination's cache line(s) can improve performance.</p>
445
<p>The moral of the story is: if you want to write truly portable
446
code, don't make any assumptions about the language
447
449
<div class="sect2" lang="en">
448
450
<div class="titlepage"><div><div><h3 class="title">
449
451
<a name="mc-manual.leaks"></a>3.3.7.�Memory leak detection</h3></div></div></div>
450
<p>Memcheck keeps track of all memory blocks issued in
451
response to calls to malloc/calloc/realloc/new. So when the
452
program exits, it knows which blocks have not been freed.
452
<p>Memcheck keeps track of all memory blocks issued in response to
453
calls to malloc/calloc/realloc/new. So when the program exits, it knows
454
which blocks have not been freed.
454
<p>If <code class="computeroutput">--leak-check</code> is set
455
appropriately, for each remaining block, Memcheck scans the entire
456
address space of the process, looking for pointers to the block.
457
Each block fits into one of the three following categories.</p>
456
<p>If <code class="option">--leak-check</code> is set appropriately, for each
457
remaining block, Memcheck scans the entire address space of the process,
458
looking for pointers to the block. Each block fits into one of the
459
three following categories.</p>
458
460
<div class="itemizedlist"><ul type="disc">
459
<li><p>Still reachable: A pointer to the start
460
of the block is found. This usually indicates programming
461
sloppiness. Since the block is still pointed at, the
462
programmer could, at least in principle, free it before
463
program exit. Because these are very common and arguably
461
<li><p>Still reachable: A pointer to the start of the block is found.
462
This usually indicates programming sloppiness. Since the block is
463
still pointed at, the programmer could, at least in principle, free
464
it before program exit. Because these are very common and arguably
464
465
not a problem, Memcheck won't report such blocks unless
465
<code class="computeroutput">--show-reachable=yes</code> is
467
<li><p>Possibly lost, or "dubious": A pointer to the
468
interior of the block is found. The pointer might originally
469
have pointed to the start and have been moved along, or it
470
might be entirely unrelated. Memcheck deems such a block as
471
"dubious", because it's unclear whether or not a pointer to it
472
still exists.</p></li>
473
<li><p>Definitely lost, or "leaked": The worst
474
outcome is that no pointer to the block can be found. The
475
block is classified as "leaked", because the programmer could
476
not possibly have freed it at program exit, since no pointer
477
to it exists. This is likely a symptom of having lost the
478
pointer at some earlier point in the program.</p></li>
466
<code class="option">--show-reachable=yes</code> is specified.</p></li>
467
<li><p>Possibly lost, or "dubious": A pointer to the interior of the
468
block is found. The pointer might originally have pointed to the
469
start and have been moved along, or it might be entirely unrelated.
470
Memcheck deems such a block as "dubious", because it's unclear
471
whether or not a pointer to it still exists.</p></li>
472
<li><p>Definitely lost, or "leaked": The worst outcome is that no
473
pointer to the block can be found. The block is classified as
474
"leaked", because the programmer could not possibly have freed it at
475
program exit, since no pointer to it exists. This is likely a
476
symptom of having lost the pointer at some earlier point in the
480
<p>For each block mentioned, Memcheck will also tell you where
481
the block was allocated. It cannot tell you how or why the
482
pointer to a leaked block has been lost; you have to work that
483
out for yourself. In general, you should attempt to ensure your
484
programs do not have any leaked or dubious blocks at exit.</p>
479
<p>For each block mentioned, Memcheck will also tell you where the
480
block was allocated. It cannot tell you how or why the pointer to a
481
leaked block has been lost; you have to work that out for yourself. In
482
general, you should attempt to ensure your programs do not have any
483
leaked or dubious blocks at exit.</p>
485
484
<p>For example:</p>
486
485
<pre class="programlisting">
487
486
8 bytes in 1 blocks are definitely lost in loss record 1 of 14
515
513
<p>The suppression (2nd) line should have the form:</p>
516
514
<pre class="programlisting">
517
515
Memcheck:suppression_type</pre>
518
<p>Or, since some of the suppressions are shared with Addrcheck:</p>
519
<pre class="programlisting">
520
Memcheck,Addrcheck:suppression_type</pre>
521
516
<p>The Memcheck suppression types are as follows:</p>
522
517
<div class="itemizedlist"><ul type="disc">
523
<li><p><code class="computeroutput">Value1</code>,
524
<code class="computeroutput">Value2</code>,
525
<code class="computeroutput">Value4</code>,
526
<code class="computeroutput">Value8</code>,
527
<code class="computeroutput">Value16</code>,
518
<li><p><code class="varname">Value1</code>,
519
<code class="varname">Value2</code>,
520
<code class="varname">Value4</code>,
521
<code class="varname">Value8</code>,
522
<code class="varname">Value16</code>,
528
523
meaning an uninitialised-value error when
529
524
using a value of 1, 2, 4, 8 or 16 bytes.</p></li>
530
<li><p>Or: <code class="computeroutput">Cond</code> (or its old
531
name, <code class="computeroutput">Value0</code>), meaning use
525
<li><p>Or: <code class="varname">Cond</code> (or its old
526
name, <code class="varname">Value0</code>), meaning use
532
527
of an uninitialised CPU condition code.</p></li>
533
<li><p>Or: <code class="computeroutput">Addr1</code>,
534
<code class="computeroutput">Addr2</code>,
535
<code class="computeroutput">Addr4</code>,
536
<code class="computeroutput">Addr8</code>,
537
<code class="computeroutput">Addr16</code>,
528
<li><p>Or: <code class="varname">Addr1</code>,
529
<code class="varname">Addr2</code>,
530
<code class="varname">Addr4</code>,
531
<code class="varname">Addr8</code>,
532
<code class="varname">Addr16</code>,
538
533
meaning an invalid address during a
539
534
memory access of 1, 2, 4, 8 or 16 bytes respectively.</p></li>
540
<li><p>Or: <code class="computeroutput">Param</code>, meaning an
535
<li><p>Or: <code class="varname">Param</code>, meaning an
541
536
invalid system call parameter error.</p></li>
542
<li><p>Or: <code class="computeroutput">Free</code>, meaning an
537
<li><p>Or: <code class="varname">Free</code>, meaning an
543
538
invalid or mismatching free.</p></li>
544
<li><p>Or: <code class="computeroutput">Overlap</code>, meaning a
539
<li><p>Or: <code class="varname">Overlap</code>, meaning a
545
540
<code class="computeroutput">src</code> /
546
541
<code class="computeroutput">dst</code> overlap in
547
<code class="computeroutput">memcpy() or a similar
548
function</code>.</p></li>
549
<li><p>Or: <code class="computeroutput">Leak</code>, meaning
542
<code class="function">memcpy()</code> or a similar function.</p></li>
543
<li><p>Or: <code class="varname">Leak</code>, meaning
550
544
a memory leak.</p></li>
552
<p>The extra information line: for Param errors, is the name
553
of the offending system call parameter. No other error kinds
554
have this extra line.</p>
555
<p>The first line of the calling context: for Value and Addr
556
errors, it is either the name of the function in which the error
557
occurred, or, failing that, the full path of the .so file or
558
executable containing the error location. For Free errors, is
559
the name of the function doing the freeing (eg,
560
<code class="computeroutput">free</code>,
561
<code class="computeroutput">__builtin_vec_delete</code>, etc). For
562
Overlap errors, is the name of the function with the overlapping
563
arguments (eg. <code class="computeroutput">memcpy()</code>,
564
<code class="computeroutput">strcpy()</code>, etc).</p>
546
<p>The extra information line: for Param errors, is the name of the
547
offending system call parameter. No other error kinds have this extra
549
<p>The first line of the calling context: for Value and Addr errors,
550
it is either the name of the function in which the error occurred, or,
551
failing that, the full path of the .so file or executable containing the
552
error location. For Free errors, is the name of the function doing the
553
freeing (eg, <code class="function">free</code>,
554
<code class="function">__builtin_vec_delete</code>, etc). For Overlap errors, is
555
the name of the function with the overlapping arguments (eg.
556
<code class="function">memcpy()</code>, <code class="function">strcpy()</code>,
565
558
<p>Lastly, there's the rest of the calling context.</p>
567
560
<div class="sect1" lang="en">
572
565
<div class="sect2" lang="en">
573
566
<div class="titlepage"><div><div><h3 class="title">
574
567
<a name="mc-manual.value"></a>3.5.1.�Valid-value (V) bits</h3></div></div></div>
575
<p>It is simplest to think of Memcheck implementing a
576
synthetic CPU which is identical to a real CPU, except
577
for one crucial detail. Every bit (literally) of data processed,
578
stored and handled by the real CPU has, in the synthetic CPU, an
579
associated "valid-value" bit, which says whether or not the
580
accompanying bit has a legitimate value. In the discussions
581
which follow, this bit is referred to as the V (valid-value)
568
<p>It is simplest to think of Memcheck implementing a synthetic CPU
569
which is identical to a real CPU, except for one crucial detail. Every
570
bit (literally) of data processed, stored and handled by the real CPU
571
has, in the synthetic CPU, an associated "valid-value" bit, which says
572
whether or not the accompanying bit has a legitimate value. In the
573
discussions which follow, this bit is referred to as the V (valid-value)
583
<p>Each byte in the system therefore has a 8 V bits which
584
follow it wherever it goes. For example, when the CPU loads a
585
word-size item (4 bytes) from memory, it also loads the
586
corresponding 32 V bits from a bitmap which stores the V bits for
587
the process' entire address space. If the CPU should later write
588
the whole or some part of that value to memory at a different
589
address, the relevant V bits will be stored back in the V-bit
591
<p>In short, each bit in the system has an associated V bit,
592
which follows it around everywhere, even inside the CPU. Yes,
593
all the CPU's registers (integer, floating point, vector and condition
594
registers) have their own V bit vectors.</p>
595
<p>Copying values around does not cause Memcheck to check for,
596
or report on, errors. However, when a value is used in a way
597
which might conceivably affect the outcome of your program's
598
computation, the associated V bits are immediately checked. If
599
any of these indicate that the value is undefined, an error is
575
<p>Each byte in the system therefore has a 8 V bits which follow it
576
wherever it goes. For example, when the CPU loads a word-size item (4
577
bytes) from memory, it also loads the corresponding 32 V bits from a
578
bitmap which stores the V bits for the process' entire address space.
579
If the CPU should later write the whole or some part of that value to
580
memory at a different address, the relevant V bits will be stored back
581
in the V-bit bitmap.</p>
582
<p>In short, each bit in the system has an associated V bit, which
583
follows it around everywhere, even inside the CPU. Yes, all the CPU's
584
registers (integer, floating point, vector and condition registers) have
585
their own V bit vectors.</p>
586
<p>Copying values around does not cause Memcheck to check for, or
587
report on, errors. However, when a value is used in a way which might
588
conceivably affect the outcome of your program's computation, the
589
associated V bits are immediately checked. If any of these indicate
590
that the value is undefined, an error is reported.</p>
601
591
<p>Here's an (admittedly nonsensical) example:</p>
602
592
<pre class="programlisting">
619
608
printf("hello there\n");
621
610
<p>then Valgrind will complain, at the
622
<code class="computeroutput">if</code>, that the condition depends
623
on uninitialised values. Note that it <span><strong class="command">doesn't</strong></span>
624
complain at the <code class="computeroutput">j += a[i];</code>,
625
since at that point the undefinedness is not "observable". It's
626
only when a decision has to be made as to whether or not to do
627
the <code class="computeroutput">printf</code> -- an observable
628
action of your program -- that Memcheck complains.</p>
629
<p>Most low level operations, such as adds, cause Memcheck to
630
use the V bits for the operands to calculate the V bits for the result.
631
Even if the result is partially or wholly undefined, it does not
611
<code class="computeroutput">if</code>, that the condition depends on
612
uninitialised values. Note that it <span><strong class="command">doesn't</strong></span> complain
613
at the <code class="varname">j += a[i];</code>, since at that point the
614
undefinedness is not "observable". It's only when a decision has to be
615
made as to whether or not to do the <code class="function">printf</code> -- an
616
observable action of your program -- that Memcheck complains.</p>
617
<p>Most low level operations, such as adds, cause Memcheck to use the
618
V bits for the operands to calculate the V bits for the result. Even if
619
the result is partially or wholly undefined, it does not
633
<p>Checks on definedness only occur in three places: when a
634
value is used to generate a memory address, when control
635
flow decision needs to be made, and when a system call is
636
detected, Valgrind checks definedness of parameters as
621
<p>Checks on definedness only occur in three places: when a value is
622
used to generate a memory address, when control flow decision needs to
623
be made, and when a system call is detected, Valgrind checks definedness
624
of parameters as required.</p>
638
625
<p>If a check should detect undefinedness, an error message is
639
issued. The resulting value is subsequently regarded as
640
well-defined. To do otherwise would give long chains of error
641
messages. In effect, we say that undefined values are
643
<p>This sounds overcomplicated. Why not just check all reads
644
from memory, and complain if an undefined value is loaded into a
645
CPU register? Well, that doesn't work well, because perfectly
646
legitimate C programs routinely copy uninitialised values around
647
in memory, and we don't want endless complaints about that.
648
Here's the canonical example. Consider a struct like
626
issued. The resulting value is subsequently regarded as well-defined.
627
To do otherwise would give long chains of error messages. In effect, we
628
say that undefined values are non-infectious.</p>
629
<p>This sounds overcomplicated. Why not just check all reads from
630
memory, and complain if an undefined value is loaded into a CPU
631
register? Well, that doesn't work well, because perfectly legitimate C
632
programs routinely copy uninitialised values around in memory, and we
633
don't want endless complaints about that. Here's the canonical example.
634
Consider a struct like this:</p>
650
635
<pre class="programlisting">
651
636
struct S { int x; char c; };
657
<p>The question to ask is: how large is <code class="computeroutput">struct
658
S</code>, in bytes? An
659
<code class="computeroutput">int</code> is 4 bytes and a
660
<code class="computeroutput">char</code> one byte, so perhaps a
661
<code class="computeroutput">struct S</code> occupies 5 bytes?
662
Wrong. All (non-toy) compilers we know of will round the size of
663
<code class="computeroutput">struct S</code> up to a whole number of
664
words, in this case 8 bytes. Not doing this forces compilers to
665
generate truly appalling code for subscripting arrays of
666
<code class="computeroutput">struct S</code>'s.</p>
667
<p>So <code class="computeroutput">s1</code> occupies 8 bytes,
668
yet only 5 of them will be initialised. For the assignment
669
<code class="computeroutput">s2 = s1</code>, gcc generates code to
670
copy all 8 bytes wholesale into
671
<code class="computeroutput">s2</code> without regard for their
672
meaning. If Memcheck simply checked values as they came out of
673
memory, it would yelp every time a structure assignment like this
674
happened. So the more complicated semantics described above is
675
necessary. This allows <code class="literal">gcc</code> to copy
676
<code class="computeroutput">s1</code> into
677
<code class="computeroutput">s2</code> any way it likes, and a
678
warning will only be emitted if the uninitialised values are
642
<p>The question to ask is: how large is <code class="varname">struct S</code>,
643
in bytes? An <code class="varname">int</code> is 4 bytes and a
644
<code class="varname">char</code> one byte, so perhaps a <code class="varname">struct
645
S</code> occupies 5 bytes? Wrong. All (non-toy) compilers we know
646
of will round the size of <code class="varname">struct S</code> up to a whole
647
number of words, in this case 8 bytes. Not doing this forces compilers
648
to generate truly appalling code for subscripting arrays of
649
<code class="varname">struct S</code>'s.</p>
650
<p>So <code class="varname">s1</code> occupies 8 bytes, yet only 5 of them will
651
be initialised. For the assignment <code class="varname">s2 = s1</code>, gcc
652
generates code to copy all 8 bytes wholesale into <code class="varname">s2</code>
653
without regard for their meaning. If Memcheck simply checked values as
654
they came out of memory, it would yelp every time a structure assignment
655
like this happened. So the more complicated semantics described above
656
is necessary. This allows <code class="literal">gcc</code> to copy
657
<code class="varname">s1</code> into <code class="varname">s2</code> any way it likes, and a
658
warning will only be emitted if the uninitialised values are later
681
661
<div class="sect2" lang="en">
682
662
<div class="titlepage"><div><div><h3 class="title">
683
663
<a name="mc-manual.vaddress"></a>3.5.2.�Valid-address (A) bits</h3></div></div></div>
684
<p>Notice that the previous subsection describes how the
685
validity of values is established and maintained without having
686
to say whether the program does or does not have the right to
687
access any particular memory location. We now consider the
689
<p>As described above, every bit in memory or in the CPU has
690
an associated valid-value (V) bit. In
691
addition, all bytes in memory, but not in the CPU, have an
692
associated valid-address (A) bit. This
693
indicates whether or not the program can legitimately read or
694
write that location. It does not give any indication of the
695
validity or the data at that location -- that's the job of the
696
V bits -- only whether or not the location may
698
<p>Every time your program reads or writes memory, Memcheck
699
checks the A bits associated with the address.
700
If any of them indicate an invalid address, an error is emitted.
701
Note that the reads and writes themselves do not change the A
702
bits, only consult them.</p>
664
<p>Notice that the previous subsection describes how the validity of
665
values is established and maintained without having to say whether the
666
program does or does not have the right to access any particular memory
667
location. We now consider the latter issue.</p>
668
<p>As described above, every bit in memory or in the CPU has an
669
associated valid-value (V) bit. In addition, all bytes in memory, but
670
not in the CPU, have an associated valid-address (A) bit. This
671
indicates whether or not the program can legitimately read or write that
672
location. It does not give any indication of the validity or the data
673
at that location -- that's the job of the V bits -- only whether or not
674
the location may be accessed.</p>
675
<p>Every time your program reads or writes memory, Memcheck checks
676
the A bits associated with the address. If any of them indicate an
677
invalid address, an error is emitted. Note that the reads and writes
678
themselves do not change the A bits, only consult them.</p>
703
679
<p>So how do the A bits get set/cleared? Like this:</p>
704
680
<div class="itemizedlist"><ul type="disc">
705
681
<li><p>When the program starts, all the global data areas are
706
682
marked as accessible.</p></li>
707
<li><p>When the program does malloc/new, the A bits for
708
exactly the area allocated, and not a byte more, are marked
709
as accessible. Upon freeing the area the A bits are changed
710
to indicate inaccessibility.</p></li>
711
<li><p>When the stack pointer register
712
(<code class="literal">SP</code>) moves up or down,
713
A bits are set. The rule is that the area
714
from <code class="literal">SP</code> up to the base of the stack is
715
marked as accessible, and below <code class="literal">SP</code> is
716
inaccessible. (If that sounds illogical, bear in mind that
717
the stack grows down, not up, on almost all Unix systems,
718
including GNU/Linux.) Tracking <code class="literal">SP</code> like
719
this has the useful side-effect that the section of stack
720
used by a function for local variables etc is automatically
721
marked accessible on function entry and inaccessible on
723
<li><p>When doing system calls, A bits are changed
724
appropriately. For example, mmap() magically makes files
725
appear in the process' address space, so the A bits must be
726
updated if mmap() succeeds.</p></li>
727
<li><p>Optionally, your program can tell Valgrind about such
728
changes explicitly, using the client request mechanism
729
described above.</p></li>
683
<li><p>When the program does malloc/new, the A bits for exactly the
684
area allocated, and not a byte more, are marked as accessible. Upon
685
freeing the area the A bits are changed to indicate
686
inaccessibility.</p></li>
687
<li><p>When the stack pointer register (<code class="literal">SP</code>) moves
688
up or down, A bits are set. The rule is that the area from
689
<code class="literal">SP</code> up to the base of the stack is marked as
690
accessible, and below <code class="literal">SP</code> is inaccessible. (If
691
that sounds illogical, bear in mind that the stack grows down, not
692
up, on almost all Unix systems, including GNU/Linux.) Tracking
693
<code class="literal">SP</code> like this has the useful side-effect that the
694
section of stack used by a function for local variables etc is
695
automatically marked accessible on function entry and inaccessible
697
<li><p>When doing system calls, A bits are changed appropriately.
698
For example, mmap() magically makes files appear in the process'
699
address space, so the A bits must be updated if mmap()
701
<li><p>Optionally, your program can tell Valgrind about such changes
702
explicitly, using the client request mechanism described
732
706
<div class="sect2" lang="en">
735
709
<p>Memcheck's checking machinery can be summarised as
737
711
<div class="itemizedlist"><ul type="disc">
738
<li><p>Each byte in memory has 8 associated
739
V (valid-value) bits, saying whether or
740
not the byte has a defined value, and a single
741
A (valid-address) bit, saying whether or
742
not the program currently has the right to read/write that
744
<li><p>When memory is read or written, the relevant
745
A bits are consulted. If they indicate an
746
invalid address, Valgrind emits an Invalid read or Invalid
747
write error.</p></li>
748
<li><p>When memory is read into the CPU's registers,
749
the relevant V bits are fetched from
750
memory and stored in the simulated CPU. They are not
752
<li><p>When a register is written out to memory, the
753
V bits for that register are written back
754
to memory too.</p></li>
755
<li><p>When values in CPU registers are used to
756
generate a memory address, or to determine the outcome of a
757
conditional branch, the V bits for those
758
values are checked, and an error emitted if any of them are
760
<li><p>When values in CPU registers are used for any
761
other purpose, Valgrind computes the V bits for the result,
762
but does not check them.</p></li>
763
<li><p>One the V bits for a value in the
764
CPU have been checked, they are then set to indicate
765
validity. This avoids long chains of errors.</p></li>
712
<li><p>Each byte in memory has 8 associated V (valid-value) bits,
713
saying whether or not the byte has a defined value, and a single A
714
(valid-address) bit, saying whether or not the program currently has
715
the right to read/write that address.</p></li>
716
<li><p>When memory is read or written, the relevant A bits are
717
consulted. If they indicate an invalid address, Valgrind emits an
718
Invalid read or Invalid write error.</p></li>
719
<li><p>When memory is read into the CPU's registers, the relevant V
720
bits are fetched from memory and stored in the simulated CPU. They
721
are not consulted.</p></li>
722
<li><p>When a register is written out to memory, the V bits for that
723
register are written back to memory too.</p></li>
724
<li><p>When values in CPU registers are used to generate a memory
725
address, or to determine the outcome of a conditional branch, the V
726
bits for those values are checked, and an error emitted if any of
727
them are undefined.</p></li>
728
<li><p>When values in CPU registers are used for any other purpose,
729
Valgrind computes the V bits for the result, but does not check
731
<li><p>One the V bits for a value in the CPU have been checked, they
732
are then set to indicate validity. This avoids long chains of
767
<p>When values are loaded from memory, valgrind checks the
768
A bits for that location and issues an illegal-address
769
warning if needed. In that case, the V bits loaded are
770
forced to indicate Valid, despite the location being invalid.</p>
771
<p>This apparently strange choice reduces the amount of
772
confusing information presented to the user. It avoids the
773
unpleasant phenomenon in which memory is read from a place
774
which is both unaddressible and contains invalid values, and,
775
as a result, you get not only an invalid-address (read/write)
776
error, but also a potentially large set of
777
uninitialised-value errors, one for every time the value is
779
<p>There is a hazy boundary case to do with multi-byte
780
loads from addresses which are partially valid and partially
781
invalid. See details of the flag
782
<code class="computeroutput">--partial-loads-ok</code> for
735
<p>When values are loaded from memory, valgrind checks the A bits
736
for that location and issues an illegal-address warning if needed.
737
In that case, the V bits loaded are forced to indicate Valid,
738
despite the location being invalid.</p>
739
<p>This apparently strange choice reduces the amount of confusing
740
information presented to the user. It avoids the unpleasant
741
phenomenon in which memory is read from a place which is both
742
unaddressible and contains invalid values, and, as a result, you get
743
not only an invalid-address (read/write) error, but also a
744
potentially large set of uninitialised-value errors, one for every
745
time the value is used.</p>
746
<p>There is a hazy boundary case to do with multi-byte loads from
747
addresses which are partially valid and partially invalid. See
748
details of the flag <code class="option">--partial-loads-ok</code> for details.
786
<p>Memcheck intercepts calls to malloc, calloc, realloc,
787
valloc, memalign, free, new, new[], delete and delete[].
788
The behaviour you get
752
<p>Memcheck intercepts calls to malloc, calloc, realloc, valloc,
753
memalign, free, new, new[], delete and delete[]. The behaviour you get
790
755
<div class="itemizedlist"><ul type="disc">
791
<li><p>malloc/new/new[]: the returned memory is marked as
792
addressible but not having valid values. This means you have
793
to write on it before you can read it.</p></li>
794
<li><p>calloc: returned memory is marked both addressible and
795
valid, since calloc() clears the area to zero.</p></li>
796
<li><p>realloc: if the new size is larger than the old, the
797
new section is addressible but invalid, as with
799
<li><p>If the new size is smaller, the dropped-off section is
800
marked as unaddressible. You may only pass to realloc a
801
pointer previously issued to you by malloc/calloc/realloc.</p></li>
802
<li><p>free/delete/delete[]: you may only pass to these
804
previously issued to you by the corresponding allocation function.
805
Otherwise, Valgrind complains. If the pointer is
806
indeed valid, Valgrind marks the entire area it points at as
807
unaddressible, and places the block in the
808
freed-blocks-queue. The aim is to defer as long as possible
809
reallocation of this block. Until that happens, all attempts
810
to access it will elicit an invalid-address error, as you
756
<li><p>malloc/new/new[]: the returned memory is marked as addressible
757
but not having valid values. This means you have to write on it
758
before you can read it.</p></li>
759
<li><p>calloc: returned memory is marked both addressible and valid,
760
since calloc() clears the area to zero.</p></li>
761
<li><p>realloc: if the new size is larger than the old, the new
762
section is addressible but invalid, as with malloc.</p></li>
763
<li><p>If the new size is smaller, the dropped-off section is marked
764
as unaddressible. You may only pass to realloc a pointer previously
765
issued to you by malloc/calloc/realloc.</p></li>
766
<li><p>free/delete/delete[]: you may only pass to these functions a
767
pointer previously issued to you by the corresponding allocation
768
function. Otherwise, Valgrind complains. If the pointer is indeed
769
valid, Valgrind marks the entire area it points at as unaddressible,
770
and places the block in the freed-blocks-queue. The aim is to defer
771
as long as possible reallocation of this block. Until that happens,
772
all attempts to access it will elicit an invalid-address error, as
773
you would hope.</p></li>
816
778
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
817
779
<a name="mc-manual.clientreqs"></a>3.6.�Client Requests</h2></div></div></div>
818
780
<p>The following client requests are defined in
819
<code class="filename">memcheck.h</code>. They also work for Addrcheck.
781
<code class="filename">memcheck.h</code>.
820
782
See <code class="filename">memcheck.h</code> for exact details of their
822
784
<div class="itemizedlist"><ul type="disc">
823
<li><p><code class="computeroutput">VALGRIND_MAKE_NOACCESS</code>,
824
<code class="computeroutput">VALGRIND_MAKE_WRITABLE</code> and
825
<code class="computeroutput">VALGRIND_MAKE_READABLE</code>.
785
<li><p><code class="varname">VALGRIND_MAKE_MEM_NOACCESS</code>,
786
<code class="varname">VALGRIND_MAKE_MEM_UNDEFINED</code> and
787
<code class="varname">VALGRIND_MAKE_MEM_DEFINED</code>.
826
788
These mark address ranges as completely inaccessible,
827
789
accessible but containing undefined data, and accessible and
828
790
containing defined data, respectively. Subsequent errors may
829
791
have their faulting addresses described in terms of these
830
792
blocks. Returns a "block handle". Returns zero when not run
831
793
on Valgrind.</p></li>
832
<li><p><code class="computeroutput">VALGRIND_DISCARD</code>: At
833
some point you may want Valgrind to stop reporting errors in
834
terms of the blocks defined by the previous three macros. To
835
do this, the above macros return a small-integer "block
836
handle". You can pass this block handle to
837
<code class="computeroutput">VALGRIND_DISCARD</code>. After
838
doing so, Valgrind will no longer be able to relate
839
addressing errors to the user-defined block associated with
840
the handle. The permissions settings associated with the
841
handle remain in place; this just affects how errors are
842
reported, not whether they are reported. Returns 1 for an
843
invalid handle and 0 for a valid handle (although passing
844
invalid handles is harmless). Always returns 0 when not run
794
<li><p><code class="varname">VALGRIND_MAKE_MEM_DEFINED_IF_ADDRESSABLE</code>.
795
This is just like <code class="varname">VALGRIND_MAKE_MEM_DEFINED</code> but only
796
affects those bytes that are already addressable.</p></li>
797
<li><p><code class="varname">VALGRIND_DISCARD</code>: At some point you may
798
want Valgrind to stop reporting errors in terms of the blocks
799
defined by the previous three macros. To do this, the above macros
800
return a small-integer "block handle". You can pass this block
801
handle to <code class="varname">VALGRIND_DISCARD</code>. After doing so,
802
Valgrind will no longer be able to relate addressing errors to the
803
user-defined block associated with the handle. The permissions
804
settings associated with the handle remain in place; this just
805
affects how errors are reported, not whether they are reported.
806
Returns 1 for an invalid handle and 0 for a valid handle (although
807
passing invalid handles is harmless). Always returns 0 when not run
845
808
on Valgrind.</p></li>
846
<li><p><code class="computeroutput">VALGRIND_CHECK_WRITABLE</code>
847
and <code class="computeroutput">VALGRIND_CHECK_READABLE</code>:
848
check immediately whether or not the given address range has
849
the relevant property, and if not, print an error message.
850
Also, for the convenience of the client, returns zero if the
851
relevant property holds; otherwise, the returned value is the
852
address of the first byte for which the property is not true.
853
Always returns 0 when not run on Valgrind.</p></li>
854
<li><p><code class="computeroutput">VALGRIND_CHECK_DEFINED</code>:
855
a quick and easy way to find out whether Valgrind thinks a
856
particular variable (lvalue, to be precise) is addressible
857
and defined. Prints an error message if not. Returns no
859
<li><p><code class="computeroutput">VALGRIND_DO_LEAK_CHECK</code>:
860
run the memory leak detector right now. Returns no value. I
861
guess this could be used to incrementally check for leaks
862
between arbitrary places in the program's execution.
863
Warning: not properly tested!</p></li>
864
<li><p><code class="computeroutput">VALGRIND_COUNT_LEAKS</code>:
865
fills in the four arguments with the number of bytes of
866
memory found by the previous leak check to be leaked,
867
dubious, reachable and suppressed. Again, useful in test
868
harness code, after calling
869
<code class="computeroutput">VALGRIND_DO_LEAK_CHECK</code>.</p></li>
870
<li><p><code class="computeroutput">VALGRIND_GET_VBITS</code> and
871
<code class="computeroutput">VALGRIND_SET_VBITS</code>: allow
872
you to get and set the V (validity) bits for an address
873
range. You should probably only set V bits that you have got
874
with <code class="computeroutput">VALGRIND_GET_VBITS</code>.
875
Only for those who really know what they are doing. Note: currently
876
disabled in Valgrind 3.1.0.</p></li>
809
<li><p><code class="varname">VALGRIND_CHECK_MEM_IS_ADDRESSABLE</code> and
810
<code class="varname">VALGRIND_CHECK_MEM_IS_DEFINED</code>: check immediately
811
whether or not the given address range has the relevant property,
812
and if not, print an error message. Also, for the convenience of
813
the client, returns zero if the relevant property holds; otherwise,
814
the returned value is the address of the first byte for which the
815
property is not true. Always returns 0 when not run on
817
<li><p><code class="varname">VALGRIND_CHECK_VALUE_IS_DEFINED</code>: a quick and easy
818
way to find out whether Valgrind thinks a particular value
819
(lvalue, to be precise) is addressable and defined. Prints an error
820
message if not. Returns no value.</p></li>
821
<li><p><code class="varname">VALGRIND_DO_LEAK_CHECK</code>: run the memory leak
822
detector right now. Returns no value. I guess this could be used
823
to incrementally check for leaks between arbitrary places in the
824
program's execution. Warning: not properly tested!</p></li>
825
<li><p><code class="varname">VALGRIND_COUNT_LEAKS</code>: fills in the four
826
arguments with the number of bytes of memory found by the previous
827
leak check to be leaked, dubious, reachable and suppressed. Again,
828
useful in test harness code, after calling
829
<code class="varname">VALGRIND_DO_LEAK_CHECK</code>.</p></li>
830
<li><p><code class="varname">VALGRIND_GET_VBITS</code> and
831
<code class="varname">VALGRIND_SET_VBITS</code>: allow you to get and set the
832
V (validity) bits for an address range. You should probably only
833
set V bits that you have got with
834
<code class="varname">VALGRIND_GET_VBITS</code>. Only for those who really
835
know what they are doing.</p></li>
added
removed
docs/html/mc-manual.html
