diff options
39 files changed, 894 insertions, 686 deletions
diff --git a/docs/doxygen.conf b/docs/doxygen.conf index 36b623264..2efb55476 100644 --- a/docs/doxygen.conf +++ b/docs/doxygen.conf @@ -13,14 +13,21 @@ EXPAND_ONLY_PREDEF=YES # not sure why this doesn't work as EXPAND_AS_DEFINED, it should! PREDEFINED="APR_DECLARE(x)=x" \ "APR_DECLARE_NONSTD(x)=x" \ + "APR_DECLARE_DATA" \ + "APR_POOL_DECLARE_ACCESSOR(x)=apr_pool_t* apr_##x##_pool_get (const apr_##x##_t *the##x)" \ + "APR_DECLARE_INHERIT_SET(x)=apr_status_t apr_##x##_inherit_set(apr_##x##_t *the##x)" \ + "APR_DECLARE_INHERIT_UNSET(x)=apr_status_t apr_##x##_inherit_unset(apr_##x##_t *the##x)" \ "APR_HAS_THREADS" \ + "__attribute__(x)=" \ DOXYGEN= OPTIMIZE_OUTPUT_FOR_C=YES -FULL_PATH_NAMES=YES +FULL_PATH_NAMES=NO # some autoconf guru needs to make configure set this correctly... -STRIP_FROM_PATH=/home/rbb/httpd-2.0/srclib/apr +# in the meantime, simply listing the headers should be alright +STRIP_FROM_PATH=/buildpath/apr -EXCLUDE_PATTERNS="*/test/*" \ +EXCLUDE_PATTERNS="*/acconfig.h" \ + "*/test/*" \ "*/arch/*" diff --git a/include/apr.h.in b/include/apr.h.in index cb65477ae..74c232945 100644 --- a/include/apr.h.in +++ b/include/apr.h.in @@ -65,17 +65,20 @@ * This is the Win32 specific version of apr.h. It is copied from * apr.hw when building the apr.dsp or libapr.dsp project. */ - /** - * @file include/apr.h - * @brief APR APR Main Include + * @file apr.h + * @brief APR Platform Definitions * @remark This is a generated header generated from include/apr.h.in by * ./configure, or copied from include/apr.hw or include/apr.hnw * for Win32 or Netware by those build environments, respectively. */ /** - * @defgroup APR APR Functions + * @defgroup APR Apache Portability Runtime library + * @{ + */ +/** + * @defgroup apr_platform Platform Definitions * @{ */ @@ -136,6 +139,54 @@ #define APR_HAVE_TIME_H @timeh@ #define APR_HAVE_UNISTD_H @unistdh@ +/** @} */ + +/* We don't include our conditional headers within the doxyblocks + * or the extern "C" namespace + */ + +#if APR_HAVE_SYS_TYPES_H +#include <sys/types.h> +#endif + +#if APR_HAVE_SYS_SOCKET_H +#include <sys/socket.h> +#endif + +#if APR_HAVE_STDINT_H +#include <stdint.h> +#endif + +#if APR_HAVE_SYS_WAIT_H +#include <sys/wait.h> +#endif + +#ifdef OS2 +#define INCL_DOS +#define INCL_DOSERRORS +#include <os2.h> +#endif + +/* header files for PATH_MAX, _POSIX_PATH_MAX */ +#if APR_HAVE_LIMITS_H +#include <limits.h> +#else +#if APR_HAVE_SYS_SYSLIMITS_H +#include <sys/syslimits.h> +#endif +#endif + + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @addtogroup apr_platform + * @ingroup APR + * @{ + */ + #define APR_HAVE_SHMEM_MMAP_TMP @havemmaptmp@ #define APR_HAVE_SHMEM_MMAP_SHM @havemmapshm@ #define APR_HAVE_SHMEM_MMAP_ZERO @havemmapzero@ @@ -190,18 +241,6 @@ #define APR_HAVE_UNION_SEMUN @have_union_semun@ #define APR_HAVE_SCTP @have_sctp@ -#if APR_HAVE_SYS_TYPES_H -#include <sys/types.h> -#endif - -#if APR_HAVE_SYS_SOCKET_H -#include <sys/socket.h> -#endif - -#if APR_HAVE_STDINT_H -#include <stdint.h> -#endif - /* APR Feature Macros */ #define APR_HAS_SHARED_MEMORY @sharedmem@ #define APR_HAS_THREADS @threads@ @@ -271,48 +310,60 @@ typedef @socklen_t_value@ apr_socklen_t; /* Mechanisms to properly type numeric literals */ @int64_literal@ - /* Definitions that APR programs need to work properly. */ -#define APR_THREAD_FUNC - -/** - * APR_DECLARE_EXPORT is defined when building the APR dynamic library, - * so that all public symbols are exported. - * - * APR_DECLARE_STATIC is defined when including the APR public headers, - * to provide static linkage when the dynamic library may be unavailable. - * - * APR_DECLARE_STATIC and APR_DECLARE_EXPORT are left undefined when - * including the APR public headers, to import and link the symbols from the - * dynamic APR library and assure appropriate indirection and calling - * conventions at compile time. +/** + * Thread callbacks from APR functions must be declared with APR_THREAD_FUNC, + * so that they follow the platform's calling convention. + * @example + */ +/** void* APR_THREAD_FUNC my_thread_entry_fn(apr_thread_t *thd, void *data); */ +#define APR_THREAD_FUNC /** * The public APR functions are declared with APR_DECLARE(), so they may * use the most appropriate calling convention. Public APR functions with * variable arguments must use APR_DECLARE_NONSTD(). * - * @deffunc APR_DECLARE(rettype) apr_func(args); + * @remark Both the declaration and implementations must use the same macro. + * @example + */ +/** APR_DECLARE(rettype) apr_func(args) + * @see APR_DECLARE_NONSTD @see APR_DECLARE_DATA + * @remark Note that when APR compiles the library itself, it passes the + * symbol -DAPR_DECLARE_EXPORT to the compiler on some platforms (e.g. Win32) + * to export public symbols from the dynamic library build.\n + * The user must define the APR_DECLARE_STATIC when compiling to target + * the static APR library on some platforms (e.g. Win32.) The public symbols + * are neither exported nor imported when APR_DECLARE_STATIC is defined.\n + * By default, compiling an application and including the APR public + * headers, without defining APR_DECLARE_STATIC, will prepare the code to be + * linked to the dynamic library. */ -#define APR_DECLARE(type) type +#define APR_DECLARE(type) type /** * The public APR functions using variable arguments are declared with - * AP_DECLARE(), as they must use the C language calling convention. - * - * @deffunc APR_DECLARE_NONSTD(rettype) apr_func(args, ...); + * APR_DECLARE_NONSTD(), as they must follow the C language calling convention. + * @see APR_DECLARE @see APR_DECLARE_DATA + * @remark Both the declaration and implementations must use the same macro. + * @example + */ +/** APR_DECLARE_NONSTD(rettype) apr_func(args, ...); */ #define APR_DECLARE_NONSTD(type) type /** * The public APR variables are declared with AP_MODULE_DECLARE_DATA. * This assures the appropriate indirection is invoked at compile time. - * - * @deffunc APR_DECLARE_DATA type apr_variable; - * @tip APR_DECLARE_DATA extern type apr_variable; syntax is required for - * declarations within headers to properly import the variable. + * @see APR_DECLARE @see APR_DECLARE_NONSTD + * @remark Note that the declaration and implementations use different forms, + * but both must include the macro. + * @example + */ +/** extern APR_DECLARE_DATA type apr_variable;\n + * APR_DECLARE_DATA type apr_variable = value; */ #define APR_DECLARE_DATA @@ -352,11 +403,8 @@ typedef @socklen_t_value@ apr_socklen_t; /* Local machine definition for console and log output. */ #define APR_EOL_STR "@eolstr@" -#if APR_HAVE_SYS_WAIT_H - -/* We have a POSIX wait interface */ -#include <sys/wait.h> +#if APR_HAVE_SYS_WAIT_H #ifdef WEXITSTATUS #define apr_wait_t int #else @@ -366,21 +414,6 @@ typedef @socklen_t_value@ apr_socklen_t; #endif /* !WEXITSTATUS */ #endif /* HAVE_SYS_WAIT_H */ -#ifdef OS2 -#define INCL_DOS -#define INCL_DOSERRORS -#include <os2.h> -#endif - -/* header files for PATH_MAX, _POSIX_PATH_MAX */ -#if APR_HAVE_LIMITS_H -#include <limits.h> -#else -#if APR_HAVE_SYS_SYSLIMITS_H -#include <sys/syslimits.h> -#endif -#endif - #if defined(PATH_MAX) #define APR_PATH_MAX PATH_MAX #elif defined(_POSIX_PATH_MAX) @@ -388,6 +421,11 @@ typedef @socklen_t_value@ apr_socklen_t; #else #error no decision has been made on APR_PATH_MAX for your platform #endif + /** @} */ +#ifdef __cplusplus +} +#endif + #endif /* APR_H */ diff --git a/include/apr.hnw b/include/apr.hnw index cc6d65164..bbe4bf7bc 100644 --- a/include/apr.hnw +++ b/include/apr.hnw @@ -67,8 +67,8 @@ */ /** - * @file include/apr.h - * @brief APR APR Main Include + * @file apr.h + * @brief APR Platform Definitions * @remark This is a generated header generated from include/apr.h.in by * ./configure, or copied from include/apr.hw or include/apr.hnw * for Win32 or Netware by those build environments, respectively. @@ -76,11 +76,6 @@ #if defined(NETWARE) || defined(DOXYGEN) -/** - * @defgroup APR APR Functions - * @{ - */ - #include <sys/types.h> #include <stddef.h> #include <stdio.h> @@ -93,13 +88,28 @@ #include <nks/synch.h> #include <nks/time.h> #include <signal.h> - - #include <novsock2.h> +#include <sys/types.h> + +#ifdef NW_BUILD_IPV6 +#include <novtcpip.h> +#endif #define _POSIX_THREAD_SAFE_FUNCTIONS 1 #define READDIR_IS_THREAD_SAFE 1 +/* Keep #include'd headers from within the __cplusplus or doxyblocks */ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @defgroup apr_platform Platform Definitions + * @ingroup APR + * @{ + */ + #define APR_INLINE #define APR_HAS_INLINE 0 #define __attribute__(__x) @@ -201,14 +211,6 @@ #define APR_HAVE_UNION_SEMUN 0 #define APR_HAVE_SCTP 0 -#if APR_HAVE_SYS_TYPES_H -#include <sys/types.h> -#endif - -#if APR_HAVE_IPV6 -#include <novtcpip.h> -#endif - /* APR Feature Macros */ #define APR_HAS_SHARED_MEMORY 0 #define APR_HAS_THREADS 1 @@ -284,43 +286,58 @@ typedef int apr_socklen_t; /* Definitions that APR programs need to work properly. */ -#define APR_THREAD_FUNC - -/** - * APR_DECLARE_EXPORT is defined when building the APR dynamic library, - * so that all public symbols are exported. - * - * APR_DECLARE_STATIC is defined when including the APR public headers, - * to provide static linkage when the dynamic library may be unavailable. - * - * APR_DECLARE_STATIC and APR_DECLARE_EXPORT are left undefined when - * including the APR public headers, to import and link the symbols from the - * dynamic APR library and assure appropriate indirection and calling - * conventions at compile time. +/** + * Thread callbacks from APR functions must be declared with APR_THREAD_FUNC, + * so that they follow the platform's calling convention. + * @example + */ +/** void* APR_THREAD_FUNC my_thread_entry_fn(apr_thread_t *thd, void *data); */ +#define APR_THREAD_FUNC /** * The public APR functions are declared with APR_DECLARE(), so they may * use the most appropriate calling convention. Public APR functions with * variable arguments must use APR_DECLARE_NONSTD(). * - * @deffunc APR_DECLARE(rettype) apr_func(args); + * @remark Both the declaration and implementations must use the same macro. + * @example + */ +/** APR_DECLARE(rettype) apr_func(args) + * @see APR_DECLARE_NONSTD @see APR_DECLARE_DATA + * @remark Note that when APR compiles the library itself, it passes the + * symbol -DAPR_DECLARE_EXPORT to the compiler on some platforms (e.g. Win32) + * to export public symbols from the dynamic library build.\n + * The user must define the APR_DECLARE_STATIC when compiling to target + * the static APR library on some platforms (e.g. Win32.) The public symbols + * are neither exported nor imported when APR_DECLARE_STATIC is defined.\n + * By default, compiling an application and including the APR public + * headers, without defining APR_DECLARE_STATIC, will prepare the code to be + * linked to the dynamic library. */ -#define APR_DECLARE(type) type +#define APR_DECLARE(type) type + /** * The public APR functions using variable arguments are declared with - * AP_DECLARE(), as they must use the C language calling convention. - * - * @deffunc APR_DECLARE_NONSTD(rettype) apr_func(args, ...); + * APR_DECLARE_NONSTD(), as they must follow the C language calling convention. + * @see APR_DECLARE @see APR_DECLARE_DATA + * @remark Both the declaration and implementations must use the same macro. + * @example + */ +/** APR_DECLARE_NONSTD(rettype) apr_func(args, ...); */ #define APR_DECLARE_NONSTD(type) type + /** * The public APR variables are declared with AP_MODULE_DECLARE_DATA. * This assures the appropriate indirection is invoked at compile time. - * - * @deffunc APR_DECLARE_DATA type apr_variable; - * @tip extern APR_DECLARE_DATA type apr_variable; syntax is required for - * declarations within headers to properly import the variable. + * @see APR_DECLARE @see APR_DECLARE_NONSTD + * @remark Note that the declaration and implementations use different forms, + * but both must include the macro. + * @example + */ +/** extern APR_DECLARE_DATA type apr_variable;\n + * APR_DECLARE_DATA type apr_variable = value; */ #define APR_DECLARE_DATA @@ -348,6 +365,10 @@ typedef int apr_wait_t; /** @} */ +#ifdef __cplusplus +} +#endif + #endif /* NETWARE */ #endif /* APR_H */ diff --git a/include/apr.hw b/include/apr.hw index 3e1526c00..e01f85925 100644 --- a/include/apr.hw +++ b/include/apr.hw @@ -66,10 +66,9 @@ * apr.hw by the apr.dsp and libapr.dsp projects. */ - /** - * @file include/apr.h - * @brief Basic APR header for WIN32 + * @file apr.h + * @brief APR Platform Definitions * @remark This is a generated header generated from include/apr.h.in by * ./configure, or copied from include/apr.hw or include/apr.hnw * for Win32 or Netware by those build environments, respectively. @@ -77,21 +76,12 @@ #if defined(WIN32) || defined(DOXYGEN) -/** - * @defgroup APR APR Functions - * @{ - */ - /* Ignore most warnings (back down to /W3) for poorly constructed headers */ #if defined(_MSC_VER) && _MSC_VER >= 1200 #pragma warning(push, 3) #endif -#ifdef __cplusplus -extern "C" { -#endif - /* disable or reduce the frequency of... * C4057: indirection to slightly different base types * C4075: slight indirection changes (unsigned short* vs short[]) @@ -103,8 +93,52 @@ extern "C" { */ #pragma warning(disable: 4100 4127 4201 4514; once: 4057 4075 4244) +/* Has windows.h already been included? If so, our preferences don't matter, + * but we will still need the winsock things no matter what was included. + * If not, include a restricted set of windows headers to our tastes. + */ +#ifndef _WINDOWS_ +#ifndef WIN32_LEAN_AND_MEAN +#define WIN32_LEAN_AND_MEAN +#endif +#ifndef _WIN32_WINNT + +/* Restrict the server to a subset of Windows NT 4.0 header files by default + */ +#define _WIN32_WINNT 0x0400 +#endif +#ifndef NOUSER +#define NOUSER +#endif +#ifndef NOMCX +#define NOMCX +#endif +#ifndef NOIME +#define NOIME +#endif +#include <windows.h> +/* + * Add a _very_few_ declarations missing from the restricted set of headers + * (If this list becomes extensive, re-enable the required headers above!) + * winsock headers were excluded by WIN32_LEAN_AND_MEAN, so include them now + */ +#define SW_HIDE 0 +#ifndef _WIN32_WCE +#include <winsock2.h> +#include <mswsock.h> +#else +#include <winsock.h> +#endif +#endif /* !_WINDOWS_ */ + +/** + * @defgroup apr_platform Platform Definitions + * @ingroup APR + * @{ + */ + #define APR_INLINE __inline -#define APR_HAS_INLINE 1 +#define APR_HAS_INLINE 1 #define __attribute__(__x) #define NO_USE_SIGACTION @@ -231,43 +265,11 @@ extern "C" { #define APR_HAVE_STRNICMP 0 #endif -/* Has windows.h already been included? If so, our preferences don't matter, - * but we will still need the winsock things no matter what was included. - * If not, include a restricted set of windows headers to our tastes. - */ -#ifndef _WINDOWS_ -#ifndef WIN32_LEAN_AND_MEAN -#define WIN32_LEAN_AND_MEAN -#endif -#ifndef _WIN32_WINNT +/** @} */ -/* Restrict the server to a subset of Windows NT 4.0 header files by default - */ -#define _WIN32_WINNT 0x0400 -#endif -#ifndef NOUSER -#define NOUSER -#endif -#ifndef NOMCX -#define NOMCX -#endif -#ifndef NOIME -#define NOIME -#endif -#include <windows.h> -/* - * Add a _very_few_ declarations missing from the restricted set of headers - * (If this list becomes extensive, re-enable the required headers above!) - * winsock headers were excluded by WIN32_LEAN_AND_MEAN, so include them now +/* We don't include our conditional headers within the doxyblocks + * or the extern "C" namespace */ -#define SW_HIDE 0 -#ifndef _WIN32_WCE -#include <winsock2.h> -#include <mswsock.h> -#else -#include <winsock.h> -#endif -#endif /* !_WINDOWS_ */ #if APR_HAVE_STDLIB_H #include <stdlib.h> @@ -287,6 +289,19 @@ extern "C" { #if APR_HAVE_PROCESS_H #include <process.h> #endif +#if APR_HAVE_IPV6 +#include <ws2tcpip.h> +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @addtogroup apr_platform + * @ingroup APR + * @{ + */ /* APR Feature Macros */ #define APR_HAS_SHARED_MEMORY 1 @@ -370,7 +385,6 @@ typedef int gid_t; #if APR_HAVE_IPV6 -#include <ws2tcpip.h> /* Appears in later flavors, not the originals. */ #ifndef in_addr6 @@ -382,51 +396,69 @@ typedef int gid_t; ( (*(const apr_uint64_t *)(const void *)(&(a)->s6_addr[0]) == 0) \ && (*(const apr_uint32_t *)(const void *)(&(a)->s6_addr[8]) == ntohl(0x0000ffff))) #endif -#endif +#endif /* APR_HAS_IPV6 */ /* Definitions that APR programs need to work properly. */ -#define APR_THREAD_FUNC __stdcall - -/** - * APR_DECLARE_EXPORT is defined when building the APR dynamic library, - * so that all public symbols are exported. - * - * APR_DECLARE_STATIC is defined when including the APR public headers, - * to provide static linkage when the dynamic library may be unavailable. - * - * APR_DECLARE_STATIC and APR_DECLARE_EXPORT are left undefined when - * including the APR public headers, to import and link the symbols from the - * dynamic APR library and assure appropriate indirection and calling - * conventions at compile time. +/** + * Thread callbacks from APR functions must be declared with APR_THREAD_FUNC, + * so that they follow the platform's calling convention. + * @example + */ +/** void* APR_THREAD_FUNC my_thread_entry_fn(apr_thread_t *thd, void *data); */ +#define APR_THREAD_FUNC __stdcall + + +#if defined(DOXYGEN) || !defined(WIN32) -#if !defined(WIN32) /** * The public APR functions are declared with APR_DECLARE(), so they may * use the most appropriate calling convention. Public APR functions with * variable arguments must use APR_DECLARE_NONSTD(). * - * @deffunc APR_DECLARE(rettype) apr_func(args); + * @remark Both the declaration and implementations must use the same macro. + * @example */ -#define APR_DECLARE(type) type +/** APR_DECLARE(rettype) apr_func(args) + * @see APR_DECLARE_NONSTD @see APR_DECLARE_DATA + * @remark Note that when APR compiles the library itself, it passes the + * symbol -DAPR_DECLARE_EXPORT to the compiler on some platforms (e.g. Win32) + * to export public symbols from the dynamic library build.\n + * The user must define the APR_DECLARE_STATIC when compiling to target + * the static APR library on some platforms (e.g. Win32.) The public symbols + * are neither exported nor imported when APR_DECLARE_STATIC is defined.\n + * By default, compiling an application and including the APR public + * headers, without defining APR_DECLARE_STATIC, will prepare the code to be + * linked to the dynamic library. + */ +#define APR_DECLARE(type) type + /** * The public APR functions using variable arguments are declared with - * AP_DECLARE(), as they must use the C language calling convention. - * - * @deffunc APR_DECLARE_NONSTD(rettype) apr_func(args, ...); + * APR_DECLARE_NONSTD(), as they must follow the C language calling convention. + * @see APR_DECLARE @see APR_DECLARE_DATA + * @remark Both the declaration and implementations must use the same macro. + * @example + */ +/** APR_DECLARE_NONSTD(rettype) apr_func(args, ...); */ #define APR_DECLARE_NONSTD(type) type + /** * The public APR variables are declared with AP_MODULE_DECLARE_DATA. * This assures the appropriate indirection is invoked at compile time. - * - * @deffunc APR_DECLARE_DATA type apr_variable; - * @tip extern APR_DECLARE_DATA type apr_variable; syntax is required for - * declarations within headers to properly import the variable. + * @see APR_DECLARE @see APR_DECLARE_NONSTD + * @remark Note that the declaration and implementations use different forms, + * but both must include the macro. + * @example + */ +/** extern APR_DECLARE_DATA type apr_variable;\n + * APR_DECLARE_DATA type apr_variable = value; */ #define APR_DECLARE_DATA + #elif defined(APR_DECLARE_STATIC) #define APR_DECLARE(type) type __stdcall #define APR_DECLARE_NONSTD(type) type @@ -495,6 +527,8 @@ struct iovec { #define APR_PATH_MAX MAX_PATH #endif +/** @} */ + #ifdef __cplusplus } #endif @@ -505,8 +539,6 @@ struct iovec { #pragma warning(pop) #endif -/** @} */ - #endif /* WIN32 */ #endif /* APR_H */ diff --git a/include/apr_allocator.h b/include/apr_allocator.h index 551fa1b1b..a07cd6557 100644 --- a/include/apr_allocator.h +++ b/include/apr_allocator.h @@ -55,26 +55,27 @@ #ifndef APR_ALLOCATOR_H #define APR_ALLOCATOR_H -#ifdef __cplusplus -extern "C" { -#endif - /** * @file apr_allocator.h - * @brief APR memory allocation - * - */ -/** - * @defgroup APR_Pool_allocator Allocator - * @ingroup APR_Pool - * @{ + * @brief APR Internal Memory Allocation */ - #include "apr.h" #include "apr_errno.h" -#define APR_WANT_MEMFUNC +#define APR_WANT_MEMFUNC /**< For no good reason? */ #include "apr_want.h" +#include "apr_pools.h" +#include "apr_thread_mutex.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @defgroup apr_allocator Internal Memory Allocation + * @ingroup APR + * @{ + */ /** the allocator structure */ typedef struct apr_allocator_t apr_allocator_t; @@ -130,8 +131,6 @@ APR_DECLARE(void) apr_allocator_free(apr_allocator_t *allocator, apr_memnode_t *memnode); -#include "apr_pools.h" - /** * Set the owner of the allocator * @param allocator The allocator to set the owner for @@ -173,8 +172,6 @@ APR_DECLARE(void) apr_allocator_max_free_set(apr_allocator_t *allocator, APR_DECLARE(void) apr_allocator_set_max_free(apr_allocator_t *allocator, apr_size_t size); -#include "apr_thread_mutex.h" - #if APR_HAS_THREADS /** * Set a mutex for the allocator to use @@ -202,6 +199,7 @@ APR_DECLARE(apr_thread_mutex_t *) apr_allocator_get_mutex( #endif /* APR_HAS_THREADS */ /** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_atomic.h b/include/apr_atomic.h index be419bf56..586903644 100644 --- a/include/apr_atomic.h +++ b/include/apr_atomic.h @@ -59,20 +59,28 @@ #ifndef APR_ATOMIC_H #define APR_ATOMIC_H -#ifdef __cplusplus -extern "C" { -#endif - -#include "apr.h" -#include "apr_pools.h" - /** * @file apr_atomic.h * @brief APR Atomic Operations */ + +#include "apr.h" +#include "apr_pools.h" + +/* Platform includes for atomics */ +#if defined(NETWARE) || defined(__MVS__) /* OS/390 */ +#include <stdlib.h> +#elif defined(__FreeBSD__) +#include <machine/atomic.h> +#endif + +#ifdef __cplusplus +extern "C" { +#endif + /** - * @defgroup APR_Atomic Atomic operations - * @ingroup APR + * @defgroup apr_atomic Atomic Operations + * @ingroup APR * @{ */ @@ -169,7 +177,6 @@ typedef LONG apr_atomic_t; #elif defined(NETWARE) -#include <stdlib.h> #define apr_atomic_t unsigned long #define apr_atomic_add(mem, val) atomic_add(mem,val) @@ -197,8 +204,6 @@ inline void *apr_atomic_casptr(void **mem, void *with, const void *cmp) #elif defined(__FreeBSD__) -#include <machine/atomic.h> - #define apr_atomic_t apr_uint32_t #define apr_atomic_add(mem, val) atomic_add_int(mem,val) #define apr_atomic_dec(mem) atomic_subtract_int(mem,1) @@ -259,7 +264,7 @@ apr_uint32_t apr_atomic_sub_sparc(volatile apr_atomic_t *mem, apr_uint32_t sub); apr_uint32_t apr_atomic_cas_sparc(volatile apr_uint32_t *mem, long with, long cmp); #elif defined(__MVS__) /* OS/390 */ -#include <stdlib.h> + #define apr_atomic_t cs_t apr_int32_t apr_atomic_add(volatile apr_atomic_t *mem, apr_int32_t val); @@ -358,6 +363,9 @@ void *apr_atomic_casptr(volatile void **mem, void *with, const void *cmp); #endif /* APR_ATOMIC_NEED_DEFAULT_INIT */ #endif /* !DOXYGEN */ + +/** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_compat.h b/include/apr_compat.h index 3651eba80..e51b79cf1 100644 --- a/include/apr_compat.h +++ b/include/apr_compat.h @@ -1,13 +1,73 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2003 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ + #ifndef APR_COMPAT_H #define APR_COMPAT_H -/** + + /** * @file apr_compat.h - * @brief APR Compatibilty Functions - * @deprecated These functions are only present for historical purposes + * @brief APR Legacy Apache 1.3 Compatibility + * @deprecated These defines are only present for historical purposes */ + /** - * @defgroup APR_compat 1.3 Compatibility Functions - * @ingroup APR + * @defgroup apr_compat APR Legacy Apache 1.3 Compatibility + * @ingroup APR * @{ */ @@ -207,5 +267,7 @@ #define AP_OVERLAP_TABLES_MERGE APR_OVERLAP_TABLES_MERGE /** @deprecated @see APR_OVERLAP_TABLES_SET */ #define AP_OVERLAP_TABLES_SET APR_OVERLAP_TABLES_SET + /** @} */ + #endif /* APR_COMPAT_H */ diff --git a/include/apr_dso.h b/include/apr_dso.h index 1efd3c563..5a5d73884 100644 --- a/include/apr_dso.h +++ b/include/apr_dso.h @@ -55,36 +55,34 @@ #ifndef APR_DSO_DOT_H #define APR_DSO_DOT_H -#include "apr.h" -#include "apr_pools.h" -#include "apr_errno.h" /** * @file apr_dso.h * @brief APR Dynamic Object Handling Routines */ - -/** - * @defgroup APR_DSO Dynamic Object Handling - * @ingroup APR - * @{ - */ +#include "apr.h" +#include "apr_pools.h" +#include "apr_errno.h" #ifdef __cplusplus extern "C" { #endif +/** + * @defgroup apr_dso Dynamic Object Handling + * @ingroup APR + * @{ + */ + #if APR_HAS_DSO || defined(DOXYGEN) /** * Structure for referencing dynamic objects - * @defvar apr_dso_handle_t */ typedef struct apr_dso_handle_t apr_dso_handle_t; /** * Structure for referencing symbols from dynamic objects - * @defvar apr_dso_handle_sym_t */ typedef void * apr_dso_handle_sym_t; @@ -123,8 +121,10 @@ APR_DECLARE(const char *) apr_dso_error(apr_dso_handle_t *dso, char *buf, apr_si #endif /* APR_HAS_DSO */ +/** @} */ + #ifdef __cplusplus } #endif -/** @} */ + #endif diff --git a/include/apr_env.h b/include/apr_env.h index f04d62044..e8c092e3c 100644 --- a/include/apr_env.h +++ b/include/apr_env.h @@ -58,12 +58,6 @@ * @file apr_env.h * @brief APR Environment functions */ -/** - * @defgroup APR_ENV Functions for manupulating the environment - * @ingroup APR_ENV - * @{ - */ - #include "apr_errno.h" #include "apr_pools.h" @@ -72,11 +66,16 @@ extern "C" { #endif /* __cplusplus */ /** + * @defgroup apr_env Functions for manupulating the environment + * @ingroup APR + * @{ + */ + +/** * Get the value of an environment variable * @param value the returned value, allocated from @a pool * @param envvar the name of the environment variable * @param pool where to allocate @a value and any temporary storage from - * @deffunc apr_status_t apr_env_get(char **value, const char *envvar, apr_pool_t *pool) */ APR_DECLARE(apr_status_t) apr_env_get(char **value, const char *envvar, apr_pool_t *pool); @@ -86,7 +85,6 @@ APR_DECLARE(apr_status_t) apr_env_get(char **value, const char *envvar, * @param envvar the name of the environment variable * @param value the value to set * @param pool where to allocate temporary storage from - * @deffunc apr_status_t apr_env_get(const char *envvar, const char *value, apr_pool_t *pool) */ APR_DECLARE(apr_status_t) apr_env_set(const char *envvar, const char *value, apr_pool_t *pool); @@ -95,13 +93,13 @@ APR_DECLARE(apr_status_t) apr_env_set(const char *envvar, const char *value, * Delete a variable from the environment * @param envvar the name of the environment variable * @param pool where to allocate temporary storage from - * @deffunc apr_status_t apr_env_delete(const char *envvar, apr_pool_t *pool) */ APR_DECLARE(apr_status_t) apr_env_delete(const char *envvar, apr_pool_t *pool); +/** @} */ #ifdef __cplusplus } #endif -/** @} */ + #endif /* ! APR_ENV_H */ diff --git a/include/apr_errno.h b/include/apr_errno.h index 74f34a038..ca7ecddb9 100644 --- a/include/apr_errno.h +++ b/include/apr_errno.h @@ -55,6 +55,11 @@ #ifndef APR_ERRNO_H #define APR_ERRNO_H +/** + * @file apr_errno.h + * @brief APR Error Codes + */ + #include "apr.h" #if APR_HAVE_ERRNO_H @@ -66,12 +71,8 @@ extern "C" { #endif /* __cplusplus */ /** - * @file apr_errno.h - * @brief APR Error Codes - */ -/** - * @defgroup APR_Error_Codes Error Codes - * @ingroup APR + * @defgroup apr_errno Error Codes + * @ingroup APR * @{ */ @@ -111,48 +112,40 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, */ #define APR_TO_OS_ERROR(e) (e == 0 ? APR_SUCCESS : e - APR_OS_START_SYSERR) -/** - * @def apr_get_os_error() +/** @def apr_get_os_error() * @return apr_status_t the last platform error, folded into apr_status_t, on most platforms * @remark This retrieves errno, or calls a GetLastError() style function, and * folds it with APR_FROM_OS_ERROR. Some platforms (such as OS2) have no * such mechanism, so this call may be unsupported. Do NOT use this * call for socket errors from socket, send, recv etc! */ -#define apr_get_os_error() -/** +/** @def apr_set_os_error(e) * Reset the last platform error, unfolded from an apr_status_t, on some platforms - * @param statcode The OS error folded in a prior call to APR_FROM_OS_ERROR() - * @deffunc void apr_set_os_error(apr_status_t statcode) - * @tip Warning: macro implementation; the statcode argument may be evaluated + * @param e The OS error folded in a prior call to APR_FROM_OS_ERROR() + * @warning This is a macro implementation; the statcode argument may be evaluated * multiple times. If the statcode was not created by apr_get_os_error * or APR_FROM_OS_ERROR, the results are undefined. This macro sets * errno, or calls a SetLastError() style function, unfolding statcode * with APR_TO_OS_ERROR. Some platforms (such as OS2) have no such * mechanism, so this call may be unsupported. */ -#define apr_set_os_error(statcode) -/** +/** @def apr_get_netos_error() * Return the last socket error, folded into apr_status_t, on all platforms - * @deffunc apr_status_t apr_get_netos_error() - * @tip This retrieves errno or calls a GetLastSocketError() style function, + * @remark This retrieves errno or calls a GetLastSocketError() style function, * and folds it with APR_FROM_OS_ERROR. */ -#define apr_get_netos_error() -/** +/** @def apr_set_netos_error(e) * Reset the last socket error, unfolded from an apr_status_t - * @param socketcode The socket error folded in a prior call to APR_FROM_OS_ERROR() - * @deffunc void apr_set_os_error(apr_status_t statcode) - * @tip Warning: macro implementation; the statcode argument may be evaluated + * @param e The socket error folded in a prior call to APR_FROM_OS_ERROR() + * @warning This is a macro implementation; the statcode argument may be evaluated * multiple times. If the statcode was not created by apr_get_os_error * or APR_FROM_OS_ERROR, the results are undefined. This macro sets * errno, or calls a WSASetLastError() style function, unfolding * socketcode with APR_TO_OS_ERROR. */ -#define apr_set_netos_error(socketcode) #endif /* defined(DOXYGEN) */ @@ -203,9 +196,8 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, /** no error. @see APR_STATUS_IS_SUCCESS */ #define APR_SUCCESS 0 -/* APR ERROR VALUES */ /** - * @defgroup APRErrorValues Error Values + * @defgroup APR_Error APR Error Values * <PRE> * <b>APR ERROR VALUES</b> * APR_ENOSTAT APR was unable to perform a stat on the file @@ -315,17 +307,18 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, #define APR_ESYMNOTFOUND (APR_OS_START_ERROR + 26) /** @see APR_STATUS_IS_EPROC_UNKNOWN */ #define APR_EPROC_UNKNOWN (APR_OS_START_ERROR + 27) +/** @} */ -/* APR ERROR VALUE TESTS */ /** - * @defgroup APRErrorValueTests Error Value Tests - * @remark For any particular error condition, more than one of these tests + * @defgroup APR_STATUS_IS Status Value Tests + * @warning For any particular error condition, more than one of these tests * may match. This is because platform-specific error codes may not * always match the semantics of the POSIX codes these tests (and the * correcponding APR error codes) are named after. A notable example * are the APR_STATUS_IS_ENOENT and APR_STATUS_IS_ENOTDIR tests on * Win32 platforms. The programmer should always be aware of this and * adjust the order of the tests accordingly. + * @{ */ /** * APR was unable to perform a stat on the file @@ -402,7 +395,12 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, /** The given process was not recognized by APR. */ #define APR_STATUS_IS_EPROC_UNKNOWN(s) ((s) == APR_EPROC_UNKNOWN) -/* APR STATUS VALUES */ +/** @} */ + +/** + * @addtogroup APR_Error + * @{ + */ /** @see APR_STATUS_IS_INCHILD */ #define APR_INCHILD (APR_OS_START_STATUS + 1) /** @see APR_STATUS_IS_INPARENT */ @@ -447,18 +445,11 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, #define APR_EMISMATCH (APR_OS_START_STATUS + 24) /** @see APR_STATUS_IS_EBUSY */ #define APR_EBUSY (APR_OS_START_STATUS + 25) +/** @} */ -/** - * @defgroup aprerr_status Status Value Tests +/** + * @addtogroup APR_STATUS_IS * @{ - */ -/** - * @param status The APR_status code to check. - * @param statcode The apr status code to test. - * @tip Warning: macro implementations; the statcode argument may be - * evaluated multiple times. To test for APR_EOF, always test - * APR_STATUS_IS_EOF(statcode) because platform-specific codes are - * not necessarily translated into the corresponding APR_Estatus code. */ /** * Program is currently executing in the child @@ -602,9 +593,11 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, * more than one error code */ #define APR_STATUS_IS_EBUSY(s) ((s) == APR_EBUSY) + /** @} */ -/** - * @defgroup aprerrcanonical Canonical Errors + +/** + * @addtogroup APR_Error APR Error Values * @{ */ /* APR CANONICAL ERROR VALUES */ @@ -800,8 +793,8 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, #endif /** @} */ -/** @} */ -#if defined(OS2) + +#if defined(OS2) && !defined(DOXYGEN) #define APR_FROM_OS_ERROR(e) (e == 0 ? APR_SUCCESS : e + APR_OS_START_SYSERR) #define APR_TO_OS_ERROR(e) (e == 0 ? APR_SUCCESS : e - APR_OS_START_SYSERR) @@ -971,7 +964,7 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, { SOCEPIPE, EPIPE } */ -#elif defined(WIN32) /* endif defined(OS2) */ +#elif defined(WIN32) && !defined(DOXYGEN) /* !defined(OS2) */ #define APR_FROM_OS_ERROR(e) (e == 0 ? APR_SUCCESS : e + APR_OS_START_SYSERR) #define APR_TO_OS_ERROR(e) (e == 0 ? APR_SUCCESS : e - APR_OS_START_SYSERR) @@ -1082,7 +1075,7 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, #define APR_STATUS_IS_ENOTEMPTY(s) ((s) == APR_ENOTEMPTY \ || (s) == APR_OS_START_SYSERR + ERROR_DIR_NOT_EMPTY) -#elif defined(NETWARE) /* !def OS2 || WIN32 */ +#elif defined(NETWARE) && !defined(DOXYGEN) /* !defined(OS2) && !defined(WIN32) */ #define APR_FROM_OS_ERROR(e) (e) #define APR_TO_OS_ERROR(e) (e) @@ -1137,7 +1130,7 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, #define APR_STATUS_IS_EXDEV(s) ((s) == APR_EXDEV) #define APR_STATUS_IS_ENOTEMPTY(s) ((s) == APR_ENOTEMPTY) -#else /* endif defined(NETWARE) */ +#else /* !defined(NETWARE) && !defined(OS2) && !defined(WIN32) */ /* * os error codes are clib error codes @@ -1152,11 +1145,15 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, */ #define apr_get_netos_error() (errno) #define apr_set_netos_error(e) (errno = (e)) +/** @} */ +/** + * @addtogroup APR_STATUS_IS + * @{ + */ /** no error */ -#define APR_STATUS_IS_SUCCESS(s) ((s) == APR_SUCCESS) +#define APR_STATUS_IS_SUCCESS(s) ((s) == APR_SUCCESS) -/* APR CANONICAL ERROR TESTS */ /** permission denied */ #define APR_STATUS_IS_EACCES(s) ((s) == APR_EACCES) /** file exists */ @@ -1236,8 +1233,9 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf, /** Directory Not Empty */ #define APR_STATUS_IS_ENOTEMPTY(s) ((s) == APR_ENOTEMPTY || \ (s) == APR_EEXIST) +/** @} */ -#endif /* !def OS2 || WIN32 */ +#endif /* !defined(NETWARE) && !defined(OS2) && !defined(WIN32) */ /** @} */ diff --git a/include/apr_file_info.h b/include/apr_file_info.h index 7e69aea13..a8914fa07 100644 --- a/include/apr_file_info.h +++ b/include/apr_file_info.h @@ -55,6 +55,11 @@ #ifndef APR_FILE_INFO_H #define APR_FILE_INFO_H +/** + * @file apr_file_info.h + * @brief APR File Information + */ + #include "apr.h" #include "apr_user.h" #include "apr_pools.h" @@ -69,13 +74,10 @@ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ + /** - * @file apr_file_info.h - * @brief APR File handling - */ -/** - * @defgroup APR_File_Handle File Handling Functions - * @ingroup APR + * @defgroup apr_file_info File Information + * @ingroup APR * @{ */ @@ -108,7 +110,7 @@ typedef enum { } apr_filetype_e; /** - * @defgroup APR_file_handle_permission File Permissions flags + * @defgroup apr_file_permissions File Permissions flags * @{ */ @@ -134,18 +136,15 @@ typedef enum { /** * Structure for referencing directories. - * @defvar apr_dir_t */ typedef struct apr_dir_t apr_dir_t; /** * Structure for determining file permissions. - * @defvar apr_fileperms_t */ typedef apr_int32_t apr_fileperms_t; #if (defined WIN32) || (defined NETWARE) /** * Structure for determining the inode of the file. - * @defvar apr_ino_t */ typedef apr_uint64_t apr_ino_t; /** @@ -162,7 +161,7 @@ typedef dev_t apr_dev_t; #endif /** - * @defgroup APR_File_Info Stat Functions + * @defgroup apr_file_stat Stat Functions * @{ */ /** file info structure */ @@ -266,7 +265,7 @@ APR_DECLARE(apr_status_t) apr_lstat(apr_finfo_t *finfo, const char *fname, apr_int32_t wanted, apr_pool_t *cont); /** @} */ /** - * @defgroup APR_DIRECTORY Directory Manipulation Functions + * @defgroup apr_dir Directory Manipulation Functions * @{ */ @@ -304,7 +303,7 @@ APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir); /** @} */ /** - * @defgroup apr_filepath FilePath Manipulation operations + * @defgroup apr_filepath Filepath Manipulation Functions * @{ */ @@ -334,10 +333,9 @@ APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir); * trailing slash if a directory */ #define APR_FILEPATH_TRUENAME 0x20 -/** @} */ + /** * Extract the rootpath from the given filepath - * @ingroup apr_filepath * @param rootpath the root file path returned with APR_SUCCESS or APR_EINCOMPLETE * @param filepath the pathname to parse for its root component * @param flags the desired rules to apply, from @@ -346,7 +344,6 @@ APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir); * APR_FILEPATH_TRUENAME Tests that the root exists, and makes it proper * </PRE> * @param p the pool to allocate the new path string from - * @deffunc apr_status_t apr_filepath_root(const char **rootpath, const char **inpath, apr_int32_t flags, apr_pool_t *p) * @remark on return, filepath points to the first non-root character in the * given filepath. In the simplest example, given a filepath of "/foo", * returns the rootpath of "/" and filepath points at "foo". This is far @@ -367,13 +364,11 @@ APR_DECLARE(apr_status_t) apr_filepath_root(const char **rootpath, /** * Merge additional file path onto the previously processed rootpath - * @ingroup apr_filepath * @param newpath the merged paths returned * @param rootpath the root file path (NULL uses the current working path) * @param addpath the path to add to the root path * @param flags the desired APR_FILEPATH_ rules to apply when merging * @param p the pool to allocate the new path string from - * @deffunc apr_status_t apr_filepath_merge(char **newpath, const char *rootpath, const char *addpath, apr_int32_t flags, apr_pool_t *p) * @remark if the flag APR_FILEPATH_TRUENAME is given, and the addpath * contains wildcard characters ('*', '?') on platforms that don't support * such characters within filenames, the paths will be merged, but the @@ -388,11 +383,9 @@ APR_DECLARE(apr_status_t) apr_filepath_merge(char **newpath, /** * Split a search path into separate components - * @ingroup apr_filepath * @param pathelts the returned components of the search path * @param liststr the search path (e.g., <tt>getenv("PATH")</tt>) * @param p the pool to allocate the array and path components from - * @deffunc apr_status_t apr_filepath_list_split(apr_array_header_t **pathelts, const char *liststr, apr_pool_t *p) * @remark empty path componenta do not become part of @a pathelts. * @remark the path separator in @a liststr is system specific; * e.g., ':' on Unix, ';' on Windows, etc. @@ -403,11 +396,9 @@ APR_DECLARE(apr_status_t) apr_filepath_list_split(apr_array_header_t **pathelts, /** * Merge a list of search path components into a single search path - * @ingroup apr_filepath * @param liststr the returned search path; may be NULL if @a pathelts is empty * @param pathelts the components of the search path * @param p the pool to allocate the search path from - * @deffunc apr_status_t apr_filepath_list_merge(char **liststr, apr_array_header_t *pathelts, apr_pool_t *p) * @remark emtpy strings in the source array are ignored. * @remark the path separator in @a liststr is system specific; * e.g., ':' on Unix, ';' on Windows, etc. @@ -418,30 +409,21 @@ APR_DECLARE(apr_status_t) apr_filepath_list_merge(char **liststr, /** * Return the default file path (for relative file names) - * @ingroup apr_filepath * @param path the default path string returned * @param flags optional flag APR_FILEPATH_NATIVE to retrieve the * default file path in os-native format. * @param p the pool to allocate the default path string from - * @deffunc apr_status_t apr_filepath_get(char **path, apr_int32_t flags, apr_pool_t *p) */ APR_DECLARE(apr_status_t) apr_filepath_get(char **path, apr_int32_t flags, apr_pool_t *p); /** * Set the default file path (for relative file names) - * @ingroup apr_filepath * @param path the default path returned * @param p the pool to allocate any working storage - * @deffunc apr_status_t apr_filepath_get(char **defpath, apr_pool_t *p) */ APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p); -/** - * @defgroup apr_filepath_encoding FilePath Character encoding - * @{ - */ - /** The FilePath character encoding is unknown */ #define APR_FILEPATH_ENCODING_UNKNOWN 0 @@ -450,18 +432,16 @@ APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p); /** The FilePath character encoding is UTF-8 */ #define APR_FILEPATH_ENCODING_UTF8 2 -/** @} */ + /** * Determine the encoding used internally by the FilePath functions - * @ingroup apr_filepath_encoding * @param style points to a variable which receives the encoding style flag * @param p the pool to allocate any working storage - * @deffunc apr_status_t apr_filepath_encoding(int *style, apr_pool_t *p) * @remark Use @c apr_os_locale_encoding and/or @c apr_os_default_encoding * to get the name of the path encoding if it's not UTF-8. */ APR_DECLARE(apr_status_t) apr_filepath_encoding(int *style, apr_pool_t *p); - +/** @} */ /** @} */ @@ -470,5 +450,3 @@ APR_DECLARE(apr_status_t) apr_filepath_encoding(int *style, apr_pool_t *p); #endif #endif /* ! APR_FILE_INFO_H */ - - diff --git a/include/apr_file_io.h b/include/apr_file_io.h index 32aaa497a..3f1184aa8 100644 --- a/include/apr_file_io.h +++ b/include/apr_file_io.h @@ -54,17 +54,11 @@ #ifndef APR_FILE_IO_H #define APR_FILE_IO_H + /** * @file apr_file_io.h * @brief APR File I/O Handling */ -/** - * @defgroup APR_File_IO_Handle I/O Handling Functions - * @ingroup APR_File_Handle - * @{ - */ - - #include "apr.h" #include "apr_pools.h" @@ -73,8 +67,8 @@ #include "apr_file_info.h" #include "apr_inherit.h" -#define APR_WANT_STDIO /* for SEEK_* */ -#define APR_WANT_IOVEC +#define APR_WANT_STDIO /**< for SEEK_* */ +#define APR_WANT_IOVEC /**< for apr_file_writev */ #include "apr_want.h" #ifdef __cplusplus @@ -82,7 +76,13 @@ extern "C" { #endif /* __cplusplus */ /** - * @defgroup apr_file_open File Open Flags/Routines + * @defgroup apr_file_io File I/O Handling Functions + * @ingroup APR + * @{ + */ + +/** + * @defgroup apr_file_open_flags File Open Flags/Routines * @{ */ @@ -108,7 +108,7 @@ extern "C" { /** @} */ /** - * @defgroup APR_file_seek_flags File Seek Flags + * @defgroup apr_file_seek_flags File Seek Flags * @{ */ @@ -122,7 +122,7 @@ extern "C" { /** @} */ /** - * @defgroup APR_file_attrs_set File Attribute Flags + * @defgroup apr_file_attrs_set_flags File Attribute Flags * @{ */ @@ -139,13 +139,12 @@ typedef int apr_seek_where_t; /** * Structure for referencing files. - * @defvar apr_file_t */ typedef struct apr_file_t apr_file_t; /* File lock types/flags */ /** - * @defgroup APR_file_lock_types File Lock Types + * @defgroup apr_file_lock_types File Lock Types * @{ */ @@ -164,6 +163,7 @@ typedef struct apr_file_t apr_file_t; #define APR_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the file lock */ /** @} */ + /** * Open the specified file. * @param new_file The opened file descriptor. @@ -195,7 +195,6 @@ typedef struct apr_file_t apr_file_t; * </PRE> * @param perm Access permissions for file. * @param cont The pool to use. - * @ingroup apr_file_open * @remark If perm is APR_OS_DEFAULT and the file is being created, appropriate * default permissions will be used. *arg1 must point to a valid file_t, * or NULL (in which case it will be allocated) @@ -274,7 +273,6 @@ APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr); * open standard error as an apr file pointer. * @param thefile The apr file to use as stderr. * @param cont The pool to allocate the file out of. - * @ingroup apr_file_open * * @remark The only reason that the apr_file_open_std* functions exist * is that you may not always have a stderr/out/in on Windows. This @@ -293,7 +291,6 @@ APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile, * open standard output as an apr file pointer. * @param thefile The apr file to use as stdout. * @param cont The pool to allocate the file out of. - * @ingroup apr_file_open * * @remark The only reason that the apr_file_open_std* functions exist * is that you may not always have a stderr/out/in on Windows. This @@ -312,7 +309,6 @@ APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile, * open standard input as an apr file pointer. * @param thefile The apr file to use as stdin. * @param cont The pool to allocate the file out of. - * @ingroup apr_file_open * * @remark The only reason that the apr_file_open_std* functions exist * is that you may not always have a stderr/out/in on Windows. This @@ -711,13 +707,11 @@ APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f); /** * Get the pool used by the file. - * @return apr_pool_t the pool */ APR_POOL_DECLARE_ACCESSOR(file); /** * Set a file to be inherited by child processes. - * @param file The file to enable inheritance. * */ APR_DECLARE_INHERIT_SET(file); @@ -727,7 +721,6 @@ APR_DECLARE(void) apr_file_set_inherit(apr_file_t *file); /** * Unset a file from being inherited by child processes. - * @param file The file to disable inheritance. */ APR_DECLARE_INHERIT_UNSET(file); @@ -742,7 +735,6 @@ APR_DECLARE(void) apr_file_unset_inherit(apr_file_t *file); * the file is opened with * APR_CREATE | APR_READ | APR_WRITE | APR_EXCL | APR_DELONCLOSE * @param p The pool to allocate the file out of. - * @ingroup apr_file_open * @remark * This function generates a unique temporary file name from template. * The last six characters of template must be XXXXXX and these are replaced @@ -754,8 +746,10 @@ APR_DECLARE(void) apr_file_unset_inherit(apr_file_t *file); APR_DECLARE(apr_status_t) apr_file_mktemp(apr_file_t **fp, char *templ, apr_int32_t flags, apr_pool_t *p); +/** @} */ + #ifdef __cplusplus } #endif -/** @} */ + #endif /* ! APR_FILE_IO_H */ diff --git a/include/apr_fnmatch.h b/include/apr_fnmatch.h index 3dfe6d666..8be40fc82 100644 --- a/include/apr_fnmatch.h +++ b/include/apr_fnmatch.h @@ -41,11 +41,6 @@ * @file apr_fnmatch.h * @brief APR FNMatch Functions */ -/** - * @defgroup APR_FNMatch FNMatch Functions - * @ingroup APR - * @{ - */ #include "apr_errno.h" @@ -53,6 +48,12 @@ extern "C" { #endif +/** + * @defgroup apr_fnmatch Filename Matching Functions + * @ingroup APR + * @{ + */ + #define APR_FNM_NOMATCH 1 /**< Match failed. */ #define APR_FNM_NOESCAPE 0x01 /**< Disable backslash escaping. */ @@ -62,11 +63,11 @@ extern "C" { * @remark This flag is an Apache addition */ -#define FNM_NOMATCH APR_FNM_NOMATCH /**< @deprecated */ -#define FNM_NOESCAPE APR_FNM_NOESCAPE /**< @deprecated */ -#define FNM_PATHNAME APR_FNM_PATHNAME /**< @deprecated */ -#define FNM_PERIOD APR_FNM_PERIOD /**< @deprecated */ -#define FNM_CASE_BLIND APR_FNM_CASE_BLIND /**< @deprecated */ +#define FNM_NOMATCH APR_FNM_NOMATCH /**< @deprecated @see APR_FNM_NOMATCH */ +#define FNM_NOESCAPE APR_FNM_NOESCAPE /**< @deprecated @see APR_FNM_NOESCAPE */ +#define FNM_PATHNAME APR_FNM_PATHNAME /**< @deprecated @see APR_FNM_PATHNAME */ +#define FNM_PERIOD APR_FNM_PERIOD /**< @deprecated @see APR_FNM_PERIOD */ +#define FNM_CASE_BLIND APR_FNM_CASE_BLIND /**< @deprecated @see APR_FNM_CASE_BLIND */ /** * Try to match the string to the given pattern, return APR_SUCCESS if @@ -95,8 +96,10 @@ APR_DECLARE(int) apr_fnmatch_test(const char *pattern); /** @deprecated @see apr_fnmatch_test */ APR_DECLARE(int) apr_is_fnmatch(const char *pattern); +/** @} */ + #ifdef __cplusplus } #endif -/** @} */ -#endif /* !_FNMATCH_H_ */ + +#endif /* !_APR_FNMATCH_H_ */ diff --git a/include/apr_general.h b/include/apr_general.h index 99b6666cb..088175725 100644 --- a/include/apr_general.h +++ b/include/apr_general.h @@ -54,10 +54,15 @@ #ifndef APR_GENERAL_H #define APR_GENERAL_H + /** * @file apr_general.h - * @brief APR Misc routines + * This is collection of oddballs that didn't fit anywhere else, + * and might move to more appropriate headers with the release + * of APR 1.0. + * @brief APR Miscellaneous library routines */ + #include "apr.h" #include "apr_pools.h" #include "apr_errno.h" @@ -71,8 +76,11 @@ extern "C" { #endif /* __cplusplus */ /** - * @defgroup APR_Misc Misc routines - * @ingroup APR + * @defgroup apr_general Miscellaneous library routines + * @ingroup APR + * This is collection of oddballs that didn't fit anywhere else, + * and might move to more appropriate headers with the release + * of APR 1.0. * @{ */ @@ -145,9 +153,9 @@ typedef int apr_signum_t; /** @deprecated @see APR_OFFSETOF */ #define APR_XtOffsetOf APR_OFFSETOF +#ifndef DOXYGEN -/** - * A couple of prototypes for functions in case some platform doesn't +/* A couple of prototypes for functions in case some platform doesn't * have it */ #if (!APR_HAVE_STRCASECMP) && (APR_HAVE_STRICMP) @@ -162,6 +170,8 @@ int strcasecmp(const char *a, const char *b); int strncasecmp(const char *a, const char *b, size_t n); #endif +#endif + /** * Alignment macros */ @@ -191,10 +201,16 @@ int strncasecmp(const char *a, const char *b, size_t n); void *memchr(const void *s, int c, size_t n); #endif +/** @} */ + +/** + * @defgroup apr_library Library initialization and termination + * @{ + */ + /** * Setup any APR internal data structures. This MUST be the first function * called for any APR library. - * @deffunc apr_status_t apr_initialize(void) * @remark See apr_app_initialize if this is an application, rather than * a library consumer of apr. */ @@ -241,23 +257,22 @@ APR_DECLARE(void) apr_terminate2(void); /** @} */ /** - * @defgroup APR_Random Random Functions - * @ingroup APR + * @defgroup apr_random Random Functions * @{ */ -#if APR_HAS_RANDOM +#if APR_HAS_RANDOM || defined(DOXYGEN) -#ifdef APR_ENABLE_FOR_1_0 -APR_DECLARE(apr_status_t) apr_generate_random_bytes(unsigned char * buf, - apr_size_t length); -#else /* TODO: I'm not sure this is the best place to put this prototype...*/ /** * Generate random bytes. * @param buf Buffer to fill with random bytes * @param length Length of buffer in bytes (becomes apr_size_t in APR 1.0) */ +#ifdef APR_ENABLE_FOR_1_0 +APR_DECLARE(apr_status_t) apr_generate_random_bytes(unsigned char * buf, + apr_size_t length); +#else APR_DECLARE(apr_status_t) apr_generate_random_bytes(unsigned char * buf, int length); #endif diff --git a/include/apr_getopt.h b/include/apr_getopt.h index c45e444b6..fbcd75450 100644 --- a/include/apr_getopt.h +++ b/include/apr_getopt.h @@ -55,6 +55,11 @@ #ifndef APR_GETOPT_H #define APR_GETOPT_H +/** + * @file apr_getopt.h + * @brief APR Command Arguments (getopt) + */ + #include "apr_pools.h" #ifdef __cplusplus @@ -62,12 +67,8 @@ extern "C" { #endif /* __cplusplus */ /** - * @file apr_getopt.h - * @brief APR Command Arguments (getopt) - */ -/** - * @defgroup APR_getopt Command Argument Parsing - * @ingroup APR + * @defgroup apr_getopt Command Argument Parsing + * @ingroup APR * @{ */ @@ -150,7 +151,7 @@ APR_DECLARE(apr_status_t) apr_getopt_init(apr_getopt_t **os, apr_pool_t *cont, * <PRE> * APR_EOF -- No more options to parse * APR_BADCH -- Found a bad option character - * APR_BADARG -- No argument followed @parameter: + * APR_BADARG -- No argument followed the option flag * APR_SUCCESS -- The next option was found. * </PRE> */ @@ -173,7 +174,7 @@ APR_DECLARE(apr_status_t) apr_getopt(apr_getopt_t *os, const char *opts, * <PRE> * APR_EOF -- No more options to parse * APR_BADCH -- Found a bad option character - * APR_BADARG -- No argument followed @parameter: + * APR_BADARG -- No argument followed the option flag * APR_SUCCESS -- The next option was found. * </PRE> * When APR_SUCCESS is returned, os->ind gives the index of the first diff --git a/include/apr_global_mutex.h b/include/apr_global_mutex.h index 6fe8b3d79..5b456de27 100644 --- a/include/apr_global_mutex.h +++ b/include/apr_global_mutex.h @@ -55,23 +55,26 @@ #ifndef APR_GLOBAL_MUTEX_H #define APR_GLOBAL_MUTEX_H +/** + * @file apr_global_mutex.h + * @brief APR Global Locking Routines + */ + #include "apr.h" #include "apr_proc_mutex.h" /* only for apr_lockmech_e */ #include "apr_pools.h" #include "apr_errno.h" +#if APR_PROC_MUTEX_IS_GLOBAL +#include "apr_proc_mutex.h" +#endif #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /** - * @file apr_global_mutex.h - * @brief APR Global Locking Routines - */ - -/** * @defgroup APR_GlobalMutex Global Locking Routines - * @ingroup APR + * @ingroup APR * @{ */ @@ -168,8 +171,6 @@ APR_POOL_DECLARE_ACCESSOR(global_mutex); * Define these platforms in terms of an apr_proc_mutex_t. */ -#include "apr_proc_mutex.h" - #define apr_global_mutex_t apr_proc_mutex_t #define apr_global_mutex_create apr_proc_mutex_create #define apr_global_mutex_child_init apr_proc_mutex_child_init @@ -181,6 +182,8 @@ APR_POOL_DECLARE_ACCESSOR(global_mutex); #endif +/** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_hash.h b/include/apr_hash.h index e3f5d7492..31d913e15 100644 --- a/include/apr_hash.h +++ b/include/apr_hash.h @@ -59,22 +59,23 @@ #ifndef APR_HASH_H #define APR_HASH_H -#ifdef __cplusplus -extern "C" { -#endif /** * @file apr_hash.h * @brief APR Hash Tables */ +#include "apr_pools.h" + +#ifdef __cplusplus +extern "C" { +#endif + /** - * @defgroup APR_Hash Hash Tables - * @ingroup APR + * @defgroup apr_hash Hash Tables + * @ingroup APR * @{ */ -#include "apr_pools.h" - /** * When passing a key to apr_hash_set or apr_hash_get, this value can be * passed to indicate a string-valued key, and have apr_hash compute the @@ -140,6 +141,11 @@ APR_DECLARE(void *) apr_hash_get(apr_hash_t *ht, const void *key, * @param p The pool to allocate the apr_hash_index_t iterator. If this * pool is NULL, then an internal, non-thread-safe iterator is used. * @param ht The hash table + * @remark There is no restriction on adding or deleting hash entries during + * an iteration (although the results may be unpredictable unless all you do + * is delete the current entry) and multiple iterations can be in + * progress at the same time. + * @example */ /** @@ -156,13 +162,8 @@ APR_DECLARE(void *) apr_hash_get(apr_hash_t *ht, const void *key, * } * return sum; * } - * - * There is no restriction on adding or deleting hash entries during an - * iteration (although the results may be unpredictable unless all you do - * is delete the current entry) and multiple iterations can be in - * progress at the same time. * </PRE> - */ + */ APR_DECLARE(apr_hash_index_t *) apr_hash_first(apr_pool_t *p, apr_hash_t *ht); /** @@ -229,13 +230,12 @@ APR_DECLARE(apr_hash_t *) apr_hash_merge(apr_pool_t *p, const void *data); /** - * Get a pointer to the pool which the hash table - * was created in - * @param hash the hash table in question + * Get a pointer to the pool which the hash table was created in */ APR_POOL_DECLARE_ACCESSOR(hash); /** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_inherit.h b/include/apr_inherit.h index 091628361..41b683633 100644 --- a/include/apr_inherit.h +++ b/include/apr_inherit.h @@ -54,40 +54,36 @@ #ifndef APR_INHERIT_H #define APR_INHERIT_H + /** - * @file apr_inherit.h - * @brief APR File Handle Inheritance - */ -/** - * @defgroup APR_File_Inheritance Inheritance Of File/Sockets - * @ingroup APR_File_Handle - * Sets/Unsets inheritance for File descriptor inheritance in children - * processes. - * - * @{ + * @file apr_inherit.h + * @brief APR File Handle Inheritance Helpers + * @remark This internal header includes internal declaration helpers + * for other headers to declare apr_foo_inherit_[un]set functions. */ -#ifdef __cplusplus -extern "C" { -#endif /* __cplusplus */ - /** - * @param name Set Inheritance for this Socket/File Handle + * Prototype for type-specific declarations of apr_foo_inherit_set + * functions. + * @remark Doxygen unwraps this macro (via doxygen.conf) to provide + * actual help for each specific occurance of apr_foo_inherit_set. + * @remark the linkage is specified for APR. It would be possible to expand + * the macros to support other linkages. */ -#define APR_DECLARE_INHERIT_SET(name) \ - APR_DECLARE(apr_status_t) apr_##name##_inherit_set( \ - apr_##name##_t *the##name) +#define APR_DECLARE_INHERIT_SET(type) \ + APR_DECLARE(apr_status_t) apr_##type##_inherit_set( \ + apr_##type##_t *the##type) /** - * @param name Unset Inheritance for this Socket/File Handle + * Prototype for type-specific declarations of apr_foo_inherit_unset + * functions. + * @remark Doxygen unwraps this macro (via doxygen.conf) to provide + * actual help for each specific occurance of apr_foo_inherit_unset. + * @remark the linkage is specified for APR. It would be possible to expand + * the macros to support other linkages. */ -#define APR_DECLARE_INHERIT_UNSET(name) \ - APR_DECLARE(apr_status_t) apr_##name##_inherit_unset( \ - apr_##name##_t *the##name) - -#ifdef __cplusplus -} -#endif -/** @} */ +#define APR_DECLARE_INHERIT_UNSET(type) \ + APR_DECLARE(apr_status_t) apr_##type##_inherit_unset( \ + apr_##type##_t *the##type) #endif /* ! APR_INHERIT_H */ diff --git a/include/apr_lib.h b/include/apr_lib.h index f35843f45..a4c6b9777 100644 --- a/include/apr_lib.h +++ b/include/apr_lib.h @@ -54,8 +54,12 @@ #ifndef APR_LIB_H #define APR_LIB_H + /** * @file apr_lib.h + * This is collection of oddballs that didn't fit anywhere else, + * and might move to more appropriate headers with the release + * of APR 1.0. * @brief APR general purpose library routines */ @@ -68,16 +72,20 @@ #if APR_HAVE_STDARG_H #include <stdarg.h> #endif -/** - * @defgroup APR_General General Purpose Library Routines - * @ingroup APR - * @{ - */ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ +/** + * @defgroup apr_lib General Purpose Library Routines + * @ingroup APR + * This is collection of oddballs that didn't fit anywhere else, + * and might move to more appropriate headers with the release + * of APR 1.0. + * @{ + */ + /** A constant representing a 'large' string. */ #define HUGE_STRING_LEN 8192 @@ -102,15 +110,13 @@ struct apr_vformatter_buff_t { * return the final element of the pathname * @param pathname The path to get the final element of * @return the final element of the path - * @example - */ -/** - * Examples: + * @remark * <PRE> - * "/foo/bar/gum" -> "gum" - * "/foo/bar/gum/" -> "" - * "gum" -> "gum" - * "wi\\n32\\stuff" -> "stuff" + * For example: + * "/foo/bar/gum" -> "gum" + * "/foo/bar/gum/" -> "" + * "gum" -> "gum" + * "bs\\path\\stuff" -> "stuff" * </PRE> */ APR_DECLARE(const char *) apr_filepath_name_get(const char *pathname); @@ -119,47 +125,6 @@ APR_DECLARE(const char *) apr_filepath_name_get(const char *pathname); APR_DECLARE(const char *) apr_filename_of_pathname(const char *pathname); /** - * These macros allow correct support of 8-bit characters on systems which - * support 8-bit characters. Pretty dumb how the cast is required, but - * that's legacy libc for ya. These new macros do not support EOF like - * the standard macros do. Tough. - * @defgroup apr_ctype ctype functions - * @{ - */ -/** @see isalnum */ -#define apr_isalnum(c) (isalnum(((unsigned char)(c)))) -/** @see isalpha */ -#define apr_isalpha(c) (isalpha(((unsigned char)(c)))) -/** @see iscntrl */ -#define apr_iscntrl(c) (iscntrl(((unsigned char)(c)))) -/** @see isdigit */ -#define apr_isdigit(c) (isdigit(((unsigned char)(c)))) -/** @see isgraph */ -#define apr_isgraph(c) (isgraph(((unsigned char)(c)))) -/** @see islower*/ -#define apr_islower(c) (islower(((unsigned char)(c)))) -/** @see isascii */ -#ifdef isascii -#define apr_isascii(c) (isascii(((unsigned char)(c)))) -#else -#define apr_isascii(c) (((c) & ~0x7f)==0) -#endif -/** @see isprint */ -#define apr_isprint(c) (isprint(((unsigned char)(c)))) -/** @see ispunct */ -#define apr_ispunct(c) (ispunct(((unsigned char)(c)))) -/** @see isspace */ -#define apr_isspace(c) (isspace(((unsigned char)(c)))) -/** @see isupper */ -#define apr_isupper(c) (isupper(((unsigned char)(c)))) -/** @see isxdigit */ -#define apr_isxdigit(c) (isxdigit(((unsigned char)(c)))) -/** @see tolower */ -#define apr_tolower(c) (tolower(((unsigned char)(c)))) -/** @see toupper */ -#define apr_toupper(c) (toupper(((unsigned char)(c)))) -/** @} */ -/** * apr_killpg * Small utility macros to make things easier to read. Not usually a * goal, to be sure.. @@ -183,9 +148,7 @@ APR_DECLARE(const char *) apr_filename_of_pathname(const char *pathname); * @param fmt The format string * @param ap The arguments to use to fill out the format string. * - * @example - */ -/** + * @remark * <PRE> * The extensions are: * @@ -249,8 +212,53 @@ APR_DECLARE(int) apr_vformatter(int (*flush_func)(apr_vformatter_buff_t *b), APR_DECLARE(apr_status_t) apr_password_get(const char *prompt, char *pwbuf, apr_size_t *bufsize); +/** @} */ + +/** + * @defgroup apr_ctype ctype functions + * These macros allow correct support of 8-bit characters on systems which + * support 8-bit characters. Pretty dumb how the cast is required, but + * that's legacy libc for ya. These new macros do not support EOF like + * the standard macros do. Tough. + * @{ + */ +/** @see isalnum */ +#define apr_isalnum(c) (isalnum(((unsigned char)(c)))) +/** @see isalpha */ +#define apr_isalpha(c) (isalpha(((unsigned char)(c)))) +/** @see iscntrl */ +#define apr_iscntrl(c) (iscntrl(((unsigned char)(c)))) +/** @see isdigit */ +#define apr_isdigit(c) (isdigit(((unsigned char)(c)))) +/** @see isgraph */ +#define apr_isgraph(c) (isgraph(((unsigned char)(c)))) +/** @see islower*/ +#define apr_islower(c) (islower(((unsigned char)(c)))) +/** @see isascii */ +#ifdef isascii +#define apr_isascii(c) (isascii(((unsigned char)(c)))) +#else +#define apr_isascii(c) (((c) & ~0x7f)==0) +#endif +/** @see isprint */ +#define apr_isprint(c) (isprint(((unsigned char)(c)))) +/** @see ispunct */ +#define apr_ispunct(c) (ispunct(((unsigned char)(c)))) +/** @see isspace */ +#define apr_isspace(c) (isspace(((unsigned char)(c)))) +/** @see isupper */ +#define apr_isupper(c) (isupper(((unsigned char)(c)))) +/** @see isxdigit */ +#define apr_isxdigit(c) (isxdigit(((unsigned char)(c)))) +/** @see tolower */ +#define apr_tolower(c) (tolower(((unsigned char)(c)))) +/** @see toupper */ +#define apr_toupper(c) (toupper(((unsigned char)(c)))) + +/** @} */ + #ifdef __cplusplus } #endif -/** @} */ + #endif /* ! APR_LIB_H */ diff --git a/include/apr_mmap.h b/include/apr_mmap.h index 744f04e62..f6255d0ae 100644 --- a/include/apr_mmap.h +++ b/include/apr_mmap.h @@ -55,6 +55,11 @@ #ifndef APR_MMAP_H #define APR_MMAP_H +/** + * @file apr_mmap.h + * @brief APR MMAP routines + */ + #include "apr.h" #include "apr_pools.h" #include "apr_errno.h" @@ -68,13 +73,10 @@ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ + /** - * @file apr_mmap.h - * @brief APR MMAP routines - */ -/** - * @defgroup APR_MMAP MMAP (Memory Map) Routines - * @ingroup APR + * @defgroup apr_mmap MMAP (Memory Map) Routines + * @ingroup APR * @{ */ @@ -219,11 +221,11 @@ APR_DECLARE(apr_status_t) apr_mmap_offset(void **addr, apr_mmap_t *mm, apr_off_t offset); #endif /* APR_HAS_MMAP */ + /** @} */ + #ifdef __cplusplus } #endif #endif /* ! APR_MMAP_H */ - - diff --git a/include/apr_network_io.h b/include/apr_network_io.h index fdc922b85..baab12fc2 100644 --- a/include/apr_network_io.h +++ b/include/apr_network_io.h @@ -58,11 +58,6 @@ * @file apr_network_io.h * @brief APR Network library */ -/** - * @defgroup APR_Net Network Routines - * @ingroup APR - * @{ - */ #include "apr.h" #include "apr_pools.h" @@ -78,13 +73,19 @@ extern "C" { #endif /* __cplusplus */ +/** + * @defgroup apr_network_io Network Routines + * @ingroup APR + * @{ + */ + #ifndef APR_MAX_SECS_TO_LINGER /** Maximum seconds to linger */ #define APR_MAX_SECS_TO_LINGER 30 #endif #ifndef MAX_SECS_TO_LINGER -/** @deprecated */ +/** @deprecated @see APR_MAX_SECS_TO_LINGER */ #define MAX_SECS_TO_LINGER APR_MAX_SECS_TO_LINGER #endif @@ -99,7 +100,7 @@ extern "C" { #endif /** - * @defgroup Sock_opt Socket option definitions + * @defgroup apr_sockopt Socket option definitions * @{ */ #define APR_SO_LINGER 1 /**< Linger */ @@ -188,7 +189,6 @@ struct in_addr { #define APR_PROTO_SCTP 132 /**< SCTP */ /** @} */ - /** * Enum to tell us if we're interested in remote or local socket */ @@ -197,8 +197,9 @@ typedef enum { APR_REMOTE } apr_interface_e; -/* I guess not everybody uses inet_addr. This defines apr_inet_addr - * appropriately. +/** + * The specific declaration of inet_addr's ... some platforms fall back + * inet_network (this is not good, but necessary) */ #if APR_HAVE_INET_ADDR @@ -268,19 +269,21 @@ struct apr_sockaddr_t { }; #if APR_HAS_SENDFILE -/* Define flags passed in on apr_socket_sendfile() */ +/** + * Support reusing the socket on platforms which support it (from disconnect, + * specifically Win32. + * @remark Optional flag passed into apr_socket_sendfile() + */ #define APR_SENDFILE_DISCONNECT_SOCKET 1 #endif /** A structure to encapsulate headers and trailers for apr_socket_sendfile */ struct apr_hdtr_t { - /** An iovec to store the headers sent before the file. - * @defvar iovec *headers */ + /** An iovec to store the headers sent before the file. */ struct iovec* headers; /** number of headers in the iovec */ int numheaders; - /** An iovec to store the trailers sent after the file. - * @defvar iovec *trailers */ + /** An iovec to store the trailers sent after the file. */ struct iovec* trailers; /** number of trailers in the iovec */ int numtrailers; @@ -838,7 +841,6 @@ APR_DECLARE(apr_status_t) apr_socket_protocol_get(apr_socket_t *sock, /** * Set a socket to be inherited by child processes. - * @param socket The socket to enable inheritance. */ APR_DECLARE_INHERIT_SET(socket); @@ -847,16 +849,17 @@ APR_DECLARE(void) apr_socket_set_inherit(apr_socket_t *skt); /** * Unset a socket from being inherited by child processes. - * @param socket The socket to disable inheritance. */ APR_DECLARE_INHERIT_UNSET(socket); /** @deprecated @see apr_socket_inherit_unset */ APR_DECLARE(void) apr_socket_unset_inherit(apr_socket_t *skt); +/** @} */ + #ifdef __cplusplus } #endif -/** @} */ + #endif /* ! APR_NETWORK_IO_H */ diff --git a/include/apr_poll.h b/include/apr_poll.h index 95cc4dddc..bd15e6379 100644 --- a/include/apr_poll.h +++ b/include/apr_poll.h @@ -58,12 +58,6 @@ * @file apr_poll.h * @brief APR Poll interface */ -/** - * @defgroup APR_Poll Poll Routines - * @ingroup APR - * @{ - */ - #include "apr.h" #include "apr_pools.h" #include "apr_errno.h" @@ -80,7 +74,13 @@ extern "C" { #endif /* __cplusplus */ /** - * @defgroup Poll options + * @defgroup apr_poll Poll Routines + * @ingroup APR + * @{ + */ + +/** + * @defgroup apr_poll_opt Poll options * @{ */ #define APR_POLLIN 0x001 /**< Can read without blocking */ @@ -281,9 +281,11 @@ APR_DECLARE(apr_status_t) apr_pollset_poll(apr_pollset_t *pollset, apr_int32_t *num, const apr_pollfd_t **descriptors); +/** @} */ + #ifdef __cplusplus } #endif -/** @} */ + #endif /* ! APR_POLL_H */ diff --git a/include/apr_pools.h b/include/apr_pools.h index fcacd5662..a08ae8907 100644 --- a/include/apr_pools.h +++ b/include/apr_pools.h @@ -55,16 +55,6 @@ #ifndef APR_POOLS_H #define APR_POOLS_H -#include "apr.h" -#include "apr_errno.h" -#include "apr_general.h" /* for APR_STRINGIFY */ -#define APR_WANT_MEMFUNC -#include "apr_want.h" - -#ifdef __cplusplus -extern "C" { -#endif - /** * @file apr_pools.h * @brief APR memory allocation @@ -81,9 +71,20 @@ extern "C" { * we can delete everything in the per-transaction apr_pool_t without fear, * and without thinking too hard about it either. */ + +#include "apr.h" +#include "apr_errno.h" +#include "apr_general.h" /* for APR_STRINGIFY */ +#define APR_WANT_MEMFUNC /**< for no good reason? */ +#include "apr_want.h" + +#ifdef __cplusplus +extern "C" { +#endif + /** - * @defgroup APR_Pool Memory Pool Functions - * @ingroup APR + * @defgroup apr_pools Memory Pool Functions + * @ingroup APR * @{ */ @@ -92,34 +93,37 @@ typedef struct apr_pool_t apr_pool_t; /** - * Pool accessor functions. + * Declaration helper macro to construct apr_foo_pool_get()s. * - * These standardized function are used by opaque (APR) data types to return + * This standardized macro is used by opaque (APR) data types to return * the apr_pool_t that is associated with the data type. * * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the * accessor function. A typical usage and result would be: - * + * <pre> * APR_POOL_DECLARE_ACCESSOR(file); * becomes: * APR_DECLARE(apr_pool_t *) apr_file_pool_get(apr_file_t *ob); + * </pre> + * @remark Doxygen unwraps this macro (via doxygen.conf) to provide + * actual help for each specific occurance of apr_foo_pool_get. + * @remark the linkage is specified for APR. It would be possible to expand + * the macros to support other linkages. + */ +#define APR_POOL_DECLARE_ACCESSOR(type) \ + APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ + (const apr_##type##_t *the##type) + +/** + * Implementation helper macro to provide apr_foo_pool_get()s. * * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to * actually define the function. It assumes the field is named "pool". - * - * Note: the linkage is specified for APR. It would be possible to expand - * the macros to support other linkages. */ - -#define APR_POOL_DECLARE_ACCESSOR(typename) \ - APR_DECLARE(apr_pool_t *) apr_##typename##_pool_get \ - (const apr_##typename##_t *ob) - -/** used to implement the pool accessor */ -#define APR_POOL_IMPLEMENT_ACCESSOR(typename) \ - APR_DECLARE(apr_pool_t *) apr_##typename##_pool_get \ - (const apr_##typename##_t *ob) { return ob->pool; } - +#define APR_POOL_IMPLEMENT_ACCESSOR(type) \ + APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ + (const apr_##type##_t *the##type) \ + { return the##type->pool; } /** @@ -412,7 +416,7 @@ APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size, /** * Set the function to be called when an allocation failure occurs. - * @tip If the program wants APR to exit on a memory allocation error, + * @remark If the program wants APR to exit on a memory allocation error, * then this function can be called to set the callback to use (for * performing cleanup and then exiting). If this function is not called, * then APR will return an error and expect the calling program to @@ -684,8 +688,8 @@ APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag); #endif /* APR_POOL_DEBUG or DOXYGEN */ - /** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_portable.h b/include/apr_portable.h index 196ab8b1e..6f79f45cd 100644 --- a/include/apr_portable.h +++ b/include/apr_portable.h @@ -62,11 +62,6 @@ * @file apr_portable.h * @brief APR Portability Routines */ -/** - * @defgroup APR_portability Portability Routines - * @ingroup APR - * @{ - */ #include "apr.h" #include "apr_pools.h" @@ -94,6 +89,12 @@ extern "C" { #endif /* __cplusplus */ +/** + * @defgroup apr_portabile Portability Routines + * @ingroup APR + * @{ + */ + #ifdef WIN32 /* The primitives for Windows types */ typedef HANDLE apr_os_file_t; @@ -310,7 +311,7 @@ APR_DECLARE(apr_status_t) apr_os_shm_get(apr_os_shm_t *osshm, #if APR_HAS_THREADS || defined(DOXYGEN) /** - * @defgroup APR_PORT_Thread Thread portability Routines + * @defgroup apr_os_thread Thread portability Routines * @{ */ /** @@ -471,7 +472,7 @@ APR_DECLARE(apr_status_t) apr_os_shm_put(apr_shm_t **shm, #if APR_HAS_DSO || defined(DOXYGEN) /** - * @defgroup apr_port_DSO DSO (Dynamic Loading) Portabiliity Routines + * @defgroup apr_os_dso DSO (Dynamic Loading) Portabiliity Routines * @{ */ /** @@ -518,11 +519,10 @@ APR_DECLARE(const char*) apr_os_default_encoding(apr_pool_t *pool); */ APR_DECLARE(const char*) apr_os_locale_encoding(apr_pool_t *pool); +/** @} */ #ifdef __cplusplus } #endif -/** @} */ - #endif /* ! APR_PORTABLE_H */ diff --git a/include/apr_proc_mutex.h b/include/apr_proc_mutex.h index e70da3588..197da270a 100644 --- a/include/apr_proc_mutex.h +++ b/include/apr_proc_mutex.h @@ -55,6 +55,11 @@ #ifndef APR_PROC_MUTEX_H #define APR_PROC_MUTEX_H +/** + * @file apr_proc_mutex.h + * @brief APR Process Locking Routines + */ + #include "apr.h" #include "apr_pools.h" #include "apr_errno.h" @@ -64,13 +69,8 @@ extern "C" { #endif /* __cplusplus */ /** - * @file apr_proc_mutex.h - * @brief APR Process Locking Routines - */ - -/** - * @defgroup APR_ProcMutex Process Locking Routines - * @ingroup APR + * @defgroup apr_proc_mutex Process Locking Routines + * @ingroup APR * @{ */ @@ -188,6 +188,8 @@ APR_DECLARE(const char *) apr_proc_mutex_defname(void); */ APR_POOL_DECLARE_ACCESSOR(proc_mutex); +/** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_ring.h b/include/apr_ring.h index 39d144ba7..2f0984b2a 100644 --- a/include/apr_ring.h +++ b/include/apr_ring.h @@ -61,12 +61,14 @@ * We'd use Dean's code directly if we could guarantee the * availability of inline functions. */ + +#ifndef APR_RING_H +#define APR_RING_H + /** * @file apr_ring.h * @brief APR Rings */ -#ifndef APR_RING_H -#define APR_RING_H /* * for offsetof() @@ -74,14 +76,11 @@ #include "apr_general.h" /** - * @defgroup APR_Rings Rings - * @ingroup APR - * @{ - */ - -/** + * @defgroup apr_ring Ring Macro Implementations + * @ingroup APR * A ring is a kind of doubly-linked list that can be manipulated * without knowing where its head is. + * @{ */ /** @@ -544,5 +543,7 @@ */ #define APR_RING_CHECK_ELEM(ep, elem, link, msg) #endif + /** @} */ + #endif /* !APR_RING_H */ diff --git a/include/apr_shm.h b/include/apr_shm.h index 15408cc12..aa5764db5 100644 --- a/include/apr_shm.h +++ b/include/apr_shm.h @@ -55,6 +55,11 @@ #ifndef APR_SHM_H #define APR_SHM_H +/** + * @file apr_shm.h + * @brief APR Shared Memory Routines + */ + #include "apr.h" #include "apr_pools.h" #include "apr_errno.h" @@ -64,13 +69,8 @@ extern "C" { #endif /* __cplusplus */ /** - * @file apr_shm.h - * @brief APR Shared Memory Routines - */ - -/** - * @defgroup APR_SHM Shared Memory Routines - * @ingroup APR + * @defgroup apr_shm Shared Memory Routines + * @ingroup APR * @{ */ @@ -156,6 +156,8 @@ APR_DECLARE(apr_size_t) apr_shm_size_get(const apr_shm_t *m); */ APR_POOL_DECLARE_ACCESSOR(shm); +/** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_signal.h b/include/apr_signal.h index 6fda5a2a3..3ef45ec97 100644 --- a/include/apr_signal.h +++ b/include/apr_signal.h @@ -54,6 +54,7 @@ #ifndef APR_SIGNAL_H #define APR_SIGNAL_H + /** * @file apr_signal.h * @brief APR Signal Handling @@ -71,8 +72,8 @@ extern "C" { #endif /* __cplusplus */ /** - * @defgroup APR_Signal Signal Handling - * @ingroup APR + * @defgroup apr_signal Handling + * @ingroup APR * @{ */ @@ -127,6 +128,7 @@ APR_DECLARE(const char *) apr_signal_get_description(int signum); void apr_signal_init(apr_pool_t *pglobal); /** @} */ + #ifdef __cplusplus } #endif /* __cplusplus */ diff --git a/include/apr_strings.h b/include/apr_strings.h index 7b2779cd7..ed90befab 100644 --- a/include/apr_strings.h +++ b/include/apr_strings.h @@ -78,6 +78,11 @@ #ifndef APR_STRINGS_H #define APR_STRINGS_H +/** + * @file apr_strings.h + * @brief APR Strings library + */ + #include "apr.h" #include "apr_errno.h" #include "apr_pools.h" @@ -91,15 +96,13 @@ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ + /** - * @file apr_strings.h - * @brief APR Strings library - */ -/** - * @defgroup APR_Strings String routines - * @ingroup APR + * @defgroup apr_strings String routines + * @ingroup APR * @{ */ + /** * Do a natural order comparison of two strings. * @param a The first string to compare @@ -145,7 +148,7 @@ APR_DECLARE(char *) apr_pstrmemdup(apr_pool_t *p, const char *s, apr_size_t n); /** * duplicate the first n characters of a string into memory allocated - * out of a pool; the new string will be '\0'-terminated + * out of a pool; the new string will be null-terminated * @param p The pool to allocate out of * @param s The string to duplicate * @param n The number of characters to duplicate @@ -218,7 +221,7 @@ APR_DECLARE_NONSTD(char *) apr_psprintf(apr_pool_t *p, const char *fmt, ...) * 2) strncpy() null fills, which is bogus, esp. when copy 8byte strings * into 8k blocks. * 3) Instead of returning the pointer to the beginning of the - * destination string, we return a pointer to the terminating '\0' + * destination string, we return a pointer to the terminating null * to allow us to check for truncation. * </PRE> */ @@ -245,7 +248,7 @@ APR_DECLARE(apr_status_t) apr_tokenize_to_argv(const char *arg_str, apr_pool_t *token_context); /** - * Split a string into separate '\0'-terminated tokens. The tokens are + * Split a string into separate null-terminated tokens. The tokens are * delimited in the string by one or more characters from the sep * argument. * @param str The string to separate; this should be specified on the @@ -259,7 +262,6 @@ APR_DECLARE(char *) apr_strtok(char *str, const char *sep, char **last); /** * @defgroup APR_Strings_Snprintf snprintf implementations - * * @warning * These are snprintf implementations based on apr_vformatter(). * @@ -302,8 +304,8 @@ APR_DECLARE_NONSTD(int) apr_snprintf(char *buf, apr_size_t len, */ APR_DECLARE(int) apr_vsnprintf(char *buf, apr_size_t len, const char *format, va_list ap); - /** @} */ + /** * create a string representation of an int, allocated from a pool * @param p The pool from which to allocate @@ -361,7 +363,9 @@ APR_DECLARE(apr_int64_t) apr_atoi64(const char *buf); * @remark All negative sizes report ' - ', apr_strfsize only formats positive values. */ APR_DECLARE(char *) apr_strfsize(apr_off_t size, char *buf); + /** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_support.h b/include/apr_support.h index f7649a0c4..50a4789e6 100644 --- a/include/apr_support.h +++ b/include/apr_support.h @@ -54,15 +54,11 @@ #ifndef APR_SUPPORT_H #define APR_SUPPORT_H + /** * @file apr_support.h * @brief APR Support functions */ -/** - * @defgroup APR_Support Internal APR support functions - * @ingroup APR_Support - * @{ - */ #include "apr.h" #include "apr_network_io.h" @@ -73,13 +69,21 @@ extern "C" { #endif /* __cplusplus */ /** + * @defgroup apr_support Internal APR support functions + * @ingroup APR + * @{ + */ + +/** * Wait for IO to occur or timeout. */ apr_status_t apr_wait_for_io_or_timeout(apr_file_t *f, apr_socket_t *s, int for_read); +/** @} */ + #ifdef __cplusplus } #endif -/** @} */ + #endif /* ! APR_SUPPORT_H */ diff --git a/include/apr_tables.h b/include/apr_tables.h index 608784d2a..f6620f8f1 100644 --- a/include/apr_tables.h +++ b/include/apr_tables.h @@ -55,6 +55,11 @@ #ifndef APR_TABLES_H #define APR_TABLES_H +/** + * @file apr_tables.h + * @brief APR Table library + */ + #include "apr.h" #include "apr_pools.h" @@ -66,23 +71,15 @@ extern "C" { #endif /* __cplusplus */ -/* - * Define the structures used by the APR general-purpose library. - */ - /** - * @file apr_tables.h - * @brief APR Table library - */ -/** - * @defgroup APR_Table Table routines - * @ingroup APR - * - * Memory allocation stuff, like pools, arrays, and tables. Pools - * and tables are opaque structures to applications, but arrays are - * published. + * @defgroup apr_tables Table and Array Functions + * @ingroup APR + * Tables are used to store entirely opaque structures + * for applications, while Arrays are usually used to + * deal with string lists. * @{ */ + /** the table abstract data type */ typedef struct apr_table_t apr_table_t; @@ -398,7 +395,7 @@ APR_DECLARE_NONSTD(int) apr_table_do(apr_table_do_callback_fn_t *comp, * @see apr_table_do_callback_fn_t */ APR_DECLARE(int) apr_table_vdo(apr_table_do_callback_fn_t *comp, - void *rec, const apr_table_t *t, va_list); + void *rec, const apr_table_t *t, va_list vp); /** flag for overlap to use apr_table_setn */ #define APR_OVERLAP_TABLES_SET (0) @@ -445,6 +442,7 @@ APR_DECLARE(void) apr_table_overlap(apr_table_t *a, const apr_table_t *b, unsigned flags); /** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_thread_cond.h b/include/apr_thread_cond.h index 52e0b5c8b..263604eb3 100644 --- a/include/apr_thread_cond.h +++ b/include/apr_thread_cond.h @@ -55,6 +55,11 @@ #ifndef APR_THREAD_COND_H #define APR_THREAD_COND_H +/** + * @file apr_thread_cond.h + * @brief APR Condition Variable Routines + */ + #include "apr.h" #include "apr_pools.h" #include "apr_errno.h" @@ -65,24 +70,17 @@ extern "C" { #endif /* __cplusplus */ -#if APR_HAS_THREADS - -/** - * @file apr_thread_cond.h - * @brief APR Condition Variable Routines - */ +#if APR_HAS_THREADS || defined(DOXYGEN) /** - * @defgroup APR_Cond Condition Variable Routines - * @ingroup APR + * @defgroup apr_thread_cond Condition Variable Routines + * @ingroup APR * @{ */ /** Opaque structure for thread condition variables */ typedef struct apr_thread_cond_t apr_thread_cond_t; -/* Function definitions */ - /** * Create and initialize a condition variable that can be used to signal * and schedule threads in a single process. @@ -159,6 +157,8 @@ APR_POOL_DECLARE_ACCESSOR(thread_cond); #endif /* APR_HAS_THREADS */ +/** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_thread_mutex.h b/include/apr_thread_mutex.h index 6d89c10c3..be943f75b 100644 --- a/include/apr_thread_mutex.h +++ b/include/apr_thread_mutex.h @@ -55,6 +55,11 @@ #ifndef APR_THREAD_MUTEX_H #define APR_THREAD_MUTEX_H +/** + * @file apr_thread_mutex.h + * @brief APR Thread Mutex Routines + */ + #include "apr.h" #include "apr_errno.h" @@ -62,16 +67,11 @@ extern "C" { #endif /* __cplusplus */ -#if APR_HAS_THREADS - -/** - * @file apr_thread_mutex.h - * @brief APR Thread Mutex Routines - */ +#if APR_HAS_THREADS || defined(DOXYGEN) /** - * @defgroup APR_ThreadMutex Thread Mutex Routines - * @ingroup APR + * @defgroup apr_thread_mutex Thread Mutex Routines + * @ingroup APR * @{ */ @@ -96,7 +96,7 @@ typedef struct apr_thread_mutex_t apr_thread_mutex_t; * APR_THREAD_MUTEX_UNNESTED disable nested locks (non-recursive). * </PRE> * @param pool the pool from which to allocate the mutex. - * @tip Be cautious in using APR_THREAD_MUTEX_DEFAULT. While this is the + * @warning Be cautious in using APR_THREAD_MUTEX_DEFAULT. While this is the * most optimial mutex based on a given platform's performance charateristics, * it will behave as either a nested or an unnested lock. */ @@ -137,9 +137,10 @@ APR_DECLARE(apr_status_t) apr_thread_mutex_destroy(apr_thread_mutex_t *mutex); */ APR_POOL_DECLARE_ACCESSOR(thread_mutex); - #endif /* APR_HAS_THREADS */ +/** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_thread_proc.h b/include/apr_thread_proc.h index 3233a9b89..805b9185d 100644 --- a/include/apr_thread_proc.h +++ b/include/apr_thread_proc.h @@ -55,6 +55,11 @@ #ifndef APR_THREAD_PROC_H #define APR_THREAD_PROC_H +/** + * @file apr_thread_proc.h + * @brief APR Thread and Process Library + */ + #include "apr.h" #include "apr_file_io.h" #include "apr_pools.h" @@ -65,17 +70,13 @@ #include <sys/resource.h> #endif - #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ + /** - * @file apr_thread_proc.h - * @brief APR Thread and Process Library - */ -/** - * @defgroup APR_Thread Thread Library - * @ingroup APR + * @defgroup apr_thread_proc Threads and Process Functions + * @ingroup APR * @{ */ @@ -131,7 +132,7 @@ typedef enum { #define APR_LIMIT_NOFILE 3 /** - * @defgroup Other_Child Other Child Flags + * @defgroup APR_OC Other Child Flags * @{ */ #define APR_OC_REASON_DEATH 0 /**< child has died, caller must call @@ -152,11 +153,8 @@ typedef enum { */ /** @} */ -/** @see apr_proc_t */ -typedef struct apr_proc_t apr_proc_t; - /** The APR process type */ -struct apr_proc_t { +typedef struct apr_proc_t { /** The process ID */ pid_t pid; /** Parent's side of pipe to child's stdin */ @@ -184,7 +182,7 @@ struct apr_proc_t { */ HANDLE hproc; #endif -}; +} apr_proc_t; /** * The prototype for APR child errfn functions. (See the description @@ -391,12 +389,6 @@ APR_DECLARE(apr_status_t) apr_threadkey_data_set(void *data, const char *key, #endif -/* Process Function definitions */ - -/** - * @package APR Process library - */ - /** * Create and initialize a new procattr variable * @param new_attr The newly created procattr. @@ -514,11 +506,13 @@ APR_DECLARE(apr_status_t) apr_procattr_limit_set(apr_procattr_t *attr, /** * Specify an error function to be called in the child process if APR * encounters an error in the child prior to running the specified program. - * @param child_errfn The function to call in the child process. - * @param userdata Parameter to be passed to errfn. + * @param attr The procattr describing the child process to be created. + * @param errfn The function to call in the child process. * @remark At the present time, it will only be called from apr_proc_create() * on platforms where fork() is used. It will never be called on other - * platforms. + * platforms, on those platforms apr_proc_create() will return the error + * in the parent process rather than invoke the callback in the now-forked + * child process. */ APR_DECLARE(apr_status_t) apr_procattr_child_errfn_set(apr_procattr_t *attr, apr_child_errfn_t *errfn); @@ -527,6 +521,7 @@ APR_DECLARE(apr_status_t) apr_procattr_child_errfn_set(apr_procattr_t *attr, * Specify that apr_proc_create() should do whatever it can to report * failures to the caller of apr_proc_create(), rather than find out in * the child. + * @param attr The procattr describing the child process to be created. * @param chk Flag to indicate whether or not extra work should be done * to try to report failures to the caller. * @remark This flag only affects apr_proc_create() on platforms where @@ -679,8 +674,9 @@ APR_DECLARE(void) apr_proc_other_child_unregister(void *data); /** * Notify the maintenance callback of a registered other child process * that application has detected an event, such as death. - * @param proc The process to check. - * @param status The status to pass to the maintenance function. + * @param proc The process to check + * @param reason The reason code to pass to the maintenance function + * @param status The status to pass to the maintenance function * @remark An example of code using this behavior; * <pre> * rv = apr_proc_wait_all_procs(&proc, &exitcode, &status, APR_WAIT, p); @@ -699,18 +695,34 @@ APR_DECLARE(apr_status_t) apr_proc_other_child_alert(apr_proc_t *proc, int reason, int status); +/** + * Test one specific other child processes and invoke the maintenance callback + * with the appropriate reason code, if still running, or the appropriate reason + * code if the process is no longer healthy. + * @param ocr The registered other child + * @param reason The reason code (e.g. APR_OC_REASON_RESTART) if still running + */ APR_DECLARE(void) apr_proc_other_child_refresh(apr_other_child_rec_t *ocr, int reason); +/** + * Test all registered other child processes and invoke the maintenance callback + * with the appropriate reason code, if still running, or the appropriate reason + * code if the process is no longer healthy. + * @param reason The reason code (e.g. APR_OC_REASON_RESTART) to running processes + */ APR_DECLARE(void) apr_proc_other_child_refresh_all(int reason); -/** @deprecated - * @see apr_proc_other_child_refresh_all(APR_OC_REASON_RESTART) +/** @deprecated @see apr_proc_other_child_refresh_all + * @remark Call apr_proc_other_child_refresh_all(APR_OC_REASON_RESTART) + * or apr_proc_other_child_refresh_all(APR_OC_REASON_RUNNING) instead. + * @bug The differing implementations of this function on Win32 (_RUNNING checks) + * and Unix (used only for _RESTART) are the reason it will be dropped with APR 1.0. */ APR_DECLARE(void) apr_proc_other_child_check(void); -/** @deprecated - * @see apr_proc_other_child_alert() +/** @deprecated @see apr_proc_other_child_alert + * @bug This function's name had nothing to do with it's purpose */ APR_DECLARE(apr_status_t) apr_proc_other_child_read(apr_proc_t *proc, int status); @@ -766,7 +778,9 @@ APR_DECLARE(apr_status_t) apr_signal_thread(int(*signal_handler)(int signum)); APR_POOL_DECLARE_ACCESSOR(thread); #endif /* APR_HAS_THREADS */ + /** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_thread_rwlock.h b/include/apr_thread_rwlock.h index 9f906abe7..210d2ec13 100644 --- a/include/apr_thread_rwlock.h +++ b/include/apr_thread_rwlock.h @@ -55,6 +55,11 @@ #ifndef APR_THREAD_RWLOCK_H #define APR_THREAD_RWLOCK_H +/** + * @file apr_thread_rwlock.h + * @brief APR Reader/Writer Lock Routines + */ + #include "apr.h" #include "apr_pools.h" #include "apr_errno.h" @@ -66,13 +71,8 @@ extern "C" { #if APR_HAS_THREADS /** - * @file apr_thread_rwlock.h - * @brief APR Thread RWLock Routines - */ - -/** - * @defgroup APR_ThreadRWLock Thread RWLock Routines - * @ingroup APR + * @defgroup apr_thread_rwlock Reader/Writer Lock Routines + * @ingroup APR * @{ */ @@ -149,6 +149,8 @@ APR_POOL_DECLARE_ACCESSOR(thread_rwlock); #endif /* APR_HAS_THREADS */ +/** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_time.h b/include/apr_time.h index bc5a7f145..60ae2de86 100644 --- a/include/apr_time.h +++ b/include/apr_time.h @@ -55,6 +55,11 @@ #ifndef APR_TIME_H #define APR_TIME_H +/** + * @file apr_time.h + * @brief APR Time Library + */ + #include "apr.h" #include "apr_pools.h" #include "apr_errno.h" @@ -62,15 +67,13 @@ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ + /** - * @file apr_time.h - * @brief APR Time Library - */ -/** - * @defgroup APR_Time Time Routines - * @ingroup APR + * @defgroup apr_time Time Routines + * @ingroup APR * @{ */ + /** month names */ APR_DECLARE_DATA extern const char apr_month_snames[12][4]; /** day names */ @@ -229,9 +232,9 @@ APR_DECLARE(void) apr_sleep(apr_interval_time_t t); #define APR_RFC822_DATE_LEN (30) /** * apr_rfc822_date formats dates in the RFC822 - * format in an efficient manner. it is a fixed length - * format and requires the indicated amount of storage - * including trailing \0 + * format in an efficient manner. It is a fixed length + * format which requires the indicated amount of storage, + * including the trailing null byte. * @param date_str String to write to. * @param t the time to convert */ @@ -242,10 +245,10 @@ APR_DECLARE(apr_status_t) apr_rfc822_date(char *date_str, apr_time_t t); /** * apr_ctime formats dates in the ctime() format * in an efficient manner. it is a fixed length format - * and requires the indicated amount of storage + * and requires the indicated amount of storage including + * the trailing null byte. * Unlike ANSI/ISO C ctime(), apr_ctime() does not include * a \n at the end of the string. - * including trailing \0 * @param date_str String to write to. * @param t the time to convert */ @@ -271,6 +274,8 @@ APR_DECLARE(apr_status_t) apr_strftime(char *s, apr_size_t *retsize, */ APR_DECLARE(void) apr_time_clock_hires(apr_pool_t *p); +/** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_user.h b/include/apr_user.h index 3b8648ec5..4b70c5c24 100644 --- a/include/apr_user.h +++ b/include/apr_user.h @@ -55,6 +55,11 @@ #ifndef APR_USER_H #define APR_USER_H +/** + * @file apr_user.h + * @brief APR User ID Services + */ + #include "apr.h" #include "apr_errno.h" #include "apr_pools.h" @@ -64,12 +69,8 @@ extern "C" { #endif /* __cplusplus */ /** - * @file apr_user.h - * @brief APR User ID Services - */ -/** - * @defgroup APR_User User id services - * @ingroup APR + * @defgroup apr_user User and Group ID Services + * @ingroup APR * @{ */ @@ -224,6 +225,7 @@ APR_DECLARE(apr_status_t) apr_compare_groups(apr_gid_t left, apr_gid_t right); #endif /* ! APR_HAS_USER */ /** @} */ + #ifdef __cplusplus } #endif diff --git a/include/apr_version.h b/include/apr_version.h index 2629b8400..ce3fdc3e2 100644 --- a/include/apr_version.h +++ b/include/apr_version.h @@ -63,7 +63,7 @@ extern "C" { /** * @file apr_version.h - * @brief + * @brief APR Versioning Interface * * APR's Version * diff --git a/include/apr_want.h b/include/apr_want.h index 7ab681090..27a27be0b 100644 --- a/include/apr_want.h +++ b/include/apr_want.h @@ -55,7 +55,7 @@ #include "apr.h" /* configuration data */ /** * @file apr_want.h - * @brief APR_WANT_HEADERS documentation + * @brief APR Standard Headers Support * * <PRE> * Features: |