You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@apr.apache.org by rb...@locus.apache.org on 2000/12/04 06:40:26 UTC
cvs commit: apr/include apr_dso.h apr_errno.h apr_file_io.h
rbb 00/12/03 21:40:26
Modified: include apr_dso.h apr_errno.h apr_file_io.h
Log:
Cleanup some docs for APR. Also, add docs for all of the canonical
names functions.
Revision Changes Path
1.25 +12 -3 apr/include/apr_dso.h
Index: apr_dso.h
===================================================================
RCS file: /home/cvs/apr/include/apr_dso.h,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- apr_dso.h 2000/12/02 19:02:27 1.24
+++ apr_dso.h 2000/12/04 05:40:25 1.25
@@ -69,7 +69,16 @@
#if APR_HAS_DSO
-typedef struct apr_dso_handle_t apr_dso_handle_t;
+/**
+ * Structure for referencing dynamic objects
+ * @defvar apr_dso_handle_t
+ */
+typedef struct apr_dso_handle_t apr_dso_handle_t;
+
+/**
+ * Structure for referencing symbols from dynamic objects
+ * @defvar apr_dso_handle_sym_t
+ */
typedef void * apr_dso_handle_sym_t;
/**
@@ -90,10 +99,10 @@
/**
* Load a symbol from a DSO handle.
* @param ressym Location to store the loaded symbol
- * @param handle handle to load from.
+ * @param handle handle to load the symbol from.
* @param symname Name of the symbol to load.
*/
-apr_status_t apr_dso_sym(apr_dso_handle_sym_t *ressym, apr_dso_handle_t *handle,
+apr_status_t apr_dso_sym(apr_dso_handle_sym_t *ressym, apr_dso_handle_t *handle,
const char *symname);
/**
1.46 +7 -0 apr/include/apr_errno.h
Index: apr_errno.h
===================================================================
RCS file: /home/cvs/apr/include/apr_errno.h,v
retrieving revision 1.45
retrieving revision 1.46
diff -u -r1.45 -r1.46
--- apr_errno.h 2000/11/29 18:15:12 1.45
+++ apr_errno.h 2000/12/04 05:40:25 1.46
@@ -69,6 +69,9 @@
* @package Error Codes
*/
+/**
+ * Type for specifying an error or status code.
+ */
typedef int apr_status_t;
/**
@@ -150,6 +153,10 @@
* platform, either because nobody has gotten to it yet,
* or the function is impossible on this platform.
* APR_EMISMATCH Two passwords do not match.
+ *
+ * @tip Error codes can be checked with APR_STATUS_IS_FOO, where foo is the
+ * error code. For example, APR_EOF can be checked for with
+ * APR_STATUS_IS_EOF.
* </PRE>
*/
1.79 +131 -65 apr/include/apr_file_io.h
Index: apr_file_io.h
===================================================================
RCS file: /home/cvs/apr/include/apr_file_io.h,v
retrieving revision 1.78
retrieving revision 1.79
diff -u -r1.78 -r1.79
--- apr_file_io.h 2000/12/02 12:07:44 1.78
+++ apr_file_io.h 2000/12/04 05:40:25 1.79
@@ -122,19 +122,51 @@
/* should be same as whence type in lseek, POSIX defines this as int */
typedef apr_int32_t apr_seek_where_t;
+/**
+ * Structure for referencing files.
+ * @defvar apr_file_t
+ */
typedef struct apr_file_t apr_file_t;
typedef struct apr_finfo_t apr_finfo_t;
+/**
+ * Structure for referencing directories.
+ * @defvar apr_dir_t
+ */
typedef struct apr_dir_t apr_dir_t;
+/**
+ * Structure for determining canonical filenames.
+ * @defvar apr_canon_t
+ */
typedef struct apr_canon_t apr_canon_t;
+/**
+ * Structure for determining file permissions.
+ * @defvar apr_fileperms_t
+ */
typedef apr_int32_t apr_fileperms_t;
-typedef uid_t apr_uid_t;
-typedef gid_t apr_gid_t;
+/**
+ * Structure for determining file owner.
+ * @defvar apr_uid_t
+ */
+typedef uid_t apr_uid_t;
+/**
+ * Structure for determining the group that owns the file.
+ * @defvar apr_gid_t
+ */
+typedef gid_t apr_gid_t;
#ifdef WIN32
-typedef apr_uint64_t apr_ino_t;
-typedef apr_uint32_t apr_dev_t;
+/**
+ * Structure for determining the inode of the file.
+ * @defvar apr_ino_t
+ */
+typedef apr_uint64_t apr_ino_t;
+/**
+ * Structure for determining the device the file is on.
+ * @defvar apr_dev_t
+ */
+typedef apr_uint32_t apr_dev_t;
#else
-typedef ino_t apr_ino_t;
-typedef dev_t apr_dev_t;
+typedef ino_t apr_ino_t;
+typedef dev_t apr_dev_t;
#endif
/**
@@ -186,120 +218,151 @@
/* Make and Merge Canonical Name Options */
-
-/**
- * Require the trusted_name+child_name result is an absolute product
- * or fail with error for the make and merge canonical name functions.
- */
#define APR_CANON_ONLY_ABSOLUTE 0
-/**
- * Allow that the trusted_name+child_name result may be a relative result
- * for the make and merge canonical name functions.
- */
#define APR_CANON_ALLOW_RELATIVE 2
-
-/**
- * Require the trusted_name+child_name result is not an absolute path
- * or fail with error for the make and merge canonical name functions.
- */
#define APR_CANON_ONLY_RELATIVE 3
-
-/**
- * Require the trusted_name+child_name result is a child of trusted_name
- * or fail with error for the make and merge canonical name functions.
- */
#define APR_CANON_CHILD_OF_TRUSTED 4
-
-/**
- * If file path elements exist (can stat) then fold the element's name
- * to lowercase for the make and merge canonical name functions.
- */
#define APR_CANON_LOWERCASE
-
-/**
- * If file path elements exist (can readdir) then fold the element's name
- * to the true case lowercase for the make and merge canonical name functions.
- */
#define APR_CANON_TRUECASE
+
+/* This is a hack, because none of these functions actually exist yet. The
+ * problem is that we generate our exports from the header files, so we are
+ * trying to export these functions, but they don't exist, so we can't link.
+ * This just makes sure that we don't try to link these functions until
+ * they actually exist.
+ */
+#ifdef APR_NOT_DONE_YET
/**
* Canonicalize the path and name.
- *
* @param new_name The newly allocated canonicalized trusted+child name
* @param trusted_name Already canonical parent path; may be NULL.
* @param child_name An absolute path or path relative to trusted_name.
- * @param options See the APR_CANON_ bit flags documentation for options
- * @param pool The context in which to allocate the new_name apr_canon_t
+ * @param options Bit-wise of:
+ * <PRE>
+ * APR_CANON_ONLY_ABSOLUTE Require the trusted_name+child_name result is
+ * an absolute product or fail with error for the
+ * make and merge canonical name functions.
+ * APR_CANON_ALLOW_RELATIVE Allow that the trusted_name+child_name result
+ * may be a relative result for the make and
+ * merge canonical name functions.
+ * APR_CANON_ONLY_RELATIVE Require the trusted_name+child_name result is
+ * not an absolute path or fail with error for
+ * the make and merge canonical name functions.
+ * APR_CANON_CHILD_OF_TRUSTED Require the trusted_name+child_name result is
+ * a child of trusted_name or fail with error for
+ * the make and merge canonical name functions.
+ * APR_CANON_LOWERCASE If file path elements exist (can stat) then
+ * fold the element's name to lowercase for the
+ * make and merge canonical name functions.
+ * APR_CANON_TRUECASE If file path elements exist (can readdir) then
+ * fold the element's name to the true case
+ * lowercase for the make and merge canonical
+ * name functions.
+ * </PRE>
+ * @param pool The pool in which to allocate the new_name apr_canon_t
*
- * @tip A canonical name is a name stipped of embedded backrefs "../",
+ * @tip A canonical name is a name stripped of embedded backrefs "../",
* thisrefs "./", successive slashes (//), or any other ambigious file
* name element. Absolute canonical names referencing the same file must
* strcmp() identically, excluding symlinks or inconsistent use of the
* APR_CANON_LOWERCASE or APR_CANON_TRUECASE options.
*
* If the name does not exist, or resolves to a relative name the given case
- * is preserved. Insignificant elements are eliminated. For example, on Win32 this
- * function removes trailing dots (which are allowed, but not stored in
+ * is preserved. Insignificant elements are eliminated. For example, on Win32
+ * this function removes trailing dots (which are allowed, but not stored in
* the file system), and "/../" under Unix is resolved to "/". The relative
* canonical name may contain leading backrefs "../", but will never contain
* any other prohibited element.
*/
-
-/*
- * @param trusted_name May be null
- * @param child_name May be absolute, in which case trusted_name is ignored
- * unless APR_CHILD_RELATIVE is tested.
- */
-/* This is a hack, because none of these functions actually exist yet. The
- * problem is that we generate our exports from the header files, so we are
- * trying to export these functions, but they don't exist, so we can't link.
- * This just makes sure that we don't try to link these functions until
- * they actually exist.
- */
-#ifdef APR_NOT_DONE_YET
apr_status_t apr_make_canonical_name(apr_canon_t **new_name,
const apr_canon_t *trusted_name,
const char *child_name,
int options,
apr_pool_t *pool);
+/**
+ * Merge two canonical names into a single canonical name.
+ * @param new_name The newly allocated canonicalized trusted+child name
+ * @param trusted_name Already canonical parent path; may be NULL.
+ * @param child_name An already canonical absolute path or path relative to
+ * trusted_name.
+ * @param options See apr_make_canonical_name for options
+ * @param pool The pool to allocate the new_name out of.
+ * @see apr_make_canonical_name
+ */
apr_status_t apr_merge_canonical_name(apr_canon_t **new_name,
const apr_canon_t *trusted_name,
const apr_canon_t *child_name,
int options,
apr_pool_t *pool);
+/**
+ * Get the canonical path in a character string
+ * @param path A location to store the canocical name
+ * @param trusted_name An already canonicalized file path
+ * @param pool The pool to allocate the path out of.
+ */
apr_status_t apr_get_canonical_name(char **path,
const apr_canon_t *trusted_name,
apr_pool_t *pool);
+/**
+ * Count the number of elements in a canonical name.
+ * @param trusted_name An already canonicalized file path
+ * @return The number of elements in the name
+ */
int apr_count_canonical_elements(const apr_canon_t *trusted_name);
+/**
+ * Query the length of some elements of the canonical name
+ * @param trusted_name An already canonicalized file path
+ * @param firstelement The numerical position of the element to start the
+ * length at.
+ * @param lastelement The numerical position of the element to end the
+ * length at.
+ * @return The length of requested elements.
+ */
int apr_get_canonical_elements_length(const apr_canon_t *trusted_name,
int firstelement, int lastelement);
+/**
+ * Get the requested elements of a canonical name in a character string
+ * @param path_elements A location to store the path elements.
+ * @param trusted_name An already canonicalized file path
+ * @param firstelement The numerical position of the element to start the
+ * length at.
+ * @param lastelement The numerical position of the element to end the
+ * length at.
+ * @param pool The pool to allocate the path out of.
+ */
apr_status_t apr_get_canonical_elements(char **path_elements,
const apr_canon_t *trusted_name,
int firstelement, int lastelement,
apr_pool_t *pool);
/**
- * Returns APR_SUCCESS if canon_name is absolute. Do not trust
- * !apr_is_absolute to determine if the path is relative. Also,
- * test apr_is_virtualroot to avoid non-filesystem pseudo roots.
+ * Determine if a canonical name is absolute.
+ * @param path The canonical name to check
+ * @warning Do not trust !apr_is_absolute to determine if the path is
+ * relative. Also, test apr_is_virtualroot to avoid non-filesystem
+ * pseudo roots.
*/
apr_status_t apr_is_absolute(apr_canon_t **path);
/**
- * Returns APR_SUCCESS if canon_name is absolute. Do not trust
- * !apr_is_relative to determine if the path is absolute.
+ * Determine if a canonical name is relative
+ * @param path The canonical name to check
+ * @warning Do not trust !apr_is_relative to determine if the path is absolute
*/
apr_status_t apr_is_relative(apr_canon_t **path);
/**
- * Returns APR_SUCCESS if the elements 0..elements resolves to a
- * platform's non-physical root, e.g. the //machine/ name that
- * isn't an adaquately complete root for UNC paths.
+ * Determine if the elements 0..elements resolves to a platform's non-physical
+ * root, e.g. the //machine/ name that isn't an adaquately complete root for
+ * UNC paths.
+ * @param path The canonical name to check
+ * @param elements The number of elements to check.
*/
apr_status_t apr_is_virtualroot(apr_canon_t **path, int elements);
#endif
@@ -398,7 +461,8 @@
* Write data to the specified file.
* @param thefile The file descriptor to write to.
* @param buf The buffer which contains the data.
- * @param nbytes On entry, the number of bytes to write; on exit, the number of bytes written.
+ * @param nbytes On entry, the number of bytes to write; on exit, the number
+ * of bytes written.
* @tip apr_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
@@ -429,7 +493,8 @@
apr_size_t nvec, apr_size_t *nbytes);
/**
- * Read data from the specified file.
+ * Read data from the specified file, ensuring that the buffer is filled
+ * before returning.
* @param thefile The file descriptor to read from.
* @param buf The buffer to store the data to.
* @param nbytes The number of bytes to read.
@@ -449,7 +514,8 @@
apr_size_t *bytes_read);
/**
- * Write data to the specified file.
+ * Write data to the specified file, ensuring that all of the data is
+ * written before returning.
* @param thefile The file descriptor to write to.
* @param buf The buffer which contains the data.
* @param nbytes The number of bytes to write.