From 9013655402344e3910c5349a121f23418f74ed49 Mon Sep 17 00:00:00 2001 From: Ryan Bloom Date: Wed, 5 Jul 2000 04:23:16 +0000 Subject: Document apr_lib.h and do some cleanup. This moves the definition of the rest of the pool functions to apr_pools.h where they belong. This also starts to document that file. git-svn-id: https://svn.apache.org/repos/asf/apr/apr/trunk@60299 13f79535-47bb-0310-9956-ffa450edef68 --- include/apr_lib.h | 221 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 170 insertions(+), 51 deletions(-) (limited to 'include/apr_lib.h') diff --git a/include/apr_lib.h b/include/apr_lib.h index 5c3960f83..9aad9405f 100644 --- a/include/apr_lib.h +++ b/include/apr_lib.h @@ -55,6 +55,8 @@ #ifndef APR_LIB_H #define APR_LIB_H +#include "apr.h" +#include "apr_pools.h" #include "apr_general.h" #include "apr_tables.h" #include "apr_file_io.h" @@ -85,27 +87,81 @@ typedef struct ap_vformatter_buff_t { char *endpos; } ap_vformatter_buff_t; -enum kill_conditions { - kill_never, /* process is never sent any signals */ - kill_always, /* process is sent SIGKILL on ap_pool_t cleanup */ - kill_after_timeout, /* SIGTERM, wait 3 seconds, SIGKILL */ - just_wait, /* wait forever for the process to complete */ - kill_only_once /* send SIGTERM and then wait */ -}; - /* - * Define the prototypes for the various APR GP routines. + +=head1 ap_status_t ap_tokenize_to_argv(const char **arg_str, char ***argv_out, ap_pool_t *token_context) + +B + + arg 1) The arguments to convert + arg 2) Output location. This is a pointer to an array of strings. + arg 3) Pool to use. + +=cut */ -APR_EXPORT(char *) ap_cpystrn(char *d, const char *s, size_t l); APR_EXPORT(ap_status_t) ap_tokenize_to_argv(const char *arg_str, char ***argv_out, ap_pool_t *token_context); + +/* + +=head1 ap_status_t ap_filename_of_pathname(const char *pathname) + +B + + arg 1) The path to get the final element of + +B: Examples: "/foo/bar/gum" -> "gum" + "/foo/bar/gum/" -> "" + "gum" -> "gum" + "wi\\n32\\stuff" -> "stuff" + +=cut + */ APR_EXPORT(const char *) ap_filename_of_pathname(const char *pathname); + + +/* + +=head1 ap_status_t ap_collapse_spaces(char *dest, const char *src) + +B + + arg 1) The destination string. It is okay to modify the string + in place. Namely dest == src + arg 2) The string to rid the spaces from. + +=cut + */ APR_EXPORT(char *) ap_collapse_spaces(char *dest, const char *src); -/*APR_EXPORT(ap_mutex_t *) ap_create_mutex(void *m);*/ -APR_EXPORT(int) ap_slack(int l, int h); +/* + +=head1 ap_status_t ap_execle(const char *c, const char *a, ...) + +B + + arg 1) The path to the new program to run + arg 2) The first argument for the new program + ...) The rest of the arguments for the new program. + +=cut + */ APR_EXPORT_NONSTD(ap_status_t) ap_execle(const char *c, const char *a, ...); + +/* + +=head1 ap_status_t ap_execve(const char *c, const char *aargv[], const char *envp[]) + +B + + arg 1) The path to the new program to run + arg 2) The arguments for the new program in an array of char *. + arg 3) The environment for the new program in an array of char * of the + form key=value + +=cut + */ APR_EXPORT_NONSTD(ap_status_t) ap_execve(const char *c, const char *argv[], const char *envp[]); @@ -193,13 +249,38 @@ APR_EXPORT_NONSTD(ap_status_t) ap_execve(const char *c, const char *argv[], * or until ap_vformatter returns. */ +/* + +=head1 int ap_vformatter(int (*flush_func)(ap_vformatter_buff_t *b), ap_vformatter_buff_t *c, const char *fmt, va_list ap) + +B + + arg 1) The function to call when the buffer is full + arg 2) The buffer to write to + arg 3) The format string + arg 4) The arguments to use to fill out the format string. + +B: The extensions are: + %pA takes a struct in_addr *, and prints it as a.b.c.d + %pI takes a struct sockaddr_in * and prints it as a.b.c.d:port + %pp takes a void * and outputs it in hex + +=cut + */ APR_EXPORT(int) ap_vformatter(int (*flush_func)(ap_vformatter_buff_t *b), ap_vformatter_buff_t *c, const char *fmt, va_list ap); +/* + +=head1 ap_status_t ap_validate_password(const char *passwd, const char *hash) + +B -/* A small routine to validate a plain text password with a password - * that has been encrypted using any algorithm APR knows about. + arg 1) The password to validate + arg 2) The password to validate against + +=cut */ APR_EXPORT(ap_status_t) ap_validate_password(const char *passwd, const char *hash); @@ -220,55 +301,93 @@ APR_EXPORT(ap_status_t) ap_validate_password(const char *passwd, const char *has * to distinguish between an output which was truncated, and an output which * exactly filled the buffer. */ + +/* + +=head1 int ap_snprintf(char *buf, size_t len, const char *format, ...) + +B + + arg 1) The buffer to write to + arg 2) The size of the buffer + arg 3) The format string + arg 4) The arguments to use to fill out the format string. + +=cut + */ APR_EXPORT(int) ap_snprintf(char *buf, size_t len, const char *format, ...) __attribute__((format(printf,3,4))); + +/* + +=head1 int ap_vsnprintf(char *buf, size_t len, const char *format, va_list ap) + +B + + arg 1) The buffer to write to + arg 2) The size of the buffer + arg 3) The format string + arg 4) The arguments to use to fill out the format string. + +=cut + */ APR_EXPORT(int) ap_vsnprintf(char *buf, size_t len, const char *format, va_list ap); /* - * APR memory structure manipulators (pools, tables, and arrays). - */ -APR_EXPORT(ap_pool_t *) ap_make_sub_pool(ap_pool_t *p, int (*apr_abort)(int retcode)); -APR_EXPORT(void) ap_clear_pool(struct ap_pool_t *p); -APR_EXPORT(void) ap_destroy_pool(struct ap_pool_t *p); -APR_EXPORT(long) ap_bytes_in_pool(ap_pool_t *p); -APR_EXPORT(long) ap_bytes_in_free_blocks(void); -APR_EXPORT(ap_pool_t *) ap_find_pool(const void *ts); -APR_EXPORT(int) ap_pool_is_ancestor(ap_pool_t *a, ap_pool_t *b); -APR_EXPORT(void) ap_pool_join(ap_pool_t *p, ap_pool_t *sub); - -/* used to guarantee to the ap_pool_t debugging code that the sub ap_pool_t will not be - * destroyed before the parent pool + +=head1 ap_status_t ap_getpass(const char *prompt, char *pwbuf, size_t *bufsize) + +B + + arg 1) The prompt to display + arg 2) Where to store the password + arg 3) The length of the password string. + +=cut */ -#ifndef POOL_DEBUG -#ifdef ap_pool_join -#undef ap_pool_join -#endif /* ap_pool_join */ -#define ap_pool_join(a,b) -#endif /* POOL_DEBUG */ - - -APR_EXPORT(void *) ap_palloc(struct ap_pool_t *c, int reqsize); -APR_EXPORT(void *) ap_pcalloc(struct ap_pool_t *p, int size); -APR_EXPORT(char *) ap_pstrdup(struct ap_pool_t *p, const char *s); -APR_EXPORT(char *) ap_pstrndup(struct ap_pool_t *p, const char *s, int n); -APR_EXPORT_NONSTD(char *) ap_pstrcat(struct ap_pool_t *p, ...); -APR_EXPORT(char *) ap_pvsprintf(struct ap_pool_t *p, const char *fmt, va_list ap); -APR_EXPORT_NONSTD(char *) ap_psprintf(struct ap_pool_t *p, const char *fmt, ...); -APR_EXPORT(void) ap_register_cleanup(struct ap_pool_t *p, void *data, - ap_status_t (*plain_cleanup) (void *), - ap_status_t (*child_cleanup) (void *)); -APR_EXPORT(void) ap_kill_cleanup(struct ap_pool_t *p, void *data, - ap_status_t (*cleanup) (void *)); -APR_EXPORT(ap_status_t) ap_run_cleanup(struct ap_pool_t *p, void *data, - ap_status_t (*cleanup) (void *)); -APR_EXPORT(void) ap_cleanup_for_exec(void); APR_EXPORT(ap_status_t) ap_getpass(const char *prompt, char *pwbuf, size_t *bufsize); -APR_EXPORT_NONSTD(ap_status_t) ap_null_cleanup(void *data); +/* + +=head1 ap_status_t ap_note_subprocess(ap_pool_t *a, ap_proc_t *pid, enum kill_conditions how) + +B + + arg 1) The pool to use to define the processes lifetime + arg 2) The process to register + arg 3) How to kill the process, one of: + kill_never -- process is never sent any signals + kill_always -- process is sent SIGKILL on ap_pool_t cleanup + kill_after_timeout -- SIGTERM, wait 3 seconds, SIGKILL + just_wait -- wait forever for the process to complete + kill_only_once -- send SIGTERM and then wait + +=cut + */ APR_EXPORT(void) ap_note_subprocess(struct ap_pool_t *a, ap_proc_t *pid, enum kill_conditions how); +/* + +=head1 char *ap_cpystrn(char *dst, const char *src, size_t dst_size) + +B + + arg 1) The destination string + arg 2) The source string + arg 3) The number of characters to copy + +B: We re-implement this function to implement these specific changes: + 1) strncpy() doesn't always null terminate and we want it to. + 2) strncpy() null fills, which is bogus, esp. when copy 8byte strings + into 8k blocks. + 3) Instead of returning the pointer to the beginning of the + destination string, we return a pointer to the terminating '\0' + to allow us to check for truncation. + +=cut + */ APR_EXPORT(char *) ap_cpystrn(char *dst, const char *src, size_t dst_size); #ifdef __cplusplus -- cgit v1.2.1