granicus.if.org Git - apache/blob - docs/manual/developer/debugging.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4
   5 <manualpage>
   6 <relativepath href=".."/>
   7
   8 <title>Debugging Memory Allocation in APR</title>
   9
  10 <summary>
  11     <p>The allocation mechanism's within APR have a number of debugging modes
  12     that can be used to assist in finding memory problems. This document
  13     describes the modes available and gives instructions on activating
  14     them.</p>
  15 </summary>
  16
  17 <section id="options"><title>Available debugging options</title>
  18     <section id="alloc_debug">
  19     <title>Allocation Debugging - ALLOC_DEBUG</title>
  20
  21       <note>Debugging support: Define this to enable code which
  22       helps detect re-use of <code>free()</code>d memory and other such
  23       nonsense.</note>
  24
  25       <p>The theory is simple. The <code>FILL_BYTE</code> (<code>0xa5</code>)
  26       is written over all <code>malloc</code>'d memory as we receive it, and
  27       is written over everything that we free up during a
  28       <code>clear_pool</code>. We check that blocks on the free list always
  29       have the <code>FILL_BYTE</code> in them, and we check during
  30       <code>palloc()</code> that the bytes still have <code>FILL_BYTE</code>
  31       in them. If you ever see garbage URLs or whatnot containing lots
  32       of <code>0xa5</code>s then you know something used data that's been
  33       freed or uninitialized.</p>
  34     </section>
  35
  36     <section id="alloc_use_malloc">
  37     <title>Malloc Support - ALLOC_USE_MALLOC</title>
  38
  39       <note>If defined all allocations will be done with
  40       <code>malloc()</code> and <code>free()</code>d appropriately at the
  41       end.</note>
  42
  43       <p>This is intended to be used with something like Electric
  44       Fence or Purify to help detect memory problems. Note that if
  45       you're using efence then you should also add in <code>ALLOC_DEBUG</code>.
  46       But don't add in <code>ALLOC_DEBUG</code> if you're using Purify because
  47       <code>ALLOC_DEBUG</code> would hide all the uninitialized read errors
  48       that Purify can diagnose.</p>
  49     </section>
  50
  51     <section id="pool_debug"><title>Pool Debugging - POOL_DEBUG</title>
  52       <note>This is intended to detect cases where the wrong pool is
  53       used when assigning data to an object in another pool.</note>
  54
  55       <p>In particular, it causes the <code>table_{set,add,merge}n</code>
  56       routines to check that their arguments are safe for the
  57       <code>apr_table_t</code> they're being placed in. It currently only works
  58       with the unix multiprocess model, but could be extended to others.</p>
  59     </section>
  60
  61     <section id="make_table_profile">
  62     <title>Table Debugging - MAKE_TABLE_PROFILE</title>
  63
  64       <note>Provide diagnostic information about make_table() calls
  65       which are possibly too small.</note>
  66
  67       <p>This requires a recent gcc which supports
  68       <code>__builtin_return_address()</code>. The error_log output will be a
  69       message such as:</p>
  70       <example>
  71         table_push: apr_table_t created by 0x804d874 hit limit of 10
  72       </example>
  73
  74       <p>Use <code>l *0x804d874</code> to find the
  75       source that corresponds to. It indicates that a <code>apr_table_t</code>
  76       allocated by a call at that address has possibly too small an
  77       initial <code>apr_table_t</code> size guess.</p>
  78     </section>
  79
  80     <section id="alloc_stats">
  81     <title>Allocation Statistics -  ALLOC_STATS</title>
  82
  83       <note>Provide some statistics on the cost of allocations.</note>
  84
  85       <p>This requires a bit of an understanding of how alloc.c works.</p>
  86     </section>
  87 </section>
  88
  89 <section id="combo"><title>Allowable Combinations</title>
  90
  91     <p>Not all the options outlined above can be activated at the
  92     same time. the following table gives more information.</p>
  93
  94     <table border="1" style="zebra">
  95     <tr><th></th>
  96         <th>ALLOC DEBUG</th>
  97         <th>ALLOC USE MALLOC</th>
  98         <th>POOL DEBUG</th>
  99         <th>MAKE TABLE PROFILE</th>
 100         <th>ALLOC STATS</th></tr>
 101     <tr><th>ALLOC DEBUG</th>
 102         <td>-</td><td>No</td><td>Yes</td><td>Yes</td><td>Yes</td></tr>
 103     <tr><th>ALLOC USE MALLOC</th>
 104         <td>No</td><td>-</td><td>No</td><td>No</td><td>No</td></tr>
 105     <tr><th>POOL DEBUG</th>
 106         <td>Yes</td><td>No</td><td>-</td><td>Yes</td><td>Yes</td></tr>
 107     <tr><th>MAKE TABLE PROFILE</th>
 108         <td>Yes</td><td>No</td><td>Yes</td><td>-</td><td>Yes</td></tr>
 109     <tr><th>ALLOC STATS</th>
 110         <td>Yes</td><td>No</td><td>Yes</td><td>Yes</td><td>-</td></tr>
 111     </table>
 112
 113     <p>Additionally the debugging options are not suitable for
 114     multi-threaded versions of the server. When trying to debug
 115     with these options the server should be started in single
 116     process mode.</p>
 117 </section>
 118
 119 <section id="howto"><title>Activating Debugging Options</title>
 120
 121     <p>The various options for debugging memory are now enabled in
 122     the <code>apr_general.h</code> header file in APR. The various options are
 123     enabled by uncommenting the define for the option you wish to
 124     use. The section of the code currently looks like this
 125     (<em>contained in srclib/apr/include/apr_pools.h</em>)</p>
 126
 127     <example>
 128       /*<br />
 129       #define ALLOC_DEBUG<br />
 130       #define POOL_DEBUG<br />
 131       #define ALLOC_USE_MALLOC<br />
 132       #define MAKE_TABLE_PROFILE<br />
 133       #define ALLOC_STATS<br />
 134       */<br />
 135       <br />
 136       typedef struct ap_pool_t {<br />
 137       <indent>
 138         union block_hdr *first;<br />
 139         union block_hdr *last;<br />
 140         struct cleanup *cleanups;<br />
 141         struct process_chain *subprocesses;<br />
 142         struct ap_pool_t *sub_pools;<br />
 143         struct ap_pool_t *sub_next;<br />
 144         struct ap_pool_t *sub_prev;<br />
 145         struct ap_pool_t *parent;<br />
 146         char *free_first_avail;<br />
 147       </indent>
 148       #ifdef ALLOC_USE_MALLOC<br />
 149       <indent>
 150         void *allocation_list;<br />
 151       </indent>
 152       #endif<br />
 153       #ifdef POOL_DEBUG<br />
 154       <indent>
 155         struct ap_pool_t *joined;<br />
 156       </indent>
 157       #endif<br />
 158       <indent>
 159         int (*apr_abort)(int retcode);<br />
 160         struct datastruct *prog_data;<br />
 161       </indent>
 162       } ap_pool_t;
 163     </example>
 164
 165     <p>To enable allocation debugging simply move the <code>#define
 166     ALLOC_DEBUG</code> above the start of the comments block and rebuild
 167     the server.</p>
 168
 169     <note><title>Note</title>
 170     <p>In order to use the various options the server <strong>must</strong>
 171     be rebuilt after editing the header file.</p>
 172     </note>
 173 </section>
 174 </manualpage>
 175