Merge r356615 into 0.9.x.

Original log message:

Clean up the documentation surrounding the APR_INCOMPLETE status code,

* include/apr_file_info.h
  (apr_stat, apr_dir_read): Note that APR_INCOMPLETE can be returned, and
   that if it is you can use the finfo->valid bitfield to determine which
   parts of the finfo are filled in.  Also break some overly long lines.

* include/apr_errno.h
  (APR_STATUS_IS_INCOMPLETE): Update docs since this is no longer specific
   to the xlate code.

* CHANGES: Note change.


git-svn-id: http://svn.apache.org/repos/asf/apr/apr/branches/0.9.x@372613 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 19 insertions, 4 deletions

diff --git a/CHANGES b/CHANGES
index 372ac496f..3e1c6d20b 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,5 +1,10 @@
 Changes with APR 0.9.8-dev
 
+  *) Documented that apr_stat and apr_dir_read can return APR_INCOMPLETE,
+     and how to determine which parts of the resulting apr_finfo_t can be
+     used in such a case.
+     [Garrett Rooney]
+
   *) Fix warning when compiling on FreeBSD by correcting the type of
      the final argument passed to sysctlbyname. [Garrett Rooney]
 
diff --git a/include/apr_errno.h b/include/apr_errno.h
index bf9402cba..f13de6036 100644
--- a/include/apr_errno.h
+++ b/include/apr_errno.h
@@ -462,8 +462,8 @@ APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf,
  */
 #define APR_STATUS_IS_TIMEUP(s)         ((s) == APR_TIMEUP)
 /** 
- * The character conversion stopped because of an incomplete character or 
- * shift sequence at the end  of the input buffer.
+ * The operation was incomplete although some processing was performed
+ * and the results are partially valid.
  * @warning
  * always use this test, as platform-specific variances may meet this
  * more than one error code 
diff --git a/include/apr_file_info.h b/include/apr_file_info.h
index 884a60c8a..5261d65f4 100644
--- a/include/apr_file_info.h
+++ b/include/apr_file_info.h
@@ -208,8 +208,13 @@ struct apr_finfo_t {
  * @param finfo Where to store the information about the file, which is
  * never touched if the call fails.
  * @param fname The name of the file to stat.
- * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values 
+ * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
+                 values 
  * @param cont the pool to use to allocate the new file. 
+ *
+ * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
+ *       not be filled in, and you need to check the @c finfo->valid bitmask
+ *       to verify that what you're looking for is there.
  */ 
 APR_DECLARE(apr_status_t) apr_stat(apr_finfo_t *finfo, const char *fname,
                                    apr_int32_t wanted, apr_pool_t *cont);
@@ -253,9 +258,14 @@ APR_DECLARE(apr_status_t) apr_dir_close(apr_dir_t *thedir);
 /**
  * Read the next entry from the specified directory. 
  * @param finfo the file info structure and filled in by apr_dir_read
- * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values 
+ * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
+                 values 
  * @param thedir the directory descriptor returned from apr_dir_open
  * @remark No ordering is guaranteed for the entries read.
+ *
+ * @note If @c APR_INCOMPLETE is returned all the fields in @a finfo may
+ *       not be filled in, and you need to check the @c finfo->valid bitmask
+ *       to verify that what you're looking for is there.
  */                        
 APR_DECLARE(apr_status_t) apr_dir_read(apr_finfo_t *finfo, apr_int32_t wanted,
                                        apr_dir_t *thedir);