You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by rb...@locus.apache.org on 2000/08/05 06:26:47 UTC
cvs commit: apache-2.0/src/lib/apr/include apr_file_io.h apr_general.h apr_hash.h apr_md5.h apr_mmap.h apr_network_io.h apr_pools.h apr_tables.h apr_thread_proc.h apr_time.h
rbb 00/08/04 21:26:47
Modified: src/lib/apr/include apr_file_io.h apr_general.h apr_hash.h
apr_md5.h apr_mmap.h apr_network_io.h apr_pools.h
apr_tables.h apr_thread_proc.h apr_time.h
Log:
Document all of the public APR structures with DocBook.
Revision Changes Path
1.64 +18 -0 apache-2.0/src/lib/apr/include/apr_file_io.h
Index: apr_file_io.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_file_io.h,v
retrieving revision 1.63
retrieving revision 1.64
diff -u -r1.63 -r1.64
--- apr_file_io.h 2000/08/02 05:26:03 1.63
+++ apr_file_io.h 2000/08/05 04:26:45 1.64
@@ -117,16 +117,34 @@
typedef ino_t apr_ino_t;
typedef dev_t apr_dev_t;
+/**
+ * The file information structure. This is analogous to the POSIX
+ * stat structure.
+ */
struct apr_finfo_t {
+ /** The access permissions of the file. Currently this mimics Unix
+ * access rights.
+ */
apr_fileperms_t protection;
+ /** The type of file. One of APR_NOFILE, APR_REG, APR_DIR, APR_CHR,
+ * APR_BLK, APR_PIPE, APR_LNK, APR_SOCK
+ */
ap_filetype_e filetype;
+ /** The user id that owns the file */
apr_uid_t user;
+ /** The group id that owns the file */
apr_gid_t group;
+ /** The inode of the file. (Not portable?) */
apr_ino_t inode;
+ /** The id of the device the file is on. (Not portable?) */
apr_dev_t device;
+ /** The size of the file */
apr_off_t size;
+ /** The time the file was last accessed */
apr_time_t atime;
+ /** The time the file was last modified */
apr_time_t mtime;
+ /** The time the file was last changed */
apr_time_t ctime;
};
1.42 +22 -2 apache-2.0/src/lib/apr/include/apr_general.h
Index: apr_general.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_general.h,v
retrieving revision 1.41
retrieving revision 1.42
diff -u -r1.41 -r1.42
--- apr_general.h 2000/08/02 05:26:04 1.41
+++ apr_general.h 2000/08/05 04:26:45 1.42
@@ -272,25 +272,45 @@
#define ALLOC_STATS
*/
-typedef struct apr_pool_t {
+typedef struct apr_pool_t apr_pool_t;
+
+/** The memory allocation structure
+ */
+struct apr_pool_t {
+ /** The first block in this pool. */
union block_hdr *first;
+ /** The last block in this pool. */
union block_hdr *last;
+ /** The list of cleanups to run on pool cleanup. */
struct cleanup *cleanups;
+ /** A list of processes to kill when this pool is cleared */
struct process_chain *subprocesses;
+ /** The first sub_pool of this pool */
struct apr_pool_t *sub_pools;
+ /** The next sibling pool */
struct apr_pool_t *sub_next;
+ /** The previous sibling pool */
struct apr_pool_t *sub_prev;
+ /** The parent pool of this pool */
struct apr_pool_t *parent;
+ /** The first free byte in this pool */
char *free_first_avail;
#ifdef ALLOC_USE_MALLOC
+ /** The allocation list if using malloc */
void *allocation_list;
#endif
#ifdef POOL_DEBUG
+ /** a list of joined pools
+ * @defvar apr_pool_t *joined */
struct apr_pool_t *joined;
#endif
+ /** A function to control how pools behave when they receive ENOMEM
+ * @deffunc int apr_abort(int retcode) */
int (*apr_abort)(int retcode);
+ /** A place to hand user data associated with this pool
+ * @defvar datastruct *prog_data */
struct datastruct *prog_data;
-}apr_pool_t;
+};
/* pool functions */
1.8 +7 -1 apache-2.0/src/lib/apr/include/apr_hash.h
Index: apr_hash.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_hash.h,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- apr_hash.h 2000/08/02 05:26:04 1.7
+++ apr_hash.h 2000/08/05 04:26:45 1.8
@@ -64,7 +64,7 @@
#endif
/**
- * package Hash Tables
+ * @package Hash Tables
*/
#include "apr_pools.h"
@@ -83,6 +83,7 @@
* Create a hash table within a pool.
* @param pool The pool to allocate the hash table out of
* @return The hash table just created
+ * @deffunc apr_hash_t *apr_make_hash(apr_pool_t *pool)
*/
APR_EXPORT(apr_hash_t *) apr_make_hash(apr_pool_t *pool);
@@ -94,6 +95,7 @@
* If the length is 0 it is assumed to be strlen(key)+1
* @param val Value to associate with the key
* @tip If the value is NULL the hash entry is deleted.
+ * @deffunc void apr_hash_set(apr_hash_t *ht, const void *key, size_t klen, const void *val)
*/
APR_EXPORT(void) apr_hash_set(apr_hash_t *ht, const void *key, size_t klen,
const void *val);
@@ -105,6 +107,7 @@
* @param klen Length of the key
* If the length is 0 it is assumed to be strlen(key)+1
* @return Returns NULL if the key is not present.
+ * @deffunc void *apr_hash_get(apr_hash_t *ht, const void *key, size_t klen)
*/
APR_EXPORT(void) *apr_hash_get(apr_hash_t *ht, const void *key, size_t klen);
@@ -132,6 +135,7 @@
* is delete the current entry) and multiple iterations can be in
* progress at the same time.
* </PRE>
+ * @deffunc apr_hash_index_t * apr_hash_first(apr_hash_t *ht)
*/
APR_EXPORT(apr_hash_index_t *) apr_hash_first(apr_hash_t *ht);
@@ -139,6 +143,7 @@
* Continue iterating over the entries in a hash table.
* @param hi The iteration state
* @return a pointer to the updated iteration state. NULL if there are no more * entries.
+ * @deffunc apr_hash_index_t * apr_hash_next(apr_hash_index_t *hi)
*/
APR_EXPORT(apr_hash_index_t *) apr_hash_next(apr_hash_index_t *hi);
@@ -150,6 +155,7 @@
* @param val Return pointer for the associated value.
* @tip The return pointers should point to a variable that will be set to the
* corresponding data, or they may be NULL if the data isn't interesting.
+ * @deffunc void apr_hash_this(apr_hash_index_t *hi, const void **key, size_t *klen, void **val);
*/
APR_EXPORT(void) apr_hash_this(apr_hash_index_t *hi, const void **key,
size_t *klen, void **val);
1.16 +12 -7 apache-2.0/src/lib/apr/include/apr_md5.h
Index: apr_md5.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_md5.h,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- apr_md5.h 2000/08/02 05:26:05 1.15
+++ apr_md5.h 2000/08/05 04:26:45 1.16
@@ -100,16 +100,21 @@
/* UINT4 defines a four byte word */
typedef unsigned int UINT4;
+typedef struct ap_md5_ctx_t ap_md5_ctx_t;
-/* MD5 context. */
-typedef struct {
- UINT4 state[4]; /* state (ABCD) */
- UINT4 count[2]; /* number of bits, modulo 2^64 (lsb first) */
- unsigned char buffer[64]; /* input buffer */
+/** MD5 context. */
+struct ap_md5_ctx_t {
+ /** state (ABCD) */
+ UINT4 state[4];
+ /** number of bits, modulo 2^64 (lsb first) */
+ UINT4 count[2];
+ /** input buffer */
+ unsigned char buffer[64];
#if APR_HAS_XLATE
- apr_xlate_t *xlate; /* translation handle */
+ /** translation handle */
+ apr_xlate_t *xlate;
#endif
-} ap_md5_ctx_t;
+};
/**
* MD5 Initialize. Begins an MD5 operation, writing a new context.
1.14 +5 -0 apache-2.0/src/lib/apr/include/apr_mmap.h
Index: apr_mmap.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_mmap.h,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- apr_mmap.h 2000/08/02 05:26:06 1.13
+++ apr_mmap.h 2000/08/05 04:26:45 1.14
@@ -75,12 +75,17 @@
* sense to keep it private, and opening it up makes some stuff easier in
* Apache.
*/
+/** The MMAP structure */
struct apr_mmap_t {
+ /** The pool the mmap structure was allocated out of. */
apr_pool_t *cntxt;
#ifdef BEOS
+ /** An area ID. Only valid on BeOS */
area_id area;
#endif
+ /** The start of the memory mapped area */
void *mm;
+ /** The amount of data in the mmap */
size_t size;
};
1.51 +7 -1 apache-2.0/src/lib/apr/include/apr_network_io.h
Index: apr_network_io.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_network_io.h,v
retrieving revision 1.50
retrieving revision 1.51
diff -u -r1.50 -r1.51
--- apr_network_io.h 2000/08/04 12:51:19 1.50
+++ apr_network_io.h 2000/08/05 04:26:45 1.51
@@ -131,11 +131,17 @@
/* Define flags passed in on apr_sendfile() */
#define APR_SENDFILE_DISCONNECT_SOCKET 1
-/* A structure to encapsulate headers and trailers for apr_sendfile */
+/** A structure to encapsulate headers and trailers for apr_sendfile */
struct apr_hdtr_t {
+ /** An iovec to store the headers sent before the file.
+ * @defvar iovec *headers */
struct iovec* headers;
+ /** number of headers in the iovec */
int numheaders;
+ /** An iovec to store the trailers sent before the file.
+ * @defvar iovec *trailers */
struct iovec* trailers;
+ /** number of trailers in the iovec */
int numtrailers;
};
#endif
1.29 +11 -0 apache-2.0/src/lib/apr/include/apr_pools.h
Index: apr_pools.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_pools.h,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- apr_pools.h 2000/08/02 05:26:06 1.28
+++ apr_pools.h 2000/08/05 04:26:45 1.29
@@ -102,9 +102,20 @@
kill_only_once /* send SIGTERM and then wait */
};
+/** A list of processes */
struct process_chain {
+ /** The process ID */
apr_proc_t *pid;
+ /** When the process should be sent a signal. <PRE>
+ * kill_never -- process is never sent any signals
+ * kill_always -- process is sent SIGKILL on apr_pool_t cleanup
+ * kill_after_timeout -- SIGTERM, wait 3 seconds, SIGKILL
+ * just_wait -- wait forever for the process to complete
+ * kill_only_once -- send SIGTERM and then wait </PRE>
+ */
enum kill_conditions kill_how;
+ /** The next process in the list
+ * @defvar process_chain *next */
struct process_chain *next;
};
1.5 +24 -4 apache-2.0/src/lib/apr/include/apr_tables.h
Index: apr_tables.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_tables.h,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- apr_tables.h 2000/08/02 05:26:07 1.4
+++ apr_tables.h 2000/08/05 04:26:45 1.5
@@ -74,38 +74,58 @@
* Define the structures used by the APR general-purpose library.
*/
+/**
+ * @package APR Table library
+ */
+
/*
* Memory allocation stuff, like pools, arrays, and tables. Pools
* and tables are opaque structures to applications, but arrays are
* published.
*/
typedef struct apr_table_t apr_table_t;
-typedef struct 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 *cont;
+ /** The amount of memory allocated for each element of the array */
int elt_size;
+ /** The number of active elements in the array */
int nelts;
+ /** The number of elements allocated in the array */
int nalloc;
+ /** The elements in the array */
char *elts;
-} apr_array_header_t;
+};
+/** The opaque table type */
struct apr_table_t {
/* This has to be first to promote backwards compatibility with
* older modules which cast a apr_table_t * to an apr_array_header_t *...
* they should use the table_elts() function for most of the
* cases they do this for.
*/
+ /** The underlying array for the table */
apr_array_header_t a;
#ifdef MAKE_TABLE_PROFILE
+ /** Who created the array. */
void *creator;
#endif
};
+
+typedef struct apr_table_entry_t apr_table_entry_t;
-typedef struct apr_table_entry_t {
+/** The type for each entry in a table */
+struct apr_table_entry_t {
+ /** The key for the current table entry */
char *key; /* maybe NULL in future;
* check when iterating thru table_elts
*/
+ /** The value for the current table entry */
char *val;
-} apr_table_entry_t;
+};
/* XXX: these know about the definition of struct apr_table_t in alloc.c. That
* definition is not here because it is supposed to be private, and by not
1.42 +12 -5 apache-2.0/src/lib/apr/include/apr_thread_proc.h
Index: apr_thread_proc.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_thread_proc.h,v
retrieving revision 1.41
retrieving revision 1.42
diff -u -r1.41 -r1.42
--- apr_thread_proc.h 2000/08/02 05:26:08 1.41
+++ apr_thread_proc.h 2000/08/05 04:26:46 1.42
@@ -99,12 +99,19 @@
* us knowing ... buggy os? */
#endif /* APR_HAS_OTHER_CHILD */
-typedef struct apr_proc_t {
+typedef struct apr_proc_t apr_proc_t;
+
+/** The APR process type */
+struct apr_proc_t {
+ /** The process ID */
pid_t pid;
- apr_file_t *in; /* Parent's side of pipe to child's stdin */
- apr_file_t *out; /* Parent's side of pipe to child's stdout */
- apr_file_t *err; /* Parent's side of pipe to child's stdouterr */
-} apr_proc_t;
+ /** Parent's side of pipe to child's stdin */
+ apr_file_t *in;
+ /** Parent's side of pipe to child's stdout */
+ apr_file_t *out;
+ /* Parent's side of pipe to child's stdouterr */
+ apr_file_t *err;
+};
typedef struct apr_thread_t apr_thread_t;
typedef struct apr_threadattr_t apr_threadattr_t;
1.25 +30 -17 apache-2.0/src/lib/apr/include/apr_time.h
Index: apr_time.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_time.h,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- apr_time.h 2000/08/02 05:26:08 1.24
+++ apr_time.h 2000/08/05 04:26:46 1.25
@@ -92,23 +92,36 @@
*/
apr_time_t apr_now(void);
-/* 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_int32_t tm_usec; /* microseconds past tm_sec */
- apr_int32_t tm_sec; /* (0-61) seconds past tm_min */
- apr_int32_t tm_min; /* (0-59) minutes past tm_hour */
- apr_int32_t tm_hour; /* (0-23) hours past midnight */
- apr_int32_t tm_mday; /* (1-31) day of the month */
- apr_int32_t tm_mon; /* (0-11) month of the year */
- apr_int32_t tm_year; /* year since 1900 */
- apr_int32_t tm_wday; /* (0-6) days since sunday */
- apr_int32_t tm_yday; /* (0-365) days since jan 1 */
- apr_int32_t tm_isdst; /* daylight saving time */
- apr_int32_t tm_gmtoff; /* seconds east of UTC */
-} ap_exploded_time_t;
+typedef struct ap_exploded_time_t ap_exploded_time_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)
+ */
+struct ap_exploded_time_t {
+ /** microseconds past tm_sec */
+ apr_int32_t tm_usec;
+ /** (0-61) seconds past tm_min */
+ apr_int32_t tm_sec;
+ /** (0-59) minutes past tm_hour */
+ apr_int32_t tm_min;
+ /** (0-23) hours past midnight */
+ apr_int32_t tm_hour;
+ /** (1-31) day of the month */
+ apr_int32_t tm_mday;
+ /** (0-11) month of the year */
+ apr_int32_t tm_mon;
+ /** year since 1900 */
+ apr_int32_t tm_year;
+ /** (0-6) days since sunday */
+ apr_int32_t tm_wday;
+ /** (0-365) days since jan 1 */
+ apr_int32_t tm_yday;
+ /** daylight saving time */
+ apr_int32_t tm_isdst;
+ /** seconds east of UTC */
+ apr_int32_t tm_gmtoff;
+};
/**
* convert an ansi time_t to an apr_time_t