diff options
| author | William A. Rowe Jr <wrowe@apache.org> | 2003-03-05 21:22:26 +0000 |
|---|---|---|
| committer | William A. Rowe Jr <wrowe@apache.org> | 2003-03-05 21:22:26 +0000 |
| commit | 26a1251cd50b032176c0c5d9bb6626c1a2b7bb52 (patch) | |
| tree | 665a1cf9958bf86499a3a742b654fe391c3a5705 | |
| parent | 1f3331ec7ac24dc7dbefd1ffcd179c7a5f1fbfc0 (diff) | |
| download | apr-26a1251cd50b032176c0c5d9bb6626c1a2b7bb52.tar.gz | |
Rebalance our exposed headers such that everything is nested properly
between extern "C" blocks and doxygen blocks, that we never include
other headers within our own header's extern "C" block, that we always
tag the entire file contents for doxygen (within the APR_HEADER_H
only-once block), and generally clean up doxygen so that it is all
consistent and generates respectable (although not yet 'great') results.
Major TODO after 0.9.2 releases; fill in the apr.h APR_HAVE/APR_HAS
and apr_type_t documentation!!!
git-svn-id: https://svn.apache.org/repos/asf/apr/apr/trunk@64397 13f79535-47bb-0310-9956-ffa450edef68
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: |