apr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jor...@apache.org
Subject cvs commit: apr/include apr_file_io.h
Date Thu, 27 May 2004 20:29:02 GMT
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:
    * <PRE>
  @@ -174,8 +174,8 @@
    * </PRE>
    * @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
  
  
  

Mime
View raw message