Commit 5b317e56 authored by Richard Bowen's avatar Richard Bowen
Browse files

Ran tidy to convert to xhtml 


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91113 13f79535-47bb-0310-9956-ffa450edef68
parent c91df556

docs/manual/developer/API.html

+1010 −926

File changed.

Preview size limit exceeded, changes collapsed.

docs/manual/developer/debugging.html

+224 −145
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<HTML>

<HEAD>

<TITLE>Debugging Memory Allocation in APR</TITLE>

</HEAD>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">



<html xmlns="http://www.w3.org/1999/xhtml">

  <head>

    <meta name="generator" content="HTML Tidy, see www.w3.org" />



    <title>Debugging Memory Allocation in APR</title>

  </head>

  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->

<BODY

 BGCOLOR="#FFFFFF"

 TEXT="#000000"

 LINK="#0000FF"

 VLINK="#000080"

 ALINK="#FF0000"

>



  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"

  vlink="#000080" alink="#FF0000">

    <!--#include virtual="header.html" -->



<H1 ALIGN="CENTER">Debugging Memory Allocation in APR<br></H1>

    <h1 align="CENTER">Debugging Memory Allocation in APR<br />

    </h1>



<p>The allocation mechanism's within APR have a number of debugging

modes that can be used to assist in finding memory problems.  This document describes

the modes available and gives instructions on activating them.</p>

    <p>The allocation mechanism's within APR have a number of

    debugging modes that can be used to assist in finding memory

    problems. This document describes the modes available and gives

    instructions on activating them.</p>



    <ul>

      <li><a href="#options">Available debugging options</a></li>



      <li><a href="#combo">Allowable combinations</a></li>



      <li><a href="#howto">How to activate debugging</a></li>

    </ul>

    <hr />



<hr>

<a name="options">

    <h2>Allocation Debugging</h2>



    <h3>ALLOC_DEBUG</h3>

<p><em>Debugging support: Define this to enable code which helps detect re-use of freed memory and other such nonsense.</em></p>



<p>The theory is simple.  The FILL_BYTE (0xa5) is written over all malloc'd memory as we receive it, and is written over everything that we free up during a clear_pool.  We check that blocks on the free list always have the FILL_BYTE in them, and we check during palloc() that the bytes still have FILL_BYTE in them.  If you ever see garbage URLs or whatnot containing lots of 0xa5s then you know something used data that's been freed or uninitialized.</p>

    <p><em>Debugging support: Define this to enable code which

    helps detect re-use of freed memory and other such

    nonsense.</em></p>



    <p>The theory is simple. The FILL_BYTE (0xa5) is written over

    all malloc'd memory as we receive it, and is written over

    everything that we free up during a clear_pool. We check that

    blocks on the free list always have the FILL_BYTE in them, and

    we check during palloc() that the bytes still have FILL_BYTE in

    them. If you ever see garbage URLs or whatnot containing lots

    of 0xa5s then you know something used data that's been freed or

    uninitialized.</p>



    <h2>Malloc Support</h2>



    <h3>ALLOC_USE_MALLOC</h3>

<p><em>If defined all allocations will be done with malloc and free()d appropriately at the end.

</em></p>



<p>This is intended to be used with something like Electric Fence or Purify to help detect memory problems.  Note that if you're using efence then you should also add in ALLOC_DEBUG.  But don't add in ALLOC_DEBUG if you're using Purify because ALLOC_DEBUG would hide all the uninitialized read errors that Purify can diagnose.</p>

    <p><em>If defined all allocations will be done with malloc and

    free()d appropriately at the end.</em></p>



    <p>This is intended to be used with something like Electric

    Fence or Purify to help detect memory problems. Note that if

    you're using efence then you should also add in ALLOC_DEBUG.

    But don't add in ALLOC_DEBUG if you're using Purify because

    ALLOC_DEBUG would hide all the uninitialized read errors that

    Purify can diagnose.</p>



    <h2>Pool Debugging</h2>



    <h3>POOL_DEBUG</h3>

<p><em>This is intended to detect cases where the wrong pool is used when assigning data to an object in another pool.</em></p>



<p>In particular, it causes the table_{set,add,merge}n routines to check that their arguments are safe for the apr_table_t they're being placed in.  It currently only works with the unix multiprocess model, but could be extended to others.</p>

    <p><em>This is intended to detect cases where the wrong pool is

    used when assigning data to an object in another pool.</em></p>



    <p>In particular, it causes the table_{set,add,merge}n routines

    to check that their arguments are safe for the apr_table_t

    they're being placed in. It currently only works with the unix

    multiprocess model, but could be extended to others.</p>



    <h2>Table Debugging</h2>



    <h3>MAKE_TABLE_PROFILE</h3>

<p><em>Provide diagnostic information about make_table() calls which are possibly too small.</em></p>



<p>This requires a recent gcc which supports __builtin_return_address().  The error_log output will be a message such as: </p>

<pre>table_push: apr_table_t created by 0x804d874 hit limit of 10</pre>

<p>Use "<em><strong>l *0x804d874</strong></em>" to find the source that corresponds to.  It

 indicates that a apr_table_t allocated by a call at that address has possibly too small an initial apr_table_t size guess.</p>

    <p><em>Provide diagnostic information about make_table() calls

    which are possibly too small.</em></p>



    <p>This requires a recent gcc which supports

    __builtin_return_address(). The error_log output will be a

    message such as:</p>

<pre>

table_push: apr_table_t created by 0x804d874 hit limit of 10

</pre>



    <p>Use "<em><strong>l *0x804d874</strong></em>" to find the

    source that corresponds to. It indicates that a apr_table_t

    allocated by a call at that address has possibly too small an

    initial apr_table_t size guess.</p>



    <h2>Allocation Statistics</h2>



    <h3>ALLOC_STATS</h3>

<p><em>Provide some statistics on the cost of allocations.</em></p>



<p>This requires a bit of an understanding of how alloc.c works.</p>

    <p><em>Provide some statistics on the cost of

    allocations.</em></p>



<hr>

    <p>This requires a bit of an understanding of how alloc.c

    works.</p>

    <hr />



<a name="combo">

    <h2>Allowable Combinations</h2>



<p>Not all the options outlined above can be activated at the same time.  the following table gives more information.</p>

    <p>Not all the options outlined above can be activated at the

    same time. the following table gives more information.</p>



<p align="center">

    <table width="80%">

      <tr>

        <th width="25%">Option 1</th>

<th width="15%">ALLOC<br>DEBUG</th>

<th width="15%">ALLOC<br>USE<br>MALLOC</th>

<th width="15%">POOL<br>DEBUG</th>

<th width="15%">MAKE<br>TABLE<br>PROFILE</th>

<th width="15%">ALLOC<br>STATS</th>



        <th width="15%">ALLOC<br />

         DEBUG</th>



        <th width="15%">ALLOC<br />

         USE<br />

         MALLOC</th>



        <th width="15%">POOL<br />

         DEBUG</th>



        <th width="15%">MAKE<br />

         TABLE<br />

         PROFILE</th>



        <th width="15%">ALLOC<br />

         STATS</th>

      </tr>



      <tr>

        <td>ALLOC_DEBUG</td>



        <td bgcolor="#ff0000">&nbsp;</td>



        <td align="center">No</td>



        <td align="center">Yes</td>



        <td align="center">Yes</td>



        <td align="center">Yes</td>

      </tr>



      <tr>

<td>ALLOC_USE<br>MALLOC</td>

        <td>ALLOC_USE<br />

         MALLOC</td>



        <td align="center">No</td>



        <td bgcolor="#ff0000">&nbsp;</td>



        <td align="center">No</td>



        <td align="center">No</td>



        <td align="center">No</td>

      </tr>



      <tr>

        <td>POOL_DEBUG</td>



        <td align="center">Yes</td>



        <td align="center">No</td>



        <td bgcolor="#ff0000">&nbsp;</td>



        <td align="center">Yes</td>



        <td align="center">Yes</td>

      </tr>



      <tr>

<td>MAKE_TABLE<br>PROFILE</td>

        <td>MAKE_TABLE<br />

         PROFILE</td>



        <td align="center">Yes</td>



        <td align="center">No</td>



        <td align="center">Yes</td>



        <td bgcolor="#ff0000">&nbsp;</td>



        <td align="center">Yes</td>

      </tr>



      <tr>

        <td>ALLOC_STATS</td>



        <td align="center">Yes</td>



        <td align="center">No</td>



        <td align="center">Yes</td>



        <td align="center">Yes</td>



        <td bgcolor="#ff0000">&nbsp;</td>

      </tr>



    </table>



<p>Additionally the debugging options are not suitable for multi-threaded versions of the server.  When trying to debug with these options the server should be started in single process mode.</p>



<hr>

    <p>Additionally the debugging options are not suitable for

    multi-threaded versions of the server. When trying to debug

    with these options the server should be started in single

    process mode.</p>

    <hr />



<a name="howto">

    <h2>Activating Debugging Options</h2>

<p>The various options for debugging memory are now enabled in the apr_general.h header file in APR.  The various options are enabled by uncommenting the define for the option you wish to use.  The section of the code currently looks like this <em>(contained in srclib/apr/include/apr_pools.h)</em></p>



    <p>The various options for debugging memory are now enabled in

    the apr_general.h header file in APR. The various options are

    enabled by uncommenting the define for the option you wish to

    use. The section of the code currently looks like this

    <em>(contained in srclib/apr/include/apr_pools.h)</em></p>

<pre>

/*

#define ALLOC_DEBUG
@@ -162,17 +246,12 @@ typedef struct ap_pool_t { 
}ap_pool_t;

</pre>



<p>To enable allocation debugging simply move the #define ALLOC_DEBUG above the start of the comments block and rebuild the server.</p>



<strong>NB. In order to use the various options the server MUST be rebuilt after editing the header file.

</strong>



    <p>To enable allocation debugging simply move the #define

    ALLOC_DEBUG above the start of the comments block and rebuild

    the server.</p>

    <strong>NB. In order to use the various options the server MUST

    be rebuilt after editing the header file.</strong> 

    <!--#include virtual="footer.html" -->



  </body>

</html>

docs/manual/developer/documenting.html

+39 −30
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">



<html xmlns="http://www.w3.org/1999/xhtml">

  <head>

    <meta name="generator" content="HTML Tidy, see www.w3.org" />



    <title>Documenting Apache 2.0</title>

  </head>

  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->

<BODY

 BGCOLOR="#FFFFFF"

 TEXT="#000000"

 LINK="#0000FF"

 VLINK="#000080"

 ALINK="#FF0000"

>



  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"

  vlink="#000080" alink="#FF0000">

    <!--#include virtual="header.html" -->



    <h1 align="center">Documentating Apache 2.0</h1>



<p>Apache 2.0 uses DoxyGen to document the API's and global variables in the

   the code.  This will explain the basics of how to document using DoxyGen.

    <p>Apache 2.0 uses DoxyGen to document the API's and global

    variables in the the code. This will explain the basics of how

    to document using DoxyGen.</p>



    <p>To start a documentation block, use /**<br />

     To end a documentation block, use */</p>



<p>In the middle of the block, there are multiple tags we can use:</p>

    <p>In the middle of the block, there are multiple tags we can

    use:</p>

<pre>

    Description of this functions purpose

    @param parameter_name description

</p>



<p>The deffunc is not always necessary.  DoxyGen does not have a full parser 



<br />

The deffunc is not always necessary.  DoxyGen does not have a full parser 

   in it, so any prototype that use a macro in the return type declaration 

   is too complex for scandoc.  Those functions require a deffunc.</p>

   is too complex for scandoc.  Those functions require a deffunc.



<p>An example (using &amp;gt; rather than &gt;):</p>

<br />

An example (using &amp;gt; rather than &gt;):

</pre>

<pre>

/**

 * return the final element of the pathname
@@ -48,17 +52,22 @@ 
 * @deffunc const char * ap_filename_of_pathname(const char *pathname)

 */

</pre>



<p>At the top of the header file, always include:</p>

<pre>

<br />

At the top of the header file, always include:

</pre>

<pre>

/**

 * @package Name of library header

 */

</pre>



<p>ScanDoc uses a new html file for each package.  The html files are named

   {Name_of_library_header}.html, so try to be concise with your names.</p>

<pre>

<br />

ScanDoc uses a new html file for each package.  The html files are named

   {Name_of_library_header}.html, so try to be concise with your names.

 

<!--#include virtual="footer.html" -->

</pre>

  </body>

</html>

docs/manual/developer/footer.html

+17 −6
Original line number Diff line number Diff line 
<HR>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">



<H3 ALIGN="CENTER">

 Apache HTTP Server Version 2.0 

</H3>

<html xmlns="http://www.w3.org/1999/xhtml">

  <head>

    <meta name="generator" content="HTML Tidy, see www.w3.org" />



    <title></title>

  </head>



  <body>

    <hr />



    <h3 align="CENTER">Apache HTTP Server Version 2.0</h3>

    <a href="./"><img src="../images/index.gif" alt="Index" /></a>

    <a href="../"><img src="../images/home.gif" alt="Home" /></a>

  </body>

</html>

<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A>

<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A>

docs/manual/developer/header.html

+19 −6
Original line number Diff line number Diff line 
<DIV ALIGN="CENTER">

 <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]">

 <H3>

  Apache HTTP Server Version 2.0 

 </H3>

</DIV>
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">



<html xmlns="http://www.w3.org/1999/xhtml">

  <head>

    <meta name="generator" content="HTML Tidy, see www.w3.org" />



    <title></title>

  </head>



  <body>

    <div align="CENTER">

      <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> 



      <h3>Apache HTTP Server Version 2.0</h3>

    </div>

  </body>

</html>