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