From: Jacob Champion Date: Mon, 12 Sep 2016 16:35:24 +0000 (+0000) Subject: util_script.h: clarify ap_scan_script_header_* behavior X-Git-Tag: 2.5.0-alpha~1160 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=747e4a2f89ef50d822a3e46d930b84a08bd332aa;p=apache 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 3566bd3825..eea48fff8f 100644 --- 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 *),