21
21
<p><span>Available Languages: </span><a href="../en/developer/debugging.html" title="English"> en </a></p>
24
<p>The allocation mechanisms within APR have a number of debugging modes
25
that can be used to assist in finding memory problems. This document
26
describes the modes available and gives instructions on activating
29
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#options">Available debugging options</a></li>
30
<li><img alt="" src="../images/down.gif" /> <a href="#combo">Allowable Combinations</a></li>
31
<li><img alt="" src="../images/down.gif" /> <a href="#howto">Activating Debugging Options</a></li>
33
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
35
<h2><a name="options" id="options">Available debugging options</a></h2>
36
<h3><a name="alloc_debug" id="alloc_debug">Allocation Debugging - ALLOC_DEBUG</a></h3>
39
<div class="note">Debugging support: Define this to enable code which
40
helps detect re-use of <code>free()</code>d memory and other such
43
<p>The theory is simple. The <code>FILL_BYTE</code> (<code>0xa5</code>)
44
is written over all <code>malloc</code>'d memory as we receive it, and
45
is written over everything that we free up during a
46
<code>clear_pool</code>. We check that blocks on the free list always
47
have the <code>FILL_BYTE</code> in them, and we check during
48
<code>palloc()</code> that the bytes still have <code>FILL_BYTE</code>
49
in them. If you ever see garbage URLs or whatnot containing lots
50
of <code>0xa5</code>s then you know something used data that's been
51
freed or uninitialized.</p>
54
<h3><a name="alloc_use_malloc" id="alloc_use_malloc">Malloc Support - ALLOC_USE_MALLOC</a></h3>
57
<div class="note">If defined all allocations will be done with
58
<code>malloc()</code> and <code>free()</code>d appropriately at the
61
<p>This is intended to be used with something like Electric
62
Fence or Purify to help detect memory problems. Note that if
63
you're using efence then you should also add in <code>ALLOC_DEBUG</code>.
64
But don't add in <code>ALLOC_DEBUG</code> if you're using Purify because
65
<code>ALLOC_DEBUG</code> would hide all the uninitialized read errors
66
that Purify can diagnose.</p>
69
<h3><a name="pool_debug" id="pool_debug">Pool Debugging - POOL_DEBUG</a></h3>
70
<div class="note">This is intended to detect cases where the wrong pool is
71
used when assigning data to an object in another pool.</div>
73
<p>In particular, it causes the <code>table_{set,add,merge}n</code>
74
routines to check that their arguments are safe for the
75
<code>apr_table_t</code> they're being placed in. It currently only works
76
with the unix multiprocess model, but could be extended to others.</p>
79
<h3><a name="make_table_profile" id="make_table_profile">Table Debugging - MAKE_TABLE_PROFILE</a></h3>
82
<div class="note">Provide diagnostic information about make_table() calls
83
which are possibly too small.</div>
85
<p>This requires a recent gcc which supports
86
<code>__builtin_return_address()</code>. The error_log output will be a
88
<div class="example"><p><code>
89
table_push: apr_table_t created by 0x804d874 hit limit of 10
92
<p>Use <code>l *0x804d874</code> to find the
93
source that corresponds to. It indicates that a <code>apr_table_t</code>
94
allocated by a call at that address has possibly too small an
95
initial <code>apr_table_t</code> size guess.</p>
98
<h3><a name="alloc_stats" id="alloc_stats">Allocation Statistics - ALLOC_STATS</a></h3>
101
<div class="note">Provide some statistics on the cost of allocations.</div>
103
<p>This requires a bit of an understanding of how <code>alloc.c</code>
106
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
107
<div class="section">
108
<h2><a name="combo" id="combo">Allowable Combinations</a></h2>
110
<p>Not all the options outlined above can be activated at the
111
same time. the following table gives more information.</p>
113
<table class="bordered"><tr class="header"><th />
115
<th>ALLOC USE MALLOC</th>
117
<th>MAKE TABLE PROFILE</th>
118
<th>ALLOC STATS</th></tr>
119
<tr><th>ALLOC DEBUG</th>
120
<td>-</td><td>No</td><td>Yes</td><td>Yes</td><td>Yes</td></tr>
121
<tr class="odd"><th>ALLOC USE MALLOC</th>
122
<td>No</td><td>-</td><td>No</td><td>No</td><td>No</td></tr>
123
<tr><th>POOL DEBUG</th>
124
<td>Yes</td><td>No</td><td>-</td><td>Yes</td><td>Yes</td></tr>
125
<tr class="odd"><th>MAKE TABLE PROFILE</th>
126
<td>Yes</td><td>No</td><td>Yes</td><td>-</td><td>Yes</td></tr>
127
<tr><th>ALLOC STATS</th>
128
<td>Yes</td><td>No</td><td>Yes</td><td>Yes</td><td>-</td></tr>
131
<p>Additionally the debugging options are not suitable for
132
multi-threaded versions of the server. When trying to debug
133
with these options the server should be started in single
135
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
136
<div class="section">
137
<h2><a name="howto" id="howto">Activating Debugging Options</a></h2>
139
<p>The various options for debugging memory are now enabled in
140
the <code>apr_general.h</code> header file in APR. The various options are
141
enabled by uncommenting the define for the option you wish to
142
use. The section of the code currently looks like this
143
(<em>contained in srclib/apr/include/apr_pools.h</em>)</p>
145
<div class="example"><p><code>
147
#define ALLOC_DEBUG<br />
148
#define POOL_DEBUG<br />
149
#define ALLOC_USE_MALLOC<br />
150
#define MAKE_TABLE_PROFILE<br />
151
#define ALLOC_STATS<br />
154
typedef struct ap_pool_t {<br />
155
<span class="indent">
156
union block_hdr *first;<br />
157
union block_hdr *last;<br />
158
struct cleanup *cleanups;<br />
159
struct process_chain *subprocesses;<br />
160
struct ap_pool_t *sub_pools;<br />
161
struct ap_pool_t *sub_next;<br />
162
struct ap_pool_t *sub_prev;<br />
163
struct ap_pool_t *parent;<br />
164
char *free_first_avail;<br />
166
#ifdef ALLOC_USE_MALLOC<br />
167
<span class="indent">
168
void *allocation_list;<br />
171
#ifdef POOL_DEBUG<br />
172
<span class="indent">
173
struct ap_pool_t *joined;<br />
176
<span class="indent">
177
int (*apr_abort)(int retcode);<br />
178
struct datastruct *prog_data;<br />
183
<p>To enable allocation debugging simply move the <code>#define
184
ALLOC_DEBUG</code> above the start of the comments block and rebuild
187
<div class="note"><h3>Note</h3>
188
<p>In order to use the various options the server <strong>must</strong>
189
be rebuilt after editing the header file.</p>
25
This document has been removed.
192
29
<div class="bottomlang">
193
30
<p><span>Available Languages: </span><a href="../en/developer/debugging.html" title="English"> en </a></p>
194
31
</div><div id="footer">
195
<p class="apache">Copyright 2011 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
32
<p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
196
33
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
b'\\ No newline at end of file'
added
removed
docs/manual/developer/debugging.html.en
