← Back to branch summary

~ubuntu-branches/ubuntu/feisty/apache2/feisty

« back to all changes in this revision

Viewing changes to docs/manual/developer/debugging.html.en

  • Committer: Bazaar Package Importer
  • Author(s): Andreas Barth
  • Date: 2006-12-09 21:05:45 UTC
  • mfrom: (0.6.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20061209210545-h70s0xaqc2v8vqr2
Tags: 2.2.3-3.2
http://bugs.debian.org/396265
* Non-maintainer upload.
* 043_ajp_connection_reuse: Patch from upstream Bugzilla, fixing a critical
  issue with regard to connection reuse in mod_proxy_ajp.
  Closes: #396265

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/manual/developer/debugging.html.en
 
1
<?xml version="1.0" encoding="ISO-8859-1"?>
 
2
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 
3
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
 
4
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
5
              This file is generated from xml source: DO NOT EDIT
 
6
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
7
      -->
 
8
<title>Debugging Memory Allocation in APR - Apache HTTP Server</title>
 
9
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
 
10
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
 
11
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
 
12
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
 
13
<body id="manual-page"><div id="page-header">
 
14
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
 
15
<p class="apache">Apache HTTP Server Version 2.2</p>
 
16
<img alt="" src="../images/feather.gif" /></div>
 
17
<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
 
18
<div id="path">
 
19
<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.2</a> &gt; <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Debugging Memory Allocation in APR</h1>
 
20
<div class="toplang">
 
21
<p><span>Available Languages: </span><a href="../en/developer/debugging.html" title="English">&nbsp;en&nbsp;</a></p>
 
22
</div>
 
23
 
 
24
    <p>The allocation mechanisms within APR have a number of debugging modes
 
25
    that can be used to assist in finding memory problems. This document
 
26
    describes the modes available and gives instructions on activating
 
27
    them.</p>
 
28
</div>
 
29
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#options">Available debugging options</a></li>
 
30
<li><img alt="" src="../images/down.gif" /> <a href="#combo">Allowable Combinations</a></li>
 
31
<li><img alt="" src="../images/down.gif" /> <a href="#howto">Activating Debugging Options</a></li>
 
32
</ul></div>
 
33
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 
34
<div class="section">
 
35
<h2><a name="options" id="options">Available debugging options</a></h2>
 
36
    <h3><a name="alloc_debug" id="alloc_debug">Allocation Debugging - ALLOC_DEBUG</a></h3>
 
37
    
 
38
 
 
39
      <div class="note">Debugging support: Define this to enable code which
 
40
      helps detect re-use of <code>free()</code>d memory and other such
 
41
      nonsense.</div>
 
42
 
 
43
      <p>The theory is simple. The <code>FILL_BYTE</code> (<code>0xa5</code>)
 
44
      is written over all <code>malloc</code>'d memory as we receive it, and
 
45
      is written over everything that we free up during a
 
46
      <code>clear_pool</code>. We check that blocks on the free list always
 
47
      have the <code>FILL_BYTE</code> in them, and we check during
 
48
      <code>palloc()</code> that the bytes still have <code>FILL_BYTE</code>
 
49
      in them. If you ever see garbage URLs or whatnot containing lots
 
50
      of <code>0xa5</code>s then you know something used data that's been
 
51
      freed or uninitialized.</p>
 
52
    
 
53
 
 
54
    <h3><a name="alloc_use_malloc" id="alloc_use_malloc">Malloc Support - ALLOC_USE_MALLOC</a></h3>
 
55
    
 
56
 
 
57
      <div class="note">If defined all allocations will be done with
 
58
      <code>malloc()</code> and <code>free()</code>d appropriately at the
 
59
      end.</div>
 
60
 
 
61
      <p>This is intended to be used with something like Electric
 
62
      Fence or Purify to help detect memory problems. Note that if
 
63
      you're using efence then you should also add in <code>ALLOC_DEBUG</code>.
 
64
      But don't add in <code>ALLOC_DEBUG</code> if you're using Purify because
 
65
      <code>ALLOC_DEBUG</code> would hide all the uninitialized read errors
 
66
      that Purify can diagnose.</p>
 
67
    
 
68
 
 
69
    <h3><a name="pool_debug" id="pool_debug">Pool Debugging - POOL_DEBUG</a></h3>
 
70
      <div class="note">This is intended to detect cases where the wrong pool is
 
71
      used when assigning data to an object in another pool.</div>
 
72
 
 
73
      <p>In particular, it causes the <code>table_{set,add,merge}n</code>
 
74
      routines to check that their arguments are safe for the
 
75
      <code>apr_table_t</code> they're being placed in. It currently only works
 
76
      with the unix multiprocess model, but could be extended to others.</p>
 
77
    
 
78
 
 
79
    <h3><a name="make_table_profile" id="make_table_profile">Table Debugging - MAKE_TABLE_PROFILE</a></h3>
 
80
    
 
81
 
 
82
      <div class="note">Provide diagnostic information about make_table() calls
 
83
      which are possibly too small.</div>
 
84
 
 
85
      <p>This requires a recent gcc which supports
 
86
      <code>__builtin_return_address()</code>. The error_log output will be a
 
87
      message such as:</p>
 
88
      <div class="example"><p><code>
 
89
        table_push: apr_table_t created by 0x804d874 hit limit of 10
 
90
      </code></p></div>
 
91
 
 
92
      <p>Use <code>l *0x804d874</code> to find the
 
93
      source that corresponds to. It indicates that a <code>apr_table_t</code>
 
94
      allocated by a call at that address has possibly too small an
 
95
      initial <code>apr_table_t</code> size guess.</p>
 
96
    
 
97
 
 
98
    <h3><a name="alloc_stats" id="alloc_stats">Allocation Statistics -  ALLOC_STATS</a></h3>
 
99
    
 
100
 
 
101
      <div class="note">Provide some statistics on the cost of allocations.</div>
 
102
 
 
103
      <p>This requires a bit of an understanding of how <code>alloc.c</code>
 
104
      works.</p>
 
105
    
 
106
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 
107
<div class="section">
 
108
<h2><a name="combo" id="combo">Allowable Combinations</a></h2>
 
109
 
 
110
    <p>Not all the options outlined above can be activated at the
 
111
    same time. the following table gives more information.</p>
 
112
 
 
113
    <table class="bordered"><tr class="header"><th />
 
114
        <th>ALLOC DEBUG</th>
 
115
        <th>ALLOC USE MALLOC</th>
 
116
        <th>POOL DEBUG</th>
 
117
        <th>MAKE TABLE PROFILE</th>
 
118
        <th>ALLOC STATS</th></tr>
 
119
<tr><th>ALLOC DEBUG</th>
 
120
        <td>-</td><td>No</td><td>Yes</td><td>Yes</td><td>Yes</td></tr>
 
121
<tr class="odd"><th>ALLOC USE MALLOC</th>
 
122
        <td>No</td><td>-</td><td>No</td><td>No</td><td>No</td></tr>
 
123
<tr><th>POOL DEBUG</th>
 
124
        <td>Yes</td><td>No</td><td>-</td><td>Yes</td><td>Yes</td></tr>
 
125
<tr class="odd"><th>MAKE TABLE PROFILE</th>
 
126
        <td>Yes</td><td>No</td><td>Yes</td><td>-</td><td>Yes</td></tr>
 
127
<tr><th>ALLOC STATS</th>
 
128
        <td>Yes</td><td>No</td><td>Yes</td><td>Yes</td><td>-</td></tr>
 
129
</table>
 
130
 
 
131
    <p>Additionally the debugging options are not suitable for
 
132
    multi-threaded versions of the server. When trying to debug
 
133
    with these options the server should be started in single
 
134
    process mode.</p>
 
135
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 
136
<div class="section">
 
137
<h2><a name="howto" id="howto">Activating Debugging Options</a></h2>
 
138
 
 
139
    <p>The various options for debugging memory are now enabled in
 
140
    the <code>apr_general.h</code> header file in APR. The various options are
 
141
    enabled by uncommenting the define for the option you wish to
 
142
    use. The section of the code currently looks like this
 
143
    (<em>contained in srclib/apr/include/apr_pools.h</em>)</p>
 
144
 
 
145
    <div class="example"><p><code>
 
146
      /*<br />
 
147
      #define ALLOC_DEBUG<br />
 
148
      #define POOL_DEBUG<br />
 
149
      #define ALLOC_USE_MALLOC<br />
 
150
      #define MAKE_TABLE_PROFILE<br />
 
151
      #define ALLOC_STATS<br />
 
152
      */<br />
 
153
      <br />
 
154
      typedef struct ap_pool_t {<br />
 
155
      <span class="indent">
 
156
        union block_hdr *first;<br />
 
157
        union block_hdr *last;<br />
 
158
        struct cleanup *cleanups;<br />
 
159
        struct process_chain *subprocesses;<br />
 
160
        struct ap_pool_t *sub_pools;<br />
 
161
        struct ap_pool_t *sub_next;<br />
 
162
        struct ap_pool_t *sub_prev;<br />
 
163
        struct ap_pool_t *parent;<br />
 
164
        char *free_first_avail;<br />
 
165
      </span>
 
166
      #ifdef ALLOC_USE_MALLOC<br />
 
167
      <span class="indent">
 
168
        void *allocation_list;<br />
 
169
      </span>
 
170
      #endif<br />
 
171
      #ifdef POOL_DEBUG<br />
 
172
      <span class="indent">
 
173
        struct ap_pool_t *joined;<br />
 
174
      </span>
 
175
      #endif<br />
 
176
      <span class="indent">
 
177
        int (*apr_abort)(int retcode);<br />
 
178
        struct datastruct *prog_data;<br />
 
179
      </span>
 
180
      } ap_pool_t;
 
181
    </code></p></div>
 
182
 
 
183
    <p>To enable allocation debugging simply move the <code>#define
 
184
    ALLOC_DEBUG</code> above the start of the comments block and rebuild
 
185
    the server.</p>
 
186
 
 
187
    <div class="note"><h3>Note</h3>
 
188
    <p>In order to use the various options the server <strong>must</strong>
 
189
    be rebuilt after editing the header file.</p>
 
190
    </div>
 
191
</div></div>
 
192
<div class="bottomlang">
 
193
<p><span>Available Languages: </span><a href="../en/developer/debugging.html" title="English">&nbsp;en&nbsp;</a></p>
 
194
</div><div id="footer">
 
195
<p class="apache">Copyright 2006 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 
196
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 
197
</body></html>
 
 
b'\\ No newline at end of file'