You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@apr.apache.org by je...@apache.org on 2002/11/10 09:35:17 UTC
cvs commit: apr/include apr_allocator.h apr_atomic.h apr_errno.h apr_file_info.h apr_file_io.h apr_general.h apr_getopt.h apr_global_mutex.h apr_lib.h apr_mmap.h apr_network_io.h apr_poll.h apr_pools.h apr_portable.h apr_proc_mutex.h apr_shm.h apr_signal.h apr_strings.h apr_support.h apr_tables.h apr_thread_cond.h apr_thread_mutex.h apr_thread_proc.h apr_thread_rwlock.h apr_time.h apr_version.h
jerenkrantz 2002/11/10 00:35:17
Modified: . CHANGES
include apr_allocator.h apr_atomic.h apr_errno.h
apr_file_info.h apr_file_io.h apr_general.h
apr_getopt.h apr_global_mutex.h apr_lib.h
apr_mmap.h apr_network_io.h apr_poll.h apr_pools.h
apr_portable.h apr_proc_mutex.h apr_shm.h
apr_signal.h apr_strings.h apr_support.h
apr_tables.h apr_thread_cond.h apr_thread_mutex.h
apr_thread_proc.h apr_thread_rwlock.h apr_time.h
apr_version.h
Log:
Go through doxygen output and remove as many errors and warnings as I could.
No code changes.
(Note removal of #define duplication in apr_poll.h/apr_network_io.h of the
APR_POLL* values. This appears to have been an oversight and is now just
in apr_poll.h)
Revision Changes Path
1.354 +2 -0 apr/CHANGES
Index: CHANGES
===================================================================
RCS file: /home/cvs/apr/CHANGES,v
retrieving revision 1.353
retrieving revision 1.354
diff -u -u -r1.353 -r1.354
--- CHANGES 6 Nov 2002 17:09:35 -0000 1.353
+++ CHANGES 10 Nov 2002 08:35:15 -0000 1.354
@@ -1,5 +1,7 @@
Changes with APR 0.9.2
+ *) Update doxygen tags. [Justin Erenkrantz]
+
*) NetWare: implemented a file IO path context scheme to directly
reference directory paths and files in the file system rather
than having to traverse the file system on every stat() or
1.11 +8 -6 apr/include/apr_allocator.h
Index: apr_allocator.h
===================================================================
RCS file: /home/cvs/apr/include/apr_allocator.h,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -u -r1.10 -r1.11
--- apr_allocator.h 4 Jul 2002 15:04:42 -0000 1.10
+++ apr_allocator.h 10 Nov 2002 08:35:16 -0000 1.11
@@ -81,15 +81,17 @@
/** the structure which holds information about the allocation */
typedef struct apr_memnode_t apr_memnode_t;
+/** basic memory node structure */
struct apr_memnode_t {
- apr_memnode_t *next;
- apr_memnode_t **ref;
- apr_uint32_t index;
- apr_uint32_t free_index;
- char *first_avail;
- char *endp;
+ apr_memnode_t *next; /**< next memnode */
+ apr_memnode_t **ref; /**< reference to self */
+ apr_uint32_t index; /**< size */
+ apr_uint32_t free_index; /**< how much free */
+ char *first_avail; /**< pointer to first free memory */
+ char *endp; /**< pointer to end of free memory */
};
+/** The base size of a memory node - aligned. */
#define APR_MEMNODE_T_SIZE APR_ALIGN_DEFAULT(sizeof(apr_memnode_t))
/** Symbolic constants */
1.42 +9 -9 apr/include/apr_atomic.h
Index: apr_atomic.h
===================================================================
RCS file: /home/cvs/apr/include/apr_atomic.h,v
retrieving revision 1.41
retrieving revision 1.42
diff -u -u -r1.41 -r1.42
--- apr_atomic.h 25 Oct 2002 16:14:22 -0000 1.41
+++ apr_atomic.h 10 Nov 2002 08:35:16 -0000 1.42
@@ -85,23 +85,23 @@
typedef apr_atomic_t;
/**
- * @param pool
* this function is required on some platforms to initialize the
* atomic operation's internal structures
- * returns APR_SUCCESS on successfull completion
+ * @param p pool
+ * @return APR_SUCCESS on successful completion
*/
apr_status_t apr_atomic_init(apr_pool_t *p);
/**
* read the value stored in a atomic variable
- * @param the pointer
+ * @param mem the pointer
* @warning on certain platforms this number is not stored
* directly in the pointer. in others it is
*/
apr_uint32_t apr_atomic_read(volatile apr_atomic_t *mem);
/**
* set the value for atomic.
- * @param the pointer
- * @param the value
+ * @param mem the pointer
+ * @param val the value
*/
void apr_atomic_set(volatile apr_atomic_t *mem, apr_uint32_t val);
/**
@@ -120,7 +120,7 @@
/**
* decrement the atomic variable by 1
* @param mem pointer to the atomic value
- * @returns zero if the value is zero, otherwise non-zero
+ * @return zero if the value is zero, otherwise non-zero
*/
int apr_atomic_dec(volatile apr_atomic_t *mem);
@@ -129,19 +129,19 @@
* If they are the same swap the value with 'with'
* @param mem pointer to the atomic value
* @param with what to swap it with
- * @param the value to compare it to
+ * @param cmp the value to compare it to
* @return the old value of the atomic
* @warning do not mix apr_atomic's with the CAS function.
* on some platforms they may be implemented by different mechanisms
*/
-apr_uint32_t apr_atomic_cas(volatile apr_uint32_t *mem,long with,long cmp);
+apr_uint32_t apr_atomic_cas(volatile apr_uint32_t *mem, long with, long cmp);
/**
* compare the pointer's value with cmp.
* If they are the same swap the value with 'with'
* @param mem pointer to the pointer
* @param with what to swap it with
- * @param the value to compare it to
+ * @param cmp the value to compare it to
* @return the old value of the pointer
*/
void *apr_atomic_casptr(volatile void **mem, void *with, const void *cmp);
1.101 +2 -2 apr/include/apr_errno.h
Index: apr_errno.h
===================================================================
RCS file: /home/cvs/apr/include/apr_errno.h,v
retrieving revision 1.100
retrieving revision 1.101
diff -u -u -r1.100 -r1.101
--- apr_errno.h 22 Oct 2002 13:52:15 -0000 1.100
+++ apr_errno.h 10 Nov 2002 08:35:16 -0000 1.101
@@ -94,7 +94,7 @@
* @def APR_FROM_OS_ERROR(os_err_type syserr)
* Fold a platform specific error into an apr_status_t code.
* @return apr_status_t
- * @param syserr The platform os error code.
+ * @param e The platform os error code.
* @warning macro implementation; the syserr argument may be evaluated
* multiple times.
*/
@@ -104,7 +104,7 @@
* @def APR_TO_OS_ERROR(apr_status_t statcode)
* @return os_err_type
* Fold an apr_status_t code back to the native platform defined error.
- * @param syserr The apr_status_t folded platform os error code.
+ * @param e The apr_status_t folded platform os error code.
* @warning 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.
1.33 +18 -17 apr/include/apr_file_info.h
Index: apr_file_info.h
===================================================================
RCS file: /home/cvs/apr/include/apr_file_info.h,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -u -r1.32 -r1.33
--- apr_file_info.h 20 Mar 2002 08:54:43 -0000 1.32
+++ apr_file_info.h 10 Nov 2002 08:35:16 -0000 1.33
@@ -147,6 +147,7 @@
* @defgroup APR_File_Info Stat Functions
* @{
*/
+/** file info structure */
typedef struct apr_finfo_t apr_finfo_t;
#define APR_FINFO_LINK 0x00000001 /**< Stat the link not the file itself if it is a link */
@@ -155,24 +156,24 @@
#define APR_FINFO_ATIME 0x00000040 /**< Access Time */
#define APR_FINFO_SIZE 0x00000100 /**< Size of the file */
#define APR_FINFO_CSIZE 0x00000200 /**< Storage size consumed by the file */
-#define APR_FINFO_DEV 0x00001000
-#define APR_FINFO_INODE 0x00002000
-#define APR_FINFO_NLINK 0x00004000
-#define APR_FINFO_TYPE 0x00008000
-#define APR_FINFO_USER 0x00010000
-#define APR_FINFO_GROUP 0x00020000
-#define APR_FINFO_UPROT 0x00100000
-#define APR_FINFO_GPROT 0x00200000
-#define APR_FINFO_WPROT 0x00400000
-#define APR_FINFO_ICASE 0x01000000 /**< if dev is case insensitive */
-#define APR_FINFO_NAME 0x02000000 /**< ->name in proper case */
+#define APR_FINFO_DEV 0x00001000 /**< Device */
+#define APR_FINFO_INODE 0x00002000 /**< Inode */
+#define APR_FINFO_NLINK 0x00004000 /**< Number of links */
+#define APR_FINFO_TYPE 0x00008000 /**< Type */
+#define APR_FINFO_USER 0x00010000 /**< User */
+#define APR_FINFO_GROUP 0x00020000 /**< Group */
+#define APR_FINFO_UPROT 0x00100000 /**< User protection bits */
+#define APR_FINFO_GPROT 0x00200000 /**< Group protection bits */
+#define APR_FINFO_WPROT 0x00400000 /**< World protection bits */
+#define APR_FINFO_ICASE 0x01000000 /**< if dev is case insensitive */
+#define APR_FINFO_NAME 0x02000000 /**< ->name in proper case */
-#define APR_FINFO_MIN 0x00008170 /**< type, mtime, ctime, atime, size */
-#define APR_FINFO_IDENT 0x00003000 /**< dev and inode */
-#define APR_FINFO_OWNER 0x00030000 /**< user and group */
-#define APR_FINFO_PROT 0x00700000 /**< all protections */
-#define APR_FINFO_NORM 0x0073b170 /**< an atomic unix apr_stat() */
-#define APR_FINFO_DIRENT 0x02000000 /**< an atomic unix apr_dir_read() */
+#define APR_FINFO_MIN 0x00008170 /**< type, mtime, ctime, atime, size */
+#define APR_FINFO_IDENT 0x00003000 /**< dev and inode */
+#define APR_FINFO_OWNER 0x00030000 /**< user and group */
+#define APR_FINFO_PROT 0x00700000 /**< all protections */
+#define APR_FINFO_NORM 0x0073b170 /**< an atomic unix apr_stat() */
+#define APR_FINFO_DIRENT 0x02000000 /**< an atomic unix apr_dir_read() */
/**
* The file information structure. This is analogous to the POSIX
1.134 +5 -1 apr/include/apr_file_io.h
Index: apr_file_io.h
===================================================================
RCS file: /home/cvs/apr/include/apr_file_io.h,v
retrieving revision 1.133
retrieving revision 1.134
diff -u -u -r1.133 -r1.134
--- apr_file_io.h 14 Oct 2002 20:07:33 -0000 1.133
+++ apr_file_io.h 10 Nov 2002 08:35:16 -0000 1.134
@@ -113,8 +113,11 @@
*/
/* flags for apr_file_seek */
+/** Set the file position */
#define APR_SET SEEK_SET
+/** Current */
#define APR_CUR SEEK_CUR
+/** Go to end of file */
#define APR_END SEEK_END
/** @} */
@@ -638,7 +641,8 @@
* will be reported if PATH already exists.
* @param path the path for the directory to be created. (use / on all systems)
* @param perm Permissions for the new direcoty.
- * @param cont the pool to use. */
+ * @param pool the pool to use.
+ */
APR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path,
apr_fileperms_t perm,
apr_pool_t *pool);
1.75 +4 -0 apr/include/apr_general.h
Index: apr_general.h
===================================================================
RCS file: /home/cvs/apr/include/apr_general.h,v
retrieving revision 1.74
retrieving revision 1.75
diff -u -u -r1.74 -r1.75
--- apr_general.h 8 Jul 2002 17:39:29 -0000 1.74
+++ apr_general.h 10 Nov 2002 08:35:16 -0000 1.75
@@ -106,6 +106,7 @@
/** a tab */
#define APR_ASCII_TAB '\011'
+/** signal numbers typedef */
typedef int apr_signum_t;
/**
@@ -181,6 +182,7 @@
#define APR_ALIGN(size, boundary) \
(((size) + ((boundary) - 1)) & ~((boundary) - 1))
+/** Default alignment */
#define APR_ALIGN_DEFAULT(size) APR_ALIGN(size, 8)
@@ -188,7 +190,9 @@
* String and memory functions
*/
+/** Properly quote a value as a string in the C preprocessor */
#define APR_STRINGIFY(n) APR_STRINGIFY_HELPER(n)
+/** Helper macro for APR_STRINGIFY */
#define APR_STRINGIFY_HELPER(n) #n
#if (!APR_HAVE_MEMMOVE)
1.39 +3 -0 apr/include/apr_getopt.h
Index: apr_getopt.h
===================================================================
RCS file: /home/cvs/apr/include/apr_getopt.h,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -u -r1.38 -r1.39
--- apr_getopt.h 13 Mar 2002 20:39:14 -0000 1.38
+++ apr_getopt.h 10 Nov 2002 08:35:16 -0000 1.39
@@ -76,7 +76,9 @@
*/
typedef void (apr_getopt_err_fn_t)(void *arg, const char *err, ...);
+/** @see apr_getopt_t */
typedef struct apr_getopt_t apr_getopt_t;
+
/**
* Structure to store command line argument information.
*/
@@ -107,6 +109,7 @@
int skip_end;
};
+/** @see apr_getopt_option_t */
typedef struct apr_getopt_option_t apr_getopt_option_t;
/**
1.8 +1 -0 apr/include/apr_global_mutex.h
Index: apr_global_mutex.h
===================================================================
RCS file: /home/cvs/apr/include/apr_global_mutex.h,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -u -r1.7 -r1.8
--- apr_global_mutex.h 9 Apr 2002 06:56:55 -0000 1.7
+++ apr_global_mutex.h 10 Nov 2002 08:35:16 -0000 1.8
@@ -77,6 +77,7 @@
#if !APR_PROC_MUTEX_IS_GLOBAL || defined(DOXYGEN)
+/** Opaque global mutex structure. */
typedef struct apr_global_mutex_t apr_global_mutex_t;
/* Function definitions */
1.59 +2 -0 apr/include/apr_lib.h
Index: apr_lib.h
===================================================================
RCS file: /home/cvs/apr/include/apr_lib.h,v
retrieving revision 1.58
retrieving revision 1.59
diff -u -u -r1.58 -r1.59
--- apr_lib.h 17 Jul 2002 02:53:25 -0000 1.58
+++ apr_lib.h 10 Nov 2002 08:35:16 -0000 1.59
@@ -78,12 +78,14 @@
extern "C" {
#endif /* __cplusplus */
+/** A constant representing a 'large' string. */
#define HUGE_STRING_LEN 8192
/*
* Define the structures used by the APR general-purpose library.
*/
+/** @see apr_vformatter_buff_t */
typedef struct apr_vformatter_buff_t apr_vformatter_buff_t;
/**
1.33 +12 -3 apr/include/apr_mmap.h
Index: apr_mmap.h
===================================================================
RCS file: /home/cvs/apr/include/apr_mmap.h,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -u -r1.32 -r1.33
--- apr_mmap.h 2 Jul 2002 23:40:37 -0000 1.32
+++ apr_mmap.h 10 Nov 2002 08:35:16 -0000 1.33
@@ -77,10 +77,14 @@
* @{
*/
+/** MMap opened for reading */
#define APR_MMAP_READ 1
+/** MMap opened for writing */
#define APR_MMAP_WRITE 2
+/** @see apr_mmap_t */
typedef struct apr_mmap_t apr_mmap_t;
+
/**
* @remark
* As far as I can tell the only really sane way to store an MMAP is as a
@@ -117,7 +121,8 @@
#if APR_HAS_MMAP || defined(DOXYGEN)
-/* Files have to be at least this big before they're mmap()d. This is to deal
+/** @def APR_MMAP_THRESHOLD
+ * Files have to be at least this big before they're mmap()d. This is to deal
* with systems where the expense of doing an mmap() and an munmap() outweighs
* the benefit for small files. It shouldn't be set lower than 1.
*/
@@ -131,12 +136,16 @@
# endif /* SUNOS4 */
#endif /* MMAP_THRESHOLD */
+/** @def APR_MMAP_LIMIT
+ * Maximum size of MMap region
+ */
#ifdef MMAP_LIMIT
# define APR_MMAP_LIMIT MMAP_LIMIT
#else
# define APR_MMAP_LIMIT (4*1024*1024)
#endif /* MMAP_LIMIT */
+/** Can this file be MMaped */
#define APR_MMAP_CANDIDATE(filelength) \
((filelength >= APR_MMAP_THRESHOLD) && (filelength < APR_MMAP_LIMIT))
@@ -191,14 +200,14 @@
/**
* Remove a mmap'ed.
- * @param mmap The mmap'ed file.
+ * @param mm The mmap'ed file.
*/
APR_DECLARE(apr_status_t) apr_mmap_delete(apr_mmap_t *mm);
/**
* Move the pointer into the mmap'ed file to the specified offset.
* @param addr The pointer to the offset specified.
- * @param mmap The mmap'ed file.
+ * @param mm The mmap'ed file.
* @param offset The offset to move to.
*/
APR_DECLARE(apr_status_t) apr_mmap_offset(void **addr, apr_mmap_t *mm,
1.132 +36 -28 apr/include/apr_network_io.h
Index: apr_network_io.h
===================================================================
RCS file: /home/cvs/apr/include/apr_network_io.h,v
retrieving revision 1.131
retrieving revision 1.132
diff -u -u -r1.131 -r1.132
--- apr_network_io.h 22 Oct 2002 20:05:34 -0000 1.131
+++ apr_network_io.h 10 Nov 2002 08:35:16 -0000 1.132
@@ -79,14 +79,17 @@
#endif /* __cplusplus */
#ifndef MAX_SECS_TO_LINGER
+/** Maximum seconds to linger */
#define MAX_SECS_TO_LINGER 30
#endif
#ifndef APRMAXHOSTLEN
+/** Maximum hostname length */
#define APRMAXHOSTLEN 256
#endif
#ifndef APR_ANYADDR
+/** Default 'any' address */
#define APR_ANYADDR "0.0.0.0"
#endif
@@ -94,19 +97,19 @@
* @defgroup Sock_opt Socket option definitions
* @{
*/
-#define APR_SO_LINGER 1
-#define APR_SO_KEEPALIVE 2
-#define APR_SO_DEBUG 4
-#define APR_SO_NONBLOCK 8
-#define APR_SO_REUSEADDR 16
-#define APR_SO_TIMEOUT 32
-#define APR_SO_SNDBUF 64
-#define APR_SO_RCVBUF 128
-#define APR_SO_DISCONNECTED 256
+#define APR_SO_LINGER 1 /**< Linger */
+#define APR_SO_KEEPALIVE 2 /**< Keepalive */
+#define APR_SO_DEBUG 4 /**< Debug */
+#define APR_SO_NONBLOCK 8 /**< Non-blocking IO */
+#define APR_SO_REUSEADDR 16 /**< Reuse addresses */
+#define APR_SO_TIMEOUT 32 /**< Timeout */
+#define APR_SO_SNDBUF 64 /**< Send buffer */
+#define APR_SO_RCVBUF 128 /**< Receive buffer */
+#define APR_SO_DISCONNECTED 256 /**< Disconnected */
#define APR_TCP_NODELAY 512 /**< For SCTP sockets, this is mapped
* to STCP_NODELAY internally.
*/
-#define APR_TCP_NOPUSH 1024
+#define APR_TCP_NOPUSH 1024 /**< No push */
#define APR_RESET_NODELAY 2048 /**< This flag is ONLY set internally
* when we set APR_TCP_NOPUSH with
* APR_TCP_NODELAY set to tell us that
@@ -124,22 +127,21 @@
* read, in cases where the app expects
* that an immediate read would fail.)
*/
-#define APR_INCOMPLETE_WRITE 8192 /* like APR_INCOMPLETE_READ, but for write
+#define APR_INCOMPLETE_WRITE 8192 /**< like APR_INCOMPLETE_READ, but for write
+ * @see APR_INCOMPLETE_READ
*/
-#define APR_POLLIN 0x001
-#define APR_POLLPRI 0x002
-#define APR_POLLOUT 0x004
-#define APR_POLLERR 0x010
-#define APR_POLLHUP 0x020
-#define APR_POLLNVAL 0x040
/** @} */
-typedef enum {APR_SHUTDOWN_READ, APR_SHUTDOWN_WRITE,
- APR_SHUTDOWN_READWRITE} apr_shutdown_how_e;
+/** Define what type of socket shutdown should occur. */
+typedef enum {
+ APR_SHUTDOWN_READ, /**< no longer allow read request */
+ APR_SHUTDOWN_WRITE, /**< no longer allow write requests */
+ APR_SHUTDOWN_READWRITE /**< no longer allow read or write requests */
+} apr_shutdown_how_e;
-#define APR_IPV4_ADDR_OK 0x01 /* see doc for apr_sockaddr_info_get() */
-#define APR_IPV6_ADDR_OK 0x02 /* see doc for apr_sockaddr_info_get() */
+#define APR_IPV4_ADDR_OK 0x01 /**< @see apr_sockaddr_info_get() */
+#define APR_IPV6_ADDR_OK 0x02 /**< @see apr_sockaddr_info_get() */
#if (!APR_HAVE_IN_ADDR)
/**
@@ -173,9 +175,9 @@
* @defgroup IP_Proto IP Protocol Definitions for use when creating sockets
* @{
*/
-#define APR_PROTO_TCP 6
-#define APR_PROTO_UDP 17
-#define APR_PROTO_SCTP 132
+#define APR_PROTO_TCP 6 /**< TCP */
+#define APR_PROTO_UDP 17 /**< UDP */
+#define APR_PROTO_SCTP 132 /**< SCTP */
/** @} */
@@ -201,11 +203,13 @@
#define apr_inet_addr inet_network
#endif
+/** A structure to represent sockets */
typedef struct apr_socket_t apr_socket_t;
/**
* A structure to encapsulate headers and trailers for apr_sendfile
*/
typedef struct apr_hdtr_t apr_hdtr_t;
+/** A structure to represent in_addr */
typedef struct in_addr apr_in_addr_t;
/** A structure to represent an IP subnet */
typedef struct apr_ipsubnet_t apr_ipsubnet_t;
@@ -213,13 +217,13 @@
/** @remark use apr_uint16_t just in case some system has a short that isn't 16 bits... */
typedef apr_uint16_t apr_port_t;
-/* It's defined here as I think it should all be platform safe...
+/** @remark It's defined here as I think it should all be platform safe...
+ * @see apr_sockaddr_t
*/
+typedef struct apr_sockaddr_t apr_sockaddr_t;
/**
* APRs socket address type, used to ensure protocol independence
*/
-typedef struct apr_sockaddr_t apr_sockaddr_t;
-
struct apr_sockaddr_t {
/** The pool to use... */
apr_pool_t *pool;
@@ -231,6 +235,7 @@
apr_port_t port;
/** The family */
apr_int32_t family;
+ /** Union of either IPv4 or IPv6 sockaddr. */
union {
/** IPv4 sockaddr structure */
struct sockaddr_in sin;
@@ -310,6 +315,7 @@
* APR_SHUTDOWN_WRITE no longer allow write requests
* APR_SHUTDOWN_READWRITE no longer allow read or write requests
* </PRE>
+ * @see apr_shutdown_how_e
* @remark This does not actually close the socket descriptor, it just
* controls which calls are still valid on the socket.
*/
@@ -511,7 +517,8 @@
/**
* @param sock The socket to send from
* @param where The apr_sockaddr_t describing where to send the data
- * @param data The data to send
+ * @param flags The flags to use
+ * @param buf The data to send
* @param len The length of the data to send
*/
APR_DECLARE(apr_status_t) apr_sendto(apr_socket_t *sock, apr_sockaddr_t *where,
@@ -521,6 +528,7 @@
/**
* @param from The apr_sockaddr_t to fill in the recipient info
* @param sock The socket to use
+ * @param flags The flags to use
* @param buf The buffer to use
* @param len The length of the available buffer
*/
1.8 +31 -26 apr/include/apr_poll.h
Index: apr_poll.h
===================================================================
RCS file: /home/cvs/apr/include/apr_poll.h,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -u -r1.7 -r1.8
--- apr_poll.h 26 Sep 2002 17:51:54 -0000 1.7
+++ apr_poll.h 10 Nov 2002 08:35:16 -0000 1.8
@@ -55,11 +55,11 @@
#ifndef APR_POLL_H
#define APR_POLL_H
/**
- * @file apr_network_io.h
- * @brief APR Network library
+ * @file apr_poll.h
+ * @brief APR Poll interface
*/
/**
- * @defgroup APR_Net Network Routines
+ * @defgroup APR_Poll Poll Routines
* @ingroup APR
* @{
*/
@@ -83,35 +83,39 @@
* @defgroup Poll options
* @{
*/
-#define APR_POLLIN 0x001
-#define APR_POLLPRI 0x002
-#define APR_POLLOUT 0x004
-#define APR_POLLERR 0x010
-#define APR_POLLHUP 0x020
-#define APR_POLLNVAL 0x040
+#define APR_POLLIN 0x001 /**< Can read without blocking */
+#define APR_POLLPRI 0x002 /**< Priority data available */
+#define APR_POLLOUT 0x004 /**< Can write without blocking */
+#define APR_POLLERR 0x010 /**< Pending error */
+#define APR_POLLHUP 0x020 /**< Hangup occurred */
+#define APR_POLLNVAL 0x040 /**< Descriptior invalid */
/** @} */
+/** Used in apr_pollfd_t to determine what the apr_descriptor is */
typedef enum {
- APR_NO_DESC,
- APR_POLL_SOCKET,
- APR_POLL_FILE,
- APR_POLL_LASTDESC
+ APR_NO_DESC, /**< nothing here */
+ APR_POLL_SOCKET, /**< descriptor refers to a socket */
+ APR_POLL_FILE, /**< descriptor refers to a file */
+ APR_POLL_LASTDESC /**< descriptor is the last one in the list */
} apr_datatype_e ;
+/** Union of either an APR file or socket. */
typedef union {
- apr_file_t *f;
- apr_socket_t *s;
+ apr_file_t *f; /**< file */
+ apr_socket_t *s; /**< socket */
} apr_descriptor;
+/** @see apr_pollfd_t */
typedef struct apr_pollfd_t apr_pollfd_t;
+/** Poll descriptor set. */
struct apr_pollfd_t {
- apr_pool_t *p;
- apr_datatype_e desc_type;
- apr_int16_t reqevents;
- apr_int16_t rtnevents;
- apr_descriptor desc;
- void *client_data; /* allows app to associate context with a descriptor */
+ apr_pool_t *p; /**< associated pool */
+ apr_datatype_e desc_type; /**< descriptor type */
+ apr_int16_t reqevents; /**< requested events */
+ apr_int16_t rtnevents; /**< returned events */
+ apr_descriptor desc; /**< @see apr_descriptor */
+ void *client_data; /**< allows app to associate context */
};
/**
@@ -128,7 +132,7 @@
/**
* Poll the sockets in the poll structure
* @param aprset The poll structure we will be using.
- * @param num The number of sockets we are polling
+ * @param numsock The number of sockets we are polling
* @param nsds The number of sockets signalled.
* @param timeout The amount of time in microseconds to wait. This is
* a maximum, not a minimum. If a socket is signalled, we
@@ -149,7 +153,7 @@
/**
* Add a socket to the poll structure.
* @param aprset The poll structure we will be using.
- * @param socket The socket to add to the current poll structure.
+ * @param sock The socket to add to the current poll structure.
* @param event The events to look for when we do the poll. One of:
* <PRE>
* APR_POLLIN signal if read will not block
@@ -224,6 +228,7 @@
* file descriptors
*/
+/** Opaque structure used for pollset API */
typedef struct apr_pollset_t apr_pollset_t;
/**
@@ -249,9 +254,9 @@
* Add a socket or file descriptor to a pollset
* @param pollset The pollset to which to add the descriptor
* @param descriptor The descriptor to add
- * @param remark If you set client_data in the descriptor, that value
- * will be returned in the client_data field whenever this
- * descriptor is signalled in apr_pollset_poll().
+ * @remark If you set client_data in the descriptor, that value
+ * will be returned in the client_data field whenever this
+ * descriptor is signalled in apr_pollset_poll().
*/
APR_DECLARE(apr_status_t) apr_pollset_add(apr_pollset_t *pollset,
const apr_pollfd_t *descriptor);
1.98 +1 -1 apr/include/apr_pools.h
Index: apr_pools.h
===================================================================
RCS file: /home/cvs/apr/include/apr_pools.h,v
retrieving revision 1.97
retrieving revision 1.98
diff -u -u -r1.97 -r1.98
--- apr_pools.h 24 Jun 2002 02:00:22 -0000 1.97
+++ apr_pools.h 10 Nov 2002 08:35:16 -0000 1.98
@@ -212,7 +212,7 @@
* pool. If it is non-NULL, the new pool will inherit all
* of its parent pool's attributes, except the apr_pool_t will
* be a sub-pool.
- * @param apr_abort A function to use if the pool cannot allocate more memory.
+ * @param abort_fn A function to use if the pool cannot allocate more memory.
* @param allocator The allocator to use with the new pool. If NULL the
* allocator of the parent pool will be used.
*/
1.84 +26 -15 apr/include/apr_portable.h
Index: apr_portable.h
===================================================================
RCS file: /home/cvs/apr/include/apr_portable.h,v
retrieving revision 1.83
retrieving revision 1.84
diff -u -u -r1.83 -r1.84
--- apr_portable.h 21 Oct 2002 11:19:41 -0000 1.83
+++ apr_portable.h 10 Nov 2002 08:35:16 -0000 1.84
@@ -160,6 +160,7 @@
* denominator typedefs for all UNIX-like systems. :)
*/
+/** Basic OS process mutex structure. */
struct apr_os_proc_mutex_t {
#if APR_HAS_SYSVSEM_SERIALIZE || APR_HAS_FCNTL_SERIALIZE || APR_HAS_FLOCK_SERIALIZE
int crossproc;
@@ -175,18 +176,23 @@
#endif
};
-typedef int apr_os_file_t;
-typedef DIR apr_os_dir_t;
-typedef int apr_os_sock_t;
-typedef struct apr_os_proc_mutex_t apr_os_proc_mutex_t;
+typedef int apr_os_file_t; /**< native file */
+typedef DIR apr_os_dir_t; /**< native dir */
+typedef int apr_os_sock_t; /**< native dir */
+typedef struct apr_os_proc_mutex_t apr_os_proc_mutex_t; /**< native proces
+ * mutex
+ */
#if APR_HAS_THREADS && APR_HAVE_PTHREAD_H
-typedef pthread_t apr_os_thread_t;
-typedef pthread_key_t apr_os_threadkey_t;
-#endif
-typedef pid_t apr_os_proc_t;
-typedef struct timeval apr_os_imp_time_t;
-typedef struct tm apr_os_exp_time_t;
-/* dso types... */
+typedef pthread_t apr_os_thread_t; /**< native thread */
+typedef pthread_key_t apr_os_threadkey_t; /**< native thread address
+ * space */
+#endif
+typedef pid_t apr_os_proc_t; /**< native pid */
+typedef struct timeval apr_os_imp_time_t; /**< native timeval */
+typedef struct tm apr_os_exp_time_t; /**< native tm */
+/** @var apr_os_dso_handle_t
+ * native dso types
+ */
#if defined(HPUX) || defined(HPUX10) || defined(HPUX11)
#include <dl.h>
typedef shl_t apr_os_dso_handle_t;
@@ -196,7 +202,7 @@
#else
typedef void * apr_os_dso_handle_t;
#endif
-typedef void* apr_os_shm_t;
+typedef void* apr_os_shm_t; /**< native SHM */
#endif
@@ -221,10 +227,15 @@
typedef struct apr_os_sock_info_t apr_os_sock_info_t;
-#if APR_PROC_MUTEX_IS_GLOBAL
+#if APR_PROC_MUTEX_IS_GLOBAL || defined(DOXYGEN)
+/** Opaque global mutex type */
#define apr_os_global_mutex_t apr_os_proc_mutex_t
+/** @return apr_os_global_mutex */
#define apr_os_global_mutex_get apr_os_proc_mutex_get
#else
+ /** Thread and process mutex for those platforms where process mutexes
+ * are not held in threads.
+ */
struct apr_os_global_mutex_t {
apr_pool_t *pool;
apr_proc_mutex_t *proc_mutex;
@@ -283,8 +294,8 @@
/**
* Get the imploded time in the platforms native format.
- * @param ostime the native time format
- * @param aprtimethe time to convert
+ * @param ostime the native time format
+ * @param aprtime the time to convert
*/
APR_DECLARE(apr_status_t) apr_os_imp_time_get(apr_os_imp_time_t **ostime,
apr_time_t *aprtime);
1.9 +15 -4 apr/include/apr_proc_mutex.h
Index: apr_proc_mutex.h
===================================================================
RCS file: /home/cvs/apr/include/apr_proc_mutex.h,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -u -r1.8 -r1.9
--- apr_proc_mutex.h 7 Jun 2002 14:04:34 -0000 1.8
+++ apr_proc_mutex.h 10 Nov 2002 08:35:16 -0000 1.9
@@ -74,10 +74,21 @@
* @{
*/
-typedef enum {APR_LOCK_FCNTL, APR_LOCK_FLOCK, APR_LOCK_SYSVSEM,
- APR_LOCK_PROC_PTHREAD, APR_LOCK_POSIXSEM,
- APR_LOCK_DEFAULT} apr_lockmech_e;
+/**
+ * Enumerated potential types for APR process locking methods
+ * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports
+ * APR_LOCK_foo. Only APR_LOCK_DEFAULT is portable.
+ */
+typedef enum {
+ APR_LOCK_FCNTL, /**< fcntl() */
+ APR_LOCK_FLOCK, /**< flock() */
+ APR_LOCK_SYSVSEM, /**< System V Semaphores */
+ APR_LOCK_PROC_PTHREAD, /**< POSIX pthread process-based locking */
+ APR_LOCK_POSIXSEM, /**< POSIX semaphore process-based locking */
+ APR_LOCK_DEFAULT /**< Use the default process lock */
+} apr_lockmech_e;
+/** Opaque structure representing a process mutex. */
typedef struct apr_proc_mutex_t apr_proc_mutex_t;
/* Function definitions */
@@ -99,6 +110,7 @@
* APR_LOCK_DEFAULT pick the default mechanism for the platform
* </PRE>
* @param pool the pool from which to allocate the mutex.
+ * @see apr_lockmech_e
* @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports
* APR_LOCK_foo. Only APR_LOCK_DEFAULT is portable.
*/
@@ -159,7 +171,6 @@
/**
* Display the name of the default mutex: APR_LOCK_DEFAULT
- * @param mutex the name of the default mutex
*/
APR_DECLARE(const char *) apr_proc_mutex_defname(void);
1.3 +2 -2 apr/include/apr_shm.h
Index: apr_shm.h
===================================================================
RCS file: /home/cvs/apr/include/apr_shm.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -u -r1.2 -r1.3
--- apr_shm.h 13 Mar 2002 20:39:15 -0000 1.2
+++ apr_shm.h 10 Nov 2002 08:35:16 -0000 1.3
@@ -84,7 +84,7 @@
* Create and make accessable a shared memory segment.
* @param m The shared memory structure to create.
* @param reqsize The desired size of the segment.
- * @param file The file to use for shared memory on platforms that
+ * @param filename The file to use for shared memory on platforms that
* require it.
* @param pool the pool from which to allocate the shared memory
* structure.
@@ -118,7 +118,7 @@
* Attach to a shared memory segment that was created
* by another process.
* @param m The shared memory structure to create.
- * @param file The file used to create the original segment.
+ * @param filename The file used to create the original segment.
* (This MUST match the original filename.)
* @param pool the pool from which to allocate the shared memory
* structure for this process.
1.15 +3 -3 apr/include/apr_signal.h
Index: apr_signal.h
===================================================================
RCS file: /home/cvs/apr/include/apr_signal.h,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -u -r1.14 -r1.15
--- apr_signal.h 8 Jun 2002 20:30:13 -0000 1.14
+++ apr_signal.h 10 Nov 2002 08:35:16 -0000 1.15
@@ -76,7 +76,7 @@
* @{
*/
-#if APR_HAVE_SIGACTION
+#if APR_HAVE_SIGACTION || defined(DOXYGEN)
#if defined(DARWIN) && !defined(__cplusplus) && !defined(_ANSI_SOURCE)
/* work around Darwin header file bugs
@@ -90,13 +90,13 @@
#define SIG_ERR (void (*)(int))-1
#endif
+/** Function prototype for signal handlers */
typedef void apr_sigfunc_t(int);
-/* ### how to doc this? */
/**
* Set the signal handler function for a given signal
* @param signo The signal (eg... SIGWINCH)
- * @parm the function to get called
+ * @param func the function to get called
*/
APR_DECLARE(apr_sigfunc_t *) apr_signal(int signo, apr_sigfunc_t * func);
1.32 +1 -1 apr/include/apr_strings.h
Index: apr_strings.h
===================================================================
RCS file: /home/cvs/apr/include/apr_strings.h,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -u -r1.31 -r1.32
--- apr_strings.h 6 Sep 2002 20:27:06 -0000 1.31
+++ apr_strings.h 10 Nov 2002 08:35:16 -0000 1.32
@@ -236,7 +236,7 @@
/**
* Convert the arguments to a program from one string to an array of
* strings terminated by a NULL pointer
- * @param str The arguments to convert
+ * @param arg_str The arguments to convert
* @param argv_out Output location. This is a pointer to an array of strings.
* @param token_context Pool to use.
*/
1.2 +5 -2 apr/include/apr_support.h
Index: apr_support.h
===================================================================
RCS file: /home/cvs/apr/include/apr_support.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -u -r1.1 -r1.2
--- apr_support.h 11 Jul 2002 05:19:44 -0000 1.1
+++ apr_support.h 10 Nov 2002 08:35:16 -0000 1.2
@@ -55,7 +55,7 @@
#ifndef APR_SUPPORT_H
#define APR_SUPPORT_H
/**
- * @file apr_file_io.h
+ * @file apr_support.h
* @brief APR Support functions
*/
/**
@@ -72,8 +72,11 @@
extern "C" {
#endif /* __cplusplus */
+/**
+ * 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);
+ int for_read);
#ifdef __cplusplus
}
1.35 +4 -3 apr/include/apr_tables.h
Index: apr_tables.h
===================================================================
RCS file: /home/cvs/apr/include/apr_tables.h,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -u -r1.34 -r1.35
--- apr_tables.h 2 Sep 2002 09:27:57 -0000 1.34
+++ apr_tables.h 10 Nov 2002 08:35:16 -0000 1.35
@@ -86,9 +86,10 @@
/** the table abstract data type */
typedef struct apr_table_t apr_table_t;
-/** An opaque array type */
+/** @see apr_array_header_t */
typedef struct apr_array_header_t apr_array_header_t;
+/** An opaque array type */
struct apr_array_header_t {
/** The pool the array is allocated out of */
apr_pool_t *pool;
@@ -204,7 +205,7 @@
* @param p The pool to allocate the new array out of
* @param first The array to put first in the new array.
* @param second The array to put second in the new array.
- * @param return A new array containing the data from the two arrays passed in.
+ * @return A new array containing the data from the two arrays passed in.
*/
APR_DECLARE(apr_array_header_t *) apr_array_append(apr_pool_t *p,
const apr_array_header_t *first,
@@ -353,7 +354,7 @@
* and apr_table_vdo().
* @param rec The data passed as the first argument to apr_table_[v]do()
* @param key The key from this iteration of the table
- * @param key The value from this iteration of the table
+ * @param value The value from this iteration of the table
* @remark Iteration continues while this callback function returns non-zero.
* To export the callback function for apr_table_[v]do() it must be declared
* in the _NONSTD convention.
1.6 +1 -0 apr/include/apr_thread_cond.h
Index: apr_thread_cond.h
===================================================================
RCS file: /home/cvs/apr/include/apr_thread_cond.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -u -r1.5 -r1.6
--- apr_thread_cond.h 13 Mar 2002 20:39:15 -0000 1.5
+++ apr_thread_cond.h 10 Nov 2002 08:35:16 -0000 1.6
@@ -78,6 +78,7 @@
* @{
*/
+/** Opaque structure for thread condition variables */
typedef struct apr_thread_cond_t apr_thread_cond_t;
/* Function definitions */
1.12 +4 -3 apr/include/apr_thread_mutex.h
Index: apr_thread_mutex.h
===================================================================
RCS file: /home/cvs/apr/include/apr_thread_mutex.h,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -u -r1.11 -r1.12
--- apr_thread_mutex.h 29 May 2002 21:19:44 -0000 1.11
+++ apr_thread_mutex.h 10 Nov 2002 08:35:16 -0000 1.12
@@ -75,11 +75,12 @@
* @{
*/
+/** Opaque thread-local mutex structure */
typedef struct apr_thread_mutex_t apr_thread_mutex_t;
-#define APR_THREAD_MUTEX_DEFAULT 0x0
-#define APR_THREAD_MUTEX_NESTED 0x1
-#define APR_THREAD_MUTEX_UNNESTED 0x2
+#define APR_THREAD_MUTEX_DEFAULT 0x0 /**< platform-optimal lock behavior */
+#define APR_THREAD_MUTEX_NESTED 0x1 /**< enable nested (recursive) locks */
+#define APR_THREAD_MUTEX_UNNESTED 0x2 /**< disable nested locks */
/* Delayed the include to avoid a circular reference */
#include "apr_pools.h"
1.88 +11 -4 apr/include/apr_thread_proc.h
Index: apr_thread_proc.h
===================================================================
RCS file: /home/cvs/apr/include/apr_thread_proc.h,v
retrieving revision 1.87
retrieving revision 1.88
diff -u -u -r1.87 -r1.88
--- apr_thread_proc.h 9 Jul 2002 01:33:42 -0000 1.87
+++ apr_thread_proc.h 10 Nov 2002 08:35:16 -0000 1.88
@@ -150,6 +150,7 @@
/** @} */
#endif /* APR_HAS_OTHER_CHILD */
+/** @see apr_proc_t */
typedef struct apr_proc_t apr_proc_t;
/** The APR process type */
@@ -176,13 +177,19 @@
#endif
};
+/** Opaque Thread structure. */
typedef struct apr_thread_t apr_thread_t;
+/** Opaque Thread attributes structure. */
typedef struct apr_threadattr_t apr_threadattr_t;
+/** Opaque Process attributes structure. */
typedef struct apr_procattr_t apr_procattr_t;
+/** Opaque control variable for one-time atomic variables. */
typedef struct apr_thread_once_t apr_thread_once_t;
+/** Opaque thread private address space. */
typedef struct apr_threadkey_t apr_threadkey_t;
#if APR_HAS_OTHER_CHILD
+/** Opaque record of child process. */
typedef struct apr_other_child_rec_t apr_other_child_rec_t;
#endif /* APR_HAS_OTHER_CHILD */
@@ -494,8 +501,8 @@
* Create a new process and execute a new program within that process.
* @param new_proc The resulting process handle.
* @param progname The program to run
- * @param const_args the arguments to pass to the new program. The first
- * one should be the program name.
+ * @param args the arguments to pass to the new program. The first
+ * one should be the program name.
* @param env The new environment table for the new process. This
* should be a list of NULL-terminated strings. This argument
* is ignored for APR_PROGRAM_ENV and APR_PROGRAM_PATH types
@@ -571,8 +578,8 @@
apr_wait_how_e waithow,
apr_pool_t *p);
-#define APR_PROC_DETACH_FOREGROUND 0
-#define APR_PROC_DETACH_DAEMONIZE 1
+#define APR_PROC_DETACH_FOREGROUND 0 /**< Do not detach */
+#define APR_PROC_DETACH_DAEMONIZE 1 /**< Detach */
/**
* Detach the process from the controlling terminal.
1.5 +1 -0 apr/include/apr_thread_rwlock.h
Index: apr_thread_rwlock.h
===================================================================
RCS file: /home/cvs/apr/include/apr_thread_rwlock.h,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -u -r1.4 -r1.5
--- apr_thread_rwlock.h 13 Mar 2002 20:39:15 -0000 1.4
+++ apr_thread_rwlock.h 10 Nov 2002 08:35:16 -0000 1.5
@@ -76,6 +76,7 @@
* @{
*/
+/** Opaque read-write thread-safe lock. */
typedef struct apr_thread_rwlock_t apr_thread_rwlock_t;
/**
1.57 +11 -8 apr/include/apr_time.h
Index: apr_time.h
===================================================================
RCS file: /home/cvs/apr/include/apr_time.h,v
retrieving revision 1.56
retrieving revision 1.57
diff -u -u -r1.56 -r1.57
--- apr_time.h 4 Aug 2002 18:29:33 -0000 1.56
+++ apr_time.h 10 Nov 2002 08:35:16 -0000 1.57
@@ -95,34 +95,38 @@
/** number of microseconds per second */
#define APR_USEC_PER_SEC APR_TIME_C(1000000)
+/** @return apr_time_t as a second */
#define apr_time_sec(time) ((time) / APR_USEC_PER_SEC)
+/** @return apr_time_t as a usec */
#define apr_time_usec(time) ((time) % APR_USEC_PER_SEC)
+/** @return apr_time_t as a msec */
#define apr_time_msec(time) (((time) / 1000) % 1000)
-
+/** @return apr_time_t as a msec */
#define apr_time_as_msec(time) ((time) / 1000)
-
+/** @return a second as an apr_time_t */
#define apr_time_from_sec(sec) ((apr_time_t)(sec) * APR_USEC_PER_SEC)
-
+/** @return a second and usec combination as an apr_time_t */
#define apr_time_make(sec, usec) ((apr_time_t)(sec) * APR_USEC_PER_SEC \
+ (apr_time_t)(usec))
/**
- * return the current time
+ * @return the current time
*/
APR_DECLARE(apr_time_t) apr_time_now(void);
+/** @see apr_time_exp_t */
+typedef struct apr_time_exp_t apr_time_exp_t;
+
/**
* a structure similar to ANSI struct tm with the following differences:
* - tm_usec isn't an ANSI field
* - tm_gmtoff isn't an ANSI field (it's a bsdism)
*/
-typedef struct apr_time_exp_t apr_time_exp_t;
-
struct apr_time_exp_t {
/** microseconds past tm_sec */
apr_int32_t tm_usec;
@@ -162,7 +166,6 @@
* @param result the exploded time
* @param input the time to explode
* @param offs the number of seconds offset to apply
- * @param zone the zone description
*/
APR_DECLARE(apr_status_t) apr_time_exp_tz(apr_time_exp_t *result,
apr_time_t input,
@@ -260,7 +263,7 @@
* Improve the clock resolution for the lifetime of the given pool.
* Generally this is only desireable on benchmarking and other very
* time-sensitive applications, and has no impact on most platforms.
- * @param pool The pool to associate the finer clock resolution
+ * @param p The pool to associate the finer clock resolution
*/
APR_DECLARE(void) apr_time_clock_hires(apr_pool_t *p);
1.10 +4 -4 apr/include/apr_version.h
Index: apr_version.h
===================================================================
RCS file: /home/cvs/apr/include/apr_version.h,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -u -r1.9 -r1.10
--- apr_version.h 12 Sep 2002 00:50:21 -0000 1.9
+++ apr_version.h 10 Nov 2002 08:35:16 -0000 1.10
@@ -121,10 +121,10 @@
* structure.
*/
typedef struct {
- int major;
- int minor;
- int patch;
- int is_dev;
+ int major; /**< major number */
+ int minor; /**< minor number */
+ int patch; /**< patch number */
+ int is_dev; /**< is development (1 or 0) */
} apr_version_t;
/**