1251875Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251875Speter * contributor license agreements. See the NOTICE file distributed with 3251875Speter * this work for additional information regarding copyright ownership. 4251875Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251875Speter * (the "License"); you may not use this file except in compliance with 6251875Speter * the License. You may obtain a copy of the License at 7251875Speter * 8251875Speter * http://www.apache.org/licenses/LICENSE-2.0 9251875Speter * 10251875Speter * Unless required by applicable law or agreed to in writing, software 11251875Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251875Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251875Speter * See the License for the specific language governing permissions and 14251875Speter * limitations under the License. 15251875Speter */ 16251875Speter 17251875Speter#ifndef APR_POOLS_H 18251875Speter#define APR_POOLS_H 19251875Speter 20251875Speter/** 21251875Speter * @file apr_pools.h 22251875Speter * @brief APR memory allocation 23251875Speter * 24251875Speter * Resource allocation routines... 25251875Speter * 26251875Speter * designed so that we don't have to keep track of EVERYTHING so that 27251875Speter * it can be explicitly freed later (a fundamentally unsound strategy --- 28251875Speter * particularly in the presence of die()). 29251875Speter * 30251875Speter * Instead, we maintain pools, and allocate items (both memory and I/O 31251875Speter * handlers) from the pools --- currently there are two, one for 32251875Speter * per-transaction info, and one for config info. When a transaction is 33251875Speter * over, we can delete everything in the per-transaction apr_pool_t without 34251875Speter * fear, and without thinking too hard about it either. 35251875Speter * 36251875Speter * Note that most operations on pools are not thread-safe: a single pool 37251875Speter * should only be accessed by a single thread at any given time. The one 38251875Speter * exception to this rule is creating a subpool of a given pool: one or more 39251875Speter * threads can safely create subpools at the same time that another thread 40251875Speter * accesses the parent pool. 41251875Speter */ 42251875Speter 43251875Speter#include "apr.h" 44251875Speter#include "apr_errno.h" 45251875Speter#include "apr_general.h" /* for APR_STRINGIFY */ 46251875Speter#define APR_WANT_MEMFUNC /**< for no good reason? */ 47251875Speter#include "apr_want.h" 48251875Speter 49251875Speter#ifdef __cplusplus 50251875Speterextern "C" { 51251875Speter#endif 52251875Speter 53251875Speter/** 54251875Speter * @defgroup apr_pools Memory Pool Functions 55251875Speter * @ingroup APR 56251875Speter * @{ 57251875Speter */ 58251875Speter 59251875Speter/** The fundamental pool type */ 60251875Spetertypedef struct apr_pool_t apr_pool_t; 61251875Speter 62251875Speter 63251875Speter/** 64251875Speter * Declaration helper macro to construct apr_foo_pool_get()s. 65251875Speter * 66251875Speter * This standardized macro is used by opaque (APR) data types to return 67251875Speter * the apr_pool_t that is associated with the data type. 68251875Speter * 69251875Speter * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the 70251875Speter * accessor function. A typical usage and result would be: 71251875Speter * <pre> 72251875Speter * APR_POOL_DECLARE_ACCESSOR(file); 73251875Speter * becomes: 74266735Speter * APR_DECLARE(apr_pool_t *) apr_file_pool_get(const apr_file_t *thefile); 75251875Speter * </pre> 76251875Speter * @remark Doxygen unwraps this macro (via doxygen.conf) to provide 77266735Speter * actual help for each specific occurrence of apr_foo_pool_get. 78251875Speter * @remark the linkage is specified for APR. It would be possible to expand 79251875Speter * the macros to support other linkages. 80251875Speter */ 81251875Speter#define APR_POOL_DECLARE_ACCESSOR(type) \ 82251875Speter APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ 83251875Speter (const apr_##type##_t *the##type) 84251875Speter 85251875Speter/** 86251875Speter * Implementation helper macro to provide apr_foo_pool_get()s. 87251875Speter * 88251875Speter * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to 89251875Speter * actually define the function. It assumes the field is named "pool". 90251875Speter */ 91251875Speter#define APR_POOL_IMPLEMENT_ACCESSOR(type) \ 92251875Speter APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ 93251875Speter (const apr_##type##_t *the##type) \ 94251875Speter { return the##type->pool; } 95251875Speter 96251875Speter 97251875Speter/** 98251875Speter * Pool debug levels 99251875Speter * 100251875Speter * <pre> 101251875Speter * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 102251875Speter * --------------------------------- 103251875Speter * | | | | | | | | x | General debug code enabled (useful in 104251875Speter * combination with --with-efence). 105251875Speter * 106251875Speter * | | | | | | | x | | Verbose output on stderr (report 107251875Speter * CREATE, CLEAR, DESTROY). 108251875Speter * 109251875Speter * | | | | x | | | | | Verbose output on stderr (report 110251875Speter * PALLOC, PCALLOC). 111251875Speter * 112251875Speter * | | | | | | x | | | Lifetime checking. On each use of a 113251875Speter * pool, check its lifetime. If the pool 114251875Speter * is out of scope, abort(). 115251875Speter * In combination with the verbose flag 116251875Speter * above, it will output LIFE in such an 117251875Speter * event prior to aborting. 118251875Speter * 119251875Speter * | | | | | x | | | | Pool owner checking. On each use of a 120251875Speter * pool, check if the current thread is the 121266735Speter * pool's owner. If not, abort(). In 122251875Speter * combination with the verbose flag above, 123251875Speter * it will output OWNER in such an event 124251875Speter * prior to aborting. Use the debug 125251875Speter * function apr_pool_owner_set() to switch 126266735Speter * a pool's ownership. 127251875Speter * 128251875Speter * When no debug level was specified, assume general debug mode. 129266735Speter * If level 0 was specified, debugging is switched off. 130251875Speter * </pre> 131251875Speter */ 132251875Speter#if defined(APR_POOL_DEBUG) 133251875Speter/* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */ 134251875Speter#if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1) 135251875Speter#undef APR_POOL_DEBUG 136251875Speter#define APR_POOL_DEBUG 1 137251875Speter#endif 138251875Speter#else 139251875Speter#define APR_POOL_DEBUG 0 140251875Speter#endif 141251875Speter 142251875Speter/** the place in the code where the particular function was called */ 143251875Speter#define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__) 144251875Speter 145251875Speter 146251875Speter 147251875Speter/** A function that is called when allocation fails. */ 148251875Spetertypedef int (*apr_abortfunc_t)(int retcode); 149251875Speter 150251875Speter/* 151251875Speter * APR memory structure manipulators (pools, tables, and arrays). 152251875Speter */ 153251875Speter 154251875Speter/* 155251875Speter * Initialization 156251875Speter */ 157251875Speter 158251875Speter/** 159251875Speter * Setup all of the internal structures required to use pools 160251875Speter * @remark Programs do NOT need to call this directly. APR will call this 161251875Speter * automatically from apr_initialize. 162251875Speter * @internal 163251875Speter */ 164251875SpeterAPR_DECLARE(apr_status_t) apr_pool_initialize(void); 165251875Speter 166251875Speter/** 167251875Speter * Tear down all of the internal structures required to use pools 168251875Speter * @remark Programs do NOT need to call this directly. APR will call this 169251875Speter * automatically from apr_terminate. 170251875Speter * @internal 171251875Speter */ 172251875SpeterAPR_DECLARE(void) apr_pool_terminate(void); 173251875Speter 174251875Speter 175251875Speter/* 176251875Speter * Pool creation/destruction 177251875Speter */ 178251875Speter 179251875Speter#include "apr_allocator.h" 180251875Speter 181251875Speter/** 182251875Speter * Create a new pool. 183251875Speter * @param newpool The pool we have just created. 184251875Speter * @param parent The parent pool. If this is NULL, the new pool is a root 185251875Speter * pool. If it is non-NULL, the new pool will inherit all 186251875Speter * of its parent pool's attributes, except the apr_pool_t will 187251875Speter * be a sub-pool. 188251875Speter * @param abort_fn A function to use if the pool cannot allocate more memory. 189251875Speter * @param allocator The allocator to use with the new pool. If NULL the 190251875Speter * allocator of the parent pool will be used. 191251875Speter * @remark This function is thread-safe, in the sense that multiple threads 192251875Speter * can safely create subpools of the same parent pool concurrently. 193251875Speter * Similarly, a subpool can be created by one thread at the same 194251875Speter * time that another thread accesses the parent pool. 195251875Speter */ 196251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool, 197251875Speter apr_pool_t *parent, 198251875Speter apr_abortfunc_t abort_fn, 199253734Speter apr_allocator_t *allocator) 200253734Speter __attribute__((nonnull(1))); 201251875Speter 202251875Speter/** 203251875Speter * Create a new pool. 204251875Speter * @deprecated @see apr_pool_create_unmanaged_ex. 205251875Speter */ 206251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t **newpool, 207251875Speter apr_abortfunc_t abort_fn, 208251875Speter apr_allocator_t *allocator); 209251875Speter 210251875Speter/** 211251875Speter * Create a new unmanaged pool. 212251875Speter * @param newpool The pool we have just created. 213251875Speter * @param abort_fn A function to use if the pool cannot allocate more memory. 214251875Speter * @param allocator The allocator to use with the new pool. If NULL a 215266735Speter * new allocator will be created with the new pool as owner. 216251875Speter * @remark An unmanaged pool is a special pool without a parent; it will 217251875Speter * NOT be destroyed upon apr_terminate. It must be explicitly 218251875Speter * destroyed by calling apr_pool_destroy, to prevent memory leaks. 219251875Speter * Use of this function is discouraged, think twice about whether 220251875Speter * you really really need it. 221266735Speter * @warning Any child cleanups registered against the new pool, or 222266735Speter * against sub-pools thereof, will not be executed during an 223266735Speter * invocation of apr_proc_create(), so resources created in an 224266735Speter * "unmanaged" pool hierarchy will leak to child processes. 225251875Speter */ 226251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool, 227251875Speter apr_abortfunc_t abort_fn, 228253734Speter apr_allocator_t *allocator) 229253734Speter __attribute__((nonnull(1))); 230251875Speter 231251875Speter/** 232251875Speter * Debug version of apr_pool_create_ex. 233251875Speter * @param newpool @see apr_pool_create. 234251875Speter * @param parent @see apr_pool_create. 235251875Speter * @param abort_fn @see apr_pool_create. 236251875Speter * @param allocator @see apr_pool_create. 237251875Speter * @param file_line Where the function is called from. 238251875Speter * This is usually APR_POOL__FILE_LINE__. 239251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 240266735Speter * Call this directly if you have your apr_pool_create_ex 241251875Speter * calls in a wrapper function and wish to override 242251875Speter * the file_line argument to reflect the caller of 243251875Speter * your wrapper function. If you do not have 244251875Speter * apr_pool_create_ex in a wrapper, trust the macro 245251875Speter * and don't call apr_pool_create_ex_debug directly. 246251875Speter */ 247251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool, 248251875Speter apr_pool_t *parent, 249251875Speter apr_abortfunc_t abort_fn, 250251875Speter apr_allocator_t *allocator, 251253734Speter const char *file_line) 252253734Speter __attribute__((nonnull(1))); 253251875Speter 254251875Speter#if APR_POOL_DEBUG 255251875Speter#define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \ 256251875Speter apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \ 257251875Speter APR_POOL__FILE_LINE__) 258251875Speter#endif 259251875Speter 260251875Speter/** 261251875Speter * Debug version of apr_pool_create_core_ex. 262251875Speter * @deprecated @see apr_pool_create_unmanaged_ex_debug. 263251875Speter */ 264251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool, 265251875Speter apr_abortfunc_t abort_fn, 266251875Speter apr_allocator_t *allocator, 267251875Speter const char *file_line); 268251875Speter 269251875Speter/** 270251875Speter * Debug version of apr_pool_create_unmanaged_ex. 271251875Speter * @param newpool @see apr_pool_create_unmanaged. 272251875Speter * @param abort_fn @see apr_pool_create_unmanaged. 273251875Speter * @param allocator @see apr_pool_create_unmanaged. 274251875Speter * @param file_line Where the function is called from. 275251875Speter * This is usually APR_POOL__FILE_LINE__. 276251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 277266735Speter * Call this directly if you have your apr_pool_create_unmanaged_ex 278251875Speter * calls in a wrapper function and wish to override 279251875Speter * the file_line argument to reflect the caller of 280251875Speter * your wrapper function. If you do not have 281251875Speter * apr_pool_create_core_ex in a wrapper, trust the macro 282251875Speter * and don't call apr_pool_create_core_ex_debug directly. 283251875Speter */ 284251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool, 285251875Speter apr_abortfunc_t abort_fn, 286251875Speter apr_allocator_t *allocator, 287253734Speter const char *file_line) 288253734Speter __attribute__((nonnull(1))); 289251875Speter 290251875Speter#if APR_POOL_DEBUG 291251875Speter#define apr_pool_create_core_ex(newpool, abort_fn, allocator) \ 292251875Speter apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 293251875Speter APR_POOL__FILE_LINE__) 294251875Speter 295251875Speter#define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator) \ 296251875Speter apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 297251875Speter APR_POOL__FILE_LINE__) 298251875Speter 299251875Speter#endif 300251875Speter 301251875Speter/** 302251875Speter * Create a new pool. 303251875Speter * @param newpool The pool we have just created. 304251875Speter * @param parent The parent pool. If this is NULL, the new pool is a root 305251875Speter * pool. If it is non-NULL, the new pool will inherit all 306251875Speter * of its parent pool's attributes, except the apr_pool_t will 307251875Speter * be a sub-pool. 308251875Speter * @remark This function is thread-safe, in the sense that multiple threads 309251875Speter * can safely create subpools of the same parent pool concurrently. 310251875Speter * Similarly, a subpool can be created by one thread at the same 311251875Speter * time that another thread accesses the parent pool. 312251875Speter */ 313251875Speter#if defined(DOXYGEN) 314251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool, 315251875Speter apr_pool_t *parent); 316251875Speter#else 317251875Speter#if APR_POOL_DEBUG 318251875Speter#define apr_pool_create(newpool, parent) \ 319251875Speter apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \ 320251875Speter APR_POOL__FILE_LINE__) 321251875Speter#else 322251875Speter#define apr_pool_create(newpool, parent) \ 323251875Speter apr_pool_create_ex(newpool, parent, NULL, NULL) 324251875Speter#endif 325251875Speter#endif 326251875Speter 327251875Speter/** 328266735Speter * Create a new unmanaged pool. 329251875Speter * @param newpool The pool we have just created. 330251875Speter */ 331251875Speter#if defined(DOXYGEN) 332251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool); 333251875SpeterAPR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool); 334251875Speter#else 335251875Speter#if APR_POOL_DEBUG 336251875Speter#define apr_pool_create_core(newpool) \ 337251875Speter apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 338251875Speter APR_POOL__FILE_LINE__) 339251875Speter#define apr_pool_create_unmanaged(newpool) \ 340251875Speter apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 341251875Speter APR_POOL__FILE_LINE__) 342251875Speter#else 343251875Speter#define apr_pool_create_core(newpool) \ 344251875Speter apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 345251875Speter#define apr_pool_create_unmanaged(newpool) \ 346251875Speter apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 347251875Speter#endif 348251875Speter#endif 349251875Speter 350251875Speter/** 351251875Speter * Find the pool's allocator 352251875Speter * @param pool The pool to get the allocator from. 353251875Speter */ 354253734SpeterAPR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool) 355253734Speter __attribute__((nonnull(1))); 356251875Speter 357251875Speter/** 358251875Speter * Clear all memory in the pool and run all the cleanups. This also destroys all 359251875Speter * subpools. 360251875Speter * @param p The pool to clear 361251875Speter * @remark This does not actually free the memory, it just allows the pool 362251875Speter * to re-use this memory for the next allocation. 363251875Speter * @see apr_pool_destroy() 364251875Speter */ 365253734SpeterAPR_DECLARE(void) apr_pool_clear(apr_pool_t *p) __attribute__((nonnull(1))); 366251875Speter 367251875Speter/** 368251875Speter * Debug version of apr_pool_clear. 369251875Speter * @param p See: apr_pool_clear. 370251875Speter * @param file_line Where the function is called from. 371251875Speter * This is usually APR_POOL__FILE_LINE__. 372251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 373266735Speter * Call this directly if you have your apr_pool_clear 374251875Speter * calls in a wrapper function and wish to override 375251875Speter * the file_line argument to reflect the caller of 376251875Speter * your wrapper function. If you do not have 377251875Speter * apr_pool_clear in a wrapper, trust the macro 378251875Speter * and don't call apr_pool_destroy_clear directly. 379251875Speter */ 380251875SpeterAPR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p, 381253734Speter const char *file_line) 382253734Speter __attribute__((nonnull(1))); 383251875Speter 384251875Speter#if APR_POOL_DEBUG 385251875Speter#define apr_pool_clear(p) \ 386251875Speter apr_pool_clear_debug(p, APR_POOL__FILE_LINE__) 387251875Speter#endif 388251875Speter 389251875Speter/** 390251875Speter * Destroy the pool. This takes similar action as apr_pool_clear() and then 391251875Speter * frees all the memory. 392251875Speter * @param p The pool to destroy 393251875Speter * @remark This will actually free the memory 394251875Speter */ 395253734SpeterAPR_DECLARE(void) apr_pool_destroy(apr_pool_t *p) __attribute__((nonnull(1))); 396251875Speter 397251875Speter/** 398251875Speter * Debug version of apr_pool_destroy. 399251875Speter * @param p See: apr_pool_destroy. 400251875Speter * @param file_line Where the function is called from. 401251875Speter * This is usually APR_POOL__FILE_LINE__. 402251875Speter * @remark Only available when APR_POOL_DEBUG is defined. 403266735Speter * Call this directly if you have your apr_pool_destroy 404251875Speter * calls in a wrapper function and wish to override 405251875Speter * the file_line argument to reflect the caller of 406251875Speter * your wrapper function. If you do not have 407251875Speter * apr_pool_destroy in a wrapper, trust the macro 408251875Speter * and don't call apr_pool_destroy_debug directly. 409251875Speter */ 410251875SpeterAPR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p, 411253734Speter const char *file_line) 412253734Speter __attribute__((nonnull(1))); 413251875Speter 414251875Speter#if APR_POOL_DEBUG 415251875Speter#define apr_pool_destroy(p) \ 416251875Speter apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__) 417251875Speter#endif 418251875Speter 419251875Speter 420251875Speter/* 421251875Speter * Memory allocation 422251875Speter */ 423251875Speter 424251875Speter/** 425251875Speter * Allocate a block of memory from a pool 426251875Speter * @param p The pool to allocate from 427251875Speter * @param size The amount of memory to allocate 428251875Speter * @return The allocated memory 429251875Speter */ 430253734SpeterAPR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size) 431253734Speter#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) 432253734Speter __attribute__((alloc_size(2))) 433253734Speter#endif 434253734Speter __attribute__((nonnull(1))); 435251875Speter 436251875Speter/** 437251875Speter * Debug version of apr_palloc 438251875Speter * @param p See: apr_palloc 439251875Speter * @param size See: apr_palloc 440251875Speter * @param file_line Where the function is called from. 441251875Speter * This is usually APR_POOL__FILE_LINE__. 442251875Speter * @return See: apr_palloc 443251875Speter */ 444251875SpeterAPR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size, 445253734Speter const char *file_line) 446253734Speter#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) 447253734Speter __attribute__((alloc_size(2))) 448253734Speter#endif 449253734Speter __attribute__((nonnull(1))); 450251875Speter 451251875Speter#if APR_POOL_DEBUG 452251875Speter#define apr_palloc(p, size) \ 453251875Speter apr_palloc_debug(p, size, APR_POOL__FILE_LINE__) 454251875Speter#endif 455251875Speter 456251875Speter/** 457251875Speter * Allocate a block of memory from a pool and set all of the memory to 0 458251875Speter * @param p The pool to allocate from 459251875Speter * @param size The amount of memory to allocate 460251875Speter * @return The allocated memory 461251875Speter */ 462251875Speter#if defined(DOXYGEN) 463251875SpeterAPR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size); 464251875Speter#elif !APR_POOL_DEBUG 465251875Speter#define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size) 466251875Speter#endif 467251875Speter 468251875Speter/** 469251875Speter * Debug version of apr_pcalloc 470251875Speter * @param p See: apr_pcalloc 471251875Speter * @param size See: apr_pcalloc 472251875Speter * @param file_line Where the function is called from. 473251875Speter * This is usually APR_POOL__FILE_LINE__. 474251875Speter * @return See: apr_pcalloc 475251875Speter */ 476251875SpeterAPR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size, 477253734Speter const char *file_line) 478253734Speter __attribute__((nonnull(1))); 479251875Speter 480251875Speter#if APR_POOL_DEBUG 481251875Speter#define apr_pcalloc(p, size) \ 482251875Speter apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__) 483251875Speter#endif 484251875Speter 485251875Speter 486251875Speter/* 487251875Speter * Pool Properties 488251875Speter */ 489251875Speter 490251875Speter/** 491251875Speter * Set the function to be called when an allocation failure occurs. 492251875Speter * @remark If the program wants APR to exit on a memory allocation error, 493251875Speter * then this function can be called to set the callback to use (for 494251875Speter * performing cleanup and then exiting). If this function is not called, 495251875Speter * then APR will return an error and expect the calling program to 496251875Speter * deal with the error accordingly. 497251875Speter */ 498251875SpeterAPR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc, 499253734Speter apr_pool_t *pool) 500253734Speter __attribute__((nonnull(2))); 501251875Speter 502251875Speter/** 503251875Speter * Get the abort function associated with the specified pool. 504251875Speter * @param pool The pool for retrieving the abort function. 505251875Speter * @return The abort function for the given pool. 506251875Speter */ 507253734SpeterAPR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool) 508253734Speter __attribute__((nonnull(1))); 509251875Speter 510251875Speter/** 511251875Speter * Get the parent pool of the specified pool. 512251875Speter * @param pool The pool for retrieving the parent pool. 513251875Speter * @return The parent of the given pool. 514251875Speter */ 515253734SpeterAPR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool) 516253734Speter __attribute__((nonnull(1))); 517251875Speter 518251875Speter/** 519251875Speter * Determine if pool a is an ancestor of pool b. 520251875Speter * @param a The pool to search 521251875Speter * @param b The pool to search for 522251875Speter * @return True if a is an ancestor of b, NULL is considered an ancestor 523251875Speter * of all pools. 524251875Speter * @remark if compiled with APR_POOL_DEBUG, this function will also 525251875Speter * return true if A is a pool which has been guaranteed by the caller 526251875Speter * (using apr_pool_join) to have a lifetime at least as long as some 527251875Speter * ancestor of pool B. 528251875Speter */ 529251875SpeterAPR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b); 530251875Speter 531251875Speter/** 532251875Speter * Tag a pool (give it a name) 533251875Speter * @param pool The pool to tag 534251875Speter * @param tag The tag 535251875Speter */ 536253734SpeterAPR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag) 537253734Speter __attribute__((nonnull(1))); 538251875Speter 539251875Speter 540251875Speter/* 541251875Speter * User data management 542251875Speter */ 543251875Speter 544251875Speter/** 545251875Speter * Set the data associated with the current pool 546251875Speter * @param data The user data associated with the pool. 547251875Speter * @param key The key to use for association 548251875Speter * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 549251875Speter * @param pool The current pool 550251875Speter * @warning The data to be attached to the pool should have a life span 551251875Speter * at least as long as the pool it is being attached to. 552251875Speter * 553251875Speter * Users of APR must take EXTREME care when choosing a key to 554251875Speter * use for their data. It is possible to accidentally overwrite 555251875Speter * data by choosing a key that another part of the program is using. 556251875Speter * Therefore it is advised that steps are taken to ensure that unique 557251875Speter * keys are used for all of the userdata objects in a particular pool 558251875Speter * (the same key in two different pools or a pool and one of its 559251875Speter * subpools is okay) at all times. Careful namespace prefixing of 560251875Speter * key names is a typical way to help ensure this uniqueness. 561251875Speter * 562251875Speter */ 563253734SpeterAPR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data, 564253734Speter const char *key, 565253734Speter apr_status_t (*cleanup)(void *), 566253734Speter apr_pool_t *pool) 567253734Speter __attribute__((nonnull(2,4))); 568251875Speter 569251875Speter/** 570251875Speter * Set the data associated with the current pool 571251875Speter * @param data The user data associated with the pool. 572251875Speter * @param key The key to use for association 573251875Speter * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 574251875Speter * @param pool The current pool 575251875Speter * @note same as apr_pool_userdata_set(), except that this version doesn't 576251875Speter * make a copy of the key (this function is useful, for example, when 577251875Speter * the key is a string literal) 578251875Speter * @warning This should NOT be used if the key could change addresses by 579251875Speter * any means between the apr_pool_userdata_setn() call and a 580251875Speter * subsequent apr_pool_userdata_get() on that key, such as if a 581251875Speter * static string is used as a userdata key in a DSO and the DSO could 582251875Speter * be unloaded and reloaded between the _setn() and the _get(). You 583251875Speter * MUST use apr_pool_userdata_set() in such cases. 584251875Speter * @warning More generally, the key and the data to be attached to the 585251875Speter * pool should have a life span at least as long as the pool itself. 586251875Speter * 587251875Speter */ 588251875SpeterAPR_DECLARE(apr_status_t) apr_pool_userdata_setn( 589253734Speter const void *data, const char *key, 590253734Speter apr_status_t (*cleanup)(void *), 591253734Speter apr_pool_t *pool) 592253734Speter __attribute__((nonnull(2,4))); 593251875Speter 594251875Speter/** 595251875Speter * Return the data associated with the current pool. 596251875Speter * @param data The user data associated with the pool. 597251875Speter * @param key The key for the data to retrieve 598251875Speter * @param pool The current pool. 599251875Speter */ 600251875SpeterAPR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key, 601253734Speter apr_pool_t *pool) 602253734Speter __attribute__((nonnull(1,2,3))); 603251875Speter 604251875Speter 605251875Speter/** 606251875Speter * @defgroup PoolCleanup Pool Cleanup Functions 607251875Speter * 608251875Speter * Cleanups are performed in the reverse order they were registered. That is: 609251875Speter * Last In, First Out. A cleanup function can safely allocate memory from 610251875Speter * the pool that is being cleaned up. It can also safely register additional 611251875Speter * cleanups which will be run LIFO, directly after the current cleanup 612251875Speter * terminates. Cleanups have to take caution in calling functions that 613251875Speter * create subpools. Subpools, created during cleanup will NOT automatically 614251875Speter * be cleaned up. In other words, cleanups are to clean up after themselves. 615251875Speter * 616251875Speter * @{ 617251875Speter */ 618251875Speter 619251875Speter/** 620251875Speter * Register a function to be called when a pool is cleared or destroyed 621266735Speter * @param p The pool to register the cleanup with 622251875Speter * @param data The data to pass to the cleanup function. 623251875Speter * @param plain_cleanup The function to call when the pool is cleared 624251875Speter * or destroyed 625251875Speter * @param child_cleanup The function to call when a child process is about 626251875Speter * to exec - this function is called in the child, obviously! 627251875Speter */ 628251875SpeterAPR_DECLARE(void) apr_pool_cleanup_register( 629253734Speter apr_pool_t *p, const void *data, 630253734Speter apr_status_t (*plain_cleanup)(void *), 631253734Speter apr_status_t (*child_cleanup)(void *)) 632253734Speter __attribute__((nonnull(3,4))); 633251875Speter 634251875Speter/** 635251875Speter * Register a function to be called when a pool is cleared or destroyed. 636251875Speter * 637266735Speter * Unlike apr_pool_cleanup_register which registers a cleanup 638266735Speter * that is called AFTER all subpools are destroyed, this function registers 639266735Speter * a function that will be called before any of the subpools are destroyed. 640251875Speter * 641266735Speter * @param p The pool to register the cleanup with 642251875Speter * @param data The data to pass to the cleanup function. 643251875Speter * @param plain_cleanup The function to call when the pool is cleared 644251875Speter * or destroyed 645251875Speter */ 646251875SpeterAPR_DECLARE(void) apr_pool_pre_cleanup_register( 647253734Speter apr_pool_t *p, const void *data, 648253734Speter apr_status_t (*plain_cleanup)(void *)) 649253734Speter __attribute__((nonnull(3))); 650251875Speter 651251875Speter/** 652251875Speter * Remove a previously registered cleanup function. 653251875Speter * 654251875Speter * The cleanup most recently registered with @a p having the same values of 655251875Speter * @a data and @a cleanup will be removed. 656251875Speter * 657251875Speter * @param p The pool to remove the cleanup from 658251875Speter * @param data The data of the registered cleanup 659251875Speter * @param cleanup The function to remove from cleanup 660251875Speter * @remarks For some strange reason only the plain_cleanup is handled by this 661251875Speter * function 662251875Speter */ 663251875SpeterAPR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data, 664253734Speter apr_status_t (*cleanup)(void *)) 665253734Speter __attribute__((nonnull(3))); 666251875Speter 667251875Speter/** 668251875Speter * Replace the child cleanup function of a previously registered cleanup. 669251875Speter * 670251875Speter * The cleanup most recently registered with @a p having the same values of 671251875Speter * @a data and @a plain_cleanup will have the registered child cleanup 672251875Speter * function replaced with @a child_cleanup. 673251875Speter * 674251875Speter * @param p The pool of the registered cleanup 675251875Speter * @param data The data of the registered cleanup 676251875Speter * @param plain_cleanup The plain cleanup function of the registered cleanup 677251875Speter * @param child_cleanup The function to register as the child cleanup 678251875Speter */ 679251875SpeterAPR_DECLARE(void) apr_pool_child_cleanup_set( 680253734Speter apr_pool_t *p, const void *data, 681253734Speter apr_status_t (*plain_cleanup)(void *), 682253734Speter apr_status_t (*child_cleanup)(void *)) 683253734Speter __attribute__((nonnull(3,4))); 684251875Speter 685251875Speter/** 686251875Speter * Run the specified cleanup function immediately and unregister it. 687251875Speter * 688251875Speter * The cleanup most recently registered with @a p having the same values of 689251875Speter * @a data and @a cleanup will be removed and @a cleanup will be called 690251875Speter * with @a data as the argument. 691251875Speter * 692251875Speter * @param p The pool to remove the cleanup from 693251875Speter * @param data The data to remove from cleanup 694251875Speter * @param cleanup The function to remove from cleanup 695251875Speter */ 696253734SpeterAPR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data, 697253734Speter apr_status_t (*cleanup)(void *)) 698253734Speter __attribute__((nonnull(3))); 699251875Speter 700251875Speter/** 701251875Speter * An empty cleanup function. 702251875Speter * 703251875Speter * Passed to apr_pool_cleanup_register() when no cleanup is required. 704251875Speter * 705251875Speter * @param data The data to cleanup, will not be used by this function. 706251875Speter */ 707251875SpeterAPR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data); 708251875Speter 709251875Speter/** 710251875Speter * Run all registered child cleanups, in preparation for an exec() 711251875Speter * call in a forked child -- close files, etc., but *don't* flush I/O 712251875Speter * buffers, *don't* wait for subprocesses, and *don't* free any 713251875Speter * memory. 714251875Speter */ 715251875SpeterAPR_DECLARE(void) apr_pool_cleanup_for_exec(void); 716251875Speter 717251875Speter/** @} */ 718251875Speter 719251875Speter/** 720251875Speter * @defgroup PoolDebug Pool Debugging functions. 721251875Speter * 722251875Speter * pools have nested lifetimes -- sub_pools are destroyed when the 723251875Speter * parent pool is cleared. We allow certain liberties with operations 724251875Speter * on things such as tables (and on other structures in a more general 725251875Speter * sense) where we allow the caller to insert values into a table which 726251875Speter * were not allocated from the table's pool. The table's data will 727251875Speter * remain valid as long as all the pools from which its values are 728251875Speter * allocated remain valid. 729251875Speter * 730251875Speter * For example, if B is a sub pool of A, and you build a table T in 731251875Speter * pool B, then it's safe to insert data allocated in A or B into T 732251875Speter * (because B lives at most as long as A does, and T is destroyed when 733251875Speter * B is cleared/destroyed). On the other hand, if S is a table in 734251875Speter * pool A, it is safe to insert data allocated in A into S, but it 735251875Speter * is *not safe* to insert data allocated from B into S... because 736251875Speter * B can be cleared/destroyed before A is (which would leave dangling 737251875Speter * pointers in T's data structures). 738251875Speter * 739251875Speter * In general we say that it is safe to insert data into a table T 740251875Speter * if the data is allocated in any ancestor of T's pool. This is the 741251875Speter * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor 742251875Speter * relationships for all data inserted into tables. APR_POOL_DEBUG also 743251875Speter * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other 744251875Speter * folks to implement similar restrictions for their own data 745251875Speter * structures. 746251875Speter * 747251875Speter * However, sometimes this ancestor requirement is inconvenient -- 748251875Speter * sometimes it's necessary to create a sub pool where the sub pool is 749251875Speter * guaranteed to have the same lifetime as the parent pool. This is a 750251875Speter * guarantee implemented by the *caller*, not by the pool code. That 751251875Speter * is, the caller guarantees they won't destroy the sub pool 752251875Speter * individually prior to destroying the parent pool. 753251875Speter * 754251875Speter * In this case the caller must call apr_pool_join() to indicate this 755251875Speter * guarantee to the APR_POOL_DEBUG code. 756251875Speter * 757251875Speter * These functions are only implemented when #APR_POOL_DEBUG is set. 758251875Speter * 759251875Speter * @{ 760251875Speter */ 761251875Speter#if APR_POOL_DEBUG || defined(DOXYGEN) 762251875Speter/** 763251875Speter * Guarantee that a subpool has the same lifetime as the parent. 764251875Speter * @param p The parent pool 765251875Speter * @param sub The subpool 766251875Speter */ 767253734SpeterAPR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub) 768253734Speter __attribute__((nonnull(2))); 769251875Speter 770251875Speter/** 771251875Speter * Find a pool from something allocated in it. 772251875Speter * @param mem The thing allocated in the pool 773251875Speter * @return The pool it is allocated in 774251875Speter */ 775251875SpeterAPR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem); 776251875Speter 777251875Speter/** 778251875Speter * Report the number of bytes currently in the pool 779251875Speter * @param p The pool to inspect 780251875Speter * @param recurse Recurse/include the subpools' sizes 781251875Speter * @return The number of bytes 782251875Speter */ 783253734SpeterAPR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse) 784253734Speter __attribute__((nonnull(1))); 785251875Speter 786251875Speter/** 787251875Speter * Lock a pool 788251875Speter * @param pool The pool to lock 789251875Speter * @param flag The flag 790251875Speter */ 791251875SpeterAPR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag); 792251875Speter 793251875Speter/* @} */ 794251875Speter 795251875Speter#else /* APR_POOL_DEBUG or DOXYGEN */ 796251875Speter 797251875Speter#ifdef apr_pool_join 798251875Speter#undef apr_pool_join 799251875Speter#endif 800251875Speter#define apr_pool_join(a,b) 801251875Speter 802251875Speter#ifdef apr_pool_lock 803251875Speter#undef apr_pool_lock 804251875Speter#endif 805251875Speter#define apr_pool_lock(pool, lock) 806251875Speter 807251875Speter#endif /* APR_POOL_DEBUG or DOXYGEN */ 808251875Speter 809251875Speter/** @} */ 810251875Speter 811251875Speter#ifdef __cplusplus 812251875Speter} 813251875Speter#endif 814251875Speter 815251875Speter#endif /* !APR_POOLS_H */ 816