Return-Path: Delivered-To: apmail-apr-cvs-archive@www.apache.org Received: (qmail 9333 invoked from network); 27 May 2004 20:29:06 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur-2.apache.org with SMTP; 27 May 2004 20:29:06 -0000 Received: (qmail 60645 invoked by uid 500); 27 May 2004 20:29:36 -0000 Delivered-To: apmail-apr-cvs-archive@apr.apache.org Received: (qmail 60566 invoked by uid 500); 27 May 2004 20:29:35 -0000 Mailing-List: contact cvs-help@apr.apache.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: Reply-To: dev@apr.apache.org Delivered-To: mailing list cvs@apr.apache.org Received: (qmail 60549 invoked by uid 98); 27 May 2004 20:29:35 -0000 X-Qmail-Scanner-Mail-From: jorton@apache.org via hermes.apache.org X-Qmail-Scanner: 1.20 (Clear:RC:0(209.237.227.194):. Processed in 0.076811 secs) Date: 27 May 2004 20:29:02 -0000 Message-ID: <20040527202902.9293.qmail@minotaur.apache.org> From: jorton@apache.org To: apr-cvs@apache.org Subject: cvs commit: apr/include apr_file_io.h X-Spam-Rating: hermes.apache.org 1.6.2 0/1000/N X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N jorton 2004/05/27 13:29:02 Modified: include apr_file_io.h Log: * include/apr_file_io.h: Doxygen/formatting/whitespace cleanups. Revision Changes Path 1.153 +108 -114 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.152 retrieving revision 1.153 diff -d -u -r1.152 -r1.153 --- apr_file_io.h 17 May 2004 20:14:49 -0000 1.152 +++ apr_file_io.h 27 May 2004 20:29:01 -0000 1.153 @@ -113,7 +113,7 @@ /** File attributes */ typedef apr_uint32_t apr_fileattrs_t; -/** should be same as whence type in lseek, POSIX defines this as int */ +/** Type to pass as whence argument to apr_file_seek. */ typedef int apr_seek_where_t; /** @@ -145,7 +145,7 @@ /** * Open the specified file. - * @param new_file The opened file descriptor. + * @param newf The opened file descriptor. * @param fname The full path to the file (using / on all systems) * @param flag Or'ed value of: * 
  @@ -174,8 +174,8 @@
    *
* @param perm Access permissions for file. * @param pool The pool to use. - * @remark If perm is APR_OS_DEFAULT and the file is being created, appropriate - * default permissions will be used. + * @remark If perm is APR_OS_DEFAULT and the file is being created, + * appropriate default permissions will be used. */ APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname, apr_int32_t flag, apr_fileperms_t perm, @@ -188,27 +188,29 @@ APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file); /** - * delete the specified file. + * Delete the specified file. * @param path The full path to the file (using / on all systems) * @param pool The pool to use. - * @remark If the file is open, it won't be removed until all instances are closed. + * @remark If the file is open, it won't be removed until all + * instances are closed. */ APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool); /** - * rename the specified file. + * Rename the specified file. * @param from_path The full path to the original file (using / on all systems) * @param to_path The full path to the new file (using / on all systems) * @param pool The pool to use. - * @warning If a file exists at the new location, then it will be overwritten. - * Moving files or directories across devices may not be possible. + * @warning If a file exists at the new location, then it will be + * overwritten. Moving files or directories across devices may not be + * possible. */ APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path, const char *to_path, apr_pool_t *pool); /** - * copy the specified file to another file. + * Copy the specified file to another file. * @param from_path The full path to the original file (using / on all systems) * @param to_path The full path to the new file (using / on all systems) * @param perms Access permissions for the new file if it is created. @@ -225,9 +227,9 @@ apr_pool_t *pool); /** - * append the specified file to another file. - * @param from_path The full path to the source file (using / on all systems) - * @param to_path The full path to the destination file (using / on all systems) + * Append the specified file to another file. + * @param from_path The full path to the source file (use / on all systems) + * @param to_path The full path to the destination file (use / on all systems) * @param perms Access permissions for the destination file if it is created. * In place of the usual or'd combination of file permissions, the * value APR_FILE_SOURCE_PERMS may be given, in which case the source @@ -248,7 +250,7 @@ APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr); /** - * open standard error as an apr file pointer. + * Open standard error as an apr file pointer. * @param thefile The apr file to use as stderr. * @param pool The pool to allocate the file out of. * @@ -256,7 +258,7 @@ * is that you may not always have a stderr/out/in on Windows. This * is generally a problem with newer versions of Windows and services. * - * The other problem is that the C library functions generally work + * @remark The other problem is that the C library functions generally work * differently on Windows and Unix. So, by using apr_file_open_std* * functions, you can get a handle to an APR struct that works with * the APR functions which are supposed to work identically on all @@ -270,15 +272,7 @@ * @param thefile The apr file to use as stdout. * @param pool The pool to allocate the file out of. * - * @remark The only reason that the apr_file_open_std* functions exist - * is that you may not always have a stderr/out/in on Windows. This - * is generally a problem with newer versions of Windows and services. - * - * The other problem is that the C library functions generally work - * differently on Windows and Unix. So, by using apr_file_open_std* - * functions, you can get a handle to an APR struct that works with - * the APR functions which are supposed to work identically on all - * platforms. + * @remark See remarks for apr_file_open_stdout. */ APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile, apr_pool_t *pool); @@ -288,15 +282,7 @@ * @param thefile The apr file to use as stdin. * @param pool The pool to allocate the file out of. * - * @remark The only reason that the apr_file_open_std* functions exist - * is that you may not always have a stderr/out/in on Windows. This - * is generally a problem with newer versions of Windows and services. - * - * The other problem is that the C library functions generally work - * differently on Windows and Unix. So, by using apr_file_open_std* - * functions, you can get a handle to an APR struct that works with - * the APR functions which are supposed to work identically on all - * platforms. + * @remark See remarks for apr_file_open_stdout. */ APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile, apr_pool_t *pool); @@ -305,21 +291,21 @@ * Read data from the specified file. * @param thefile The file descriptor to read from. * @param buf The buffer to store the data to. - * @param nbytes On entry, the number of bytes to read; on exit, the number of bytes read. - * @remark apr_file_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. + * @param nbytes On entry, the number of bytes to read; on exit, the number + * of bytes read. * - * It is not possible for both bytes to be read and an APR_EOF or other - * error to be returned. + * @remark apr_file_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. * - * APR_EINTR is never returned. + * @remark It is not possible for both bytes to be read and an APR_EOF + * or other error to be returned. APR_EINTR is never returned. */ APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf, - apr_size_t *nbytes); + apr_size_t *nbytes); /** * Write data to the specified file. @@ -327,17 +313,17 @@ * @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. - * @remark apr_file_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. + * @remark apr_file_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. * - * APR_EINTR is never returned. + * @remark It is possible for both bytes to be written and an error to + * be returned. APR_EINTR is never returned. */ APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf, - apr_size_t *nbytes); + apr_size_t *nbytes); /** * Write data from iovec array to the specified file. @@ -347,16 +333,16 @@ * be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function * will fail with APR_EINVAL. * @param nbytes The number of bytes written. - * @remark It is possible for both bytes to be written and an error to be returned. - * APR_EINTR is never returned. * - * apr_file_writev is available even if the underlying operating system + * @remark It is possible for both bytes to be written and an error to + * be returned. APR_EINTR is never returned. * - * doesn't provide writev(). + * @remark apr_file_writev is available even if the underlying + * operating system doesn't provide writev(). */ APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile, - const struct iovec *vec, - apr_size_t nvec, apr_size_t *nbytes); + const struct iovec *vec, + apr_size_t nvec, apr_size_t *nbytes); /** * Read data from the specified file, ensuring that the buffer is filled @@ -365,21 +351,22 @@ * @param buf The buffer to store the data to. * @param nbytes The number of bytes to read. * @param bytes_read If non-NULL, this will contain the number of bytes read. - * @remark apr_file_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, - * then the process/thread will block until it is available or EOF - * is reached. 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 error to be - * returned. And if *bytes_read is less than nbytes, an - * accompanying error is _always_ returned. + * @remark apr_file_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, then the process/thread will block until it is + * available or EOF is reached. If a char was put back into the + * stream via ungetc, it will be the first character returned. * - * APR_EINTR is never returned. + * @remark It is possible for both bytes to be read and an error to be + * returned. And if *bytes_read is less than nbytes, an accompanying + * error is _always_ returned. + * + * @remark APR_EINTR is never returned. */ APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf, - apr_size_t nbytes, - apr_size_t *bytes_read); + apr_size_t nbytes, + apr_size_t *bytes_read); /** * Write data to the specified file, ensuring that all of the data is @@ -387,54 +374,58 @@ * @param thefile The file descriptor to write to. * @param buf The buffer which contains the data. * @param nbytes The number of bytes to write. - * @param bytes_written If non-NULL, this will contain the number of bytes written. - * @remark apr_file_write will write up to the specified number of bytes, but never - * more. If the OS cannot write that many bytes, the process/thread - * will block until they can be written. Exceptional error such as - * "out of space" or "pipe closed" will terminate with an error. + * @param bytes_written If non-NULL, set to the number of bytes written. + * + * @remark apr_file_write will write up to the specified number of + * bytes, but never more. If the OS cannot write that many bytes, the + * process/thread will block until they can be written. Exceptional + * error such as "out of space" or "pipe closed" will terminate with + * an error. * - * It is possible for both bytes to be written and an error to be - * returned. And if *bytes_written is less than nbytes, an - * accompanying error is _always_ returned. + * @remark It is possible for both bytes to be written and an error to + * be returned. And if *bytes_written is less than nbytes, an + * accompanying error is _always_ returned. * - * APR_EINTR is never returned. + * @remark APR_EINTR is never returned. */ -APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, const void *buf, - apr_size_t nbytes, - apr_size_t *bytes_written); +APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, + const void *buf, + apr_size_t nbytes, + apr_size_t *bytes_written); /** - * put a character into the specified file. + * Write a character into the specified file. * @param ch The character to write. * @param thefile The file descriptor to write to */ APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile); /** - * get a character from the specified file. + * Read a character from the specified file. * @param ch The character to read into * @param thefile The file descriptor to read from */ APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile); /** - * put a character back onto a specified stream. + * Put a character back onto a specified stream. * @param ch The character to write. * @param thefile The file descriptor to write to */ APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile); /** - * Get a string from a specified file. + * Read a string from the specified file. * @param str The buffer to store the string in. * @param len The length of the string * @param thefile The file descriptor to read from * @remark The buffer will be NUL-terminated if any characters are stored. */ -APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, apr_file_t *thefile); +APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, + apr_file_t *thefile); /** - * Put the string into a specified file. + * Write the string into the specified file. * @param str The string to write. * @param thefile The file descriptor to write to */ @@ -447,30 +438,30 @@ APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile); /** - * duplicate the specified file descriptor. + * Duplicate the specified file descriptor. * @param new_file The structure to duplicate into. * @param old_file The file to duplicate. * @param p The pool to use for the new file. - * @remark *new_file must point to a valid apr_file_t, or point to NULL + * @remark *new_file must point to a valid apr_file_t, or point to NULL. */ APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file, - apr_file_t *old_file, - apr_pool_t *p); + apr_file_t *old_file, + apr_pool_t *p); /** - * duplicate the specified file descriptor and close the original + * Duplicate the specified file descriptor and close the original * @param new_file The old file that is to be closed and reused * @param old_file The file to duplicate * @param p The pool to use for the new file * - * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL + * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL. */ APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file, apr_file_t *old_file, apr_pool_t *p); /** - * move the specified file descriptor to a new pool + * Move the specified file descriptor to a new pool * @param new_file Pointer in which to return the new apr_file_t * @param old_file The file to move * @param p The pool to which the descriptor is to be moved @@ -507,7 +498,8 @@ * @param out The file descriptor to use as output from the pipe. * @param pool The pool to operate on. */ -APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, apr_file_t **out, +APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, + apr_file_t **out, apr_pool_t *pool); /** @@ -517,8 +509,8 @@ * @param pool The pool to operate on. */ APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename, - apr_fileperms_t perm, - apr_pool_t *pool); + apr_fileperms_t perm, + apr_pool_t *pool); /** * Get the timeout value for a pipe or manipulate the blocking state. @@ -535,7 +527,7 @@ * forever, 0 means do not wait at all. */ APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe, - apr_interval_time_t timeout); + apr_interval_time_t timeout); /** file (un)locking functions. */ @@ -564,8 +556,8 @@ * @param thefile The currently open file. */ APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path, - apr_file_t *thefile); - + apr_file_t *thefile); + /** * Return the data associated with the current file. * @param data The user data associated with the file. @@ -573,7 +565,7 @@ * @param file The currently open file. */ APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key, - apr_file_t *file); + apr_file_t *file); /** * Set the data associated with the current file. @@ -583,8 +575,8 @@ * @param cleanup The cleanup routine to use when the file is destroyed. */ APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data, - const char *key, - apr_status_t (*cleanup)(void *)); + const char *key, + apr_status_t (*cleanup)(void *)); /** * Write a string to a file using a printf format. @@ -601,14 +593,16 @@ * set the specified file's permission bits. * @param fname The file (name) to apply the permissions to. * @param perms The permission bits to apply to the file. - * @warning Some platforms may not be able to apply all of the available - * permission bits; APR_INCOMPLETE will be returned if some permissions - * are specified which could not be set. * - * Platforms which do not implement this feature will return APR_ENOTIMPL. + * @warning Some platforms may not be able to apply all of the + * available permission bits; APR_INCOMPLETE will be returned if some + * permissions are specified which could not be set. + * + * @warning Platforms which do not implement this feature will return + * APR_ENOTIMPL. */ APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname, - apr_fileperms_t perms); + apr_fileperms_t perms); /** * Set attributes of the specified file. @@ -647,7 +641,7 @@ /** * Create a new directory on the file system. - * @param path the path for the directory to be created. (use / on all systems) + * @param path the path for the directory to be created. (use / on all systems) * @param perm Permissions for the new direcoty. * @param pool the pool to use. */ @@ -657,7 +651,7 @@ /** Creates a new directory on the file system, but behaves like * 'mkdir -p'. Creates intermediate directories as required. No error * will be reported if PATH already exists. - * @param path the path for the directory to be created. (use / on all systems) + * @param path the path for the directory to be created. (use / on all systems) * @param perm Permissions for the new direcoty. * @param pool the pool to use. */ @@ -667,7 +661,7 @@ /** * Remove directory from the file system. - * @param path the path for the directory to be removed. (use / on all systems) + * @param path the path for the directory to be removed. (use / on all systems) * @param pool the pool to use. */ APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool); @@ -679,9 +673,9 @@ * @param thefile The file to get information about. */ APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo, - apr_int32_t wanted, - apr_file_t *thefile); - + apr_int32_t wanted, + apr_file_t *thefile); + /** * Truncate the file's length to the specified offset