You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by rb...@locus.apache.org on 2000/07/05 06:23:19 UTC
cvs commit: apache-2.0/src/lib/apr/include apr_lib.h apr_pools.h
rbb 00/07/04 21:23:17
Modified: src/lib/apr/include apr_lib.h apr_pools.h
Log:
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.
Revision Changes Path
1.34 +170 -51 apache-2.0/src/lib/apr/include/apr_lib.h
Index: apr_lib.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_lib.h,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -r1.33 -r1.34
--- apr_lib.h 2000/06/08 19:29:38 1.33
+++ apr_lib.h 2000/07/05 04:23:15 1.34
@@ -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 @@
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<Convert the arguments to a program from one string to an array of strings terminated by a NULL>
+
+ 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<return the final element of the pathname>
+
+ arg 1) The path to get the final element of
+
+B<NOTE>: 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<Strip spaces from a string>
+
+ 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);
+
+/*
+
+=head1 ap_status_t ap_execle(const char *c, const char *a, ...)
-/*APR_EXPORT(ap_mutex_t *) ap_create_mutex(void *m);*/
-APR_EXPORT(int) ap_slack(int l, int h);
+B<Replace the current process image with a new process>
+
+ 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<Replace the current process image with a new process>
+
+ 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 @@
* 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<a generic printf-style formatting routine with some extensions>
+
+ 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<NOTE>: 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)
-/* A small routine to validate a plain text password with a password
- * that has been encrypted using any algorithm APR knows about.
+B<Validate any password encypted with any algorithm that APR understands>
+
+ 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 @@
* 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<snprintf routine based on ap_vformatter. This means it understands the same extensions.>
+
+ 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<vsnprintf routine based on ap_vformatter. This means it understands the same extensions.>
+
+ 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).
+
+=head1 ap_status_t ap_getpass(const char *prompt, char *pwbuf, size_t *bufsize)
+
+B<Display a prompt and read in the password from stdin.>
+
+ arg 1) The prompt to display
+ arg 2) Where to store the password
+ arg 3) The length of the password string.
+
+=cut
*/
-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
- */
-#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<Register a process to be killed when a pool dies.>
+
+ 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<copy n characters from src to dest>
+
+ arg 1) The destination string
+ arg 2) The source string
+ arg 3) The number of characters to copy
+
+B<NOTE>: 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
1.19 +115 -2 apache-2.0/src/lib/apr/include/apr_pools.h
Index: apr_pools.h
===================================================================
RCS file: /home/cvs/apache-2.0/src/lib/apr/include/apr_pools.h,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- apr_pools.h 2000/06/17 16:33:08 1.18
+++ apr_pools.h 2000/07/05 04:23:16 1.19
@@ -80,11 +80,23 @@
* alloc.c.
*/
-#include "apr_lib.h"
+#include "apr.h"
+#include "apr_thread_proc.h"
#if APR_HAVE_SYS_TYPES_H
#include <sys/types.h>
#endif
+#if APR_HAVE_STDARG_H
+#include <stdarg.h>
+#endif
+
+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 */
+};
struct process_chain {
ap_proc_t *pid;
@@ -175,11 +187,112 @@
#ifndef BLOCK_MINALLOC
#define BLOCK_MINALLOC 8192
#endif
+
+/*
+ * APR memory structure manipulators (pools, tables, and arrays).
+ */
+/*
+
+=head1 ap_pool_t *ap_make_sub_pool(ap_pool_t *p, int (*apr_abort)(int retcode))
+
+B<make a sub pool from the current pool>
+
+ arg 1) The pool to use as a parent pool
+ arg 2) A function to use if the pool cannot allocate more memory.
+ return) The new sub-pool
+
+B<NOTE>: The apr_abort function provides a way to quit the program if the
+ machine is out of memory. By default, APR will return with an
+ error.
+
+=cut
+ */
+APR_EXPORT(ap_pool_t *) ap_make_sub_pool(ap_pool_t *p, int (*apr_abort)(int retcode));
+
+/*
+
+=head1 void ap_clear_pool(ap_pool_t *p)
+
+B<clear all memory in the pool>
+
+ arg 1) The pool to clear
+
+B<NOTE>: This does not actually free the memory, it just allows the pool
+ to re-use this memory for the next allocation.
+
+=cut
+ */
+APR_EXPORT(void) ap_clear_pool(struct ap_pool_t *p);
+
+/*
+
+=head1 void ap_destroy_pool(ap_pool_t *p)
+
+B<destroy the pool>
+
+ arg 1) The pool to destroy
-/* Finally, some accounting */
+B<NOTE>: This will actually free the memory
+=cut
+ */
+APR_EXPORT(void) ap_destroy_pool(struct ap_pool_t *p);
+
+/*
+
+=head1 long *ap_bytes_in_pool(ap_pool_t *p)
+
+B<report the number of bytes currently in the pool>
+
+ arg 1) The pool to inspect
+ return) The number of bytes
+
+=cut
+ */
APR_EXPORT(long) ap_bytes_in_pool(ap_pool_t *p);
+
+/*
+
+=head1 long *ap_bytes_in_free_blocks(ap_pool_t *p)
+
+B<report the number of bytes currently in the list of free blocks>
+
+ return) The number of bytes
+
+=cut
+ */
APR_EXPORT(long) ap_bytes_in_free_blocks(void);
+
+APR_EXPORT(int) ap_pool_is_ancestor(ap_pool_t *a, ap_pool_t *b);
+
+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);
+
+
+/* used to guarantee to the ap_pool_t debugging code that the sub ap_pool_t will not be
+ * destroyed before the parent pool
+ */
+#ifndef POOL_DEBUG
+#ifdef ap_pool_join
+#undef ap_pool_join
+#endif /* ap_pool_join */
+#define ap_pool_join(a,b)
+#endif /* POOL_DEBUG */
#ifdef __cplusplus
}
Re: cvs commit: apache-2.0/src/lib/apr/include apr_lib.h apr_pools.h
Posted by rb...@covalent.net.
On 5 Jul 2000 rbb@locus.apache.org wrote:
> rbb 00/07/04 21:23:17
>
> Modified: src/lib/apr/include apr_lib.h apr_pools.h
> Log:
> 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.
This change actually causes some warnings, which may be real and they may
not be. I'll look into those tomorrow sometime. I need to get off the
computer tonight though. If somebody else wants to beat me to these,
it would be very much appreciated. :-)
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: cvs commit: apache-2.0/src/lib/apr/include apr_lib.h apr_pools.h
Posted by rb...@covalent.net.
On 5 Jul 2000 rbb@locus.apache.org wrote:
> rbb 00/07/04 21:23:17
>
> Modified: src/lib/apr/include apr_lib.h apr_pools.h
> Log:
> 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.
This change actually causes some warnings, which may be real and they may
not be. I'll look into those tomorrow sometime. I need to get off the
computer tonight though. If somebody else wants to beat me to these,
it would be very much appreciated. :-)
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------