diff options
| author | rbb <rbb@13f79535-47bb-0310-9956-ffa450edef68> | 2000-04-16 04:46:56 +0000 |
|---|---|---|
| committer | rbb <rbb@13f79535-47bb-0310-9956-ffa450edef68> | 2000-04-16 04:46:56 +0000 |
| commit | 5fe3c759a295e20e1dfd3cddcec90f8f1e082307 (patch) | |
| tree | 7d4506f999ed4d9bb53c0fb15ab4154d5d97d033 | |
| parent | 3d9cfdd67afc7b084e35cdc1fab7a0f3a5354095 (diff) | |
| download | libapr-5fe3c759a295e20e1dfd3cddcec90f8f1e082307.tar.gz | |
Change the format for APR function documentation. This uses the perldoc
scripts to generate either plain text, html, or any other format perldoc
can generate. This also fixes the comments to say ap_pool instead of
ap_context.
git-svn-id: http://svn.apache.org/repos/asf/apr/apr/trunk@59869 13f79535-47bb-0310-9956-ffa450edef68
| -rw-r--r-- | APRDesign | 25 | ||||
| -rw-r--r-- | include/apr_dso.h | 59 | ||||
| -rw-r--r-- | include/apr_file_io.h | 688 | ||||
| -rw-r--r-- | include/apr_general.h | 159 | ||||
| -rw-r--r-- | include/apr_getopt.h | 41 | ||||
| -rw-r--r-- | include/apr_iconv.h | 4 | ||||
| -rw-r--r-- | include/apr_lib.h | 2 | ||||
| -rw-r--r-- | include/apr_lock.h | 158 | ||||
| -rw-r--r-- | include/apr_mmap.h | 51 | ||||
| -rw-r--r-- | include/apr_network_io.h | 743 | ||||
| -rw-r--r-- | include/apr_portable.h | 306 | ||||
| -rw-r--r-- | include/apr_shmem.h | 166 | ||||
| -rw-r--r-- | include/apr_thread_proc.h | 690 | ||||
| -rw-r--r-- | include/apr_time.h | 71 |
14 files changed, 1969 insertions, 1194 deletions
@@ -168,16 +168,25 @@ above the prototypes to be checked into the unix tree. The format for the comment block is: -/* ***APRDOC******************************************************** - * Function prototype with variable names - * A one or two line description of what the function does. - * arg 1) A brief description of the first argument. - * ... - * arg N) A brief description of the Nth argument. - * NOTE: This is optional. If there is anything programmers need to - * know about your function, add it here. +/* + +=head1 function prototype + +B<Brief description of function> + + arg 1) explanation of arg 1 + arg 2) explanation of arg 2 + arg N) explanation of arg N + +B<NOTE>: Any extra information the programmer needs. + +=cut */ +The spacing for the documentation is VERY important, because the docs are +processed with perldoc, and this spacing is required for the perldoc scripts +to work properly. + For an actual example, look at any function in the fileio/unix directory. APR Error reporting diff --git a/include/apr_dso.h b/include/apr_dso.h index ea7ae47dc..01f71c34c 100644 --- a/include/apr_dso.h +++ b/include/apr_dso.h @@ -65,37 +65,54 @@ extern "C" { typedef struct ap_dso_handle_t ap_dso_handle_t; typedef void * ap_dso_handle_sym_t; -/* ***APRDOC******************************************************** - * ap_status_t ap_dso_init(void) - * Initialize the underlying DSO library. +/* + +=head1 ap_status_t ap_dso_init(void) + +B<Initialize the underlying DSO library.> + +=cut */ ap_status_t ap_dso_init(void); -/* ***APRDOC******************************************************** - * ap_status_t ap_dso_load(ap_dso_handle_t **res_handle, const char *path, - * ap_context_t *ctx) - * Load a DSO library. - * arg 1) Location to store new handle for the DSO. - * arg 2) Path to the DSO library - * arg 3) Context to use. +/* + +=head1 ap_status_t ap_dso_load(ap_dso_handle_t **res_handle, const char *path, ap_pool_t *ctx) + +B<Load a DSO library.> + + arg 1) Location to store new handle for the DSO. + arg 2) Path to the DSO library + arg 3) Pool to use. + +=cut */ ap_status_t ap_dso_load(ap_dso_handle_t **res_handle, const char *path, ap_pool_t *ctx); -/* ***APRDOC******************************************************** - * ap_status_t ap_dso_unload(ap_dso_handle_t *handle) - * Close a DSO library. - * arg 1) handle to close. +/* + +=head1 ap_status_t ap_dso_unload(ap_dso_handle_t *handle) + +B<Close a DSO library.> + + arg 1) handle to close. + +=cut */ ap_status_t ap_dso_unload(ap_dso_handle_t *handle); -/* ***APRDOC******************************************************** - * ap_status_t ap_dso_sym(ap_dso_handle_sym_t *ressym, ap_dso_handle_t *handle - * const char *symname) - * Load a symbol from a DSO handle. - * arg 1) Location to store the loaded symbol - * arg 2) handle to load from. - * arg 3) Name of the symbol to load. +/* + +=head1 ap_status_t ap_dso_sym(ap_dso_handle_sym_t *ressym, ap_dso_handle_t *handle *, const char *symname) + +B<Load a symbol from a DSO handle.> + + arg 1) Location to store the loaded symbol + arg 2) handle to load from. + arg 3) Name of the symbol to load. + +=cut */ ap_status_t ap_dso_sym(ap_dso_handle_sym_t *ressym, ap_dso_handle_t *handle, const char *symname); diff --git a/include/apr_file_io.h b/include/apr_file_io.h index 1dfcabbcb..1eeeb4129 100644 --- a/include/apr_file_io.h +++ b/include/apr_file_io.h @@ -78,8 +78,8 @@ typedef enum {APR_NOFILE, APR_REG, APR_DIR, APR_CHR, APR_BLK, APR_PIPE, APR_LNK, #define APR_BINARY 32 /* Open the file in binary mode */ #define APR_EXCL 64 /* Open should fail if APR_CREATE and file exists. */ +#define APR_BUFFERED 128 /* Open the file for buffered I/O */ #define APR_DELONCLOSE 256 /* Delete the file after close */ -#define APR_BUFFERED 512 /* Buffered I/O */ /* flags for ap_seek */ #define APR_SET SEEK_SET @@ -125,373 +125,555 @@ struct ap_finfo_t { }; /* Function definitions */ -/* ***APRDOC******************************************************** - * ap_status_t ap_open(ap_file_t **new, char *fname, ap_int32 flag, - * ap_fileperms perm, ap_context_t *cont) - * Open the specified file. - * arg 1) The opened file descriptor. - * arg 2) The full path to the file (using / on all systems) - * arg 3) Or'ed value of: - * APR_READ open for reading - * APR_WRITE open for writing - * APR_CREATE create the file if not there - * APR_APPEND file ptr is set to end prior to all writes - * APR_TRUNCATE set length to zero if file exists - * APR_BINARY not a text file (This flag is ignored on UNIX because it has no meaning) - * APR_BUFFERED buffer the data. Default is non-buffered - * APR_EXCL return error if APR_CREATE and file exists - * APR_DELONCLOSE delete the file after closing. - * arg 4) Access permissions for file. - * arg 5) The context to use. - * NOTE: If mode is APR_OS_DEFAULT, the system open command will be - * called without any mode parameters. *arg1 must point to a valid - * file_t, or NULL (in which case it will be allocated) +/* + +=head1 ap_status_t ap_open(ap_file_t **new, char *fname, ap_int32 flag, ap_fileperms perm, ap_pool_t *cont) + +B<Open the specified file.> + + arg 1) The opened file descriptor. + arg 2) The full path to the file (using / on all systems) + arg 3) Or'ed value of: + APR_READ open for reading + APR_WRITE open for writing + APR_CREATE create the file if not there + APR_APPEND file ptr is set to end prior to all writes + APR_TRUNCATE set length to zero if file exists + APR_BINARY not a text file (This flag is ignored on + UNIX because it has no meaning) + APR_BUFFERED buffer the data. Default is non-buffered + APR_EXCL return error if APR_CREATE and file exists + APR_DELONCLOSE delete the file after closing. + arg 4) Access permissions for file. + arg 5) The pool to use. + +B<NOTE>: If mode is APR_OS_DEFAULT, the system open command will be + called without any mode parameters. *arg1 must point to a valid + file_t, or NULL (in which case it will be allocated) + +=cut */ ap_status_t ap_open(ap_file_t **new, const char *fname, ap_int32_t flag, ap_fileperms_t perm, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_close(ap_file_t *file) - * Close the specified file. - * arg 1) The file descriptor to close. +/* + +=head1 ap_status_t ap_close(ap_file_t *file) + +B<Close the specified file.> + + arg 1) The file descriptor to close. + +=cut */ ap_status_t ap_close(ap_file_t *file); -/* ***APRDOC******************************************************** - * ap_status_t ap_remove_file(char *path, ap_context_t *cont) - * delete the specified file. - * arg 1) The full path to the file (using / on all systems) - * arg 2) The context to use. - * NOTE: If the file is open, it won't be removed until all instances are - * closed. +/* + +=head1 ap_status_t ap_remove_file(char *path, ap_pool_t *cont) + +B<delete the specified file.> + + arg 1) The full path to the file (using / on all systems) + arg 2) The pool to use. + +B<NOTE>: If the file is open, it won't be removed until all instances are + closed. + +=cut */ ap_status_t ap_remove_file(char *path, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_eof(ap_file_t *fptr) - * Are we at the end of the file - * arg 1) The apr file we are testing. - * NOTE: Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise. +/* + +=head1 ap_status_t ap_eof(ap_file_t *fptr) + +B<Are we at the end of the file> + + arg 1) The apr file we are testing. + +B<NOTE>: Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise. + +=cut */ ap_status_t ap_eof(ap_file_t *fptr); -/* ***APRDOC******************************************************** - * ap_status_t ap_ferror(ap_file_t *fptr) - * Is there an error on the stream? - * arg 1) The apr file we are testing. - * NOTE: Returns -1 if the error indicator is set, APR_SUCCESS otherwise. +/* + +=head1 ap_status_t ap_ferror(ap_file_t *fptr) + +B<Is there an error on the stream?> + + arg 1) The apr file we are testing. + +B<NOTE>: Returns -1 if the error indicator is set, APR_SUCCESS otherwise. + +=cut */ ap_status_t ap_ferror(ap_file_t *fptr); -/* ***APRDOC******************************************************** - * ap_status_t ap_open_stderr(ap_file_t **thefile, ap_context_t *cont) - * open standard error as an apr file pointer. - * arg 1) The apr file to use as stderr. - * arg 2) The context to allocate the file out of. +/* + +=head1 ap_status_t ap_open_stderr(ap_file_t **thefile, ap_pool_t *cont) + +B<open standard error as an apr file pointer.> + + arg 1) The apr file to use as stderr. + arg 2) The pool to allocate the file out of. + +=cut */ ap_status_t ap_open_stderr(ap_file_t **thefile, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_read(ap_file_t *thefile, void *buf, ap_ssize_t *nbytes) - * Read data from the specified file. - * arg 1) The file descriptor to read from. - * arg 2) The buffer to store the data to. - * arg 3) On entry, the number of bytes to read; on exit, the number - * of bytes read. - * NOTE: ap_read will read up to the specified number of bytes, but never - * more. If there isn't enough data to fill that number of bytes, all of - * the available data is read. The third argument is modified to reflect the - * number of bytes read. If a char was put back into the stream via - * ungetc, it will be the first character returned. - * - * It is possible for both bytes to be read and an APR_EOF or other error - * to be returned. - * - * APR_EINTR is never returned. +/* + +=head1 ap_status_t ap_read(ap_file_t *thefile, void *buf, ap_ssize_t *nbytes) + +B<Read data from the specified file.> + + arg 1) The file descriptor to read from. + arg 2) The buffer to store the data to. + arg 3) On entry, the number of bytes to read; on exit, the number + of bytes read. + +B<NOTE>: ap_read will read up to the specified number of bytes, but never + more. If there isn't enough data to fill that number of bytes, all of + the available data is read. The third argument is modified to reflect the + number of bytes read. If a char was put back into the stream via + ungetc, it will be the first character returned. + + It is possible for both bytes to be read and an APR_EOF or other error + to be returned. + + APR_EINTR is never returned. + +=cut */ ap_status_t ap_read(ap_file_t *thefile, void *buf, ap_ssize_t *nbytes); -/* ***APRDOC******************************************************** - * ap_status_t ap_write(ap_file_t *thefile, void *buf, ap_ssize_t *nbytes) - * Write data to the specified file. - * arg 1) The file descriptor to write to. - * arg 2) The buffer which contains the data. - * arg 3) On entry, the number of bytes to write; on exit, the number - * of bytes write. - * NOTE: ap_write will write up to the specified number of bytes, but never - * more. If the OS cannot write that many bytes, it will write as many as it - * can. The third argument is modified to reflect the * number of bytes - * written. - * - * It is possible for both bytes to be written and an error to be - * returned. - * - * APR_EINTR is never returned. +/* + +=head1 ap_status_t ap_write(ap_file_t *thefile, void *buf, ap_ssize_t *nbytes) + +B<Write data to the specified file.> + + arg 1) The file descriptor to write to. + arg 2) The buffer which contains the data. + arg 3) On entry, the number of bytes to write; on exit, the number + of bytes write. + +B<NOTE>: ap_write will write up to the specified number of bytes, but never + more. If the OS cannot write that many bytes, it will write as many as it + can. The third argument is modified to reflect the * number of bytes + written. + + It is possible for both bytes to be written and an error to be + returned. + + APR_EINTR is never returned. + +=cut */ ap_status_t ap_write(ap_file_t *thefile, void *buf, ap_ssize_t *nbytes); -/* ***APRDOC******************************************************** - * ap_status_t ap_writev(ap_file_t *thefile, struct iovec *vec, ap_size_t nvec, - * ap_ssize_t *nbytes) - * Write data from iovec array to the specified file. - * arg 1) The file descriptor to write to. - * arg 2) The array from which to get the data to write to the file. - * arg 3) The number of elements in the struct iovec array. This must be - * smaller than AP_MAX_IOVEC_SIZE. If it isn't, the function will - * fail with APR_EINVAL. - * arg 4) The number of bytes written. - * - * It is possible for both bytes to be written and an error to be - * returned. - * - * APR_EINTR is never returned. - * - * ap_writev is available even if the underlying operating system - * doesn't provide writev(). +/* + +=head1 ap_status_t ap_writev(ap_file_t *thefile, struct iovec *vec, ap_size_t nvec, ap_ssize_t *nbytes) + +B<Write data from iovec array to the specified file.> + + arg 1) The file descriptor to write to. + arg 2) The array from which to get the data to write to the file. + arg 3) The number of elements in the struct iovec array. This must be + smaller than AP_MAX_IOVEC_SIZE. If it isn't, the function will + fail with APR_EINVAL. + arg 4) The number of bytes written. + + It is possible for both bytes to be written and an error to be + returned. + + APR_EINTR is never returned. + + ap_writev is available even if the underlying operating system + doesn't provide writev(). + +=cut */ ap_status_t ap_writev(ap_file_t *thefile, const struct iovec *vec, ap_size_t nvec, ap_ssize_t *nbytes); -/* ***APRDOC******************************************************** - * ap_status_t ap_putc(char ch, ap_file_t *thefile) - * put a character into the specified file. - * arg 1) The character to write. - * arg 2) The file descriptor to write to +/* + +=head1 ap_status_t ap_putc(char ch, ap_file_t *thefile) + +B<put a character into the specified file.> + + arg 1) The character to write. + arg 2) The file descriptor to write to + +=cut */ ap_status_t ap_putc(char ch, ap_file_t *thefile); -/* ***APRDOC******************************************************** - * ap_status_t ap_getc(char *ch, ap_file_t *thefil) - * get a character from the specified file. - * arg 1) The character to write. - * arg 2) The file descriptor to write to +/* + +=head1 ap_status_t ap_getc(char *ch, ap_file_t *thefil) + +B<get a character from the specified file.> + + arg 1) The character to write. + arg 2) The file descriptor to write to + +=cut */ ap_status_t ap_getc(char *ch, ap_file_t *thefile); -/* ***APRDOC******************************************************** - * ap_status_t ap_ungetc(char ch, ap_file_t *thefile) - * put a character back onto a specified stream. - * arg 1) The character to write. - * arg 2) The file descriptor to write to +/* + +=head1 ap_status_t ap_ungetc(char ch, ap_file_t *thefile) + +B<put a character back onto a specified stream.> + + arg 1) The character to write. + arg 2) The file descriptor to write to + +=cut */ ap_status_t ap_ungetc(char ch, ap_file_t *thefile); -/* ***APRDOC******************************************************** - * ap_status_t ap_fgets(char *str, int len, ap_file_t *thefile) - * Get a string from a specified file. - * arg 1) The buffer to store the string in. - * arg 2) The length of the string - * arg 3) The file descriptor to read from +/* + +=head1 ap_status_t ap_fgets(char *str, int len, ap_file_t *thefile) + +B<Get a string from a specified file.> + + arg 1) The buffer to store the string in. + arg 2) The length of the string + arg 3) The file descriptor to read from + +=cut */ ap_status_t ap_fgets(char *str, int len, ap_file_t *thefile); -/* ***APRDOC******************************************************** - * ap_status_t ap_puts(char *str, ap_file_t *thefile) - * Put the string into a specified file. - * arg 1) The string to write. - * arg 2) The file descriptor to write to from +/* + +=head1 ap_status_t ap_puts(char *str, ap_file_t *thefile) + +B<Put the string into a specified file.> + + arg 1) The string to write. + arg 2) The file descriptor to write to from + +=cut */ ap_status_t ap_puts(char *str, ap_file_t *thefile); -/* ***APRDOC******************************************************** - * ap_status_t ap_flush(ap_file_t *thefile) - * Flush the file's buffer. - * arg 1) The file descriptor to flush +/* + +=head1 ap_status_t ap_flush(ap_file_t *thefile) + +B<Flush the file's buffer.> + + arg 1) The file descriptor to flush + +=cut */ ap_status_t ap_flush(ap_file_t *thefile); API_EXPORT(int) ap_fprintf(ap_file_t *fptr, const char *format, ...) __attribute__((format(printf,2,3))); -/* ***APRDOC******************************************************** - * ap_status_t ap_dupfile(ap_file_t **new_file, ap_file_t *old_file) - * duplicate the specified file descriptor. - * arg 1) The structure to duplicate into. - * arg 2) The file to duplicate. - * NOTE: *arg1 must point to a valid ap_file_t, or point to NULL +/* + +=head1 ap_status_t ap_dupfile(ap_file_t **new_file, ap_file_t *old_file) + +B<duplicate the specified file descriptor.> + + arg 1) The structure to duplicate into. + arg 2) The file to duplicate. + +B<NOTE>: *arg1 must point to a valid ap_file_t, or point to NULL + +=cut */ ap_status_t ap_dupfile(ap_file_t **new_file, ap_file_t *old_file); -/* ***APRDOC******************************************************** - * ap_status_t ap_getfileinfo(ap_finfo_t *finfo, ap_file_t *thefile) - * get the specified file's stats.. - * arg 1) Where to store the information about the file. - * arg 2) The file to get information about. +/* + +=head1 ap_status_t ap_getfileinfo(ap_finfo_t *finfo, ap_file_t *thefile) + +B<get the specified file's stats..> + + arg 1) Where to store the information about the file. + arg 2) The file to get information about. + +=cut */ ap_status_t ap_getfileinfo(ap_finfo_t *finfo, ap_file_t *thefile); ap_status_t ap_stat(ap_finfo_t *finfo, const char *fname, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_stat(ap_file_t **finfo, char *fname, ap_context_t *cont) - * get the specified file's stats. The file is specified by filename, - * instead of using a pre-opened file. - * arg 1) Where to store the information about the file. - * arg 2) The name of the file to stat. - * arg 3) the context to use to allocate the new file. +/* + +=head1 ap_status_t ap_stat(ap_file_t **finfo, char *fname, ap_pool_t *cont) + +B<get the specified file's stats. The file is specified by filename, instead of using a pre-opened file.> + + arg 1) Where to store the information about the file. + arg 2) The name of the file to stat. + arg 3) the pool to use to allocate the new file. + +=cut */ ap_status_t ap_stat(ap_finfo_t *finfo, const char *fname, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_seek(ap_file_t *thefile, ap_seek_where_t where, - * ap_off_t *offset) - * Move the read/write file offset to a specified byte within a file. - * arg 1) The file descriptor - * arg 2) How to move the pointer, one of: - * APR_SET -- set the offset to offset - * APR_CUR -- add the offset to the current position - * APR_END -- add the offset to the current file size - * arg 3) The offset to move the pointer to. - * NOTE: The third argument is modified to be the offset the pointer - * was actually moved to. +/* + +=head1 ap_status_t ap_seek(ap_file_t *thefile, ap_seek_where_t where, ap_off_t *offset) + +B<Move the read/write file offset to a specified byte within a file.> + + arg 1) The file descriptor + arg 2) How to move the pointer, one of: + APR_SET -- set the offset to offset + APR_CUR -- add the offset to the current position + APR_END -- add the offset to the current file size + arg 3) The offset to move the pointer to. + +B<NOTE>: The third argument is modified to be the offset the pointer + was actually moved to. + +=cut */ ap_status_t ap_seek(ap_file_t *thefile, ap_seek_where_t where,ap_off_t *offset); -/* ***APRDOC******************************************************** - * ap_status_t ap_opendir(ap_dir_t **new, char *dirname, ap_context_t *cont) - * Open the specified directory. - * arg 1) The opened directory descriptor. - * arg 2) The full path to the directory (use / on all systems) - * arg 3) The context to use. +/* + +=head1 ap_status_t ap_opendir(ap_dir_t **new, char *dirname, ap_pool_t *cont) + +B<Open the specified directory.> + + arg 1) The opened directory descriptor. + arg 2) The full path to the directory (use / on all systems) + arg 3) The pool to use. + +=cut */ ap_status_t ap_opendir(ap_dir_t **new, const char *dirname, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_closedir(ap_dir_t *thedir) - * close the specified directory. - * arg 1) the directory descriptor to close. +/* + +=head1 ap_status_t ap_closedir(ap_dir_t *thedir) + +B<close the specified directory.> + + arg 1) the directory descriptor to close. + +=cut */ ap_status_t ap_closedir(ap_dir_t *thedir); -/* ***APRDOC******************************************************** - * ap_status_t ap_readdir(ap_dir_t *thedir) - * Read the next entry from the specified directory. - * arg 1) the directory descriptor to read from, and fill out. - * NOTE: All systems return . and .. as the first two files. +/* + +=head1 ap_status_t ap_readdir(ap_dir_t *thedir) + +B<Read the next entry from the specified directory.> + + arg 1) the directory descriptor to read from, and fill out. + +B<NOTE>: All systems return . and .. as the first two files. + +=cut */ ap_status_t ap_readdir(ap_dir_t *thedir); -/* ***APRDOC******************************************************** - * ap_status_t ap_rewinddir(ap_dir_t *thedir) - * Rewind the directory to the first entry. - * arg 1) the directory descriptor to rewind. +/* + +=head1 ap_status_t ap_rewinddir(ap_dir_t *thedir) + +B<Rewind the directory to the first entry.> + + arg 1) the directory descriptor to rewind. + +=cut */ ap_status_t ap_rewinddir(ap_dir_t *thedir); -/* ***APRDOC******************************************************** - * ap_status_t ap_make_dir(const char *path, ap_fileperms_t perm, - * ap_context_t *cont) - * Create a new directory on the file system. - * arg 1) the path for the directory to be created. (use / on all systems) - * arg 2) Permissions for the new direcoty. - * arg 3) the context to use. +/* + +=head1 ap_status_t ap_make_dir(const char *path, ap_fileperms_t perm, ap_pool_t *cont) + +B<Create a new directory on the file system.> + + arg 1) the path for the directory to be created. (use / on all systems) + arg 2) Permissions for the new direcoty. + arg 3) the pool to use. + +=cut */ ap_status_t ap_make_dir(const char *path, ap_fileperms_t perm, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_remove_dir(const char *path, ap_context_t *cont) - * Remove directory from the file system. - * arg 1) the path for the directory to be removed. (use / on all systems) - * arg 2) the context to use. +/* + +=head1 ap_status_t ap_remove_dir(const char *path, ap_pool_t *cont) + +B<Remove directory from the file system.> + + arg 1) the path for the directory to be removed. (use / on all systems) + arg 2) the pool to use. + +=cut */ ap_status_t ap_remove_dir(const char *path, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_create_pipe(ap_file_t **in, ap_file_t **out, - * ap_context_t *cont) - * Create an anonymous pipe. - * arg 1) The file descriptor to use as input to the pipe. - * arg 2) The file descriptor to use as output from the pipe. - * arg 3) The context to operate on. +/* + +=head1 ap_status_t ap_create_pipe(ap_file_t **in, ap_file_t **out, ap_pool_t *cont) + +B<Create an anonymous pipe.> + + arg 1) The file descriptor to use as input to the pipe. + arg 2) The file descriptor to use as output from the pipe. + arg 3) The pool to operate on. + +=cut */ ap_status_t ap_create_pipe(ap_file_t **in, ap_file_t **out, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_create_namedpipe(char *filename, ap_fileperms_t perm, - * ap_context_t *cont) - * Create a named pipe. - * arg 1) The filename of the named pipe - * arg 2) The permissions for the newly created pipe. - * arg 3) The context to operate on. +/* + +=head1 ap_status_t ap_create_namedpipe(char *filename, ap_fileperms_t perm, ap_pool_t *cont) + +B<Create a named pipe.> + + arg 1) The filename of the named pipe + arg 2) The permissions for the newly created pipe. + arg 3) The pool to operate on. + +=cut */ ap_status_t ap_create_namedpipe(char *filename, ap_fileperms_t perm, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_pipe_timeout(ap_file_t *thepipe, ap_int32_t timeout) - * Set the timeout value for a pipe. - * arg 1) The pipe we are setting a timeout on. - * arg 3) The timeout value in seconds. Values < 0 mean wait forever, 0 - * means do not wait at all. +/* + +=head1 ap_status_t ap_set_pipe_timeout(ap_file_t *thepipe, ap_int32_t timeout) + +B<Set the timeout value for a pipe.> + + arg 1) The pipe we are setting a timeout on. + arg 2) The timeout value in seconds. Values < 0 mean wait forever, 0 + means do not wait at all. + +=cut */ ap_status_t ap_set_pipe_timeout(ap_file_t *thepipe, ap_interval_time_t timeout); -/* ***APRDOC******************************************************** - * ap_status_t ap_block_pipe(ap_file_t *thepipe) - * Set a pipe to use blocking I/O. - * arg 1) The pipe to operate on. +/* + +=head1 ap_status_t ap_block_pipe(ap_file_t *thepipe) + +B<Set a pipe to use blocking I/O.> + + arg 1) The pipe to operate on. + +=cut */ ap_status_t ap_block_pipe(ap_file_t *thepipe); /*accessor and general file_io functions. */ -/* ***APRDOC******************************************************** - * ap_status_t ap_get_filename(char **new, ap_file_t *thefile) - * return the file name of the current file. - * arg 1) The path of the file. - * arg 2) The currently open file. +/* + +=head1 ap_status_t ap_get_filename(char **new, ap_file_t *thefile) + +B<return the file name of the current file.> + + arg 1) The path of the file. + arg 2) The currently open file. + +=cut */ ap_status_t ap_get_filename(char **new, ap_file_t *thefile); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_dir_filename(char **new, ap_dir_t *thedir) - * Get the file name of the current directory entry. - * arg 1) the file name of the directory entry. - * arg 2) the currently open directory. +/* + +=head1 ap_status_t ap_get_dir_filename(char **new, ap_dir_t *thedir) + +B<Get the file name of the current directory entry.> + + arg 1) the file name of the directory entry. + arg 2) the currently open directory. + +=cut */ ap_status_t ap_get_dir_filename(char **new, ap_dir_t *thedir); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_filedata(void **data, char *key, ap_file_t *file) - * Return the data associated with the current file. - * arg 1) The user data associated with the file. - * arg 2) The key to use for retreiving data associated with this file. - * arg 3) The currently open file. +/* + +=head1 ap_status_t ap_get_filedata(void **data, char *key, ap_file_t *file) + +B<Return the data associated with the current file.> + + arg 1) The user data associated with the file. + arg 2) The key to use for retreiving data associated with this file. + arg 3) The currently open file. + +=cut */ ap_status_t ap_get_filedata(void **data, char *key, ap_file_t *file); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_filedata(ap_file_t *file, void *data, char *key, - * ap_status (*cleanup) (void *)) - * Set the data associated with the current file. - * arg 1) The currently open file. - * arg 2) The user data to associate with the file. - * arg 3) The key to use for assocaiteing data with the file. - * arg 4) The cleanup routine to use when the file is destroyed. +/* + +=head1 ap_status_t ap_set_filedata(ap_file_t *file, void *data, char *key, ap_status (*cleanup) (void *)) + +B<Set the data associated with the current file.> + + arg 1) The currently open file. + arg 2) The user data to associate with the file. + arg 3) The key to use for assocaiteing data with the file. + arg 4) The cleanup routine to use when the file is destroyed. + +=cut */ ap_status_t ap_set_filedata(ap_file_t *file, void *data, char *key, ap_status_t (*cleanup) (void *)); -/* ***APRDOC******************************************************** - * ap_status_t ap_dir_entry_size(ap_ssize_t *size, ap_dir_t *thedir) - * Get the size of the current directory entry. - * arg 1) the size of the directory entry. - * arg 2) the currently open directory. +/* + +=head1 ap_status_t ap_dir_entry_size(ap_ssize_t *size, ap_dir_t *thedir) + +B<Get the size of the current directory entry.> + + arg 1) the size of the directory entry. + arg 2) the currently open directory. + +=cut */ ap_status_t ap_dir_entry_size(ap_ssize_t *size, ap_dir_t *thedir); -/* ***APRDOC******************************************************** - * ap_status_t ap_dir_entry_mtime(ap_time_t *mtime, ap_dir_t *thedir) - * Get the last modified time of the current directory entry. - * arg 1) the last modified time of the directory entry. - * arg 2) the currently open directory. +/* + +=head1 ap_status_t ap_dir_entry_mtime(ap_time_t *mtime, ap_dir_t *thedir) + +B<Get the last modified time of the current directory entry.> + + arg 1) the last modified time of the directory entry. + arg 2) the currently open directory. + +=cut */ ap_status_t ap_dir_entry_mtime(ap_time_t *mtime, ap_dir_t *thedir); -/* ***APRDOC******************************************************** - * ap_status_t ap_dir_entry_ftype(ap_filetype_e *type, ap_dir_t *thedir) - * Get the file type of the current directory entry. - * arg 1) the file type of the directory entry. - * arg 2) the currently open directory. +/* + +=head1 ap_status_t ap_dir_entry_ftype(ap_filetype_e *type, ap_dir_t *thedir) + +B<Get the file type of the current directory entry.> + + arg 1) the file type of the directory entry. + arg 2) the currently open directory. + +=cut */ ap_status_t ap_dir_entry_ftype(ap_filetype_e *type, ap_dir_t *thedir); diff --git a/include/apr_general.h b/include/apr_general.h index 7c74d67d7..715ea1fea 100644 --- a/include/apr_general.h +++ b/include/apr_general.h @@ -212,13 +212,18 @@ typedef int ap_signum_t; #endif #if APR_HAS_RANDOM -/* ***APRDOC******************************************************** - * TODO: I'm not sure this is the best place to put this prototype... - * ap_status_t ap_generate_random_bytes(unsigned char * buf, int length) - * Generate a string of random bytes. - * arg 1) Random bytes go here - * arg 2) size of the buffer +/* + +=head1 ap_status_t ap_generate_random_bytes(unsigned char * buf, int length) + +B<Generate a string of random bytes.> + + arg 1) Random bytes go here + arg 2) size of the buffer + +=cut */ +/* TODO: I'm not sure this is the best place to put this prototype...*/ ap_status_t ap_generate_random_bytes(unsigned char * buf, int length); #endif @@ -242,83 +247,113 @@ typedef struct ap_pool_t { struct datastruct *prog_data; }ap_pool_t; -/* Context functions */ -/* ***APRDOC******************************************************** - * ap_status_t ap_create_context(ap_context_t **newcont, ap_context_t *cont) - * Create a new context. - * arg 1) The context we have just created. - * arg 2) The parent context. If this is NULL, the new context is a root - * context. If it is non-NULL, the new context will inherit all - * of it's parent context's attributes, except the ap_context_t will be a - * sub-pool. +/* pool functions */ +/* + +=head1 ap_status_t ap_create_pool(ap_pool_t **newcont, ap_pool_t *cont) + +B<Create a new pool.> + + arg 1) The pool we have just created. + arg 2) The parent pool. If this is NULL, the new pool is a root + pool. If it is non-NULL, the new pool will inherit all + of it's parent pool's attributes, except the ap_pool_t will + be a sub-pool. + +=cut */ ap_status_t ap_create_pool(ap_pool_t **newcont, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_destroy_context(ap_context_t *cont) - * Free the context and all of it's child contexts'. - * arg 1) The context to free. +/* + +=head1 ap_status_t ap_destroy_pool(ap_pool_t *cont) + +B<Free the pool and all of it's child pools'.> + + arg 1) The pool to free. + +=cut */ -ap_status_t ap_destroy_context(ap_pool_t *cont); ap_status_t ap_exit(ap_pool_t *); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_userdata(void *data, char *key, - * ap_status_t (*cleanup) (void *), - * ap_context_t *cont) - * Set the data associated with the current context. - * arg 1) The user data associated with the context. - * arg 2) The key to use for association - * arg 3) The cleanup program to use to cleanup the data; - * arg 4) The current context. - * NOTE: The data to be attached to the context should have the same - * life span as the context it is being attached to. - * - * Users of APR must take EXTREME care when choosing a key to - * use for their data. It is possible to accidentally overwrite - * data by choosing a key that another part of the program is using - * It is advised that steps are taken to ensure that a unique - * key is used at all times. +/* + +=head1 ap_status_t ap_set_userdata(void *data, char *key, ap_status_t (*cleanup) (void *), ap_pool_t *cont) + +B<Set the data associated with the current pool>. + + arg 1) The user data associated with the pool. + arg 2) The key to use for association + arg 3) The cleanup program to use to cleanup the data; + arg 4) The current pool. + +B<NOTE>: The data to be attached to the pool should have the same + life span as the pool it is being attached to. + + Users of APR must take EXTREME care when choosing a key to + use for their data. It is possible to accidentally overwrite + data by choosing a key that another part of the program is using + It is advised that steps are taken to ensure that a unique + key is used at all times. + +=cut */ ap_status_t ap_set_userdata(void *data, char *key, ap_status_t (*cleanup) (void *), ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_userdata(void **data, char *key, ap_context_t *cont) - * Return the data associated with the current context. - * arg 1) The key for the data to retrieve - * arg 2) The user data associated with the context. - * arg 3) The current context. +/* + +=head1 ap_status_t ap_get_userdata(void **data, char *key, ap_pool_t *cont) + +B<Return the data associated with the current pool.> + + arg 1) The key for the data to retrieve + arg 2) The user data associated with the pool. + arg 3) The current pool. + +=cut */ ap_status_t ap_get_userdata(void **, char *key, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_initialize(void) - * Setup any APR internal data structures. This MUST be the first - * function called for any APR program. +/* + +=head1 ap_status_t ap_initialize(void) + +B<Setup any APR internal data structures. This MUST be the first function called for any APR program.> + +=cut */ ap_status_t ap_initialize(void); -/* ***APRDOC******************************************************* - * void ap_terminate(void) - * Tear down any APR internal data structures which aren't - * torn down automatically. An APR program must call this - * function at termination once it has stopped using APR - * services. +/* + +=head1 void ap_terminate(void) + +B<Tear down any APR internal data structures which aren't torn down automatically.> + +B<NOTE>: An APR program must call this function at termination once it + has stopped using APR services. + +=cut */ void ap_terminate(void); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_abort(int (*apr_abort)(int retcode), ap_context_t *cont) - * Set the APR_ABORT function. - * NOTE: This is in for backwards compatability. If the program using - * APR wants APR to exit on a memory allocation error, then this - * function should be called to set the function to use in order - * to actually exit the program. If this function is not called, - * then APR will return an error and expect the calling program to - * deal with the error accordingly. +/* + +=head1 ap_status_t ap_set_abort(int (*apr_abort)(int retcode), ap_pool_t *cont) + +B<Set the APR_ABORT function.> + +B<NOTE>: This is in for backwards compatability. If the program using + APR wants APR to exit on a memory allocation error, then this + function should be called to set the function to use in order + to actually exit the program. If this function is not called, + then APR will return an error and expect the calling program to + deal with the error accordingly. + +=cut */ ap_status_t ap_set_abort(int (*apr_abort)(int retcode), ap_pool_t *cont); diff --git a/include/apr_getopt.h b/include/apr_getopt.h index 044c45760..f9ae7603f 100644 --- a/include/apr_getopt.h +++ b/include/apr_getopt.h @@ -63,24 +63,29 @@ API_VAR_IMPORT int API_VAR_IMPORT char * ap_optarg; /* argument associated with option */ -/* ***APRDOC******************************************************** - * ap_status_t ap_getopt(ap_int32_t nargc, char *const *nargv, - * const char *ostr, ap_int32_t *rv, ap_context_t *cont) - * Parse the command line options passed to the program. - * arg 1) The number of arguments passed to ap_getopt to parse - * arg 2) The array of command line options to parse - * arg 3) A string of characters that are acceptable options to the program. - * characters followed by ":" are required to have an option - * associated - * arg 4) The next option found. There are four potential values for - * this variable on exit. They are: - * APR_EOF -- No more options to parse - * APR_BADCH -- Found a bad option character - * APR_BADARG -- Missing parameter for the found option - * Other -- The next option found. - * arg 5) The context to operate on. - * NOTE: Arguments 2 and 3 are most commonly argc and argv from - * main(argc, argv) +/* + +=head1 ap_status_t ap_getopt(ap_int32_t nargc, char *const *nargv, const char *ostr, ap_int32_t *rv, ap_pool_t *cont) + +B<Parse the command line options passed to the program.> + + arg 1) The number of arguments passed to ap_getopt to parse + arg 2) The array of command line options to parse + arg 3) A string of characters that are acceptable options to the program. + characters followed by ":" are required to have an option + associated + arg 4) The next option found. There are four potential values for + this variable on exit. They are: + APR_EOF -- No more options to parse + APR_BADCH -- Found a bad option character + APR_BADARG -- Missing parameter for the found option + Other -- The next option found. + arg 5) The pool to operate on. + +B<NOTE>: Arguments 2 and 3 are most commonly argc and argv from + main(argc, argv) + +=cut */ ap_status_t ap_getopt(ap_int32_t nargc, char *const *nargv, const char *ostr, ap_int32_t *rv, ap_pool_t *cont); diff --git a/include/apr_iconv.h b/include/apr_iconv.h index 6d101a396..3ea4702f4 100644 --- a/include/apr_iconv.h +++ b/include/apr_iconv.h @@ -70,7 +70,7 @@ typedef void ap_iconv_t; /* For platforms where we don't bother with translating between codepages */ -#define ap_codepage_open(convset, topage, frompage, context) +#define ap_codepage_open(convset, topage, frompage, pool) #define ap_translate_codepage(convset, inbuf, inbytes_left, outbuf, \ outbytes_left) outbuf=inbuf; /* The purpose of ap_translate char is to translate one character @@ -85,7 +85,7 @@ typedef void ap_iconv_t; typedef struct ap_iconv_t ap_iconv_t; void ap_codepage_open(ap_iconv_t **convset, const char *topage, - const char *frompage, ap_pool_t *context); + const char *frompage, ap_pool_t *pool); void ap_translate_codepage(ap_iconv_t *convset, const char *inbuf, ap_size_t inbytes_left, const char *outbuf, ap_size_t outbytes_left); diff --git a/include/apr_lib.h b/include/apr_lib.h index 18bc28484..94c0ae6d5 100644 --- a/include/apr_lib.h +++ b/include/apr_lib.h @@ -127,7 +127,7 @@ enum kill_conditions { * Define the prototypes for the various APR GP routines. */ API_EXPORT(char *) ap_cpystrn(char *d, const char *s, size_t l); -API_EXPORT(int) ap_tokenize_to_argv(ap_pool_t *token_context, +API_EXPORT(int) ap_tokenize_to_argv(ap_pool_t *token_pool, char *arg_str, char ***argv_out); API_EXPORT(const char *) ap_filename_of_pathname(const char *pathname); API_EXPORT(char *) ap_collapse_spaces(char *dest, const char *src); diff --git a/include/apr_lock.h b/include/apr_lock.h index 2dfdd541a..b2ebc2382 100644 --- a/include/apr_lock.h +++ b/include/apr_lock.h @@ -69,89 +69,123 @@ typedef enum {APR_MUTEX, APR_READWRITE} ap_locktype_e; typedef struct ap_lock_t ap_lock_t; /* Function definitions */ -/* ***APRDOC******************************************************** - * ap_status_t ap_create_lock(ap_lock_t **lock, ap_locktype_e type, - * ap_lockscope_e scope, const char *fname, - * ap_context_t *cont) - * Create a new instance of a lock structure. - * arg 1) The newly created lock structure. - * arg 2) The type of lock to create, one of: - * APR_MUTEX - * APR_READWRITE - * arg 3) The scope of the lock to create, one of: - * APR_CROSS_PROCESS -- lock processes from the protected area. - * APR_INTRAPROCESS -- lock threads from the protected area. - * APR_LOCKALL -- lock processes and threads from the - * protected area. - * arg 4) A file name to use if the lock mechanism requires one. This - * argument should always be provided. The lock code itself will - * determine if it should be used. - * arg 5) The context to operate on. - * NOTE: APR_CROSS_PROCESS may lock both processes and threads, but it is - * only guaranteed to lock processes. +/* + +=head1 ap_status_t ap_create_lock(ap_lock_t **lock, ap_locktype_e type, ap_lockscope_e scope, const char *fname, ap_pool_t *cont) + +B<Create a new instance of a lock structure.> + + arg 1) The newly created lock structure. + arg 2) The type of lock to create, one of: + APR_MUTEX + APR_READWRITE + arg 3) The scope of the lock to create, one of: + APR_CROSS_PROCESS -- lock processes from the protected area. + APR_INTRAPROCESS -- lock threads from the protected area. + APR_LOCKALL -- lock processes and threads from the + protected area. + arg 4) A file name to use if the lock mechanism requires one. This + argument should always be provided. The lock code itself will + determine if it should be used. + arg 5) The pool to operate on. + +B<NOTE>: APR_CROSS_PROCESS may lock both processes and threads, but it is + only guaranteed to lock processes. + +=cut */ ap_status_t ap_create_lock(ap_lock_t **lock, ap_locktype_e type, ap_lockscope_e scope, const char *fname, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_lock(ap_lock_t *lock) - * Lock a protected region. - * arg 1) The lock to set. +/* + +=head1 ap_status_t ap_lock(ap_lock_t *lock) + +B<Lock a protected region.> + + arg 1) The lock to set. + +=cut */ ap_status_t ap_lock(ap_lock_t *lock); -/* ***APRDOC******************************************************** - * ap_status_t ap_unlock(ap_lock_t *lock) - * Unlock a protected region. - * arg 1) The lock to reset. +/* + +=head1 ap_status_t ap_unlock(ap_lock_t *lock) + +B<Unlock a protected region.> + + arg 1) The lock to reset. + +=cut */ ap_status_t ap_unlock(ap_lock_t *lock); -/* ***APRDOC******************************************************** - * ap_status_t ap_destroy_lock(ap_lock_t *lock) - * Free the memory associated with a lock. - * arg 1) The lock to free. - * NOTE: If the lock is currently active when it is destroyed, it - * will be unlocked first. +/* + +=head1 ap_status_t ap_destroy_lock(ap_lock_t *lock) + +B<Free the memory associated with a lock.> + + arg 1) The lock to free. + +B<NOTE>: If the lock is currently active when it is destroyed, it + will be unlocked first. + +=cut */ ap_status_t ap_destroy_lock(ap_lock_t *lock); -/* ***APRDOC******************************************************** - * ap_status_t ap_child_init_lock(ap_lock_t **lock, const char *fname, - * ap_context_t *cont) - * Re-open a lock in a child process. - * arg 1) The newly re-opened lock structure. - * arg 2) A file name to use if the lock mechanism requires one. This - * argument should always be provided. The lock code itself will - * determine if it should be used. This filename should be the same - * one that was passed to ap_create_lock - * arg 3) The context to operate on. - * NOTE: This function doesn't always do something, it depends on the - * locking mechanism chosen for the platform, but it is a good - * idea to call it regardless, because it makes the code more - * portable. +/* + +=head1 ap_status_t ap_child_init_lock(ap_lock_t **lock, const char *fname, ap_pool_t *cont) + +B<Re-open a lock in a child process.> + + arg 1) The newly re-opened lock structure. + arg 2) A file name to use if the lock mechanism requires one. This + argument should always be provided. The lock code itself will + determine if it should be used. This filename should be the same + one that was passed to ap_create_lock + arg 3) The pool to operate on. + +B<NOTE>: This function doesn't always do something, it depends on the + locking mechanism chosen for the platform, but it is a good + idea to call it regardless, because it makes the code more + portable. + +=cut */ ap_status_t ap_child_init_lock(ap_lock_t **lock, const char *fname, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_lockdata(ap_lock_t *lock, char *key, void *data) - * Return the context associated with the current lock. - * arg 1) The currently open lock. - * arg 2) The key to use when retreiving data associated with this lock - * arg 3) The user data associated with the lock. +/* + +=head1 ap_status_t ap_get_lockdata(ap_lock_t *lock, char *key, void *data) + +B<Return the pool associated with the current lock.> + + arg 1) The currently open lock. + arg 2) The key to use when retreiving data associated with this lock + arg 3) The user data associated with the lock. + +=cut */ ap_status_t ap_get_lockdata(ap_lock_t *lock, char *key, void *data); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_lockdata(ap_lock_t *lock, void *data, char *key, - * ap_status_t (*cleanup) (void *)) - * Return the context associated with the current lock. - * arg 1) The currently open lock. - * arg 2) The user data to associate with the lock. - * arg 3) The key to use when associating data with this lock - * arg 4) The cleanup to use when the lock is destroyed. +/* + +=head1 ap_status_t ap_set_lockdata(ap_lock_t *lock, void *data, char *key, ap_status_t (*cleanup) (void *)) + +B<Return the pool associated with the current lock.> + + arg 1) The currently open lock. + arg 2) The user data to associate with the lock. + arg 3) The key to use when associating data with this lock + arg 4) The cleanup to use when the lock is destroyed. + +=cut */ ap_status_t ap_set_lockdata(ap_lock_t *lock, void *data, char *key, ap_status_t (*cleanup) (void *)); diff --git a/include/apr_mmap.h b/include/apr_mmap.h index 7cf2349f0..598b0e3f9 100644 --- a/include/apr_mmap.h +++ b/include/apr_mmap.h @@ -69,31 +69,46 @@ typedef struct ap_mmap_t ap_mmap_t; /* Function definitions */ -/* ***APRDOC******************************************************** - * ap_status_t ap_mmap_create(ap_mmap_t **new, ap_file_t *file, ap_off_t offset) - * Create a new mmap'ed file out of an existing APR file. - * arg 1) The newly created mmap'ed file. - * arg 2) The file turn into an mmap. - * arg 3) The offset into the file to start the data pointer at. - * arg 4) The size of the file - * arg 5) The context to use when creating the mmap. +/* + +=head1 ap_status_t ap_mmap_create(ap_mmap_t **new, ap_file_t *file, ap_off_t offset) + +B<Create a new mmap'ed file out of an existing APR file.> + + arg 1) The newly created mmap'ed file. + arg 2) The file turn into an mmap. + arg 3) The offset into the file to start the data pointer at. + arg 4) The size of the file + arg 5) The pool to use when creating the mmap. + +=cut */ ap_status_t ap_mmap_create(ap_mmap_t ** newmmap, ap_file_t *file, ap_off_t offset, ap_size_t size, ap_pool_t *cntxt); -/* ***APRDOC******************************************************** - * ap_status_t ap_mmap_delete(ap_mmap_t *mmap) - * Remove a mmap'ed. - * arg 1) The mmap'ed file. +/* + +=head1 ap_status_t ap_mmap_delete(ap_mmap_t *mmap) + +B<Remove a mmap'ed.> + + arg 1) The mmap'ed file. + +=cut */ ap_status_t ap_mmap_delete(ap_mmap_t *mmap); -/* ***APRDOC******************************************************** - * ap_status_t ap_mmap_offset(void **addr, ap_mmap_t *mmap, ap_offset_t offset) - * Move the pointer into the mmap'ed file to the specified offset. - * arg 1) The pointer to the offset specified. - * arg 2) The mmap'ed file. - * arg 3) The offset to move to. +/* + +=head1 ap_status_t ap_mmap_offset(void **addr, ap_mmap_t *mmap, ap_offset_t offset) + +B<Move the pointer into the mmap'ed file to the specified offset.> + + arg 1) The pointer to the offset specified. + arg 2) The mmap'ed file. + arg 3) The offset to move to. + +=cut */ ap_status_t ap_mmap_offset(void **addr, ap_mmap_t *mmap, ap_off_t offset); diff --git a/include/apr_network_io.h b/include/apr_network_io.h index 7068b391e..492801f08 100644 --- a/include/apr_network_io.h +++ b/include/apr_network_io.h @@ -137,400 +137,565 @@ struct ap_hdtr_t { /* function definitions */ -/* ***APRDOC******************************************************** - * ap_status_t ap_create_tcp_socket(ap_socket_t **new, ap_context_t *cont) - * Create a socket for tcp communication. - * arg 1) The new socket that has been setup. - * arg 2) The context to use +/* + +=head1 ap_status_t ap_create_tcp_socket(ap_socket_t **new, ap_pool_t *cont) + +B<Create a socket for tcp communication.> + + arg 1) The new socket that has been setup. + arg 2) The pool to use + +=cut */ ap_status_t ap_create_tcp_socket(ap_socket_t **new, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_shutdown(ap_socket_t *thesocket, ap_shutdown_how_e how) - * Shutdown either reading, writing, or both sides of a tcp socket. - * arg 1) The socket to close - * arg 2) How to shutdown the socket. One of: - * APR_SHUTDOWN_READ -- no longer allow read requests - * APR_SHUTDOWN_WRITE -- no longer allow write requests - * APR_SHUTDOWN_READWRITE -- no longer allow read or write requests - * NOTE: This does not actually close the socket descriptor, it just - * controls which calls are still valid on the socket. - */ +/* + +=head1 ap_status_t ap_shutdown(ap_socket_t *thesocket, ap_shutdown_how_e how) + +B<Shutdown either reading, writing, or both sides of a tcp socket.> + + arg 1) The socket to close + arg 2) How to shutdown the socket. One of: + APR_SHUTDOWN_READ -- no longer allow read requests + APR_SHUTDOWN_WRITE -- no longer allow write requests + APR_SHUTDOWN_READWRITE -- no longer allow read or write requests + +B<NOTE>: This does not actually close the socket descriptor, it just + controls which calls are still valid on the socket. + +=cut + / ap_status_t ap_shutdown(ap_socket_t *ithesocket, ap_shutdown_how_e how); -/* ***APRDOC******************************************************** - * ap_status_t ap_close_socket(ap_socket_t *thesocket) - * Close a tcp socket. - * arg 1) The socket to close +/* + +=head1 ap_status_t ap_close_socket(ap_socket_t *thesocket) + +B<Close a tcp socket.> + + arg 1) The socket to close + +=cut */ ap_status_t ap_close_socket(ap_socket_t *thesocket); -/* ***APRDOC******************************************************** - * ap_status_t ap_bind(ap_socket_t *sock) - * Bind the socket to it's assocaited port - * arg 1) The socket to bind - * NOTE: This is where we will find out if there is any other process - * using the selected port. +/* + +=head1 ap_status_t ap_bind(ap_socket_t *sock) + +B<Bind the socket to it's assocaited port> + + arg 1) The socket to bind + +B<NOTE>: This is where we will find out if there is any other process + using the selected port. + +=cut */ ap_status_t ap_bind(ap_socket_t *sock); -/* ***APRDOC******************************************************** - * ap_status_t ap_listen(ap_socket_t *sock, ap_int32_t backlog) - * Listen to a bound socketi for connections. - * arg 1) The socket to listen on - * arg 2) The number of outstanding connections allowed in the sockets - * listen queue. If this value is less than zero, the listen - * queue size is set to zero. +/* + +=head1 ap_status_t ap_listen(ap_socket_t *sock, ap_int32_t backlog) + +B<Listen to a bound socketi for connections.> + + arg 1) The socket to listen on + arg 2) The number of outstanding connections allowed in the sockets + listen queue. If this value is less than zero, the listen + queue size is set to zero. + +=cut */ ap_status_t ap_listen(ap_socket_t *sock, ap_int32_t backlog); -/* ***APRDOC******************************************************** - * ap_status_t ap_accept(ap_socket_t **new, ap_socket_t *sock, - ap_context_t *connection_context) - * Accept a new connection request - * arg 1) A copy of the socket that is connected to the socket that - * made the connection request. This is the socket which should - * be used for all future communication. - * arg 2) The socket we are listening on. - * arg 3) The context for the new socket. +/* + +=head1 ap_status_t ap_accept(ap_socket_t **new, ap_socket_t *sock, ap_pool_t *connection_pool) + +B<Accept a new connection request> + + arg 1) A copy of the socket that is connected to the socket that + made the connection request. This is the socket which should + be used for all future communication. + arg 2) The socket we are listening on. + arg 3) The pool for the new socket. + +=cut */ ap_status_t ap_accept(ap_socket_t **new, const ap_socket_t *sock, - ap_pool_t *connection_context); + ap_pool_t *connection_pool); + +/* + +=head1 ap_status_t ap_connect(ap_socket_t *sock, char *hostname) + +B<Issue a connection request to a socket either on the same machine or a different one.> -/* ***APRDOC******************************************************** - * ap_status_t ap_connect(ap_socket_t *sock, char *hostname) - * Issue a connection request to a socket either on the same machine - * or a different one. - * arg 1) The socket we wish to use for our side of the connection - * arg 2) The hostname of the machine we wish to connect to. If NULL, - * APR assumes that the sockaddr_in in the apr_socket is completely - * filled out. + arg 1) The socket we wish to use for our side of the connection + arg 2) The hostname of the machine we wish to connect to. If NULL, + APR assumes that the sockaddr_in in the apr_socket is completely + filled out. + +=cut */ ap_status_t ap_connect(ap_socket_t *sock, char *hostname); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_remote_hostname(char **name, ap_socket_t *sock) - * Get name of the machine we are currently connected to. - * arg 1) A buffer to store the hostname in. - * arg 2) The socket to examine. +/* + +=head1 ap_status_t ap_get_remote_hostname(char **name, ap_socket_t *sock) + +B<Get name of the machine we are currently connected to.> + + arg 1) A buffer to store the hostname in. + arg 2) The socket to examine. + +=cut */ ap_status_t ap_get_remote_hostname(char **name, ap_socket_t *sock); -/* ***APRDOC******************************************************** - * ap_status_t ap_gethostname(char *buf, ap_int32_t len, ap_context_t *cont) - * Get name of the current machine - * arg 1) A buffer to store the hostname in. - * arg 2) The maximum length of the hostname that can be stored in the - * buffer provided. - * arg 3) The context to use. +/* + +=head1 ap_status_t ap_gethostname(char *buf, ap_int32_t len, ap_pool_t *cont) + +B<Get name of the current machine> + + arg 1) A buffer to store the hostname in. + arg 2) The maximum length of the hostname that can be stored in the + buffer provided. + arg 3) The pool to use. + +=cut */ ap_status_t ap_gethostname(char *buf, int len, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_socketdata(void **data, char *key, ap_socket_t *sock) - * Return the context associated with the current socket. - * arg 1) The currently open socket. - * arg 2) The user data associated with the socket. +/* + +=head1 ap_status_t ap_get_socketdata(void **data, char *key, ap_socket_t *sock) + +B<Return the pool associated with the current socket.> + + arg 1) The currently open socket. + arg 2) The user data associated with the socket. + +=cut */ ap_status_t ap_get_socketdata(void **data, char *key, ap_socket_t *sock); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_socketdata(ap_socket_t *sock, void *data, char *key, - ap_status_t (*cleanup) (void *)) - * Set the context associated with the current socket. - * arg 1) The currently open socket. - * arg 2) The user data to associate with the socket. - * arg 3) The key to associate with the data. - * arg 4) The cleanup to call when the socket is destroyed. +/* + +=head1 ap_status_t ap_set_socketdata(ap_socket_t *sock, void *data, char *key, ap_status_t (*cleanup) (void *)) + +B<Set the pool associated with the current socket.> + + arg 1) The currently open socket. + arg 2) The user data to associate with the socket. + arg 3) The key to associate with the data. + arg 4) The cleanup to call when the socket is destroyed. + +=cut */ ap_status_t ap_set_socketdata(ap_socket_t *sock, void *data, char *key, ap_status_t (*cleanup) (void*)); -/* ***APRDOC******************************************************** - * ap_status_t ap_send(ap_socket_t *sock, const char *buf, ap_ssize_t *len) - * Send data over a network. - * arg 1) The socket to send the data over. - * arg 2) The buffer which contains the data to be sent. - * arg 3) On entry, the number of bytes to send; on exit, the number - * of bytes sent. - * NOTE: This functions acts like a blocking write by default. To change - * this behavior, use ap_setsocketopt with the APR_SO_TIMEOUT option. - * - * It is possible for both bytes to be sent and an error to be returned. - * - * APR_EINTR is never returned. +/* + +=head1 ap_status_t ap_send(ap_socket_t *sock, const char *buf, ap_ssize_t *len) + +B<Send data over a network.> + + arg 1) The socket to send the data over. + arg 2) The buffer which contains the data to be sent. + arg 3) On entry, the number of bytes to send; on exit, the number + of bytes sent. + +B<NOTE>: This functions acts like a blocking write by default. To change + this behavior, use ap_setsocketopt with the APR_SO_TIMEOUT option. + + It is possible for both bytes to be sent and an error to be returned. + + APR_EINTR is never returned. + +=cut */ ap_status_t ap_send(ap_socket_t *sock, const char *buf, ap_ssize_t *len); -/* ***APRDOC******************************************************** - * ap_status_t ap_sendv(ap_socket_t *sock, const struct iovec *vec, - ap_int32_t nvec, ap_int32_t *len) - * Send multiple packets of data over a network. - * arg 1) The socket to send the data over. - * arg 2) The array of iovec structs containing the data to send - * arg 3) The number of iovec structs in the array - * arg 4) Receives the number of bytes actually written - * NOTE: This functions acts like a blocking write by default. To change - * this behavior, use ap_setsocketopt with the APR_SO_TIMEOUT option. - * The number of bytes actually sent is stored in argument 3. - * - * It is possible for both bytes to be sent and an error to be returned. - * - * APR_EINTR is never returned. +/* + +=head1 ap_status_t ap_sendv(ap_socket_t *sock, const struct iovec *vec, ap_int32_t nvec, ap_int32_t *len) + +B<Send multiple packets of data over a network.> + + arg 1) The socket to send the data over. + arg 2) The array of iovec structs containing the data to send + arg 3) The number of iovec structs in the array + arg 4) Receives the number of bytes actually written + +B<NOTE>: This functions acts like a blocking write by default. To change + this behavior, use ap_setsocketopt with the APR_SO_TIMEOUT option. + The number of bytes actually sent is stored in argument 3. + + It is possible for both bytes to be sent and an error to be returned. + + APR_EINTR is never returned. + +=cut */ ap_status_t ap_sendv(ap_socket_t *sock, const struct iovec *vec, ap_int32_t nvec, ap_int32_t *len); #if APR_HAS_SENDFILE -/* ***APRDOC******************************************************** - * ap_status_t ap_sendfile(ap_socket_t *sock, ap_file_t *file, ap_hdtr_t *hdtr, - * ap_off_t *offset, ap_size_t *len, ap_int32_t flags) - * Send a file from an open file descriptor to a socket, along with - * optional headers and trailers - * arg 1) The socket to which we're writing - * arg 2) The open file from which to read - * arg 3) A structure containing the headers and trailers to send - * arg 4) Offset into the file where we should begin writing - * arg 5) Number of bytes to send - * arg 6) OS-specific flags to pass to sendfile() - * NOTE: This functions acts like a blocking write by default. To change - * this behavior, use ap_setsocketopt with the APR_SO_TIMEOUT option. - * The number of bytes actually sent is stored in argument 5. +/* + +=head1 ap_status_t ap_sendfile(ap_socket_t *sock, ap_file_t *file, ap_hdtr_t *hdtr, ap_off_t *offset, ap_size_t *len, ap_int32_t flags) + +B<Send a file from an open file descriptor to a socket, along with optional headers and trailers> + + arg 1) The socket to which we're writing + arg 2) The open file from which to read + arg 3) A structure containing the headers and trailers to send + arg 4) Offset into the file where we should begin writing + arg 5) Number of bytes to send + arg 6) OS-specific flags to pass to sendfile() + +B<NOTE>: This functions acts like a blocking write by default. To change + this behavior, use ap_setsocketopt with the APR_SO_TIMEOUT option. + The number of bytes actually sent is stored in argument 5. + +=cut */ ap_status_t ap_sendfile(ap_socket_t *sock, ap_file_t *file, ap_hdtr_t *hdtr, ap_off_t *offset, ap_size_t *len, ap_int32_t flags); #endif -/* ***APRDOC******************************************************** - * ap_status_t ap_recv(ap_socket_t *sock, char *buf, ap_ssize_t *len) - * Read data from a network. - * arg 1) The socket to read the data from. - * arg 2) The buffer to store the data in. - * arg 3) On entry, the number of bytes to receive; on exit, the number - * of bytes received. - * NOTE: This functions acts like a blocking write by default. To change - * this behavior, use ap_setsocketopt with the APR_SO_TIMEOUT option. - * The number of bytes actually sent is stored in argument 3. - * - * It is possible for both bytes to be received and an APR_EOF or - * other error to be returned. - * - * APR_EINTR is never returned. +/* + +=head1 ap_status_t ap_recv(ap_socket_t *sock, char *buf, ap_ssize_t *len) + +B<Read data from a network.> + + arg 1) The socket to read the data from. + arg 2) The buffer to store the data in. + arg 3) On entry, the number of bytes to receive; on exit, the number + of bytes received. + +B<NOTE>: This functions acts like a blocking write by default. To change + this behavior, use ap_setsocketopt with the APR_SO_TIMEOUT option. + The number of bytes actually sent is stored in argument 3. + + It is possible for both bytes to be received and an APR_EOF or + other error to be returned. + + APR_EINTR is never returned. + +=cut */ ap_status_t ap_recv(ap_socket_t *sock, char *buf, ap_ssize_t *len); -/* ***APRDOC******************************************************** - * ap_status_t ap_setsocketopt(ap_socket_t *sock, ap_int32_t opt, ap_int32_t on) - * Setup socket options for the specified socket - * arg 1) The socket to set up. - * arg 2) The option we would like to configure. One of: - * APR_SO_DEBUG -- turn on debugging information - * APR_SO_KEEPALIVE -- keep connections active - * APR_SO_LINGER -- lingers on close if data is present - * APR_SO_NONBLOCK -- Turns blocking on/off for socket - * APR_SO_REUSEADDR -- The rules used in validating addresses - * supplied to bind should allow reuse - * of local addresses. - * APR_SO_TIMEOUT -- Set the timeout value in seconds. - * values < 0 mean wait forever. 0 means - * don't wait at all. - * APR_SO_SNDBUF -- Set the SendBufferSize - * arg 3) Are we turning the option on or off. +/* + +=head1 ap_status_t ap_setsocketopt(ap_socket_t *sock, ap_int32_t opt, ap_int32_t on) + +B<Setup socket options for the specified socket> + + arg 1) The socket to set up. + arg 2) The option we would like to configure. One of: + APR_SO_DEBUG -- turn on debugging information + APR_SO_KEEPALIVE -- keep connections active + APR_SO_LINGER -- lingers on close if data is present + APR_SO_NONBLOCK -- Turns blocking on/off for socket + APR_SO_REUSEADDR -- The rules used in validating addresses + supplied to bind should allow reuse + of local addresses. + APR_SO_TIMEOUT -- Set the timeout value in seconds. + values < 0 mean wait forever. 0 means + don't wait at all. + APR_SO_SNDBUF -- Set the SendBufferSize + arg 3) Are we turning the option on or off. + +=cut */ ap_status_t ap_setsocketopt(ap_socket_t *sock, ap_int32_t opt, ap_int32_t on); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_local_port(ap_socket_t *sock, ap_uint32_t port) - * Assocaite a local port with a socket. - * arg 1) The socket to set - * arg 2) The local port this socket will be dealing with. - * NOTE: This does not bind the two together, it is just telling apr - * that this socket is going to use this port if possible. If - * the port is already used, we won't find out about it here. +/* + +=head1 ap_status_t ap_set_local_port(ap_socket_t *sock, ap_uint32_t port) + Assocaite a local port with a socket. + + arg 1) The socket to set + arg 2) The local port this socket will be dealing with. + +B<NOTE>: This does not bind the two together, it is just telling apr + that this socket is going to use this port if possible. If + the port is already used, we won't find out about it here. + +=cut */ ap_status_t ap_set_local_port(ap_socket_t *sock, ap_uint32_t port); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_remote_port(ap_socket_t *sock, ap_uint32_t port) - * Assocaite a remote port with a socket. - * arg 1) The socket to enquire about. - * arg 2) The local port this socket will be dealing with. - * NOTE: This does not make a connection to the remote port, it is just - * telling apr which port ap_connect() should attempt to connect to. +/* + +=head1 ap_status_t ap_set_remote_port(ap_socket_t *sock, ap_uint32_t port) + +B<Assocaite a remote port with a socket.> + + arg 1) The socket to enquire about. + arg 2) The local port this socket will be dealing with. + +B<NOTE>: This does not make a connection to the remote port, it is just + telling apr which port ap_connect() should attempt to connect to. + +=cut */ ap_status_t ap_set_remote_port(ap_socket_t *sock, ap_uint32_t port); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_local_port(ap_uint32_t *port, ap_socket_t *sock) - * Return the local port with a socket. - * arg 1) The local port this socket is associated with. - * arg 2) The socket to enquire about. +/* + +=head1 ap_status_t ap_get_local_port(ap_uint32_t *port, ap_socket_t *sock) + +B<Return the local port with a socket.> + + arg 1) The local port this socket is associated with. + arg 2) The socket to enquire about. + +=cut */ ap_status_t ap_get_local_port(ap_uint32_t *port, ap_socket_t *sock); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_remote_port(ap_uint32_t *port, ap_socket_t *sock) - * Return the remote port associated with a socket. - * arg 1) The remote port this socket is associated with. - * arg 2) The socket to enquire about. +/* + +=head1 ap_status_t ap_get_remote_port(ap_uint32_t *port, ap_socket_t *sock) + +B<Return the remote port associated with a socket.> + + arg 1) The remote port this socket is associated with. + arg 2) The socket to enquire about. + +=cut */ ap_status_t ap_get_remote_port(ap_uint32_t *port, ap_socket_t *sock); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_local_ipaddr(ap_socket_t *sock, cont char *addr) - * Assocaite a local socket addr with an apr socket. - * arg 1) The socket to use - * arg 2) The IP address to attach to the socket. - * Use APR_ANYADDR to use any IP addr on the machine. - * NOTE: This does not bind the two together, it is just telling apr - * that this socket is going to use this address if possible. +/* + +=head1 ap_status_t ap_set_local_ipaddr(ap_socket_t *sock, cont char *addr) + +B<Assocaite a local socket addr with an apr socket.> + + arg 1) The socket to use + arg 2) The IP address to attach to the socket. + Use APR_ANYADDR to use any IP addr on the machine. + +B<NOTE>: This does not bind the two together, it is just telling apr + that this socket is going to use this address if possible. + +=cut */ ap_status_t ap_set_local_ipaddr(ap_socket_t *sock, const char *addr); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_remote_ipaddr(ap_socket_t *sock, cont char *addr) - * Assocaite a remote socket addr with an apr socket. - * arg 1) The socket to use - * arg 2) The IP address to attach to the socket. - * NOTE: This does not make a connection to the remote address, it is just - * telling apr which address ap_connect() should attempt to connect to. +/* + +=head1 ap_status_t ap_set_remote_ipaddr(ap_socket_t *sock, cont char *addr) + +B<Assocaite a remote socket addr with an apr socket.> + + arg 1) The socket to use + arg 2) The IP address to attach to the socket. + +B<NOTE>: This does not make a connection to the remote address, it is just + telling apr which address ap_connect() should attempt to connect to. + +=cut */ ap_status_t ap_set_remote_ipaddr(ap_socket_t *sock, const char *addr); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_local_ipaddr(char **addr, const ap_socket_t *sock) - * Return the local IP address associated with an apr socket. - * arg 1) The local IP address associated with the socket. - * arg 2) The socket to use +/* + +=head1 ap_status_t ap_get_local_ipaddr(char **addr, const ap_socket_t *sock) + +B<Return the local IP address associated with an apr socket.> + + arg 1) The local IP address associated with the socket. + arg 2) The socket to use + +=cut */ ap_status_t ap_get_local_ipaddr(char **addr, const ap_socket_t *sock); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_remote_ipaddr(char **addr, const ap_socket_t *sock) - * Return the remote IP address associated with an apr socket. - * arg 1) The remote IP address associated with the socket. - * arg 2) The socket to use +/* + +=head1 ap_status_t ap_get_remote_ipaddr(char **addr, const ap_socket_t *sock) + +B<Return the remote IP address associated with an apr socket.> + + arg 1) The remote IP address associated with the socket. + arg 2) The socket to use + +=cut */ ap_status_t ap_get_remote_ipaddr(char **addr, const ap_socket_t *sock); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_local_name(struct sockaddr_in **name, - * const ap_socket_t *sock) - * Return the local socket name as a BSD style struct sockaddr_in. - * arg 1) The local name associated with the socket. - * arg 2) The socket to use +/* + +=head1 ap_status_t ap_get_local_name(struct sockaddr_in **name, const ap_socket_t *sock) + +B<Return the local socket name as a BSD style struct sockaddr_in.> + + arg 1) The local name associated with the socket. + arg 2) The socket to use + +=cut */ ap_status_t ap_get_local_name(struct sockaddr_in **name, const ap_socket_t *sock); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_remote_name(struct sockaddr_in **name, - * const ap_socket_t *sock) - * Return the remote socket name as a BSD style struct sockaddr_in. - * arg 1) The remote name associated with the socket. - * arg 2) The socket to use +/* + +=head1 ap_status_t ap_get_remote_name(struct sockaddr_in **name, const ap_socket_t *sock) + +B<Return the remote socket name as a BSD style struct sockaddr_in.> + + arg 1) The remote name associated with the socket. + arg 2) The socket to use + +=cut */ ap_status_t ap_get_remote_name(struct sockaddr_in **name, const ap_socket_t *sock); -/* ***APRDOC******************************************************** - * ap_status_t ap_setup_poll(ap_pollfd_t **new, ap_int32_t num, - * ap_context_t *cont) - * Setup the memory required for poll to operate properly. - * arg 1) The poll structure to be used. - * arg 2) The number of socket descriptors to be polled. - * arg 3) The context to operate on. +/* + +=head1 ap_status_t ap_setup_poll(ap_pollfd_t **new, ap_int32_t num, ap_pool_t *cont) + +B<Setup the memory required for poll to operate properly.> + + arg 1) The poll structure to be used. + arg 2) The number of socket descriptors to be polled. + arg 3) The pool to operate on. + +=cut */ ap_status_t ap_setup_poll(ap_pollfd_t **new, ap_int32_t num, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_poll(ap_pollfd_t *aprset, ap_int32_t *nsds, - * ap_interval_time_t timeout) - * Poll the sockets in the poll structure. This is a blocking call, - * and it will not return until either a socket has been signalled, or - * the timeout has expired. - * arg 1) The poll structure we will be using. - * arg 2) The number of sockets we are polling. - * arg 3) The amount of time in microseconds to wait. This is a maximum, not - * a minimum. If a socket is signalled, we will wake up before this - * time. A negative number means wait until a socket is signalled. - * NOTE: The number of sockets signalled is returned in the second argument. - */ -ap_status_t ap_poll(ap_pollfd_t *aprset, ap_int32_t *nsds, - ap_interval_time_t timeout); - -/* ***APRDOC******************************************************** - * ap_status_t ap_add_poll_socket(ap_pollfd_t *aprset, ap_socket_t *sock, - * ap_int16_t event) - * Add a socket to the poll structure. - * arg 1) The poll structure we will be using. - * arg 2) The socket to add to the current poll structure. - * arg 3) The events to look for when we do the poll. One of: - * APR_POLLIN -- signal if read will not block - * APR_POLLPRI -- signal if prioirty data is availble to be read - * APR_POLLOUT -- signal if write will not block +/* + +=head1 ap_status_t ap_poll(ap_pollfd_t *aprset, ap_int32_t *nsds, ap_interval_time_t timeout) + +B<Poll the sockets in the poll structure.> + + arg 1) The poll structure we will be using. + arg 2) The number of sockets we are polling. + arg 3) The amount of time in microseconds to wait. This is a maximum, not + a minimum. If a socket is signalled, we will wake up before this + time. A negative number means wait until a socket is signalled. + +B<NOTE>: The number of sockets signalled is returned in the second argument. + + This is a blocking call, and it will not return until either a + socket has been signalled, or the timeout has expired. + +=cut + */ +ap_status_t ap_poll(ap_pollfd_t *aprset, ap_int32_t *nsds, ap_interval_time_t timeout); + +/* + +=head1 ap_status_t ap_add_poll_socket(ap_pollfd_t *aprset, ap_socket_t *sock, ap_int16_t event) + +B<Add a socket to the poll structure.> + + arg 1) The poll structure we will be using. + arg 2) The socket to add to the current poll structure. + arg 3) The events to look for when we do the poll. One of: + APR_POLLIN -- signal if read will not block + APR_POLLPRI -- signal if prioirty data is availble to be read + APR_POLLOUT -- signal if write will not block + +=cut */ ap_status_t ap_add_poll_socket(ap_pollfd_t *aprset, ap_socket_t *socket, ap_int16_t event); -/* ***APRDOC******************************************************** - * ap_status_t ap_remove_poll_socket(ap_pollfd_t *aprset, ap_socket_t *sock, - * ap_int16_t events) - * Add a socket to the poll structure. - * arg 1) The poll structure we will be using. - * arg 2) The socket to remove from the current poll structure. - * arg 3) The events to stop looking for during the poll. One of: - * APR_POLLIN -- signal if read will not block - * APR_POLLPRI -- signal if prioirty data is availble to be read - * APR_POLLOUT -- signal if write will not block +/* + +=head1 ap_status_t ap_remove_poll_socket(ap_pollfd_t *aprset, ap_socket_t *sock, ap_int16_t events) + +B<Add a socket to the poll structure.> + + arg 1) The poll structure we will be using. + arg 2) The socket to remove from the current poll structure. + arg 3) The events to stop looking for during the poll. One of: + APR_POLLIN -- signal if read will not block + APR_POLLPRI -- signal if prioirty data is availble to be read + APR_POLLOUT -- signal if write will not block + +=cut */ ap_status_t ap_remove_poll_socket(ap_pollfd_t *aprset, ap_socket_t *sock, ap_int16_t events); -/* ***APRDOC******************************************************** - * ap_status_t ap_clear_poll_sockets(ap_pollfd_t *aprset, ap_int16_t events) - * Remove all sockets from the poll structure. - * arg 1) The poll structure we will be using. - * arg 2) The events to clear from all sockets. One of: - * APR_POLLIN -- signal if read will not block - * APR_POLLPRI -- signal if prioirty data is availble to be read - * APR_POLLOUT -- signal if write will not block +/* + +=head1 ap_status_t ap_clear_poll_sockets(ap_pollfd_t *aprset, ap_int16_t events) + +B<Remove all sockets from the poll structure.> + + arg 1) The poll structure we will be using. + arg 2) The events to clear from all sockets. One of: + APR_POLLIN -- signal if read will not block + APR_POLLPRI -- signal if prioirty data is availble to be read + APR_POLLOUT -- signal if write will not block + +=cut */ ap_status_t ap_clear_poll_sockets(ap_pollfd_t *aprset, ap_int16_t events); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_revents(ap_int_16_t *event, ap_socket_t *sock, - * ap_pollfd_t *aprset) - * Get the return events for the specified socket. - * arg 1) The returned events for the socket. One of: - * APR_POLLIN -- Data is available to be read - * APR_POLLPRI -- Prioirty data is availble to be read - * APR_POLLOUT -- Write will succeed - * APR_POLLERR -- An error occurred on the socket - * APR_POLLHUP -- The connection has been terminated - * APR_POLLNVAL -- This is an invalid socket to poll on. - * Socket not open. - * arg 2) The socket we wish to get information about. - * arg 3) The poll structure we will be using. +/* + +=head1 ap_status_t ap_get_revents(ap_int_16_t *event, ap_socket_t *sock, ap_pollfd_t *aprset) + +B<Get the return events for the specified socket.> + + arg 1) The returned events for the socket. One of: + APR_POLLIN -- Data is available to be read + APR_POLLPRI -- Prioirty data is availble to be read + APR_POLLOUT -- Write will succeed + APR_POLLERR -- An error occurred on the socket + APR_POLLHUP -- The connection has been terminated + APR_POLLNVAL -- This is an invalid socket to poll on. + Socket not open. + arg 2) The socket we wish to get information about. + arg 3) The poll structure we will be using. + +=cut */ ap_status_t ap_get_revents(ap_int16_t *event, ap_socket_t *sock, ap_pollfd_t *aprset); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_polldata(ap_pollfd_t *pollfd, char *key, void *data) - * Return the context associated with the current poll. - * arg 1) The currently open pollfd. - * arg 2) The key to use for retreiving data associated with a poll struct. - * arg 3) The user data associated with the pollfd. +/* + +=head1 ap_status_t ap_get_polldata(ap_pollfd_t *pollfd, char *key, void *data) + +B<Return the pool associated with the current poll.> + + arg 1) The currently open pollfd. + arg 2) The key to use for retreiving data associated with a poll struct. + arg 3) The user data associated with the pollfd. + +=cut */ ap_status_t ap_get_polldata(ap_pollfd_t *pollfd, char *key, void *data); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_polldata(ap_pollfd_t *pollfd, void *data, char *key, - ap_status_t (*cleanup) (void *)) - * Return the context associated with the current poll. - * arg 1) The currently open pollfd. - * arg 2) The user data to associate with the pollfd. +/* + +=head1 ap_status_t ap_set_polldata(ap_pollfd_t *pollfd, void *data, char *key, ap_status_t (*cleanup) (void *)) + +B<Return the pool associated with the current poll.> + + arg 1) The currently open pollfd. + arg 2) The user data to associate with the pollfd. +=cut */ ap_status_t ap_set_polldata(ap_pollfd_t *pollfd, void *data, char *key, ap_status_t (*cleanup) (void *)); diff --git a/include/apr_portable.h b/include/apr_portable.h index 768632a7a..dca3d43dd 100644 --- a/include/apr_portable.h +++ b/include/apr_portable.h @@ -178,176 +178,260 @@ typedef struct timeval ap_os_imp_time_t; typedef struct tm ap_os_exp_time_t; #endif -/* ***APRDOC******************************************************** - * ap_status_t ap_get_os_file(ap_os_file_t *thefile, ap_file_t *file) - * convert the file from apr type to os specific type. - * arg 1) The os specific file we are converting to - * arg 2) The apr file to convert. - * NOTE: On Unix, it is only possible to get a file descriptor from - * an apr file type. +/* + +=head1 ap_status_t ap_get_os_file(ap_os_file_t *thefile, ap_file_t *file) + +B<convert the file from apr type to os specific type.> + + arg 1) The os specific file we are converting to + arg 2) The apr file to convert. + +B<NOTE>: On Unix, it is only possible to get a file descriptor from + an apr file type. + +=cut */ ap_status_t ap_get_os_file(ap_os_file_t *thefile, ap_file_t *file); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_os_dir(ap_os_dir_t **thedir, ap_dir_t *dir) - * convert the dir from apr type to os specific type. - * arg 1) The os specific dir we are converting to - * arg 2) The apr dir to convert. +/* + +=head1 ap_status_t ap_get_os_dir(ap_os_dir_t **thedir, ap_dir_t *dir) + +B<convert the dir from apr type to os specific type.> + + arg 1) The os specific dir we are converting to + arg 2) The apr dir to convert. + +=cut */ ap_status_t ap_get_os_dir(ap_os_dir_t **thedir, ap_dir_t *dir); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_os_sock(ap_os_sock_t *thesock, ap_socket_t *sock) - * Convert the socket from an apr type to an OS specific socket - * arg 1) The socket to convert. - * arg 2) The os specifc equivelant of the apr socket.. +/* + +=head1 ap_status_t ap_get_os_sock(ap_os_sock_t *thesock, ap_socket_t *sock) + +B<Convert the socket from an apr type to an OS specific socket> + + arg 1) The socket to convert. + arg 2) The os specifc equivelant of the apr socket.. + +=cut */ ap_status_t ap_get_os_sock(ap_os_sock_t *thesock, ap_socket_t *sock); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_os_lock(ap_os_lock_t *oslock, ap_lock_t *lock) - * onvert the lock from os specific type to apr type - * arg 1) The os specific lock we are converting to. - * arg 2) The apr lock to convert. +/* + +=head1 ap_status_t ap_get_os_lock(ap_os_lock_t *oslock, ap_lock_t *lock) + +B<Convert the lock from os specific type to apr type> + + arg 1) The os specific lock we are converting to. + arg 2) The apr lock to convert. + +=cut */ ap_status_t ap_get_os_lock(ap_os_lock_t *oslock, ap_lock_t *lock); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_os_proc(ap_os_proc_t *theproc, ap_proc_t *proc) - * convert the proc from os specific type to apr type. - * arg 1) The os specific proc we are converting to - * arg 2) The apr proc we are converting +/* + +=head1 ap_status_t ap_get_os_proc(ap_os_proc_t *theproc, ap_proc_t *proc) + +B<convert the proc from os specific type to apr type.> + + arg 1) The os specific proc we are converting to + arg 2) The apr proc we are converting + +=cut */ ap_status_t ap_get_os_proc(ap_os_proc_t *theproc, ap_proc_t *proc); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_os_exp_time(ap_os_exp_time_t **ostime, ap_exploded_time_t *aprtime) - * Get the exploded time in the platforms native format. - * arg 1) the native time format - * arg 2) the time to convert +/* + +=head1 ap_status_t ap_get_os_exp_time(ap_os_exp_time_t **ostime, ap_exploded_time_t *aprtime) + +B<Get the exploded time in the platforms native format.> + + arg 1) the native time format + arg 2) the time to convert + +=cut */ ap_status_t ap_get_os_exp_time(ap_os_exp_time_t **, ap_exploded_time_t *); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_os_imp_time(ap_os_imp_time_t **ostime, ap_time_t *aprtime) - * Get the imploded time in the platforms native format. - * arg 1) the native time format - * arg 2) the time to convert +/* + +=head1 ap_status_t ap_get_os_imp_time(ap_os_imp_time_t **ostime, ap_time_t *aprtime) + +B<Get the imploded time in the platforms native format.> + + arg 1) the native time format + arg 2) the time to convert + +=cut */ ap_status_t ap_get_os_imp_time(ap_os_imp_time_t **, ap_time_t *); #if APR_HAS_THREADS -/* ***APRDOC******************************************************** - * ap_status_t ap_get_os_thread(ap_thread_t *thethd, ap_os_thread_t *thd) - * convert the thread to os specific type from apr type. - * arg 1) The apr thread to convert - * arg 2) The os specific thread we are converting to +/* + +=head1 ap_status_t ap_get_os_thread(ap_thread_t *thethd, ap_os_thread_t *thd) + +B<convert the thread to os specific type from apr type.> + + arg 1) The apr thread to convert + arg 2) The os specific thread we are converting to + +=cut */ ap_status_t ap_get_os_thread(ap_os_thread_t *thethd, ap_thread_t *thd); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_os_threadkey(ap_threadkey_t *thekey, ap_os_threadkey_t *key) - * convert the thread private memory key to os specific type - * from an apr type. - * arg 1) The apr handle we are converting from. - * arg 2) The os specific handle we are converting to. +/* + +=head1 ap_status_t ap_get_os_threadkey(ap_threadkey_t *thekey, ap_os_threadkey_t *key) + +B<convert the thread private memory key to os specific type from an apr type.> + + arg 1) The apr handle we are converting from. + arg 2) The os specific handle we are converting to. + +=cut */ ap_status_t ap_get_os_threadkey(ap_os_threadkey_t *thekey, ap_threadkey_t *key); #endif -/* ***APRDOC******************************************************** - * ap_status_t ap_put_os_file(ap_file_t **file, ap_os_file_t *thefile, - * ap_context_t *cont) - * convert the file from os specific type to apr type. - * arg 1) The apr file we are converting to. - * arg 2) The os specific file to convert - * arg 3) The context to use if it is needed. - * NOTE: On Unix, it is only possible to put a file descriptor into - * an apr file type. +/* + +=head1 ap_status_t ap_put_os_file(ap_file_t **file, ap_os_file_t *thefile, ap_pool_t *cont) + +B<convert the file from os specific type to apr type.> + + arg 1) The apr file we are converting to. + arg 2) The os specific file to convert + arg 3) The pool to use if it is needed. + +B<NOTE>: On Unix, it is only possible to put a file descriptor into + an apr file type. + +=cut */ ap_status_t ap_put_os_file(ap_file_t **file, ap_os_file_t *thefile, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_put_os_dir(ap_dir_t **dir, ap_os_dir_t *thedir, - * ap_context_t *cont) - * convert the dir from os specific type to apr type. - * arg 1) The apr dir we are converting to. - * arg 2) The os specific dir to convert - * arg 3) The context to use when creating to apr directory. +/* + +=head1 ap_status_t ap_put_os_dir(ap_dir_t **dir, ap_os_dir_t *thedir, ap_pool_t *cont) + +B<convert the dir from os specific type to apr type.> + + arg 1) The apr dir we are converting to. + arg 2) The os specific dir to convert + arg 3) The pool to use when creating to apr directory. + +=cut */ ap_status_t ap_put_os_dir(ap_dir_t **dir, ap_os_dir_t *thedir, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_put_os_sock(ap_socket_t **sock, ap_os_socket_t *thesock, - * ap_context_t *cont) - * Convert a socket from the os specific type to the apr type - * arg 1) The context to use. - * arg 2) The socket to convert to. - * arg 3) The socket we are converting to an apr type. +/* + +=head1 ap_status_t ap_put_os_sock(ap_socket_t **sock, ap_os_socket_t *thesock, ap_pool_t *cont) + +B<Convert a socket from the os specific type to the apr type> + + arg 1) The pool to use. + arg 2) The socket to convert to. + arg 3) The socket we are converting to an apr type. + +=cut */ ap_status_t ap_put_os_sock(ap_socket_t **sock, ap_os_sock_t *thesock, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_put_os_lock(ap_lock_t **lock, ap_os_lock_t *, - * ap_context_t *cont) - * onvert the lock from os specific type to apr type - * arg 1) The apr lock we are converting to. - * arg 2) The os specific lock to convert. - * arg 3) The context to use if it is needed. +/* + +=head1 ap_status_t ap_put_os_lock(ap_lock_t **lock, ap_os_lock_t *, ap_pool_t *cont) + +B<Convert the lock from os specific type to apr type> + + arg 1) The apr lock we are converting to. + arg 2) The os specific lock to convert. + arg 3) The pool to use if it is needed. + +=cut */ ap_status_t ap_put_os_lock(ap_lock_t **lock, ap_os_lock_t *thelock, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_put_os_proc(ap_proc_t *proc, ap_os_proc_t *theproc, - * ap_context_t *cont) - * convert the proc from os specific type to apr type. - * arg 1) The apr proc we are converting to. - * arg 2) The os specific proc to convert - * arg 3) The context to use if it is needed. +/* + +=head1 ap_status_t ap_put_os_proc(ap_proc_t *proc, ap_os_proc_t *theproc, ap_pool_t *cont) + +B<convert the proc from os specific type to apr type.> + + arg 1) The apr proc we are converting to. + arg 2) The os specific proc to convert + arg 3) The pool to use if it is needed. + +=cut */ ap_status_t ap_put_os_proc(ap_proc_t **proc, ap_os_proc_t *theproc, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_put_os_imp_time(ap_time_t *aprtime, ap_os_imp_time_t **ostime, ap_context_t, *cont) - * Put the imploded time in the APR format. - * arg 1) the APR time format - * arg 2) the time to convert - * arg 3) the context to use if necessary +/* + +=head1 ap_status_t ap_put_os_imp_time(ap_time_t *aprtime, ap_os_imp_time_t **ostime, ap_pool_t, *cont) + +B<Put the imploded time in the APR format.> + + arg 1) the APR time format + arg 2) the time to convert + arg 3) the pool to use if necessary + +=cut */ ap_status_t ap_put_os_imp_time(ap_time_t *, ap_os_imp_time_t **, ap_pool_t *); -/* ***APRDOC******************************************************** - * ap_status_t ap_put_os_exp_time(ap_exploded_time_t *aprtime, ap_os_exp_time_t **ostime, ap_context_t, *cont) - * Put the exploded time in the APR format. - * arg 1) the APR time format - * arg 2) the time to convert - * arg 3) the context to use if necessary +/* + +=head1 ap_status_t ap_put_os_exp_time(ap_exploded_time_t *aprtime, ap_os_exp_time_t **ostime, ap_pool_t, *cont) + +B<Put the exploded time in the APR format.> + + arg 1) the APR time format + arg 2) the time to convert + arg 3) the pool to use if necessary + +=cut */ ap_status_t ap_put_os_exp_time(ap_exploded_time_t *, ap_os_exp_time_t **, ap_pool_t *); #if APR_HAS_THREADS -/* ***APRDOC******************************************************** - * ap_status_t ap_put_os_thread(ap_thread_t *thd, ap_os_thread_t *thethd, - * ap_context_t *cont) - * convert the thread from os specific type to apr type. - * arg 1) The apr thread we are converting to. - * arg 2) The os specific thread to convert - * arg 3) The context to use if it is needed. +/* + +=head1 ap_status_t ap_put_os_thread(ap_thread_t *thd, ap_os_thread_t *thethd, ap_pool_t *cont) + +B<convert the thread from os specific type to apr type.> + + arg 1) The apr thread we are converting to. + arg 2) The os specific thread to convert + arg 3) The pool to use if it is needed. + +=cut */ ap_status_t ap_put_os_thread(ap_thread_t **thd, ap_os_thread_t *thethd, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_put_os_threadkey(ap_threadkey_t *key, ap_os_threadkey_t *thekey, - * ap_context_t *cont) - * convert the thread private memory key from os specific type to apr type. - * arg 1) The apr handle we are converting to. - * arg 2) The os specific handle to convert - * arg 3) The context to use if it is needed. +/* + +=head1 ap_status_t ap_put_os_threadkey(ap_threadkey_t *key, ap_os_threadkey_t *thekey, ap_pool_t *cont) + +B<convert the thread private memory key from os specific type to apr type.> + + arg 1) The apr handle we are converting to. + arg 2) The os specific handle to convert + arg 3) The pool to use if it is needed. + +=cut */ ap_status_t ap_put_os_threadkey(ap_threadkey_t **key, ap_os_threadkey_t *thekey, ap_pool_t *cont); diff --git a/include/apr_shmem.h b/include/apr_shmem.h index 1ddb0b673..47cf5944f 100644 --- a/include/apr_shmem.h +++ b/include/apr_shmem.h @@ -73,92 +73,134 @@ typedef key_t ap_shm_name_t; typedef struct shmem_t ap_shmem_t; -/* ***APRDOC******************************************************** - * ap_status_t ap_shm_init(ap_shmem_t *m, ap_size_t reqsize, char *file) - * Create a pool of shared memory for use later. - * arg 1) The shared memory block. - * arg 2) The size of the shared memory pool. - * arg 3) The file to use for the shared memory on platforms that - * require it. - * arg 4) The context to use +/* + +=head1 ap_status_t ap_shm_init(ap_shmem_t *m, ap_size_t reqsize, char *file) + +B<Create a pool of shared memory for use later.> + + arg 1) The shared memory block. + arg 2) The size of the shared memory pool. + arg 3) The file to use for the shared memory on platforms that + require it. + arg 4) The pool to use + +=cut */ ap_status_t ap_shm_init(ap_shmem_t **m, ap_size_t reqsize, const char *file, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_shm_destroy(ap_shmem_t *m) - * Destroy the shared memory block. - * arg 1) The shared memory block to destroy. +/* + +=head1 ap_status_t ap_shm_destroy(ap_shmem_t *m) + +B<Destroy the shared memory block.> + + arg 1) The shared memory block to destroy. + +=cut */ ap_status_t ap_shm_destroy(ap_shmem_t *m); -/* ***APRDOC******************************************************** - * ap_status_t ap_shm_malloc(ap_shmem_t *c, ap_size_t reqsize) - * allocate memory from the block of shared memory. - * arg 1) The shared memory block to destroy. - * arg 2) How much memory to allocate +/* + +=head1 ap_status_t ap_shm_malloc(ap_shmem_t *c, ap_size_t reqsize) + +B<allocate memory from the block of shared memory.> + + arg 1) The shared memory block to destroy. + arg 2) How much memory to allocate + +=cut */ void *ap_shm_malloc(ap_shmem_t *c, ap_size_t reqsize); -/* ***APRDOC******************************************************** - * void *ap_shm_calloc(ap_shmem_t *shared, ap_size_t size) - * allocate memory from the block of shared memory and initialize it - * to zero. - * arg 1) The shared memory block to destroy. - * arg 2) How much memory to allocate +/* + +=head1 void *ap_shm_calloc(ap_shmem_t *shared, ap_size_t size) + +B<allocate memory from the block of shared memory and initialize it to zero.> + + arg 1) The shared memory block to destroy. + arg 2) How much memory to allocate + +=cut */ void *ap_shm_calloc(ap_shmem_t *shared, ap_size_t size); -/* ***APRDOC******************************************************** - * ap_status_t ap_shm_free(ap_shmem_t *shared, void *entity) - * free shared memory previously allocated. - * arg 1) The shared memory block to destroy. +/* + +=head1 ap_status_t ap_shm_free(ap_shmem_t *shared, void *entity) + +B<free shared memory previously allocated.> + + arg 1) The shared memory block to destroy. + +=cut */ ap_status_t ap_shm_free(ap_shmem_t *shared, void *free); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_shm_name(ap_shmem_t *c, ap_shm_name_t **name) - * Get the name of the shared memory segment if not using - * anonymous shared memory. - * arg 1) The shared memory block to destroy. - * arg 2) The name of the shared memory block, NULL if anonymous - * shared memory. - * return) APR_USES_ANONYMOUS_SHM if we are using anonymous shared - * memory. APR_USES_FILEBASED_SHM if our shared memory is - * based on file access. APR_USES_KEYBASED_SHM if shared - * memory is based on a key value such as shmctl. If the - * shared memory is anonymous, the name is NULL. +/* + +=head1 ap_status_t ap_get_shm_name(ap_shmem_t *c, ap_shm_name_t **name) + +B<Get the name of the shared memory segment if not using anonymous shared memory.> + + arg 1) The shared memory block to destroy. + arg 2) The name of the shared memory block, NULL if anonymous + shared memory. + return) APR_USES_ANONYMOUS_SHM if we are using anonymous shared + memory. APR_USES_FILEBASED_SHM if our shared memory is + based on file access. APR_USES_KEYBASED_SHM if shared + memory is based on a key value such as shmctl. If the + shared memory is anonymous, the name is NULL. + +=cut */ ap_status_t ap_get_shm_name(ap_shmem_t *c, ap_shm_name_t **name); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_shm_name(ap_shmem_t *c, ap_shm_name_t *name) - * Set the name of the shared memory segment if not using - * anonymous shared memory. This is to allow processes to open - * shared memory created by another process. - * arg 1) The shared memory block to destroy. - * arg 2) The name of the shared memory block, NULL if anonymous - * shared memory. - * return) APR_USES_ANONYMOUS_SHM if we are using anonymous shared - * memory. APR_SUCCESS if we are using named shared memory - * and we were able to assign the name correctly. +/* + +=head1 ap_status_t ap_set_shm_name(ap_shmem_t *c, ap_shm_name_t *name) + +B<Set the name of the shared memory segment if not using +anonymous shared memory.> This is to allow processes to open +shared memory created by another process. + + arg 1) The shared memory block to destroy. + arg 2) The name of the shared memory block, NULL if anonymous + shared memory. + return) APR_USES_ANONYMOUS_SHM if we are using anonymous shared + memory. APR_SUCCESS if we are using named shared memory + and we were able to assign the name correctly. + +=cut */ ap_status_t ap_set_shm_name(ap_shmem_t *c, ap_shm_name_t *name); -/* ***APRDOC******************************************************** - * ap_status_t ap_open_shmem(ap_shmem_t *c) - * Open the shared memory block in a child process. - * arg 1) The shared memory block to open in the child. - * return) This should be called after ap_set_shm_name. The ap_shmem_t - * variable must refer to the memory segment to open. +/* + +=head1 ap_status_t ap_open_shmem(ap_shmem_t *c) + +B<Open the shared memory block in a child process.> + + arg 1) The shared memory block to open in the child. + return) This should be called after ap_set_shm_name. The ap_shmem_t + variable must refer to the memory segment to open. + +=cut */ ap_status_t ap_open_shmem(ap_shmem_t *c); -/* ***APRDOC******************************************************** - * ap_status_t ap_shm_avail(ap_shmem_t *c, ap_size_t *size) - * Determine how much memory is available in the specified shared - * memory block - * arg 1) The shared memory block to open in the child. - * arg 2) The amount of space available in the shared memory block. +/* + +=head1 ap_status_t ap_shm_avail(ap_shmem_t *c, ap_size_t *size) + +B<Determine how much memory is available in the specified shared memory block> + + arg 1) The shared memory block to open in the child. + arg 2) The amount of space available in the shared memory block. + +=cut */ ap_status_t ap_shm_avail(ap_shmem_t *c, ap_size_t *avail); diff --git a/include/apr_thread_proc.h b/include/apr_thread_proc.h index 907762baa..5a171c6bf 100644 --- a/include/apr_thread_proc.h +++ b/include/apr_thread_proc.h @@ -97,361 +97,507 @@ typedef void *(API_THREAD_FUNC *ap_thread_start_t)(void *); /* Thread Function definitions */ -/* ***APRDOC******************************************************** - * ap_status_t ap_create_threadattr(ap_threadattr_t **new, ap_context_t *cont) - * Create and initialize a new threadattr variable - * arg 1) The newly created threadattr. - * arg 2) The context to use +/* + +=head1 ap_status_t ap_create_threadattr(ap_threadattr_t **new, ap_pool_t *cont) + +B<Create and initialize a new threadattr variable> + + arg 1) The newly created threadattr. + arg 2) The pool to use + +=cut */ ap_status_t ap_create_threadattr(ap_threadattr_t **new, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_setthreadattr_detach(ap_threadattr_t *attr, ap_int32_t on) - * Set if newly created threads should be created in detach mode. - * arg 1) The threadattr to affect - * arg 2) Thread detach state on or off +/* + +=head1 ap_status_t ap_setthreadattr_detach(ap_threadattr_t *attr, ap_int32_t on) + +B<Set if newly created threads should be created in detach mode.> + + arg 1) The threadattr to affect + arg 2) Thread detach state on or off + +=cut */ ap_status_t ap_setthreadattr_detach(ap_threadattr_t *attr, ap_int32_t on); -/* ***APRDOC******************************************************** - * ap_status_t ap_getthreadattr_detach(ap_threadattr_t *attr) - * Get the detach mode for this threadattr. - * arg 1) The threadattr to reference +/* + +=head1 ap_status_t ap_getthreadattr_detach(ap_threadattr_t *attr) + +B<Get the detach mode for this threadattr.> + + arg 1) The threadattr to reference + +=cut */ ap_status_t ap_getthreadattr_detach(ap_threadattr_t *iattr); -/* ***APRDOC******************************************************** - * ap_status_t ap_create_thread(ap_thread_t **new, ap_threadattr_t *attr, - * ap_thread_start_t func, void *data, - * ap_context_t *cont) - * Create a new thread of execution - * arg 1) The newly created thread handle. - * arg 2) The threadattr to use to determine how to create the thread - * arg 3) The function to start the new thread in - * arg 4) Any data to be passed to the starting function - * arg 5) The context to use +/* + +=head1 ap_status_t ap_create_thread(ap_thread_t **new, ap_threadattr_t *attr, ap_thread_start_t func, void *data, ap_pool_t *cont) + +B<Create a new thread of execution> + + arg 1) The newly created thread handle. + arg 2) The threadattr to use to determine how to create the thread + arg 3) The function to start the new thread in + arg 4) Any data to be passed to the starting function + arg 5) The pool to use + +=cut */ ap_status_t ap_create_thread(ap_thread_t **new, ap_threadattr_t *attr, ap_thread_start_t func, void *data, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_thread_exit(ap_thread_t *thd, ap_status_t *retval) - * stop the current thread - * arg 1) The thread to stop - * arg 2) The return value to pass back to any thread that cares +/* + +=head1 ap_status_t ap_thread_exit(ap_thread_t *thd, ap_status_t *retval) + +B<stop the current thread> + + arg 1) The thread to stop + arg 2) The return value to pass back to any thread that cares + +=cut */ ap_status_t ap_thread_exit(ap_thread_t *thd, ap_status_t *retval); -/* ***APRDOC******************************************************** - * ap_status_t ap_thread_join(ap_status_t *retval, ap_thread_t *thd) - * block until the desired thread stops executing. - * arg 1) The return value from the dead thread. - * arg 2) The thread to join +/* + +=head1 ap_status_t ap_thread_join(ap_status_t *retval, ap_thread_t *thd) + +B<block until the desired thread stops executing.> + + arg 1) The return value from the dead thread. + arg 2) The thread to join + +=cut */ ap_status_t ap_thread_join(ap_status_t *retval, ap_thread_t *thd); -/* ***APRDOC******************************************************** - * ap_status_t ap_thread_detach(ap_thread_t *thd) - * detach a thread - * arg 1) The thread to detach +/* + +=head1 ap_status_t ap_thread_detach(ap_thread_t *thd) + +B<detach a thread> + + arg 1) The thread to detach + +=cut */ ap_status_t ap_thread_detach(ap_thread_t *thd); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_threaddata(void **data, char *key, ap_thread_t *thread) - * Return the context associated with the current thread. - * arg 1) The user data associated with the thread. - * arg 2) The key to associate with the data - * arg 3) The currently open thread. +/* + +=head1 ap_status_t ap_get_threaddata(void **data, char *key, ap_thread_t *thread) + +B<Return the pool associated with the current thread.> + + arg 1) The user data associated with the thread. + arg 2) The key to associate with the data + arg 3) The currently open thread. + +=cut */ ap_status_t ap_get_threaddata(void **data, char *key, ap_thread_t *thread); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_threaddata(void *data, char *key, - ap_status_t (*cleanup) (void *), - ap_thread_t *thread) - * Return the context associated with the current thread. - * arg 1) The user data to associate with the thread. - * arg 2) The key to use for associating the data with the tread - * arg 3) The cleanup routine to use when the thread is destroyed. - * arg 4) The currently open thread. +/* + +=head1 ap_status_t ap_set_threaddata(void *data, char *key, ap_status_t (*cleanup) (void *), ap_thread_t *thread) + +B<Return the pool associated with the current thread.> + + arg 1) The user data to associate with the thread. + arg 2) The key to use for associating the data with the tread + arg 3) The cleanup routine to use when the thread is destroyed. + arg 4) The currently open thread. + +=cut */ ap_status_t ap_set_threaddata(void *data, char *key, ap_status_t (*cleanup) (void *), ap_thread_t *thread); -/* ***APRDOC******************************************************** - * ap_status_t ap_create_thread_private(ap_threadkey_t **key, - * void (*dest)(void *), - * ap_context_t *cont) - * Create and initialize a new thread private address space - * arg 1) The thread private handle. - * arg 2) The destructor to use when freeing the private memory. - * arg 3) The context to use +/* + +=head1 ap_status_t ap_create_thread_private(ap_threadkey_t **key, void (*dest)(void *), ap_pool_t *cont) + +B<Create and initialize a new thread private address space> + + arg 1) The thread private handle. + arg 2) The destructor to use when freeing the private memory. + arg 3) The pool to use + +=cut */ ap_status_t ap_create_thread_private(ap_threadkey_t **key, void (*dest)(void *), ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_thread_private(void **new, ap_threadkey_t *key) - * Get a pointer to the thread private memory - * arg 1) The data stored in private memory - * arg 2) The handle for the desired thread private memory +/* + +=head1 ap_status_t ap_get_thread_private(void **new, ap_threadkey_t *key) + +B<Get a pointer to the thread private memory> + + arg 1) The data stored in private memory + arg 2) The handle for the desired thread private memory + +=cut */ ap_status_t ap_get_thread_private(void **new, ap_threadkey_t *key); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_thread_private(void *priv, ap_threadkey_t *key) - * Set the data to be stored in thread private memory - * arg 1) The data to be stored in private memory - * arg 2) The handle for the desired thread private memory +/* + +=head1 ap_status_t ap_set_thread_private(void *priv, ap_threadkey_t *key) + +B<Set the data to be stored in thread private memory> + + arg 1) The data to be stored in private memory + arg 2) The handle for the desired thread private memory + +=cut */ ap_status_t ap_set_thread_private(void *priv, ap_threadkey_t *key); -/* ***APRDOC******************************************************** - * ap_status_t ap_delete_thread_private(ap_threadkey_t *key) - * Free the thread private memory - * arg 1) The handle for the desired thread private memory +/* + +=head1 ap_status_t ap_delete_thread_private(ap_threadkey_t *key) + +B<Free the thread private memory> + + arg 1) The handle for the desired thread private memory + +=cut */ ap_status_t ap_delete_thread_private(ap_threadkey_t *key); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_threadkeydata(void **data, char *key, - * ap_threadkey_t *threadkey) - * Return the context associated with the current threadkey. - * arg 1) The user data associated with the threadkey. - * arg 2) The key associated with the data - * arg 3) The currently open threadkey. +/* + +=head1 ap_status_t ap_get_threadkeydata(void **data, char *key, ap_threadkey_t *threadkey) + +B<Return the pool associated with the current threadkey.> + + arg 1) The user data associated with the threadkey. + arg 2) The key associated with the data + arg 3) The currently open threadkey. + +=cut */ ap_status_t ap_get_threadkeydata(void **data, char *key, ap_threadkey_t *threadkey); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_threadkeydata(void *data, char *key, - ap_status_t (*cleanup) (void *), - ap_threadkey_t *threadkey) - * Return the context associated with the current threadkey. - * arg 1) The data to set. - * arg 1) The key to associate with the data. - * arg 2) The user data to associate with the threadkey. - * arg 1) The currently open threadkey. +/* + +=head1 ap_status_t ap_set_threadkeydata(void *data, char *key, ap_status_t (*cleanup) (void *), ap_threadkey_t *threadkey) + +B<Return the pool associated with the current threadkey.> + + arg 1) The data to set. + arg 2) The key to associate with the data. + arg 3) The cleanup routine to use when the file is destroyed. + arg 4) The currently open threadkey. + +=cut */ ap_status_t ap_set_threadkeydata(void *data, char *key, ap_status_t (*cleanup) (void *), ap_threadkey_t *threadkey); /* Process Function definitions */ -/* ***APRDOC******************************************************** - * ap_status_t ap_createprocattr_init(ap_procattr_t **new, ap_context_t *cont) - * Create and initialize a new procattr variable - * arg 1) The newly created procattr. - * arg 2) The context to use +/* + +=head1 ap_status_t ap_createprocattr_init(ap_procattr_t **new, ap_pool_t *cont) + +B<Create and initialize a new procattr variable> + + arg 1) The newly created procattr. + arg 2) The pool to use + +=cut */ ap_status_t ap_createprocattr_init(ap_procattr_t **new, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_setprocattr_io(ap_procattr_t *attr, ap_int32_t in, - * ap_int32_t *out, ap_int32_t err) - * Determine if any of stdin, stdout, or stderr should be linked - * to pipes when starting a child process. - * arg 1) The procattr we care about. - * arg 2) Should stdin be a pipe bnack to the parent? - * arg 3) Should stdout be a pipe bnack to the parent? - * arg 4) Should stderr be a pipe bnack to the parent? +/* + +=head1 ap_status_t ap_setprocattr_io(ap_procattr_t *attr, ap_int32_t in, ap_int32_t *out, ap_int32_t err) + +B<Determine if any of stdin, stdout, or stderr should be linked to pipes when starting a child process.> + + arg 1) The procattr we care about. + arg 2) Should stdin be a pipe back to the parent? + arg 3) Should stdout be a pipe back to the parent? + arg 4) Should stderr be a pipe back to the parent? + +=cut */ ap_status_t ap_setprocattr_io(ap_procattr_t *attr, ap_int32_t in, ap_int32_t out, ap_int32_t err); -/* ***APRDOC******************************************************** - * ap_status_t ap_setprocattr_childin(ap_procattr_t *attr, ap_file_t *child_in, - * ap_file_t *parent_in) - * Set the child_in and/or parent_in values to existing ap_file_t - * values. This is NOT a required initializer function. This is - * useful if you have already opened a pipe (or multiple files) - * that you wish to use, perhaps persistently across mutiple - * process invocations - such as a log file. You can save some - * extra function calls by not creating your own pipe since this - * creates one in the process space for you. - * arg 1) The procattr we care about. - * arg 2) ap_file_t value to use as child_in. Must be a valid file. - * arg 3) ap_file_t value to use as parent_in. Must be a valid file. +/* + +=head1 ap_status_t ap_setprocattr_childin(ap_procattr_t *attr, ap_file_t *child_in, ap_file_t *parent_in) + +B<Set the child_in and/or parent_in values to existing ap_file_t values.> + + arg 1) The procattr we care about. + arg 2) ap_file_t value to use as child_in. Must be a valid file. + arg 3) ap_file_t value to use as parent_in. Must be a valid file. + +B<NOTE>: This is NOT a required initializer function. This is + useful if you have already opened a pipe (or multiple files) + that you wish to use, perhaps persistently across mutiple + process invocations - such as a log file. You can save some + extra function calls by not creating your own pipe since this + creates one in the process space for you. + +=cut */ ap_status_t ap_setprocattr_childin(struct ap_procattr_t *attr, ap_file_t *child_in, ap_file_t *parent_in); -/* ***APRDOC******************************************************** - * ap_status_t ap_setprocattr_childout(ap_procattr_t *attr, - * ap_file_t *child_out, - * ap_file_t *parent_out) - * Set the child_out and parent_out values to existing ap_file_t - * values. This is NOT a required initializer function. This is - * useful if you have already opened a pipe (or multiple files) - * that you wish to use, perhaps persistently across mutiple - * process invocations - such as a log file. - * arg 1) The procattr we care about. - * arg 2) ap_file_t value to use as child_out. Must be a valid file. - * arg 3) ap_file_t value to use as parent_out. Must be a valid file. +/* + +=head1 ap_status_t ap_setprocattr_childout(ap_procattr_t *attr, ap_file_t *child_out, ap_file_t *parent_out) + +B<Set the child_out and parent_out values to existing ap_file_t values.> + + arg 1) The procattr we care about. + arg 2) ap_file_t value to use as child_out. Must be a valid file. + arg 3) ap_file_t value to use as parent_out. Must be a valid file. + +B<NOTE>: This is NOT a required initializer function. This is + useful if you have already opened a pipe (or multiple files) + that you wish to use, perhaps persistently across mutiple + process invocations - such as a log file. + +=cut */ ap_status_t ap_setprocattr_childout(struct ap_procattr_t *attr, ap_file_t *child_out, ap_file_t *parent_out); -/* ***APRDOC******************************************************** - * ap_status_t ap_setprocattr_childerr(ap_procattr_t *attr, - * ap_file_t *child_err, - * ap_file_t *parent_err) - * Set the child_err and parent_err values to existing ap_file_t - * values. This is NOT a required initializer function. This is - * useful if you have already opened a pipe (or multiple files) - * that you wish to use, perhaps persistently across mutiple - * process invocations - such as a log file. - * arg 1) The procattr we care about. - * arg 2) ap_file_t value to use as child_err. Must be a valid file. - * arg 3) ap_file_t value to use as parent_err. Must be a valid file. +/* + +=head1 ap_status_t ap_setprocattr_childerr(ap_procattr_t *attr, ap_file_t *child_err, ap_file_t *parent_err) + +B<Set the child_err and parent_err values to existing ap_file_t values.> + + arg 1) The procattr we care about. + arg 2) ap_file_t value to use as child_err. Must be a valid file. + arg 3) ap_file_t value to use as parent_err. Must be a valid file. + +B<NOTE>: This is NOT a required initializer function. This is + useful if you have already opened a pipe (or multiple files) + that you wish to use, perhaps persistently across mutiple + process invocations - such as a log file. + +=cut */ ap_status_t ap_setprocattr_childerr(struct ap_procattr_t *attr, ap_file_t *child_err, ap_file_t *parent_err); -/* ***APRDOC******************************************************** - * ap_status_t ap_setprocattr_dir(ap_procattr_t *attr, constchar *dir) - * Set which directory the child process should start executing in. - * arg 1) The procattr we care about. - * arg 2) Which dir to start in. By default, this is the same dir as - * the parent currently resides in, when the createprocess call - * is made. +/* + +=head1 ap_status_t ap_setprocattr_dir(ap_procattr_t *attr, constchar *dir) + +B<Set which directory the child process should start executing in.> + + arg 1) The procattr we care about. + arg 2) Which dir to start in. By default, this is the same dir as + the parent currently resides in, when the createprocess call + is made. + +=cut */ ap_status_t ap_setprocattr_dir(ap_procattr_t *attr, const char *dir); -/* ***APRDOC******************************************************** - * ap_status_t ap_setprocattr_cmdtype(ap_procattr_t *attr, ap_cmdtype_e cmd) - * Set what type of command the child process will call. - * arg 1) The procattr we care about. - * arg 2) The type of command. One of: - * APR_SHELLCMD -- Shell script - * APR_PROGRAM -- Executable program (default) +/* + +=head1 ap_status_t ap_setprocattr_cmdtype(ap_procattr_t *attr, ap_cmdtype_e cmd) + +B<Set what type of command the child process will call.> + + arg 1) The procattr we care about. + arg 2) The type of command. One of: + APR_SHELLCMD -- Shell script + APR_PROGRAM -- Executable program (default) + +=cut */ ap_status_t ap_setprocattr_cmdtype(ap_procattr_t *attr, ap_cmdtype_e cmd); -/* ***APRDOC******************************************************** - * ap_status_t ap_setprocattr_detach(ap_procattr_t *attr, ap_int32_t detach) - * Determine if the chlid should start in detached state. - * arg 1) The procattr we care about. - * arg 2) Should the child start in detached state? Default is no. +/* + +=head1 ap_status_t ap_setprocattr_detach(ap_procattr_t *attr, ap_int32_t detach) + +B<Determine if the chlid should start in detached state.> + + arg 1) The procattr we care about. + arg 2) Should the child start in detached state? Default is no. + +=cut */ ap_status_t ap_setprocattr_detach(ap_procattr_t *attr, ap_int32_t detach); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_procdata(char *key, void *data, ap_proc_t *proc) - * Return the context associated with the current proc. - * arg 1) The key associated with the data to retreive. - * arg 2) The user data associated with the proc. - * arg 3) The currently open proc. +/* + +=head1 ap_status_t ap_get_procdata(char *key, void *data, ap_proc_t *proc) + +B<Return the pool associated with the current proc.> + + arg 1) The key associated with the data to retreive. + arg 2) The user data associated with the proc. + arg 3) The currently open proc. + +=cut */ ap_status_t ap_get_procdata(char *key, void *data, ap_proc_t *proc); -/* ***APRDOC******************************************************** - * ap_status_t ap_set_procdata(void *data, char *key, - * ap_status_t (*cleanup) (void *), ap_proc_t *proc) - * Return the context associated with the current proc. - * arg 2) The user data to associate with the file. - * arg 3) The key to use for assocaiteing data with the file. - * arg 4) The cleanup routine to use when the file is destroyed. - * arg 1) The current process. +/* + +=head1 ap_status_t ap_set_procdata(void *data, char *key, ap_status_t (*cleanup) (void *), ap_proc_t *proc) + +B<Return the pool associated with the current proc.> + + arg 1) The user data to associate with the file. + arg 2) The key to use for assocaiteing data with the file. + arg 3) The cleanup routine to use when the file is destroyed. + arg 4) The current process. + +=cut */ ap_status_t ap_set_procdata(void *data, char *key, ap_status_t (*cleanup) (void *), ap_proc_t *proc); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_childin(ap_file_t **new, ap_proc_t *proc) - * Get the file handle that is assocaited with a child's stdin. - * arg 1) The returned file handle. - * arg 2) The process handle that corresponds to the desired child process +/* + +=head1 ap_status_t ap_get_childin(ap_file_t **new, ap_proc_t *proc) + +B<Get the file handle that is assocaited with a child's stdin.> + + arg 1) The returned file handle. + arg 2) The process handle that corresponds to the desired child process + +=cut */ ap_status_t ap_get_childin(ap_file_t **new, ap_proc_t *proc); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_childout(ap_file_t **new, ap_proc_t *proc) - * Get the file handle that is assocaited with a child's stdout. - * arg 1) The returned file handle. - * arg 2) The process handle that corresponds to the desired child process +/* + +=head1 ap_status_t ap_get_childout(ap_file_t **new, ap_proc_t *proc) + +B<Get the file handle that is assocaited with a child's stdout.> + + arg 1) The returned file handle. + arg 2) The process handle that corresponds to the desired child process + +=cut */ ap_status_t ap_get_childout(ap_file_t **new, ap_proc_t *proc); -/* ***APRDOC******************************************************** - * ap_status_t ap_get_childerr(ap_file_t **new, ap_proc_t *proc) - * Get the file handle that is assocaited with a child's stderr. - * arg 1) The returned file handle. - * arg 2) The process handle that corresponds to the desired child process +/* + +=head1 ap_status_t ap_get_childerr(ap_file_t **new, ap_proc_t *proc) + +B<Get the file handle that is assocaited with a child's stderr.> + + arg 1) The returned file handle. + arg 2) The process handle that corresponds to the desired child process + +=cut */ ap_status_t ap_get_childerr(ap_file_t **new, ap_proc_t *proc); #if APR_HAS_FORK -/* ***APRDOC******************************************************** - * ap_status_t ap_fork(ap_proc_t **proc, ap_context_t *cont) - * This is currently the only non-portable call in APR. This executes - * a standard unix fork. - * arg 1) The resulting process handle. - * arg 2) The context to use. +/* + +=head1 ap_status_t ap_fork(ap_proc_t **proc, ap_pool_t *cont) + +B<This is currently the only non-portable call in APR. This executes a standard unix fork.> + + arg 1) The resulting process handle. + arg 2) The pool to use. + +=cut */ ap_status_t ap_fork(ap_proc_t **proc, ap_pool_t *cont); #endif -/* ***APRDOC******************************************************** - * ap_status_t ap_create_process(ap_proc_t **new, const char *progname, - * char *const args[], char **env, - * ap_procattr_t *attr, ap_context_t *cont) - * Create a new process and execute a new program within that process. - * arg 1) The resulting process handle. - * arg 2) The program to run - * arg 3) the arguments to pass to the new program. The first one should - * be the program name. - * arg 4) The new environment ap_table_t for the new process. This should be a - * list of NULL-terminated strings. - * arg 5) the procattr we should use to determine how to create the new - * process - * arg 6) The context to use. +/* + +=head1 ap_status_t ap_create_process(ap_proc_t **new, const char *progname, char *const args[], char **env, ap_procattr_t *attr, ap_pool_t *cont) + +B<Create a new process and execute a new program within that process.> + + arg 1) The resulting process handle. + arg 2) The program to run + arg 3) the arguments to pass to the new program. The first one should + be the program name. + arg 4) The new environment ap_table_t for the new process. This should be a + list of NULL-terminated strings. + arg 5) the procattr we should use to determine how to create the new + process + arg 6) The pool to use. + +=cut */ ap_status_t ap_create_process(ap_proc_t **new, const char *progname, char *const args[], char **env, ap_procattr_t *attr, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * ap_status_t ap_wait_proc(ap_proc_t *proc, ap_wait_how waithow) - * Wait for a child process to die - * arg 1) The process handle that corresponds to the desired child process - * arg 2) How should we wait. One of: - * APR_WAIT -- block until the child process dies. - * APR_NOWAIT -- return immediately regardless of if the - * child is dead or not. - * NOTE: The childs status is in the return code to this process. It is - * one of: - * APR_CHILD_DONE -- child is no longer running. - * APR_CHILD_NOTDONE -- child is still running. +/* + +=head1 ap_status_t ap_wait_proc(ap_proc_t *proc, ap_wait_how waithow) + +B<Wait for a child process to die> + + arg 1) The process handle that corresponds to the desired child process + arg 2) How should we wait. One of: + APR_WAIT -- block until the child process dies. + APR_NOWAIT -- return immediately regardless of if the + child is dead or not. + +B<NOTE>: The childs status is in the return code to this process. It is + one of: + APR_CHILD_DONE -- child is no longer running. + APR_CHILD_NOTDONE -- child is still running. + +=cut */ ap_status_t ap_wait_proc(ap_proc_t *proc, ap_wait_how_e waithow); -/* ***APRDOC******************************************************** - * ap_status_t ap_detach(ap_proc_t **new, ap_context_t *cont) - * Detach the process from the controlling terminal. - * arg 1) The new process handler - * arg 2) The context to use if it is needed. +/* + +=head1 ap_status_t ap_detach(ap_proc_t **new, ap_pool_t *cont) + +B<Detach the process from the controlling terminal.> + + arg 1) The new process handler + arg 2) The pool to use if it is needed. + +=cut */ ap_status_t ap_detach(ap_proc_t **new, ap_pool_t *cont); -/* ***APRDOC******************************************************** - * void ap_register_other_child(ap_proc_t *pid, - * void (*maintenance) (int reason, void *data), - * void *data, int write_fd, ap_context_t *p) - * Register an other_child -- a child which must be kept track of so - * that the program knows when it has dies or disappeared. - * arg 1) pid is the pid of the child. - * arg 2) maintenance is a function that is invoked with a reason and the - * data pointer passed here. - * arg 3) The data to pass to the maintenance function. - * arg 4) An fd that is probed for writing. If it is ever unwritable - * then the maintenance is invoked with reason OC_REASON_UNWRITABLE. - * arg 5) The context to use for allocating memory. +/* + +=head1 void ap_register_other_child(ap_proc_t *pid, void (*maintenance) (int reason, void *data), void *data, int write_fd, ap_pool_t *p) + +B<Register an other_child -- a child which must be kept track of so that the program knows when it has dies or disappeared.> + + arg 1) pid is the pid of the child. + arg 2) maintenance is a function that is invoked with a reason and the + data pointer passed here. + arg 3) The data to pass to the maintenance function. + arg 4) An fd that is probed for writing. If it is ever unwritable + then the maintenance is invoked with reason OC_REASON_UNWRITABLE. + arg 5) The pool to use for allocating memory. + +=cut */ /* XXX: it's not clear how write_fd can be made portable -- i think this * needs to take an ap_file_t, expecting the write_fd to be a pipe. -dean @@ -460,38 +606,56 @@ void ap_register_other_child(ap_proc_t *pid, void (*maintenance) (int reason, void *), void *data, int write_fd, ap_pool_t *p); -/* ***APRDOC******************************************************** - * void ap_unregister_other_child(void *data) - * Stop watching the specified process. - * arg 1) The data to pass to the maintenance function. This is - * used to find the process to unregister. - * NOTE: Since this can be called by a maintenance function while we're - * scanning the other_children list, all scanners should protect - * themself by loading ocr->next before calling any maintenance - * function. +/* + +=head1 void ap_unregister_other_child(void *data) + +B<Stop watching the specified process.> + + arg 1) The data to pass to the maintenance function. This is + used to find the process to unregister. + +B<NOTE>: Since this can be called by a maintenance function while we're + scanning the other_children list, all scanners should protect + themself by loading ocr->next before calling any maintenance + function. + +=cut */ void ap_unregister_other_children(void *data); -/* ***APRDOC******************************************************** - * ap_status_t ap_reap_other_child(ap_proc_t *piod) - * Check on the specified process. If it is gone, call the - * maintenance function. - * arg 1) The process to check. +/* + +=head1 ap_status_t ap_reap_other_child(ap_proc_t *piod) + +B<Check on the specified process. If it is gone, call the maintenance function.> + + arg 1) The process to check. + +=cut */ ap_status_t ap_reap_other_child(ap_proc_t *pid); -/* ***APRDOC******************************************************** - * void ap_check_other_child(void) - * Loop through all registered other_children and call the - * appropriate maintenance function when necessary. +/* + +=head1 void ap_check_other_child(void) + +B<Loop through all registered other_children and call the appropriate maintenance function when necessary.> + +=cut */ void ap_check_other_child(void); -/* ***APRDOC******************************************************** - * ap_status_t ap_kill(ap_proc_t *proc, int sig) - * Terminate a process. - * arg 1) The process to terminate. - * arg 2) How to kill the process. +/* + +=head1 ap_status_t ap_kill(ap_proc_t *proc, int sig) + +B<Terminate a process.> + + arg 1) The process to terminate. + arg 2) How to kill the process. + +=cut */ ap_status_t ap_kill(ap_proc_t *proc, int sig); #ifdef __cplusplus diff --git a/include/apr_time.h b/include/apr_time.h index f81a40718..e38cdb84b 100644 --- a/include/apr_time.h +++ b/include/apr_time.h @@ -83,9 +83,13 @@ typedef ap_int32_t ap_interval_time_t; #define AP_USEC_PER_SEC (1000000LL) #endif -/* ***APRDOC******************************************************** - * ap_time_t ap_now(void) - * return the current time +/* + +=head1 ap_time_t ap_now(void) + +B<return the current time> + +=cut */ ap_time_t ap_now(void); @@ -107,36 +111,55 @@ typedef struct { ap_int32_t tm_gmtoff; /* seconds east of UTC */ } ap_exploded_time_t; -/* ***APRDOC******************************************************** - * ap_status_t ap_ansi_time_to_ap_time(ap_time_t *result, time_t input) - * convert an ansi time_t to an ap_time_t - * arg 1) the resulting ap_time_t - * arg 2) the time_t to convert +/* + +=head1 ap_status_t ap_ansi_time_to_ap_time(ap_time_t *result, time_t input) + +B<convert an ansi time_t to an ap_time_t> + + arg 1) the resulting ap_time_t + arg 2) the time_t to convert + +=cut */ ap_status_t ap_ansi_time_to_ap_time(ap_time_t *result, time_t input); -/* ***APRDOC******************************************************** - * ap_status_t ap_explode_gmt(ap_exploded_time_t *result, ap_time_t input) - * convert a time to its human readable components in GMT timezone - * arg 1) the exploded time - * arg 2) the time to explode +/* + +=head1 ap_status_t ap_explode_gmt(ap_exploded_time_t *result, ap_time_t input) + +B<convert a time to its human readable components in GMT timezone> + + arg 1) the exploded time + arg 2) the time to explode + +=cut */ ap_status_t ap_explode_gmt(ap_exploded_time_t *result, ap_time_t input); -/* ***APRDOC******************************************************** - * ap_status_t ap_explode_localtime(ap_exploded_time_t *result, ap_time_t input) - * convert a time to its human readable components in local timezone - * arg 1) the exploded time - * arg 2) the time to explode +/* + +=head1 ap_status_t ap_explode_localtime(ap_exploded_time_t *result, ap_time_t input) + +B<convert a time to its human readable components in local timezone> + + arg 1) the exploded time + arg 2) the time to explode + +=cut */ ap_status_t ap_explode_localtime(ap_exploded_time_t *result, ap_time_t input); -/* ***APRDOC******************************************************** - * ap_status_t ap_implode_time(ap_time_t *t, ap_exploded_time_t *xt) - * Convert time value from human readable format to number of seconds - * since epoch - * arg 1) the resulting imploded time - * arg 2) the input exploded time +/* + +=head1 ap_status_t ap_implode_time(ap_time_t *t, ap_exploded_time_t *xt) + +B<Convert time value from human readable format to number of seconds since epoch> + + arg 1) the resulting imploded time + arg 2) the input exploded time + +=cut */ ap_status_t ap_implode_time(ap_time_t *result, ap_exploded_time_t *input); |