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