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