debugging.xml revision c82fca6d3f5608b946f18d37e8710b1d71e3478d
<?xml version="1.0" encoding="UTF-8" ?>
<manualpage>
<relativepath href=".."/>
<parentdocument href="./">Developer Documentation</parentdocument>
<title>Debugging Memory Allocation in APR</title>
<summary>
<p>The allocation mechanism's within APR have a number of debugging modes
that can be used to assist in finding memory problems. This document
describes the modes available and gives instructions on activating
them.</p>
</summary>
<section id="options"><title>Available debugging options</title>
<section id="alloc_debug">
<title>Allocation Debugging - ALLOC_DEBUG</title>
<note>Debugging support: Define this to enable code which
helps detect re-use of <code>free()</code>d memory and other such
nonsense.</note>
<p>The theory is simple. The <code>FILL_BYTE</code> (<code>0xa5</code>)
is written over all <code>malloc</code>'d memory as we receive it, and
is written over everything that we free up during a
<code>clear_pool</code>. We check that blocks on the free list always
have the <code>FILL_BYTE</code> in them, and we check during
<code>palloc()</code> that the bytes still have <code>FILL_BYTE</code>
in them. If you ever see garbage URLs or whatnot containing lots
of <code>0xa5</code>s then you know something used data that's been
freed or uninitialized.</p>
</section>
<section id="alloc_use_malloc">
<title>Malloc Support - ALLOC_USE_MALLOC</title>
<note>If defined all allocations will be done with
<code>malloc()</code> and <code>free()</code>d appropriately at the
end.</note>
<p>This is intended to be used with something like Electric
Fence or Purify to help detect memory problems. Note that if
you're using efence then you should also add in <code>ALLOC_DEBUG</code>.
But don't add in <code>ALLOC_DEBUG</code> if you're using Purify because
<code>ALLOC_DEBUG</code> would hide all the uninitialized read errors
that Purify can diagnose.</p>
</section>
<section id="pool_debug"><title>Pool Debugging - POOL_DEBUG</title>
<note>This is intended to detect cases where the wrong pool is
used when assigning data to an object in another pool.</note>
<p>In particular, it causes the <code>table_{set,add,merge}n</code>
routines to check that their arguments are safe for the
<code>apr_table_t</code> they're being placed in. It currently only works
with the unix multiprocess model, but could be extended to others.</p>
</section>
<section id="make_table_profile">
<title>Table Debugging - MAKE_TABLE_PROFILE</title>
<note>Provide diagnostic information about make_table() calls
which are possibly too small.</note>
<p>This requires a recent gcc which supports
<code>__builtin_return_address()</code>. The error_log output will be a
message such as:</p>
<example>
table_push: apr_table_t created by 0x804d874 hit limit of 10
</example>
<p>Use <code>l *0x804d874</code> to find the
source that corresponds to. It indicates that a <code>apr_table_t</code>
allocated by a call at that address has possibly too small an
initial <code>apr_table_t</code> size guess.</p>
</section>
<section id="alloc_stats">
<title>Allocation Statistics - ALLOC_STATS</title>
<note>Provide some statistics on the cost of allocations.</note>
</section>
</section>
<section id="combo"><title>Allowable Combinations</title>
<p>Not all the options outlined above can be activated at the
same time. the following table gives more information.</p>
<table border="1" style="zebra">
<tr><th></th>
<th>ALLOC DEBUG</th>
<th>ALLOC USE MALLOC</th>
<th>POOL DEBUG</th>
<th>MAKE TABLE PROFILE</th>
<th>ALLOC STATS</th></tr>
<tr><th>ALLOC DEBUG</th>
<td>-</td><td>No</td><td>Yes</td><td>Yes</td><td>Yes</td></tr>
<tr><th>ALLOC USE MALLOC</th>
<td>No</td><td>-</td><td>No</td><td>No</td><td>No</td></tr>
<tr><th>POOL DEBUG</th>
<td>Yes</td><td>No</td><td>-</td><td>Yes</td><td>Yes</td></tr>
<tr><th>MAKE TABLE PROFILE</th>
<td>Yes</td><td>No</td><td>Yes</td><td>-</td><td>Yes</td></tr>
<tr><th>ALLOC STATS</th>
<td>Yes</td><td>No</td><td>Yes</td><td>Yes</td><td>-</td></tr>
</table>
<p>Additionally the debugging options are not suitable for
multi-threaded versions of the server. When trying to debug
with these options the server should be started in single
process mode.</p>
</section>
<section id="howto"><title>Activating Debugging Options</title>
<p>The various options for debugging memory are now enabled in
enabled by uncommenting the define for the option you wish to
use. The section of the code currently looks like this
<example>
/*<br />
#define ALLOC_DEBUG<br />
#define POOL_DEBUG<br />
#define ALLOC_USE_MALLOC<br />
#define MAKE_TABLE_PROFILE<br />
#define ALLOC_STATS<br />
*/<br />
<br />
typedef struct ap_pool_t {<br />
<indent>
union block_hdr *first;<br />
union block_hdr *last;<br />
struct cleanup *cleanups;<br />
struct process_chain *subprocesses;<br />
struct ap_pool_t *sub_pools;<br />
struct ap_pool_t *sub_next;<br />
struct ap_pool_t *sub_prev;<br />
struct ap_pool_t *parent;<br />
char *free_first_avail;<br />
</indent>
#ifdef ALLOC_USE_MALLOC<br />
<indent>
void *allocation_list;<br />
</indent>
#endif<br />
#ifdef POOL_DEBUG<br />
<indent>
struct ap_pool_t *joined;<br />
</indent>
#endif<br />
<indent>
int (*apr_abort)(int retcode);<br />
struct datastruct *prog_data;<br />
</indent>
} ap_pool_t;
</example>
<p>To enable allocation debugging simply move the <code>#define
ALLOC_DEBUG</code> above the start of the comments block and rebuild
the server.</p>
<note><title>Note</title>
<p>In order to use the various options the server <strong>must</strong>
be rebuilt after editing the header file.</p>
</note>
</section>
</manualpage>