You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@apr.apache.org by je...@apache.org on 2005/02/08 00:12:08 UTC
svn commit: r151768 [28/47] - in apr/site/trunk/docs/docs/apr: ./ iconv/
util/
Modified: apr/site/trunk/docs/docs/apr/apr__pools_8h-source.html
URL: http://svn.apache.org/viewcvs/apr/site/trunk/docs/docs/apr/apr__pools_8h-source.html?view=diff&r1=151767&r2=151768
==============================================================================
--- apr/site/trunk/docs/docs/apr/apr__pools_8h-source.html (original)
+++ apr/site/trunk/docs/docs/apr/apr__pools_8h-source.html Mon Feb 7 15:10:17 2005
@@ -3,659 +3,660 @@
<title>Apache Portable Runtime: apr_pools.h Source File</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
-<!-- Generated by Doxygen 1.3.8 -->
+<!-- Generated by Doxygen 1.3.7 -->
<div class="qindex"><a class="qindex" href="index.html">Main Page</a> | <a class="qindex" href="modules.html">Modules</a> | <a class="qindex" href="annotated.html">Data Structures</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="functions.html">Data Fields</a> | <a class="qindex" href="globals.html">Globals</a> | <a class="qindex" href="pages.html">Related Pages</a></div>
-<h1>apr_pools.h</h1><a href="apr__pools_8h.html">Go to the documentation of this file.</a><pre class="fragment"><div>00001 <span class="comment">/* Copyright 2000-2004 The Apache Software Foundation</span>
-00002 <span class="comment"> *</span>
-00003 <span class="comment"> * Licensed under the Apache License, Version 2.0 (the "License");</span>
-00004 <span class="comment"> * you may not use this file except in compliance with the License.</span>
-00005 <span class="comment"> * You may obtain a copy of the License at</span>
-00006 <span class="comment"> *</span>
-00007 <span class="comment"> * http://www.apache.org/licenses/LICENSE-2.0</span>
-00008 <span class="comment"> *</span>
-00009 <span class="comment"> * Unless required by applicable law or agreed to in writing, software</span>
-00010 <span class="comment"> * distributed under the License is distributed on an "AS IS" BASIS,</span>
-00011 <span class="comment"> * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span>
-00012 <span class="comment"> * See the License for the specific language governing permissions and</span>
-00013 <span class="comment"> * limitations under the License.</span>
-00014 <span class="comment"> */</span>
-00015
-00016 <span class="preprocessor">#ifndef APR_POOLS_H</span>
-00017 <span class="preprocessor"></span><span class="preprocessor">#define APR_POOLS_H</span>
-00018 <span class="preprocessor"></span><span class="comment"></span>
-00019 <span class="comment">/**</span>
-00020 <span class="comment"> * @file apr_pools.h</span>
-00021 <span class="comment"> * @brief APR memory allocation</span>
-00022 <span class="comment"> *</span>
-00023 <span class="comment"> * Resource allocation routines...</span>
-00024 <span class="comment"> *</span>
-00025 <span class="comment"> * designed so that we don't have to keep track of EVERYTHING so that</span>
-00026 <span class="comment"> * it can be explicitly freed later (a fundamentally unsound strategy ---</span>
-00027 <span class="comment"> * particularly in the presence of die()).</span>
-00028 <span class="comment"> *</span>
-00029 <span class="comment"> * Instead, we maintain pools, and allocate items (both memory and I/O</span>
-00030 <span class="comment"> * handlers) from the pools --- currently there are two, one for per</span>
-00031 <span class="comment"> * transaction info, and one for config info. When a transaction is over,</span>
-00032 <span class="comment"> * we can delete everything in the per-transaction apr_pool_t without fear,</span>
-00033 <span class="comment"> * and without thinking too hard about it either.</span>
-00034 <span class="comment"> */</span>
-00035
-00036 <span class="preprocessor">#include "apr.h"</span>
-00037 <span class="preprocessor">#include "<a class="code" href="apr__errno_8h.html">apr_errno.h</a>"</span>
-00038 <span class="preprocessor">#include "<a class="code" href="apr__general_8h.html">apr_general.h</a>"</span> <span class="comment">/* for APR_STRINGIFY */</span>
-<a name="l00039"></a><a class="code" href="apr__pools_8h.html#a0">00039</a> <span class="preprocessor">#define APR_WANT_MEMFUNC </span><span class="comment">/**< for no good reason? */</span>
-00040 <span class="preprocessor">#include "<a class="code" href="apr__want_8h.html">apr_want.h</a>"</span>
-00041
-00042 <span class="preprocessor">#ifdef __cplusplus</span>
-00043 <span class="preprocessor"></span><span class="keyword">extern</span> <span class="stringliteral">"C"</span> {
-00044 <span class="preprocessor">#endif</span>
-00045 <span class="preprocessor"></span><span class="comment"></span>
-00046 <span class="comment">/**</span>
-00047 <span class="comment"> * @defgroup apr_pools Memory Pool Functions</span>
-00048 <span class="comment"> * @ingroup APR </span>
-00049 <span class="comment"> * @{</span>
-00050 <span class="comment"> */</span>
-00051 <span class="comment"></span>
-00052 <span class="comment">/** The fundamental pool type */</span>
-<a name="l00053"></a><a class="code" href="group__apr__pools.html#ga0">00053</a> <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="group__apr__pools.html#ga0">apr_pool_t</a> <a class="code" href="group__apr__pools.html#ga0">apr_pool_t</a>;
-00054
-00055 <span class="comment"></span>
-00056 <span class="comment">/**</span>
-00057 <span class="comment"> * Declaration helper macro to construct apr_foo_pool_get()s.</span>
-00058 <span class="comment"> *</span>
-00059 <span class="comment"> * This standardized macro is used by opaque (APR) data types to return</span>
-00060 <span class="comment"> * the apr_pool_t that is associated with the data type.</span>
-00061 <span class="comment"> *</span>
-00062 <span class="comment"> * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the</span>
-00063 <span class="comment"> * accessor function. A typical usage and result would be:</span>
-00064 <span class="comment"> * <pre></span>
-00065 <span class="comment"> * APR_POOL_DECLARE_ACCESSOR(file);</span>
-00066 <span class="comment"> * becomes:</span>
-00067 <span class="comment"> * APR_DECLARE(apr_pool_t *) apr_file_pool_get(apr_file_t *ob);</span>
-00068 <span class="comment"> * </pre></span>
-00069 <span class="comment"> * @remark Doxygen unwraps this macro (via doxygen.conf) to provide </span>
-00070 <span class="comment"> * actual help for each specific occurance of apr_foo_pool_get.</span>
-00071 <span class="comment"> * @remark the linkage is specified for APR. It would be possible to expand</span>
-00072 <span class="comment"> * the macros to support other linkages.</span>
-00073 <span class="comment"> */</span>
-<a name="l00074"></a><a class="code" href="group__apr__pools.html#ga30">00074</a> <span class="preprocessor">#define APR_POOL_DECLARE_ACCESSOR(type) \</span>
-00075 <span class="preprocessor"> APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \</span>
-00076 <span class="preprocessor"> (const apr_##type##_t *the##type)</span>
-00077 <span class="preprocessor"></span><span class="comment"></span>
-00078 <span class="comment">/** </span>
-00079 <span class="comment"> * Implementation helper macro to provide apr_foo_pool_get()s.</span>
-00080 <span class="comment"> *</span>
-00081 <span class="comment"> * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to</span>
-00082 <span class="comment"> * actually define the function. It assumes the field is named "pool".</span>
-00083 <span class="comment"> */</span>
-<a name="l00084"></a><a class="code" href="group__apr__pools.html#ga31">00084</a> <span class="preprocessor">#define APR_POOL_IMPLEMENT_ACCESSOR(type) \</span>
-00085 <span class="preprocessor"> APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \</span>
-00086 <span class="preprocessor"> (const apr_##type##_t *the##type) \</span>
-00087 <span class="preprocessor"> { return the##type->pool; }</span>
-00088 <span class="preprocessor"></span>
-00089 <span class="comment"></span>
-00090 <span class="comment">/**</span>
-00091 <span class="comment"> * Pool debug levels</span>
-00092 <span class="comment"> *</span>
-00093 <span class="comment"> * <pre></span>
-00094 <span class="comment"> * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |</span>
-00095 <span class="comment"> * ---------------------------------</span>
-00096 <span class="comment"> * | | | | | | | | x | General debug code enabled (useful in</span>
-00097 <span class="comment"> * combination with --with-efence).</span>
-00098 <span class="comment"> *</span>
-00099 <span class="comment"> * | | | | | | | x | | Verbose output on stderr (report</span>
-00100 <span class="comment"> * CREATE, CLEAR, DESTROY).</span>
-00101 <span class="comment"> *</span>
-00102 <span class="comment"> * | | | | x | | | | | Verbose output on stderr (report</span>
-00103 <span class="comment"> * PALLOC, PCALLOC).</span>
-00104 <span class="comment"> *</span>
-00105 <span class="comment"> * | | | | | | x | | | Lifetime checking. On each use of a</span>
-00106 <span class="comment"> * pool, check its lifetime. If the pool</span>
-00107 <span class="comment"> * is out of scope, abort().</span>
-00108 <span class="comment"> * In combination with the verbose flag</span>
-00109 <span class="comment"> * above, it will output LIFE in such an</span>
-00110 <span class="comment"> * event prior to aborting.</span>
-00111 <span class="comment"> *</span>
-00112 <span class="comment"> * | | | | | x | | | | Pool owner checking. On each use of a</span>
-00113 <span class="comment"> * pool, check if the current thread is the</span>
-00114 <span class="comment"> * pools owner. If not, abort(). In</span>
-00115 <span class="comment"> * combination with the verbose flag above,</span>
-00116 <span class="comment"> * it will output OWNER in such an event</span>
-00117 <span class="comment"> * prior to aborting. Use the debug</span>
-00118 <span class="comment"> * function apr_pool_owner_set() to switch</span>
-00119 <span class="comment"> * a pools ownership.</span>
-00120 <span class="comment"> *</span>
-00121 <span class="comment"> * When no debug level was specified, assume general debug mode.</span>
-00122 <span class="comment"> * If level 0 was specified, debugging is switched off</span>
-00123 <span class="comment"> * </pre></span>
-00124 <span class="comment"> */</span>
-00125 <span class="preprocessor">#if defined(APR_POOL_DEBUG)</span>
-00126 <span class="preprocessor"></span><span class="comment">/* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */</span>
-00127 <span class="preprocessor">#if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1)</span>
-00128 <span class="preprocessor"></span><span class="preprocessor">#undef APR_POOL_DEBUG</span>
-00129 <span class="preprocessor"></span><span class="preprocessor">#define APR_POOL_DEBUG 1</span>
-00130 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
-00131 <span class="preprocessor"></span><span class="preprocessor">#else</span>
-<a name="l00132"></a><a class="code" href="group__apr__pools.html#ga32">00132</a> <span class="preprocessor"></span><span class="preprocessor">#define APR_POOL_DEBUG 0</span>
-00133 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
-00134 <span class="preprocessor"></span><span class="comment"></span>
-00135 <span class="comment">/** the place in the code where the particular function was called */</span>
-<a name="l00136"></a><a class="code" href="group__apr__pools.html#ga33">00136</a> <span class="preprocessor">#define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__)</span>
-00137 <span class="preprocessor"></span>
-00138
-00139 <span class="comment"></span>
-00140 <span class="comment">/** A function that is called when allocation fails. */</span>
-<a name="l00141"></a><a class="code" href="group__apr__pools.html#ga1">00141</a> <span class="keyword">typedef</span> int (*<a class="code" href="group__apr__pools.html#ga1">apr_abortfunc_t</a>)(<span class="keywordtype">int</span> retcode);
-00142
-00143 <span class="comment">/*</span>
-00144 <span class="comment"> * APR memory structure manipulators (pools, tables, and arrays).</span>
-00145 <span class="comment"> */</span>
-00146
-00147 <span class="comment">/*</span>
-00148 <span class="comment"> * Initialization</span>
-00149 <span class="comment"> */</span>
-00150 <span class="comment"></span>
-00151 <span class="comment">/**</span>
-00152 <span class="comment"> * Setup all of the internal structures required to use pools</span>
-00153 <span class="comment"> * @remark Programs do NOT need to call this directly. APR will call this</span>
-00154 <span class="comment"> * automatically from apr_initialize.</span>
-00155 <span class="comment"> * @internal</span>
-00156 <span class="comment"> */</span>
-00157 APR_DECLARE(<a class="code" href="group__apr__errno.html#ga0">apr_status_t</a>) apr_pool_initialize(<span class="keywordtype">void</span>);
-00158 <span class="comment"></span>
-00159 <span class="comment">/**</span>
-00160 <span class="comment"> * Tear down all of the internal structures required to use pools</span>
-00161 <span class="comment"> * @remark Programs do NOT need to call this directly. APR will call this</span>
-00162 <span class="comment"> * automatically from apr_terminate.</span>
-00163 <span class="comment"> * @internal</span>
-00164 <span class="comment"> */</span>
-00165 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_terminate(<span class="keywordtype">void</span>);
-00166
+<h1>apr_pools.h</h1><a href="apr__pools_8h.html">Go to the documentation of this file.</a><pre class="fragment"><div>00001 <span class="comment">/* Copyright 2000-2005 The Apache Software Foundation or its licensors, as</span>
+00002 <span class="comment"> * applicable.</span>
+00003 <span class="comment"> *</span>
+00004 <span class="comment"> * Licensed under the Apache License, Version 2.0 (the "License");</span>
+00005 <span class="comment"> * you may not use this file except in compliance with the License.</span>
+00006 <span class="comment"> * You may obtain a copy of the License at</span>
+00007 <span class="comment"> *</span>
+00008 <span class="comment"> * http://www.apache.org/licenses/LICENSE-2.0</span>
+00009 <span class="comment"> *</span>
+00010 <span class="comment"> * Unless required by applicable law or agreed to in writing, software</span>
+00011 <span class="comment"> * distributed under the License is distributed on an "AS IS" BASIS,</span>
+00012 <span class="comment"> * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span>
+00013 <span class="comment"> * See the License for the specific language governing permissions and</span>
+00014 <span class="comment"> * limitations under the License.</span>
+00015 <span class="comment"> */</span>
+00016
+00017 <span class="preprocessor">#ifndef APR_POOLS_H</span>
+00018 <span class="preprocessor"></span><span class="preprocessor">#define APR_POOLS_H</span>
+00019 <span class="preprocessor"></span><span class="comment"></span>
+00020 <span class="comment">/**</span>
+00021 <span class="comment"> * @file apr_pools.h</span>
+00022 <span class="comment"> * @brief APR memory allocation</span>
+00023 <span class="comment"> *</span>
+00024 <span class="comment"> * Resource allocation routines...</span>
+00025 <span class="comment"> *</span>
+00026 <span class="comment"> * designed so that we don't have to keep track of EVERYTHING so that</span>
+00027 <span class="comment"> * it can be explicitly freed later (a fundamentally unsound strategy ---</span>
+00028 <span class="comment"> * particularly in the presence of die()).</span>
+00029 <span class="comment"> *</span>
+00030 <span class="comment"> * Instead, we maintain pools, and allocate items (both memory and I/O</span>
+00031 <span class="comment"> * handlers) from the pools --- currently there are two, one for per</span>
+00032 <span class="comment"> * transaction info, and one for config info. When a transaction is over,</span>
+00033 <span class="comment"> * we can delete everything in the per-transaction apr_pool_t without fear,</span>
+00034 <span class="comment"> * and without thinking too hard about it either.</span>
+00035 <span class="comment"> */</span>
+00036
+00037 <span class="preprocessor">#include "apr.h"</span>
+00038 <span class="preprocessor">#include "<a class="code" href="apr__errno_8h.html">apr_errno.h</a>"</span>
+00039 <span class="preprocessor">#include "<a class="code" href="apr__general_8h.html">apr_general.h</a>"</span> <span class="comment">/* for APR_STRINGIFY */</span>
+<a name="l00040"></a><a class="code" href="apr__pools_8h.html#a0">00040</a> <span class="preprocessor">#define APR_WANT_MEMFUNC </span><span class="comment">/**< for no good reason? */</span>
+00041 <span class="preprocessor">#include "<a class="code" href="apr__want_8h.html">apr_want.h</a>"</span>
+00042
+00043 <span class="preprocessor">#ifdef __cplusplus</span>
+00044 <span class="preprocessor"></span><span class="keyword">extern</span> <span class="stringliteral">"C"</span> {
+00045 <span class="preprocessor">#endif</span>
+00046 <span class="preprocessor"></span><span class="comment"></span>
+00047 <span class="comment">/**</span>
+00048 <span class="comment"> * @defgroup apr_pools Memory Pool Functions</span>
+00049 <span class="comment"> * @ingroup APR </span>
+00050 <span class="comment"> * @{</span>
+00051 <span class="comment"> */</span>
+00052 <span class="comment"></span>
+00053 <span class="comment">/** The fundamental pool type */</span>
+<a name="l00054"></a><a class="code" href="group__apr__pools.html#ga0">00054</a> <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="group__apr__pools.html#ga0">apr_pool_t</a> <a class="code" href="group__apr__pools.html#ga0">apr_pool_t</a>;
+00055
+00056 <span class="comment"></span>
+00057 <span class="comment">/**</span>
+00058 <span class="comment"> * Declaration helper macro to construct apr_foo_pool_get()s.</span>
+00059 <span class="comment"> *</span>
+00060 <span class="comment"> * This standardized macro is used by opaque (APR) data types to return</span>
+00061 <span class="comment"> * the apr_pool_t that is associated with the data type.</span>
+00062 <span class="comment"> *</span>
+00063 <span class="comment"> * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the</span>
+00064 <span class="comment"> * accessor function. A typical usage and result would be:</span>
+00065 <span class="comment"> * <pre></span>
+00066 <span class="comment"> * APR_POOL_DECLARE_ACCESSOR(file);</span>
+00067 <span class="comment"> * becomes:</span>
+00068 <span class="comment"> * APR_DECLARE(apr_pool_t *) apr_file_pool_get(apr_file_t *ob);</span>
+00069 <span class="comment"> * </pre></span>
+00070 <span class="comment"> * @remark Doxygen unwraps this macro (via doxygen.conf) to provide </span>
+00071 <span class="comment"> * actual help for each specific occurance of apr_foo_pool_get.</span>
+00072 <span class="comment"> * @remark the linkage is specified for APR. It would be possible to expand</span>
+00073 <span class="comment"> * the macros to support other linkages.</span>
+00074 <span class="comment"> */</span>
+<a name="l00075"></a><a class="code" href="group__apr__pools.html#ga30">00075</a> <span class="preprocessor">#define APR_POOL_DECLARE_ACCESSOR(type) \</span>
+00076 <span class="preprocessor"> APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \</span>
+00077 <span class="preprocessor"> (const apr_##type##_t *the##type)</span>
+00078 <span class="preprocessor"></span><span class="comment"></span>
+00079 <span class="comment">/** </span>
+00080 <span class="comment"> * Implementation helper macro to provide apr_foo_pool_get()s.</span>
+00081 <span class="comment"> *</span>
+00082 <span class="comment"> * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to</span>
+00083 <span class="comment"> * actually define the function. It assumes the field is named "pool".</span>
+00084 <span class="comment"> */</span>
+<a name="l00085"></a><a class="code" href="group__apr__pools.html#ga31">00085</a> <span class="preprocessor">#define APR_POOL_IMPLEMENT_ACCESSOR(type) \</span>
+00086 <span class="preprocessor"> APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \</span>
+00087 <span class="preprocessor"> (const apr_##type##_t *the##type) \</span>
+00088 <span class="preprocessor"> { return the##type->pool; }</span>
+00089 <span class="preprocessor"></span>
+00090 <span class="comment"></span>
+00091 <span class="comment">/**</span>
+00092 <span class="comment"> * Pool debug levels</span>
+00093 <span class="comment"> *</span>
+00094 <span class="comment"> * <pre></span>
+00095 <span class="comment"> * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |</span>
+00096 <span class="comment"> * ---------------------------------</span>
+00097 <span class="comment"> * | | | | | | | | x | General debug code enabled (useful in</span>
+00098 <span class="comment"> * combination with --with-efence).</span>
+00099 <span class="comment"> *</span>
+00100 <span class="comment"> * | | | | | | | x | | Verbose output on stderr (report</span>
+00101 <span class="comment"> * CREATE, CLEAR, DESTROY).</span>
+00102 <span class="comment"> *</span>
+00103 <span class="comment"> * | | | | x | | | | | Verbose output on stderr (report</span>
+00104 <span class="comment"> * PALLOC, PCALLOC).</span>
+00105 <span class="comment"> *</span>
+00106 <span class="comment"> * | | | | | | x | | | Lifetime checking. On each use of a</span>
+00107 <span class="comment"> * pool, check its lifetime. If the pool</span>
+00108 <span class="comment"> * is out of scope, abort().</span>
+00109 <span class="comment"> * In combination with the verbose flag</span>
+00110 <span class="comment"> * above, it will output LIFE in such an</span>
+00111 <span class="comment"> * event prior to aborting.</span>
+00112 <span class="comment"> *</span>
+00113 <span class="comment"> * | | | | | x | | | | Pool owner checking. On each use of a</span>
+00114 <span class="comment"> * pool, check if the current thread is the</span>
+00115 <span class="comment"> * pools owner. If not, abort(). In</span>
+00116 <span class="comment"> * combination with the verbose flag above,</span>
+00117 <span class="comment"> * it will output OWNER in such an event</span>
+00118 <span class="comment"> * prior to aborting. Use the debug</span>
+00119 <span class="comment"> * function apr_pool_owner_set() to switch</span>
+00120 <span class="comment"> * a pools ownership.</span>
+00121 <span class="comment"> *</span>
+00122 <span class="comment"> * When no debug level was specified, assume general debug mode.</span>
+00123 <span class="comment"> * If level 0 was specified, debugging is switched off</span>
+00124 <span class="comment"> * </pre></span>
+00125 <span class="comment"> */</span>
+00126 <span class="preprocessor">#if defined(APR_POOL_DEBUG)</span>
+00127 <span class="preprocessor"></span><span class="comment">/* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */</span>
+00128 <span class="preprocessor">#if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1)</span>
+00129 <span class="preprocessor"></span><span class="preprocessor">#undef APR_POOL_DEBUG</span>
+00130 <span class="preprocessor"></span><span class="preprocessor">#define APR_POOL_DEBUG 1</span>
+00131 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
+00132 <span class="preprocessor"></span><span class="preprocessor">#else</span>
+<a name="l00133"></a><a class="code" href="group__apr__pools.html#ga32">00133</a> <span class="preprocessor"></span><span class="preprocessor">#define APR_POOL_DEBUG 0</span>
+00134 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
+00135 <span class="preprocessor"></span><span class="comment"></span>
+00136 <span class="comment">/** the place in the code where the particular function was called */</span>
+<a name="l00137"></a><a class="code" href="group__apr__pools.html#ga33">00137</a> <span class="preprocessor">#define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__)</span>
+00138 <span class="preprocessor"></span>
+00139
+00140 <span class="comment"></span>
+00141 <span class="comment">/** A function that is called when allocation fails. */</span>
+<a name="l00142"></a><a class="code" href="group__apr__pools.html#ga1">00142</a> <span class="keyword">typedef</span> int (*apr_abortfunc_t)(<span class="keywordtype">int</span> retcode);
+00143
+00144 <span class="comment">/*</span>
+00145 <span class="comment"> * APR memory structure manipulators (pools, tables, and arrays).</span>
+00146 <span class="comment"> */</span>
+00147
+00148 <span class="comment">/*</span>
+00149 <span class="comment"> * Initialization</span>
+00150 <span class="comment"> */</span>
+00151 <span class="comment"></span>
+00152 <span class="comment">/**</span>
+00153 <span class="comment"> * Setup all of the internal structures required to use pools</span>
+00154 <span class="comment"> * @remark Programs do NOT need to call this directly. APR will call this</span>
+00155 <span class="comment"> * automatically from apr_initialize.</span>
+00156 <span class="comment"> * @internal</span>
+00157 <span class="comment"> */</span>
+00158 APR_DECLARE(apr_status_t) apr_pool_initialize(<span class="keywordtype">void</span>);
+00159 <span class="comment"></span>
+00160 <span class="comment">/**</span>
+00161 <span class="comment"> * Tear down all of the internal structures required to use pools</span>
+00162 <span class="comment"> * @remark Programs do NOT need to call this directly. APR will call this</span>
+00163 <span class="comment"> * automatically from apr_terminate.</span>
+00164 <span class="comment"> * @internal</span>
+00165 <span class="comment"> */</span>
+00166 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_terminate(<span class="keywordtype">void</span>);
00167
-00168 <span class="comment">/*</span>
-00169 <span class="comment"> * Pool creation/destruction</span>
-00170 <span class="comment"> */</span>
-00171
-00172 #include "apr_allocator.h"
-00173 <span class="comment"></span>
-00174 <span class="comment">/**</span>
-00175 <span class="comment"> * Create a new pool.</span>
-00176 <span class="comment"> * @param newpool The pool we have just created.</span>
-00177 <span class="comment"> * @param parent The parent pool. If this is NULL, the new pool is a root</span>
-00178 <span class="comment"> * pool. If it is non-NULL, the new pool will inherit all</span>
-00179 <span class="comment"> * of its parent pool's attributes, except the apr_pool_t will</span>
-00180 <span class="comment"> * be a sub-pool.</span>
-00181 <span class="comment"> * @param abort_fn A function to use if the pool cannot allocate more memory.</span>
-00182 <span class="comment"> * @param allocator The allocator to use with the new pool. If NULL the</span>
-00183 <span class="comment"> * allocator of the parent pool will be used.</span>
-00184 <span class="comment"> */</span>
-00185 APR_DECLARE(<a class="code" href="group__apr__errno.html#ga0">apr_status_t</a>) apr_pool_create_ex(apr_pool_t **newpool,
-00186 apr_pool_t *parent,
-00187 <a class="code" href="group__apr__pools.html#ga1">apr_abortfunc_t</a> abort_fn,
-00188 <a class="code" href="group__apr__allocator.html#ga0">apr_allocator_t</a> *allocator);
-00189 <span class="comment"></span>
-00190 <span class="comment">/**</span>
-00191 <span class="comment"> * Debug version of apr_pool_create_ex.</span>
-00192 <span class="comment"> * @param newpool @see apr_pool_create.</span>
-00193 <span class="comment"> * @param parent @see apr_pool_create.</span>
-00194 <span class="comment"> * @param abort_fn @see apr_pool_create.</span>
-00195 <span class="comment"> * @param allocator @see apr_pool_create.</span>
-00196 <span class="comment"> * @param file_line Where the function is called from.</span>
-00197 <span class="comment"> * This is usually APR_POOL__FILE_LINE__.</span>
-00198 <span class="comment"> * @remark Only available when APR_POOL_DEBUG is defined.</span>
-00199 <span class="comment"> * Call this directly if you have you apr_pool_create_ex</span>
-00200 <span class="comment"> * calls in a wrapper function and wish to override</span>
-00201 <span class="comment"> * the file_line argument to reflect the caller of</span>
-00202 <span class="comment"> * your wrapper function. If you do not have</span>
-00203 <span class="comment"> * apr_pool_create_ex in a wrapper, trust the macro</span>
-00204 <span class="comment"> * and don't call apr_pool_create_ex_debug directly.</span>
-00205 <span class="comment"> */</span>
-00206 APR_DECLARE(<a class="code" href="group__apr__errno.html#ga0">apr_status_t</a>) apr_pool_create_ex_debug(apr_pool_t **newpool,
-00207 apr_pool_t *parent,
-00208 <a class="code" href="group__apr__pools.html#ga1">apr_abortfunc_t</a> abort_fn,
-00209 <a class="code" href="group__apr__allocator.html#ga0">apr_allocator_t</a> *allocator,
-00210 const <span class="keywordtype">char</span> *file_line);
-00211
-00212 #if APR_POOL_DEBUG
-00213 #define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \
-00214 apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
-00215 APR_POOL__FILE_LINE__)
-00216 #endif
-00217 <span class="comment"></span>
-00218 <span class="comment">/**</span>
-00219 <span class="comment"> * Create a new pool.</span>
-00220 <span class="comment"> * @param newpool The pool we have just created.</span>
-00221 <span class="comment"> * @param parent The parent pool. If this is NULL, the new pool is a root</span>
-00222 <span class="comment"> * pool. If it is non-NULL, the new pool will inherit all</span>
-00223 <span class="comment"> * of its parent pool's attributes, except the apr_pool_t will</span>
-00224 <span class="comment"> * be a sub-pool.</span>
-00225 <span class="comment"> */</span>
-00226 #if defined(DOXYGEN)
-00227 APR_DECLARE(<a class="code" href="group__apr__errno.html#ga0">apr_status_t</a>) apr_pool_create(apr_pool_t **newpool,
-00228 apr_pool_t *parent);
-00229 #else
-00230 #if APR_POOL_DEBUG
-00231 #define apr_pool_create(newpool, parent) \
-00232 apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
-00233 APR_POOL__FILE_LINE__)
-00234 #else
-00235 #define apr_pool_create(newpool, parent) \
-00236 apr_pool_create_ex(newpool, parent, NULL, NULL)
-00237 #endif
+00168
+00169 <span class="comment">/*</span>
+00170 <span class="comment"> * Pool creation/destruction</span>
+00171 <span class="comment"> */</span>
+00172
+00173 #include "apr_allocator.h"
+00174 <span class="comment"></span>
+00175 <span class="comment">/**</span>
+00176 <span class="comment"> * Create a new pool.</span>
+00177 <span class="comment"> * @param newpool The pool we have just created.</span>
+00178 <span class="comment"> * @param parent The parent pool. If this is NULL, the new pool is a root</span>
+00179 <span class="comment"> * pool. If it is non-NULL, the new pool will inherit all</span>
+00180 <span class="comment"> * of its parent pool's attributes, except the apr_pool_t will</span>
+00181 <span class="comment"> * be a sub-pool.</span>
+00182 <span class="comment"> * @param abort_fn A function to use if the pool cannot allocate more memory.</span>
+00183 <span class="comment"> * @param allocator The allocator to use with the new pool. If NULL the</span>
+00184 <span class="comment"> * allocator of the parent pool will be used.</span>
+00185 <span class="comment"> */</span>
+00186 APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
+00187 apr_pool_t *parent,
+00188 apr_abortfunc_t abort_fn,
+00189 apr_allocator_t *allocator);
+00190 <span class="comment"></span>
+00191 <span class="comment">/**</span>
+00192 <span class="comment"> * Debug version of apr_pool_create_ex.</span>
+00193 <span class="comment"> * @param newpool @see apr_pool_create.</span>
+00194 <span class="comment"> * @param parent @see apr_pool_create.</span>
+00195 <span class="comment"> * @param abort_fn @see apr_pool_create.</span>
+00196 <span class="comment"> * @param allocator @see apr_pool_create.</span>
+00197 <span class="comment"> * @param file_line Where the function is called from.</span>
+00198 <span class="comment"> * This is usually APR_POOL__FILE_LINE__.</span>
+00199 <span class="comment"> * @remark Only available when APR_POOL_DEBUG is defined.</span>
+00200 <span class="comment"> * Call this directly if you have you apr_pool_create_ex</span>
+00201 <span class="comment"> * calls in a wrapper function and wish to override</span>
+00202 <span class="comment"> * the file_line argument to reflect the caller of</span>
+00203 <span class="comment"> * your wrapper function. If you do not have</span>
+00204 <span class="comment"> * apr_pool_create_ex in a wrapper, trust the macro</span>
+00205 <span class="comment"> * and don't call apr_pool_create_ex_debug directly.</span>
+00206 <span class="comment"> */</span>
+00207 APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
+00208 apr_pool_t *parent,
+00209 apr_abortfunc_t abort_fn,
+00210 apr_allocator_t *allocator,
+00211 const <span class="keywordtype">char</span> *file_line);
+00212
+00213 #if APR_POOL_DEBUG
+00214 #define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \
+00215 apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
+00216 APR_POOL__FILE_LINE__)
+00217 #endif
+00218 <span class="comment"></span>
+00219 <span class="comment">/**</span>
+00220 <span class="comment"> * Create a new pool.</span>
+00221 <span class="comment"> * @param newpool The pool we have just created.</span>
+00222 <span class="comment"> * @param parent The parent pool. If this is NULL, the new pool is a root</span>
+00223 <span class="comment"> * pool. If it is non-NULL, the new pool will inherit all</span>
+00224 <span class="comment"> * of its parent pool's attributes, except the apr_pool_t will</span>
+00225 <span class="comment"> * be a sub-pool.</span>
+00226 <span class="comment"> */</span>
+00227 #if defined(DOXYGEN)
+00228 APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
+00229 apr_pool_t *parent);
+00230 #else
+00231 #if APR_POOL_DEBUG
+00232 #define apr_pool_create(newpool, parent) \
+00233 apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
+00234 APR_POOL__FILE_LINE__)
+00235 #else
+00236 #define apr_pool_create(newpool, parent) \
+00237 apr_pool_create_ex(newpool, parent, NULL, NULL)
00238 #endif
-00239 <span class="comment"></span>
-00240 <span class="comment">/**</span>
-00241 <span class="comment"> * Find the pools allocator</span>
-00242 <span class="comment"> * @param pool The pool to get the allocator from.</span>
-00243 <span class="comment"> */</span>
-00244 APR_DECLARE(<a class="code" href="group__apr__allocator.html#ga0">apr_allocator_t</a> *) apr_pool_allocator_get(apr_pool_t *pool);
-00245 <span class="comment"></span>
-00246 <span class="comment">/**</span>
-00247 <span class="comment"> * Clear all memory in the pool and run all the cleanups. This also destroys all</span>
-00248 <span class="comment"> * subpools.</span>
-00249 <span class="comment"> * @param p The pool to clear</span>
-00250 <span class="comment"> * @remark This does not actually free the memory, it just allows the pool</span>
-00251 <span class="comment"> * to re-use this memory for the next allocation.</span>
-00252 <span class="comment"> * @see apr_pool_destroy()</span>
-00253 <span class="comment"> */</span>
-00254 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_clear(apr_pool_t *p);
-00255 <span class="comment"></span>
-00256 <span class="comment">/**</span>
-00257 <span class="comment"> * Debug version of apr_pool_clear.</span>
-00258 <span class="comment"> * @param p See: apr_pool_clear.</span>
-00259 <span class="comment"> * @param file_line Where the function is called from.</span>
-00260 <span class="comment"> * This is usually APR_POOL__FILE_LINE__.</span>
-00261 <span class="comment"> * @remark Only available when APR_POOL_DEBUG is defined.</span>
-00262 <span class="comment"> * Call this directly if you have you apr_pool_clear</span>
-00263 <span class="comment"> * calls in a wrapper function and wish to override</span>
-00264 <span class="comment"> * the file_line argument to reflect the caller of</span>
-00265 <span class="comment"> * your wrapper function. If you do not have</span>
-00266 <span class="comment"> * apr_pool_clear in a wrapper, trust the macro</span>
-00267 <span class="comment"> * and don't call apr_pool_destroy_clear directly.</span>
-00268 <span class="comment"> */</span>
-00269 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_clear_debug(apr_pool_t *p,
-00270 const <span class="keywordtype">char</span> *file_line);
-00271
-00272 #if APR_POOL_DEBUG
-00273 #define apr_pool_clear(p) \
-00274 apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
-00275 #endif
-00276 <span class="comment"></span>
-00277 <span class="comment">/**</span>
-00278 <span class="comment"> * Destroy the pool. This takes similar action as apr_pool_clear() and then</span>
-00279 <span class="comment"> * frees all the memory.</span>
-00280 <span class="comment"> * @param p The pool to destroy</span>
-00281 <span class="comment"> * @remark This will actually free the memory</span>
-00282 <span class="comment"> */</span>
-00283 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_destroy(apr_pool_t *p);
-00284 <span class="comment"></span>
-00285 <span class="comment">/**</span>
-00286 <span class="comment"> * Debug version of apr_pool_destroy.</span>
-00287 <span class="comment"> * @param p See: apr_pool_destroy.</span>
-00288 <span class="comment"> * @param file_line Where the function is called from.</span>
-00289 <span class="comment"> * This is usually APR_POOL__FILE_LINE__.</span>
-00290 <span class="comment"> * @remark Only available when APR_POOL_DEBUG is defined.</span>
-00291 <span class="comment"> * Call this directly if you have you apr_pool_destroy</span>
-00292 <span class="comment"> * calls in a wrapper function and wish to override</span>
-00293 <span class="comment"> * the file_line argument to reflect the caller of</span>
-00294 <span class="comment"> * your wrapper function. If you do not have</span>
-00295 <span class="comment"> * apr_pool_destroy in a wrapper, trust the macro</span>
-00296 <span class="comment"> * and don't call apr_pool_destroy_debug directly.</span>
-00297 <span class="comment"> */</span>
-00298 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_destroy_debug(apr_pool_t *p,
-00299 const <span class="keywordtype">char</span> *file_line);
-00300
-00301 #if APR_POOL_DEBUG
-00302 #define apr_pool_destroy(p) \
-00303 apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
-00304 #endif
-00305
+00239 #endif
+00240 <span class="comment"></span>
+00241 <span class="comment">/**</span>
+00242 <span class="comment"> * Find the pools allocator</span>
+00243 <span class="comment"> * @param pool The pool to get the allocator from.</span>
+00244 <span class="comment"> */</span>
+00245 APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool);
+00246 <span class="comment"></span>
+00247 <span class="comment">/**</span>
+00248 <span class="comment"> * Clear all memory in the pool and run all the cleanups. This also destroys all</span>
+00249 <span class="comment"> * subpools.</span>
+00250 <span class="comment"> * @param p The pool to clear</span>
+00251 <span class="comment"> * @remark This does not actually free the memory, it just allows the pool</span>
+00252 <span class="comment"> * to re-use this memory for the next allocation.</span>
+00253 <span class="comment"> * @see apr_pool_destroy()</span>
+00254 <span class="comment"> */</span>
+00255 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_clear(apr_pool_t *p);
+00256 <span class="comment"></span>
+00257 <span class="comment">/**</span>
+00258 <span class="comment"> * Debug version of apr_pool_clear.</span>
+00259 <span class="comment"> * @param p See: apr_pool_clear.</span>
+00260 <span class="comment"> * @param file_line Where the function is called from.</span>
+00261 <span class="comment"> * This is usually APR_POOL__FILE_LINE__.</span>
+00262 <span class="comment"> * @remark Only available when APR_POOL_DEBUG is defined.</span>
+00263 <span class="comment"> * Call this directly if you have you apr_pool_clear</span>
+00264 <span class="comment"> * calls in a wrapper function and wish to override</span>
+00265 <span class="comment"> * the file_line argument to reflect the caller of</span>
+00266 <span class="comment"> * your wrapper function. If you do not have</span>
+00267 <span class="comment"> * apr_pool_clear in a wrapper, trust the macro</span>
+00268 <span class="comment"> * and don't call apr_pool_destroy_clear directly.</span>
+00269 <span class="comment"> */</span>
+00270 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_clear_debug(apr_pool_t *p,
+00271 const <span class="keywordtype">char</span> *file_line);
+00272
+00273 #if APR_POOL_DEBUG
+00274 #define apr_pool_clear(p) \
+00275 apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
+00276 #endif
+00277 <span class="comment"></span>
+00278 <span class="comment">/**</span>
+00279 <span class="comment"> * Destroy the pool. This takes similar action as apr_pool_clear() and then</span>
+00280 <span class="comment"> * frees all the memory.</span>
+00281 <span class="comment"> * @param p The pool to destroy</span>
+00282 <span class="comment"> * @remark This will actually free the memory</span>
+00283 <span class="comment"> */</span>
+00284 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_destroy(apr_pool_t *p);
+00285 <span class="comment"></span>
+00286 <span class="comment">/**</span>
+00287 <span class="comment"> * Debug version of apr_pool_destroy.</span>
+00288 <span class="comment"> * @param p See: apr_pool_destroy.</span>
+00289 <span class="comment"> * @param file_line Where the function is called from.</span>
+00290 <span class="comment"> * This is usually APR_POOL__FILE_LINE__.</span>
+00291 <span class="comment"> * @remark Only available when APR_POOL_DEBUG is defined.</span>
+00292 <span class="comment"> * Call this directly if you have you apr_pool_destroy</span>
+00293 <span class="comment"> * calls in a wrapper function and wish to override</span>
+00294 <span class="comment"> * the file_line argument to reflect the caller of</span>
+00295 <span class="comment"> * your wrapper function. If you do not have</span>
+00296 <span class="comment"> * apr_pool_destroy in a wrapper, trust the macro</span>
+00297 <span class="comment"> * and don't call apr_pool_destroy_debug directly.</span>
+00298 <span class="comment"> */</span>
+00299 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_destroy_debug(apr_pool_t *p,
+00300 const <span class="keywordtype">char</span> *file_line);
+00301
+00302 #if APR_POOL_DEBUG
+00303 #define apr_pool_destroy(p) \
+00304 apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
+00305 #endif
00306
-00307 <span class="comment">/*</span>
-00308 <span class="comment"> * Memory allocation</span>
-00309 <span class="comment"> */</span>
-00310 <span class="comment"></span>
-00311 <span class="comment">/**</span>
-00312 <span class="comment"> * Allocate a block of memory from a pool</span>
-00313 <span class="comment"> * @param p The pool to allocate from</span>
-00314 <span class="comment"> * @param size The amount of memory to allocate</span>
-00315 <span class="comment"> * @return The allocated memory</span>
-00316 <span class="comment"> */</span>
-00317 APR_DECLARE(<span class="keywordtype">void</span> *) apr_palloc(apr_pool_t *p, apr_size_t size);
-00318 <span class="comment"></span>
-00319 <span class="comment">/**</span>
-00320 <span class="comment"> * Debug version of apr_palloc</span>
-00321 <span class="comment"> * @param p See: apr_palloc</span>
-00322 <span class="comment"> * @param size See: apr_palloc</span>
-00323 <span class="comment"> * @param file_line Where the function is called from.</span>
-00324 <span class="comment"> * This is usually APR_POOL__FILE_LINE__.</span>
-00325 <span class="comment"> * @return See: apr_palloc</span>
-00326 <span class="comment"> */</span>
-00327 APR_DECLARE(<span class="keywordtype">void</span> *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
-00328 const <span class="keywordtype">char</span> *file_line);
-00329
-00330 #if APR_POOL_DEBUG
-00331 #define apr_palloc(p, size) \
-00332 apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
-00333 #endif
-00334 <span class="comment"></span>
-00335 <span class="comment">/**</span>
-00336 <span class="comment"> * Allocate a block of memory from a pool and set all of the memory to 0</span>
-00337 <span class="comment"> * @param p The pool to allocate from</span>
-00338 <span class="comment"> * @param size The amount of memory to allocate</span>
-00339 <span class="comment"> * @return The allocated memory</span>
-00340 <span class="comment"> */</span>
-00341 #if defined(DOXYGEN)
-00342 APR_DECLARE(<span class="keywordtype">void</span> *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
-00343 #elif !APR_POOL_DEBUG
-00344 #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
-00345 #endif
-00346 <span class="comment"></span>
-00347 <span class="comment">/**</span>
-00348 <span class="comment"> * Debug version of apr_pcalloc</span>
-00349 <span class="comment"> * @param p See: apr_pcalloc</span>
-00350 <span class="comment"> * @param size See: apr_pcalloc</span>
-00351 <span class="comment"> * @param file_line Where the function is called from.</span>
-00352 <span class="comment"> * This is usually APR_POOL__FILE_LINE__.</span>
-00353 <span class="comment"> * @return See: apr_pcalloc</span>
-00354 <span class="comment"> */</span>
-00355 APR_DECLARE(<span class="keywordtype">void</span> *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
-00356 const <span class="keywordtype">char</span> *file_line);
-00357
-00358 #if APR_POOL_DEBUG
-00359 #define apr_pcalloc(p, size) \
-00360 apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
-00361 #endif
-00362
+00307
+00308 <span class="comment">/*</span>
+00309 <span class="comment"> * Memory allocation</span>
+00310 <span class="comment"> */</span>
+00311 <span class="comment"></span>
+00312 <span class="comment">/**</span>
+00313 <span class="comment"> * Allocate a block of memory from a pool</span>
+00314 <span class="comment"> * @param p The pool to allocate from</span>
+00315 <span class="comment"> * @param size The amount of memory to allocate</span>
+00316 <span class="comment"> * @return The allocated memory</span>
+00317 <span class="comment"> */</span>
+00318 APR_DECLARE(<span class="keywordtype">void</span> *) apr_palloc(apr_pool_t *p, apr_size_t size);
+00319 <span class="comment"></span>
+00320 <span class="comment">/**</span>
+00321 <span class="comment"> * Debug version of apr_palloc</span>
+00322 <span class="comment"> * @param p See: apr_palloc</span>
+00323 <span class="comment"> * @param size See: apr_palloc</span>
+00324 <span class="comment"> * @param file_line Where the function is called from.</span>
+00325 <span class="comment"> * This is usually APR_POOL__FILE_LINE__.</span>
+00326 <span class="comment"> * @return See: apr_palloc</span>
+00327 <span class="comment"> */</span>
+00328 APR_DECLARE(<span class="keywordtype">void</span> *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
+00329 const <span class="keywordtype">char</span> *file_line);
+00330
+00331 #if APR_POOL_DEBUG
+00332 #define apr_palloc(p, size) \
+00333 apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
+00334 #endif
+00335 <span class="comment"></span>
+00336 <span class="comment">/**</span>
+00337 <span class="comment"> * Allocate a block of memory from a pool and set all of the memory to 0</span>
+00338 <span class="comment"> * @param p The pool to allocate from</span>
+00339 <span class="comment"> * @param size The amount of memory to allocate</span>
+00340 <span class="comment"> * @return The allocated memory</span>
+00341 <span class="comment"> */</span>
+00342 #if defined(DOXYGEN)
+00343 APR_DECLARE(<span class="keywordtype">void</span> *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
+00344 #elif !APR_POOL_DEBUG
+00345 #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
+00346 #endif
+00347 <span class="comment"></span>
+00348 <span class="comment">/**</span>
+00349 <span class="comment"> * Debug version of apr_pcalloc</span>
+00350 <span class="comment"> * @param p See: apr_pcalloc</span>
+00351 <span class="comment"> * @param size See: apr_pcalloc</span>
+00352 <span class="comment"> * @param file_line Where the function is called from.</span>
+00353 <span class="comment"> * This is usually APR_POOL__FILE_LINE__.</span>
+00354 <span class="comment"> * @return See: apr_pcalloc</span>
+00355 <span class="comment"> */</span>
+00356 APR_DECLARE(<span class="keywordtype">void</span> *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
+00357 const <span class="keywordtype">char</span> *file_line);
+00358
+00359 #if APR_POOL_DEBUG
+00360 #define apr_pcalloc(p, size) \
+00361 apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
+00362 #endif
00363
-00364 <span class="comment">/*</span>
-00365 <span class="comment"> * Pool Properties</span>
-00366 <span class="comment"> */</span>
-00367 <span class="comment"></span>
-00368 <span class="comment">/**</span>
-00369 <span class="comment"> * Set the function to be called when an allocation failure occurs.</span>
-00370 <span class="comment"> * @remark If the program wants APR to exit on a memory allocation error,</span>
-00371 <span class="comment"> * then this function can be called to set the callback to use (for</span>
-00372 <span class="comment"> * performing cleanup and then exiting). If this function is not called,</span>
-00373 <span class="comment"> * then APR will return an error and expect the calling program to</span>
-00374 <span class="comment"> * deal with the error accordingly.</span>
-00375 <span class="comment"> */</span>
-00376 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_abort_set(<a class="code" href="group__apr__pools.html#ga1">apr_abortfunc_t</a> abortfunc,
-00377 apr_pool_t *pool);
-00378 <span class="comment"></span>
-00379 <span class="comment">/**</span>
-00380 <span class="comment"> * Get the abort function associated with the specified pool.</span>
-00381 <span class="comment"> * @param pool The pool for retrieving the abort function.</span>
-00382 <span class="comment"> * @return The abort function for the given pool.</span>
-00383 <span class="comment"> */</span>
-00384 APR_DECLARE(<a class="code" href="group__apr__pools.html#ga1">apr_abortfunc_t</a>) apr_pool_abort_get(apr_pool_t *pool);
-00385 <span class="comment"></span>
-00386 <span class="comment">/**</span>
-00387 <span class="comment"> * Get the parent pool of the specified pool.</span>
-00388 <span class="comment"> * @param pool The pool for retrieving the parent pool.</span>
-00389 <span class="comment"> * @return The parent of the given pool.</span>
-00390 <span class="comment"> */</span>
-00391 APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool);
-00392 <span class="comment"></span>
-00393 <span class="comment">/**</span>
-00394 <span class="comment"> * Determine if pool a is an ancestor of pool b</span>
-00395 <span class="comment"> * @param a The pool to search</span>
-00396 <span class="comment"> * @param b The pool to search for</span>
-00397 <span class="comment"> * @return True if a is an ancestor of b, NULL is considered an ancestor</span>
-00398 <span class="comment"> * of all pools.</span>
-00399 <span class="comment"> */</span>
-00400 APR_DECLARE(<span class="keywordtype">int</span>) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
-00401 <span class="comment"></span>
-00402 <span class="comment">/**</span>
-00403 <span class="comment"> * Tag a pool (give it a name)</span>
-00404 <span class="comment"> * @param pool The pool to tag</span>
-00405 <span class="comment"> * @param tag The tag</span>
-00406 <span class="comment"> */</span>
-00407 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_tag(apr_pool_t *pool, const <span class="keywordtype">char</span> *tag);
-00408
+00364
+00365 <span class="comment">/*</span>
+00366 <span class="comment"> * Pool Properties</span>
+00367 <span class="comment"> */</span>
+00368 <span class="comment"></span>
+00369 <span class="comment">/**</span>
+00370 <span class="comment"> * Set the function to be called when an allocation failure occurs.</span>
+00371 <span class="comment"> * @remark If the program wants APR to exit on a memory allocation error,</span>
+00372 <span class="comment"> * then this function can be called to set the callback to use (for</span>
+00373 <span class="comment"> * performing cleanup and then exiting). If this function is not called,</span>
+00374 <span class="comment"> * then APR will return an error and expect the calling program to</span>
+00375 <span class="comment"> * deal with the error accordingly.</span>
+00376 <span class="comment"> */</span>
+00377 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_abort_set(apr_abortfunc_t abortfunc,
+00378 apr_pool_t *pool);
+00379 <span class="comment"></span>
+00380 <span class="comment">/**</span>
+00381 <span class="comment"> * Get the abort function associated with the specified pool.</span>
+00382 <span class="comment"> * @param pool The pool for retrieving the abort function.</span>
+00383 <span class="comment"> * @return The abort function for the given pool.</span>
+00384 <span class="comment"> */</span>
+00385 APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool);
+00386 <span class="comment"></span>
+00387 <span class="comment">/**</span>
+00388 <span class="comment"> * Get the parent pool of the specified pool.</span>
+00389 <span class="comment"> * @param pool The pool for retrieving the parent pool.</span>
+00390 <span class="comment"> * @return The parent of the given pool.</span>
+00391 <span class="comment"> */</span>
+00392 APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool);
+00393 <span class="comment"></span>
+00394 <span class="comment">/**</span>
+00395 <span class="comment"> * Determine if pool a is an ancestor of pool b</span>
+00396 <span class="comment"> * @param a The pool to search</span>
+00397 <span class="comment"> * @param b The pool to search for</span>
+00398 <span class="comment"> * @return True if a is an ancestor of b, NULL is considered an ancestor</span>
+00399 <span class="comment"> * of all pools.</span>
+00400 <span class="comment"> */</span>
+00401 APR_DECLARE(<span class="keywordtype">int</span>) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
+00402 <span class="comment"></span>
+00403 <span class="comment">/**</span>
+00404 <span class="comment"> * Tag a pool (give it a name)</span>
+00405 <span class="comment"> * @param pool The pool to tag</span>
+00406 <span class="comment"> * @param tag The tag</span>
+00407 <span class="comment"> */</span>
+00408 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_tag(apr_pool_t *pool, const <span class="keywordtype">char</span> *tag);
00409
-00410 <span class="comment">/*</span>
-00411 <span class="comment"> * User data management</span>
-00412 <span class="comment"> */</span>
-00413 <span class="comment"></span>
-00414 <span class="comment">/**</span>
-00415 <span class="comment"> * Set the data associated with the current pool</span>
-00416 <span class="comment"> * @param data The user data associated with the pool.</span>
-00417 <span class="comment"> * @param key The key to use for association</span>
-00418 <span class="comment"> * @param cleanup The cleanup program to use to cleanup the data (NULL if none)</span>
-00419 <span class="comment"> * @param pool The current pool</span>
-00420 <span class="comment"> * @warning The data to be attached to the pool should have a life span</span>
-00421 <span class="comment"> * at least as long as the pool it is being attached to.</span>
-00422 <span class="comment"> *</span>
-00423 <span class="comment"> * Users of APR must take EXTREME care when choosing a key to</span>
-00424 <span class="comment"> * use for their data. It is possible to accidentally overwrite</span>
-00425 <span class="comment"> * data by choosing a key that another part of the program is using.</span>
-00426 <span class="comment"> * Therefore it is advised that steps are taken to ensure that unique</span>
-00427 <span class="comment"> * keys are used for all of the userdata objects in a particular pool</span>
-00428 <span class="comment"> * (the same key in two different pools or a pool and one of its</span>
-00429 <span class="comment"> * subpools is okay) at all times. Careful namespace prefixing of</span>
-00430 <span class="comment"> * key names is a typical way to help ensure this uniqueness.</span>
-00431 <span class="comment"> *</span>
-00432 <span class="comment"> */</span>
-00433 APR_DECLARE(<a class="code" href="group__apr__errno.html#ga0">apr_status_t</a>) apr_pool_userdata_set(
-00434 const <span class="keywordtype">void</span> *data,
-00435 const <span class="keywordtype">char</span> *key,
-00436 <a class="code" href="group__apr__errno.html#ga0">apr_status_t</a> (*cleanup)(<span class="keywordtype">void</span> *),
-00437 apr_pool_t *pool);
-00438 <span class="comment"></span>
-00439 <span class="comment">/**</span>
-00440 <span class="comment"> * Set the data associated with the current pool</span>
-00441 <span class="comment"> * @param data The user data associated with the pool.</span>
-00442 <span class="comment"> * @param key The key to use for association</span>
-00443 <span class="comment"> * @param cleanup The cleanup program to use to cleanup the data (NULL if none)</span>
-00444 <span class="comment"> * @param pool The current pool</span>
-00445 <span class="comment"> * @note same as apr_pool_userdata_set(), except that this version doesn't</span>
-00446 <span class="comment"> * make a copy of the key (this function is useful, for example, when</span>
-00447 <span class="comment"> * the key is a string literal)</span>
-00448 <span class="comment"> * @warning This should NOT be used if the key could change addresses by</span>
-00449 <span class="comment"> * any means between the apr_pool_userdata_setn() call and a</span>
-00450 <span class="comment"> * subsequent apr_pool_userdata_get() on that key, such as if a</span>
-00451 <span class="comment"> * static string is used as a userdata key in a DSO and the DSO could</span>
-00452 <span class="comment"> * be unloaded and reloaded between the _setn() and the _get(). You</span>
-00453 <span class="comment"> * MUST use apr_pool_userdata_set() in such cases.</span>
-00454 <span class="comment"> * @warning More generally, the key and the data to be attached to the</span>
-00455 <span class="comment"> * pool should have a life span at least as long as the pool itself.</span>
-00456 <span class="comment"> *</span>
-00457 <span class="comment"> */</span>
-00458 APR_DECLARE(<a class="code" href="group__apr__errno.html#ga0">apr_status_t</a>) apr_pool_userdata_setn(
-00459 const <span class="keywordtype">void</span> *data,
-00460 const <span class="keywordtype">char</span> *key,
-00461 <a class="code" href="group__apr__errno.html#ga0">apr_status_t</a> (*cleanup)(<span class="keywordtype">void</span> *),
-00462 apr_pool_t *pool);
-00463 <span class="comment"></span>
-00464 <span class="comment">/**</span>
-00465 <span class="comment"> * Return the data associated with the current pool.</span>
-00466 <span class="comment"> * @param data The user data associated with the pool.</span>
-00467 <span class="comment"> * @param key The key for the data to retrieve</span>
-00468 <span class="comment"> * @param pool The current pool.</span>
-00469 <span class="comment"> */</span>
-00470 APR_DECLARE(<a class="code" href="group__apr__errno.html#ga0">apr_status_t</a>) apr_pool_userdata_get(<span class="keywordtype">void</span> **data, const <span class="keywordtype">char</span> *key,
-00471 apr_pool_t *pool);
-00472
+00410
+00411 <span class="comment">/*</span>
+00412 <span class="comment"> * User data management</span>
+00413 <span class="comment"> */</span>
+00414 <span class="comment"></span>
+00415 <span class="comment">/**</span>
+00416 <span class="comment"> * Set the data associated with the current pool</span>
+00417 <span class="comment"> * @param data The user data associated with the pool.</span>
+00418 <span class="comment"> * @param key The key to use for association</span>
+00419 <span class="comment"> * @param cleanup The cleanup program to use to cleanup the data (NULL if none)</span>
+00420 <span class="comment"> * @param pool The current pool</span>
+00421 <span class="comment"> * @warning The data to be attached to the pool should have a life span</span>
+00422 <span class="comment"> * at least as long as the pool it is being attached to.</span>
+00423 <span class="comment"> *</span>
+00424 <span class="comment"> * Users of APR must take EXTREME care when choosing a key to</span>
+00425 <span class="comment"> * use for their data. It is possible to accidentally overwrite</span>
+00426 <span class="comment"> * data by choosing a key that another part of the program is using.</span>
+00427 <span class="comment"> * Therefore it is advised that steps are taken to ensure that unique</span>
+00428 <span class="comment"> * keys are used for all of the userdata objects in a particular pool</span>
+00429 <span class="comment"> * (the same key in two different pools or a pool and one of its</span>
+00430 <span class="comment"> * subpools is okay) at all times. Careful namespace prefixing of</span>
+00431 <span class="comment"> * key names is a typical way to help ensure this uniqueness.</span>
+00432 <span class="comment"> *</span>
+00433 <span class="comment"> */</span>
+00434 APR_DECLARE(apr_status_t) apr_pool_userdata_set(
+00435 const <span class="keywordtype">void</span> *data,
+00436 const <span class="keywordtype">char</span> *key,
+00437 apr_status_t (*cleanup)(<span class="keywordtype">void</span> *),
+00438 apr_pool_t *pool);
+00439 <span class="comment"></span>
+00440 <span class="comment">/**</span>
+00441 <span class="comment"> * Set the data associated with the current pool</span>
+00442 <span class="comment"> * @param data The user data associated with the pool.</span>
+00443 <span class="comment"> * @param key The key to use for association</span>
+00444 <span class="comment"> * @param cleanup The cleanup program to use to cleanup the data (NULL if none)</span>
+00445 <span class="comment"> * @param pool The current pool</span>
+00446 <span class="comment"> * @note same as apr_pool_userdata_set(), except that this version doesn't</span>
+00447 <span class="comment"> * make a copy of the key (this function is useful, for example, when</span>
+00448 <span class="comment"> * the key is a string literal)</span>
+00449 <span class="comment"> * @warning This should NOT be used if the key could change addresses by</span>
+00450 <span class="comment"> * any means between the apr_pool_userdata_setn() call and a</span>
+00451 <span class="comment"> * subsequent apr_pool_userdata_get() on that key, such as if a</span>
+00452 <span class="comment"> * static string is used as a userdata key in a DSO and the DSO could</span>
+00453 <span class="comment"> * be unloaded and reloaded between the _setn() and the _get(). You</span>
+00454 <span class="comment"> * MUST use apr_pool_userdata_set() in such cases.</span>
+00455 <span class="comment"> * @warning More generally, the key and the data to be attached to the</span>
+00456 <span class="comment"> * pool should have a life span at least as long as the pool itself.</span>
+00457 <span class="comment"> *</span>
+00458 <span class="comment"> */</span>
+00459 APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
+00460 const <span class="keywordtype">void</span> *data,
+00461 const <span class="keywordtype">char</span> *key,
+00462 apr_status_t (*cleanup)(<span class="keywordtype">void</span> *),
+00463 apr_pool_t *pool);
+00464 <span class="comment"></span>
+00465 <span class="comment">/**</span>
+00466 <span class="comment"> * Return the data associated with the current pool.</span>
+00467 <span class="comment"> * @param data The user data associated with the pool.</span>
+00468 <span class="comment"> * @param key The key for the data to retrieve</span>
+00469 <span class="comment"> * @param pool The current pool.</span>
+00470 <span class="comment"> */</span>
+00471 APR_DECLARE(apr_status_t) apr_pool_userdata_get(<span class="keywordtype">void</span> **data, const <span class="keywordtype">char</span> *key,
+00472 apr_pool_t *pool);
00473
-00474 <span class="comment">/*</span>
-00475 <span class="comment"> * Cleanup</span>
-00476 <span class="comment"> *</span>
-00477 <span class="comment"> * Cleanups are performed in the reverse order they were registered. That is:</span>
-00478 <span class="comment"> * Last In, First Out. A cleanup function can safely allocate memory from</span>
-00479 <span class="comment"> * the pool that is being cleaned up. It can also safely register additional</span>
-00480 <span class="comment"> * cleanups which will be run LIFO, directly after the current cleanup</span>
-00481 <span class="comment"> * terminates. Cleanups have to take caution in calling functions that</span>
-00482 <span class="comment"> * create subpools. Subpools, created during cleanup will NOT automatically</span>
-00483 <span class="comment"> * be cleaned up. In other words, cleanups are to clean up after themselves.</span>
-00484 <span class="comment"> */</span>
-00485 <span class="comment"></span>
-00486 <span class="comment">/**</span>
-00487 <span class="comment"> * Register a function to be called when a pool is cleared or destroyed</span>
-00488 <span class="comment"> * @param p The pool register the cleanup with</span>
-00489 <span class="comment"> * @param data The data to pass to the cleanup function.</span>
-00490 <span class="comment"> * @param plain_cleanup The function to call when the pool is cleared</span>
-00491 <span class="comment"> * or destroyed</span>
-00492 <span class="comment"> * @param child_cleanup The function to call when a child process is about</span>
-00493 <span class="comment"> * to exec - this function is called in the child, obviously!</span>
-00494 <span class="comment"> */</span>
-00495 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_cleanup_register(
-00496 apr_pool_t *p,
-00497 const <span class="keywordtype">void</span> *data,
-00498 <a class="code" href="group__apr__errno.html#ga0">apr_status_t</a> (*plain_cleanup)(<span class="keywordtype">void</span> *),
-00499 <a class="code" href="group__apr__errno.html#ga0">apr_status_t</a> (*child_cleanup)(<span class="keywordtype">void</span> *));
-00500 <span class="comment"></span>
-00501 <span class="comment">/**</span>
-00502 <span class="comment"> * Remove a previously registered cleanup function</span>
-00503 <span class="comment"> * @param p The pool remove the cleanup from</span>
-00504 <span class="comment"> * @param data The data to remove from cleanup</span>
-00505 <span class="comment"> * @param cleanup The function to remove from cleanup</span>
-00506 <span class="comment"> * @remarks For some strange reason only the plain_cleanup is handled by this</span>
-00507 <span class="comment"> * function</span>
-00508 <span class="comment"> */</span>
-00509 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_cleanup_kill(apr_pool_t *p, const <span class="keywordtype">void</span> *data,
-00510 <a class="code" href="group__apr__errno.html#ga0">apr_status_t</a> (*cleanup)(<span class="keywordtype">void</span> *));
-00511 <span class="comment"></span>
-00512 <span class="comment">/**</span>
-00513 <span class="comment"> * Replace the child cleanup of a previously registered cleanup</span>
-00514 <span class="comment"> * @param p The pool of the registered cleanup</span>
-00515 <span class="comment"> * @param data The data of the registered cleanup</span>
-00516 <span class="comment"> * @param plain_cleanup The plain cleanup function of the registered cleanup</span>
-00517 <span class="comment"> * @param child_cleanup The function to register as the child cleanup</span>
-00518 <span class="comment"> */</span>
-00519 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_child_cleanup_set(
-00520 apr_pool_t *p,
-00521 const <span class="keywordtype">void</span> *data,
-00522 <a class="code" href="group__apr__errno.html#ga0">apr_status_t</a> (*plain_cleanup)(<span class="keywordtype">void</span> *),
-00523 <a class="code" href="group__apr__errno.html#ga0">apr_status_t</a> (*child_cleanup)(<span class="keywordtype">void</span> *));
-00524 <span class="comment"></span>
-00525 <span class="comment">/**</span>
-00526 <span class="comment"> * Run the specified cleanup function immediately and unregister it. Use</span>
-00527 <span class="comment"> * @a data instead of the data that was registered with the cleanup.</span>
-00528 <span class="comment"> * @param p The pool remove the cleanup from</span>
-00529 <span class="comment"> * @param data The data to remove from cleanup</span>
-00530 <span class="comment"> * @param cleanup The function to remove from cleanup</span>
-00531 <span class="comment"> */</span>
-00532 APR_DECLARE(<a class="code" href="group__apr__errno.html#ga0">apr_status_t</a>) apr_pool_cleanup_run(
-00533 apr_pool_t *p,
-00534 <span class="keywordtype">void</span> *data,
-00535 <a class="code" href="group__apr__errno.html#ga0">apr_status_t</a> (*cleanup)(<span class="keywordtype">void</span> *));
-00536 <span class="comment"></span>
-00537 <span class="comment">/**</span>
-00538 <span class="comment"> * An empty cleanup function</span>
-00539 <span class="comment"> * @param data The data to cleanup</span>
-00540 <span class="comment"> */</span>
-00541 APR_DECLARE_NONSTD(<a class="code" href="group__apr__errno.html#ga0">apr_status_t</a>) apr_pool_cleanup_null(<span class="keywordtype">void</span> *data);
-00542
-00543 <span class="comment">/* Preparing for exec() --- close files, etc., but *don't* flush I/O</span>
-00544 <span class="comment"> * buffers, *don't* wait for subprocesses, and *don't* free any memory.</span>
-00545 <span class="comment"> */</span><span class="comment"></span>
-00546 <span class="comment">/**</span>
-00547 <span class="comment"> * Run all of the child_cleanups, so that any unnecessary files are</span>
-00548 <span class="comment"> * closed because we are about to exec a new program</span>
-00549 <span class="comment"> */</span>
-00550 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_cleanup_for_exec(<span class="keywordtype">void</span>);
-00551
-00552 <span class="comment"></span>
-00553 <span class="comment">/**</span>
-00554 <span class="comment"> * @defgroup PoolDebug Pool Debugging functions.</span>
-00555 <span class="comment"> *</span>
-00556 <span class="comment"> * pools have nested lifetimes -- sub_pools are destroyed when the</span>
-00557 <span class="comment"> * parent pool is cleared. We allow certain liberties with operations</span>
-00558 <span class="comment"> * on things such as tables (and on other structures in a more general</span>
-00559 <span class="comment"> * sense) where we allow the caller to insert values into a table which</span>
-00560 <span class="comment"> * were not allocated from the table's pool. The table's data will</span>
-00561 <span class="comment"> * remain valid as long as all the pools from which its values are</span>
-00562 <span class="comment"> * allocated remain valid.</span>
-00563 <span class="comment"> *</span>
-00564 <span class="comment"> * For example, if B is a sub pool of A, and you build a table T in</span>
-00565 <span class="comment"> * pool B, then it's safe to insert data allocated in A or B into T</span>
-00566 <span class="comment"> * (because B lives at most as long as A does, and T is destroyed when</span>
-00567 <span class="comment"> * B is cleared/destroyed). On the other hand, if S is a table in</span>
-00568 <span class="comment"> * pool A, it is safe to insert data allocated in A into S, but it</span>
-00569 <span class="comment"> * is *not safe* to insert data allocated from B into S... because</span>
-00570 <span class="comment"> * B can be cleared/destroyed before A is (which would leave dangling</span>
-00571 <span class="comment"> * pointers in T's data structures).</span>
-00572 <span class="comment"> *</span>
-00573 <span class="comment"> * In general we say that it is safe to insert data into a table T</span>
-00574 <span class="comment"> * if the data is allocated in any ancestor of T's pool. This is the</span>
-00575 <span class="comment"> * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor</span>
-00576 <span class="comment"> * relationships for all data inserted into tables. APR_POOL_DEBUG also</span>
-00577 <span class="comment"> * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other</span>
-00578 <span class="comment"> * folks to implement similar restrictions for their own data</span>
-00579 <span class="comment"> * structures.</span>
-00580 <span class="comment"> *</span>
-00581 <span class="comment"> * However, sometimes this ancestor requirement is inconvenient --</span>
-00582 <span class="comment"> * sometimes we're forced to create a sub pool (such as through</span>
-00583 <span class="comment"> * apr_sub_req_lookup_uri), and the sub pool is guaranteed to have</span>
-00584 <span class="comment"> * the same lifetime as the parent pool. This is a guarantee implemented</span>
-00585 <span class="comment"> * by the *caller*, not by the pool code. That is, the caller guarantees</span>
-00586 <span class="comment"> * they won't destroy the sub pool individually prior to destroying the</span>
-00587 <span class="comment"> * parent pool.</span>
-00588 <span class="comment"> *</span>
-00589 <span class="comment"> * In this case the caller must call apr_pool_join() to indicate this</span>
-00590 <span class="comment"> * guarantee to the APR_POOL_DEBUG code. There are a few examples spread</span>
-00591 <span class="comment"> * through the standard modules.</span>
-00592 <span class="comment"> *</span>
-00593 <span class="comment"> * These functions are only implemented when #APR_POOL_DEBUG is set.</span>
-00594 <span class="comment"> *</span>
-00595 <span class="comment"> * @{</span>
-00596 <span class="comment"> */</span>
-00597 #if APR_POOL_DEBUG || defined(DOXYGEN)<span class="comment"></span>
-00598 <span class="comment">/**</span>
-00599 <span class="comment"> * Guarantee that a subpool has the same lifetime as the parent.</span>
-00600 <span class="comment"> * @param p The parent pool</span>
-00601 <span class="comment"> * @param sub The subpool</span>
-00602 <span class="comment"> */</span>
-00603 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_join(apr_pool_t *p, apr_pool_t *sub);
-00604 <span class="comment"></span>
-00605 <span class="comment">/**</span>
-00606 <span class="comment"> * Find a pool from something allocated in it.</span>
-00607 <span class="comment"> * @param mem The thing allocated in the pool</span>
-00608 <span class="comment"> * @return The pool it is allocated in</span>
-00609 <span class="comment"> */</span>
-00610 APR_DECLARE(apr_pool_t *) apr_pool_find(const <span class="keywordtype">void</span> *mem);
-00611 <span class="comment"></span>
-00612 <span class="comment">/**</span>
-00613 <span class="comment"> * Report the number of bytes currently in the pool</span>
-00614 <span class="comment"> * @param p The pool to inspect</span>
-00615 <span class="comment"> * @param recurse Recurse/include the subpools' sizes</span>
-00616 <span class="comment"> * @return The number of bytes</span>
-00617 <span class="comment"> */</span>
-00618 APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, <span class="keywordtype">int</span> recurse);
-00619 <span class="comment"></span>
-00620 <span class="comment">/**</span>
-00621 <span class="comment"> * Lock a pool</span>
-00622 <span class="comment"> * @param pool The pool to lock</span>
-00623 <span class="comment"> * @param flag The flag</span>
-00624 <span class="comment"> */</span>
-00625 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_lock(apr_pool_t *pool, <span class="keywordtype">int</span> flag);
-00626
-00627 <span class="comment">/* @} */</span>
-00628
-00629 #else <span class="comment">/* APR_POOL_DEBUG or DOXYGEN */</span>
-00630
-00631 #ifdef apr_pool_join
-00632 #undef apr_pool_join
-00633 #endif
-00634 #define apr_pool_join(a,b)
-00635
-00636 #ifdef apr_pool_lock
-00637 #undef apr_pool_lock
-00638 #endif
-00639 #define apr_pool_lock(pool, lock)
-00640
-00641 #endif <span class="comment">/* APR_POOL_DEBUG or DOXYGEN */</span>
-00642 <span class="comment"></span>
-00643 <span class="comment">/** @} */</span>
-00644
-00645 #ifdef __cplusplus
-00646 }
-00647 #endif
-00648
-00649 #endif <span class="comment">/* !APR_POOLS_H */</span>
-</div></pre><hr size="1"><address style="align: right;"><small>Generated on Wed Sep 1 21:36:05 2004 for Apache Portable Runtime by
+00474
+00475 <span class="comment">/*</span>
+00476 <span class="comment"> * Cleanup</span>
+00477 <span class="comment"> *</span>
+00478 <span class="comment"> * Cleanups are performed in the reverse order they were registered. That is:</span>
+00479 <span class="comment"> * Last In, First Out. A cleanup function can safely allocate memory from</span>
+00480 <span class="comment"> * the pool that is being cleaned up. It can also safely register additional</span>
+00481 <span class="comment"> * cleanups which will be run LIFO, directly after the current cleanup</span>
+00482 <span class="comment"> * terminates. Cleanups have to take caution in calling functions that</span>
+00483 <span class="comment"> * create subpools. Subpools, created during cleanup will NOT automatically</span>
+00484 <span class="comment"> * be cleaned up. In other words, cleanups are to clean up after themselves.</span>
+00485 <span class="comment"> */</span>
+00486 <span class="comment"></span>
+00487 <span class="comment">/**</span>
+00488 <span class="comment"> * Register a function to be called when a pool is cleared or destroyed</span>
+00489 <span class="comment"> * @param p The pool register the cleanup with</span>
+00490 <span class="comment"> * @param data The data to pass to the cleanup function.</span>
+00491 <span class="comment"> * @param plain_cleanup The function to call when the pool is cleared</span>
+00492 <span class="comment"> * or destroyed</span>
+00493 <span class="comment"> * @param child_cleanup The function to call when a child process is about</span>
+00494 <span class="comment"> * to exec - this function is called in the child, obviously!</span>
+00495 <span class="comment"> */</span>
+00496 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_cleanup_register(
+00497 apr_pool_t *p,
+00498 const <span class="keywordtype">void</span> *data,
+00499 apr_status_t (*plain_cleanup)(<span class="keywordtype">void</span> *),
+00500 apr_status_t (*child_cleanup)(<span class="keywordtype">void</span> *));
+00501 <span class="comment"></span>
+00502 <span class="comment">/**</span>
+00503 <span class="comment"> * Remove a previously registered cleanup function</span>
+00504 <span class="comment"> * @param p The pool remove the cleanup from</span>
+00505 <span class="comment"> * @param data The data to remove from cleanup</span>
+00506 <span class="comment"> * @param cleanup The function to remove from cleanup</span>
+00507 <span class="comment"> * @remarks For some strange reason only the plain_cleanup is handled by this</span>
+00508 <span class="comment"> * function</span>
+00509 <span class="comment"> */</span>
+00510 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_cleanup_kill(apr_pool_t *p, const <span class="keywordtype">void</span> *data,
+00511 apr_status_t (*cleanup)(<span class="keywordtype">void</span> *));
+00512 <span class="comment"></span>
+00513 <span class="comment">/**</span>
+00514 <span class="comment"> * Replace the child cleanup of a previously registered cleanup</span>
+00515 <span class="comment"> * @param p The pool of the registered cleanup</span>
+00516 <span class="comment"> * @param data The data of the registered cleanup</span>
+00517 <span class="comment"> * @param plain_cleanup The plain cleanup function of the registered cleanup</span>
+00518 <span class="comment"> * @param child_cleanup The function to register as the child cleanup</span>
+00519 <span class="comment"> */</span>
+00520 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_child_cleanup_set(
+00521 apr_pool_t *p,
+00522 const <span class="keywordtype">void</span> *data,
+00523 apr_status_t (*plain_cleanup)(<span class="keywordtype">void</span> *),
+00524 apr_status_t (*child_cleanup)(<span class="keywordtype">void</span> *));
+00525 <span class="comment"></span>
+00526 <span class="comment">/**</span>
+00527 <span class="comment"> * Run the specified cleanup function immediately and unregister it. Use</span>
+00528 <span class="comment"> * @a data instead of the data that was registered with the cleanup.</span>
+00529 <span class="comment"> * @param p The pool remove the cleanup from</span>
+00530 <span class="comment"> * @param data The data to remove from cleanup</span>
+00531 <span class="comment"> * @param cleanup The function to remove from cleanup</span>
+00532 <span class="comment"> */</span>
+00533 APR_DECLARE(apr_status_t) apr_pool_cleanup_run(
+00534 apr_pool_t *p,
+00535 <span class="keywordtype">void</span> *data,
+00536 apr_status_t (*cleanup)(<span class="keywordtype">void</span> *));
+00537 <span class="comment"></span>
+00538 <span class="comment">/**</span>
+00539 <span class="comment"> * An empty cleanup function</span>
+00540 <span class="comment"> * @param data The data to cleanup</span>
+00541 <span class="comment"> */</span>
+00542 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(<span class="keywordtype">void</span> *data);
+00543
+00544 <span class="comment">/* Preparing for exec() --- close files, etc., but *don't* flush I/O</span>
+00545 <span class="comment"> * buffers, *don't* wait for subprocesses, and *don't* free any memory.</span>
+00546 <span class="comment"> */</span><span class="comment"></span>
+00547 <span class="comment">/**</span>
+00548 <span class="comment"> * Run all of the child_cleanups, so that any unnecessary files are</span>
+00549 <span class="comment"> * closed because we are about to exec a new program</span>
+00550 <span class="comment"> */</span>
+00551 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_cleanup_for_exec(<span class="keywordtype">void</span>);
+00552
+00553 <span class="comment"></span>
+00554 <span class="comment">/**</span>
+00555 <span class="comment"> * @defgroup PoolDebug Pool Debugging functions.</span>
+00556 <span class="comment"> *</span>
+00557 <span class="comment"> * pools have nested lifetimes -- sub_pools are destroyed when the</span>
+00558 <span class="comment"> * parent pool is cleared. We allow certain liberties with operations</span>
+00559 <span class="comment"> * on things such as tables (and on other structures in a more general</span>
+00560 <span class="comment"> * sense) where we allow the caller to insert values into a table which</span>
+00561 <span class="comment"> * were not allocated from the table's pool. The table's data will</span>
+00562 <span class="comment"> * remain valid as long as all the pools from which its values are</span>
+00563 <span class="comment"> * allocated remain valid.</span>
+00564 <span class="comment"> *</span>
+00565 <span class="comment"> * For example, if B is a sub pool of A, and you build a table T in</span>
+00566 <span class="comment"> * pool B, then it's safe to insert data allocated in A or B into T</span>
+00567 <span class="comment"> * (because B lives at most as long as A does, and T is destroyed when</span>
+00568 <span class="comment"> * B is cleared/destroyed). On the other hand, if S is a table in</span>
+00569 <span class="comment"> * pool A, it is safe to insert data allocated in A into S, but it</span>
+00570 <span class="comment"> * is *not safe* to insert data allocated from B into S... because</span>
+00571 <span class="comment"> * B can be cleared/destroyed before A is (which would leave dangling</span>
+00572 <span class="comment"> * pointers in T's data structures).</span>
+00573 <span class="comment"> *</span>
+00574 <span class="comment"> * In general we say that it is safe to insert data into a table T</span>
+00575 <span class="comment"> * if the data is allocated in any ancestor of T's pool. This is the</span>
+00576 <span class="comment"> * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor</span>
+00577 <span class="comment"> * relationships for all data inserted into tables. APR_POOL_DEBUG also</span>
+00578 <span class="comment"> * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other</span>
+00579 <span class="comment"> * folks to implement similar restrictions for their own data</span>
+00580 <span class="comment"> * structures.</span>
+00581 <span class="comment"> *</span>
+00582 <span class="comment"> * However, sometimes this ancestor requirement is inconvenient --</span>
+00583 <span class="comment"> * sometimes we're forced to create a sub pool (such as through</span>
[... 74 lines stripped ...]