util_script.h: clarify ap_scan_script_header_* behavior

The ap_scan_script_header_* functions were documented to be pass/fail,
but they also have a third "state" that is returned when HTTP conditions
(If-Modified-Since, etc.) aren't met. This has led to some recent bugs,
so document it.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1760404 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/include/util_script.h b/include/util_script.h
index 3566bd38253b3a3b2322c3fd96576c6cc940fdd3..eea48fff8f6b869e7605c8b4149e6b281b5bbc5b 100644 (file)
--- a/include/util_script.h
+++ b/include/util_script.h
@@ -80,12 +80,17 @@ AP_DECLARE(void) ap_add_common_vars(request_rec *r);
 /**
  * Read headers output from a script, ensuring that the output is valid.  If
  * the output is valid, then the headers are added to the headers out of the
- * current request
+ * current request. If the request method is GET or HEAD and the script's
+ * response will not meet the request's HTTP conditions, a conditional status
+ * code is returned.
  * @param r The current request
  * @param f The file to read from
  * @param buffer Empty when calling the function.  On output, if there was an
  *               error, the string that cause the error is stored here.
- * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
+ * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
+ *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
+ *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
+ *         not meet the request's conditions
  * @fn int ap_scan_script_header_err(request_rec *r, apr_file_t *f, char *buffer)
  */
 AP_DECLARE(int) ap_scan_script_header_err(request_rec *r, apr_file_t *f, char *buffer);
@@ -93,13 +98,18 @@ AP_DECLARE(int) ap_scan_script_header_err(request_rec *r, apr_file_t *f, char *b
 /**
  * Read headers output from a script, ensuring that the output is valid.  If
  * the output is valid, then the headers are added to the headers out of the
- * current request
+ * current request. If the request method is GET or HEAD and the script's
+ * response will not meet the request's HTTP conditions, a conditional status
+ * code is returned.
  * @param r The current request
  * @param f The file to read from
  * @param buffer Empty when calling the function.  On output, if there was an
  *               error, the string that cause the error is stored here.
  * @param module_index The module index to be used for logging
- * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
+ * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
+ *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
+ *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
+ *         not meet the request's conditions
  */
 AP_DECLARE(int) ap_scan_script_header_err_ex(request_rec *r, apr_file_t *f,
                                              char *buffer, int module_index);
@@ -108,12 +118,17 @@ AP_DECLARE(int) ap_scan_script_header_err_ex(request_rec *r, apr_file_t *f,
 /**
  * Read headers output from a script, ensuring that the output is valid.  If
  * the output is valid, then the headers are added to the headers out of the
- * current request
+ * current request. If the request method is GET or HEAD and the script's
+ * response will not meet the request's HTTP conditions, a conditional status
+ * code is returned.
  * @param r The current request
  * @param bb The brigade from which to read
  * @param buffer Empty when calling the function.  On output, if there was an
  *               error, the string that cause the error is stored here.
- * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
+ * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
+ *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
+ *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
+ *         not meet the request's conditions
  * @fn int ap_scan_script_header_err_brigade(request_rec *r, apr_bucket_brigade *bb, char *buffer)
  */
 AP_DECLARE(int) ap_scan_script_header_err_brigade(request_rec *r,
@@ -123,13 +138,18 @@ AP_DECLARE(int) ap_scan_script_header_err_brigade(request_rec *r,
 /**
  * Read headers output from a script, ensuring that the output is valid.  If
  * the output is valid, then the headers are added to the headers out of the
- * current request
+ * current request. If the request method is GET or HEAD and the script's
+ * response will not meet the request's HTTP conditions, a conditional status
+ * code is returned.
  * @param r The current request
  * @param bb The brigade from which to read
  * @param buffer Empty when calling the function.  On output, if there was an
  *               error, the string that cause the error is stored here.
  * @param module_index The module index to be used for logging
- * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
+ * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
+ *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
+ *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
+ *         not meet the request's conditions
  */
 AP_DECLARE(int) ap_scan_script_header_err_brigade_ex(request_rec *r,
                                                      apr_bucket_brigade *bb,
@@ -139,7 +159,9 @@ AP_DECLARE(int) ap_scan_script_header_err_brigade_ex(request_rec *r,
 /**
  * Read headers strings from a script, ensuring that the output is valid.  If
  * the output is valid, then the headers are added to the headers out of the
- * current request
+ * current request. If the request method is GET or HEAD and the script's
+ * response will not meet the request's HTTP conditions, a conditional status
+ * code is returned.
  * @param r The current request
  * @param buffer Empty when calling the function.  On output, if there was an
  *               error, the string that cause the error is stored here.
@@ -149,7 +171,10 @@ AP_DECLARE(int) ap_scan_script_header_err_brigade_ex(request_rec *r,
  * The varargs are string arguments to parse consecutively for headers,
  * with a NULL argument to terminate the list.
  *
- * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
+ * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
+ *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
+ *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
+ *         not meet the request's conditions
  */
 AP_DECLARE_NONSTD(int) ap_scan_script_header_err_strs(request_rec *r,
                                                       char *buffer,
@@ -160,7 +185,9 @@ AP_DECLARE_NONSTD(int) ap_scan_script_header_err_strs(request_rec *r,
 /**
  * Read headers strings from a script, ensuring that the output is valid.  If
  * the output is valid, then the headers are added to the headers out of the
- * current request
+ * current request. If the request method is GET or HEAD and the script's
+ * response will not meet the request's HTTP conditions, a conditional status
+ * code is returned.
  * @param r The current request
  * @param buffer Empty when calling the function.  On output, if there was an
  *               error, the string that cause the error is stored here.
@@ -171,7 +198,10 @@ AP_DECLARE_NONSTD(int) ap_scan_script_header_err_strs(request_rec *r,
  * The varargs are string arguments to parse consecutively for headers,
  * with a NULL argument to terminate the list.
  *
- * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
+ * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
+ *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
+ *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
+ *         not meet the request's conditions
  */
 AP_DECLARE_NONSTD(int) ap_scan_script_header_err_strs_ex(request_rec *r,
                                                          char *buffer,
@@ -184,14 +214,19 @@ AP_DECLARE_NONSTD(int) ap_scan_script_header_err_strs_ex(request_rec *r,
 /**
  * Read headers output from a script, ensuring that the output is valid.  If
  * the output is valid, then the headers are added to the headers out of the
- * current request
+ * current request. If the request method is GET or HEAD and the script's
+ * response will not meet the request's HTTP conditions, a conditional status
+ * code is returned.
  * @param r The current request
  * @param buffer Empty when calling the function.  On output, if there was an
  *               error, the string that cause the error is stored here.
  * @param getsfunc Function to read the headers from.  This function should
                    act like gets()
  * @param getsfunc_data The place to read from
- * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
+ * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
+ *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
+ *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
+ *         not meet the request's conditions
  */
 AP_DECLARE(int) ap_scan_script_header_err_core(request_rec *r, char *buffer,
                                                int (*getsfunc) (char *, int, void *),
@@ -200,7 +235,9 @@ AP_DECLARE(int) ap_scan_script_header_err_core(request_rec *r, char *buffer,
 /**
  * Read headers output from a script, ensuring that the output is valid.  If
  * the output is valid, then the headers are added to the headers out of the
- * current request
+ * current request. If the request method is GET or HEAD and the script's
+ * response will not meet the request's HTTP conditions, a conditional status
+ * code is returned.
  * @param r The current request
  * @param buffer Empty when calling the function.  On output, if there was an
  *               error, the string that cause the error is stored here.
@@ -208,7 +245,10 @@ AP_DECLARE(int) ap_scan_script_header_err_core(request_rec *r, char *buffer,
                    act like gets()
  * @param getsfunc_data The place to read from
  * @param module_index The module index to be used for logging
- * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR otherwise
+ * @return HTTP_OK on success, HTTP_INTERNAL_SERVER_ERROR or other 5xx status
+ *         code on failure, or a conditional status code (HTTP_NOT_MODIFIED or
+ *         HTTP_PRECONDITION_FAILED) to indicate that the script's response does
+ *         not meet the request's conditions
  */
 AP_DECLARE(int) ap_scan_script_header_err_core_ex(request_rec *r, char *buffer,
                                         int (*getsfunc) (char *, int, void *),