You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by jc...@apache.org on 2016/09/12 16:35:24 UTC
svn commit: r1760404 - /httpd/httpd/trunk/include/util_script.h
Author: jchampion
Date: Mon Sep 12 16:35:24 2016
New Revision: 1760404
URL: http://svn.apache.org/viewvc?rev=1760404&view=rev
Log:
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.
Modified:
httpd/httpd/trunk/include/util_script.h
Modified: httpd/httpd/trunk/include/util_script.h
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/include/util_script.h?rev=1760404&r1=1760403&r2=1760404&view=diff
==============================================================================
--- httpd/httpd/trunk/include/util_script.h (original)
+++ httpd/httpd/trunk/include/util_script.h Mon Sep 12 16:35:24 2016
@@ -80,12 +80,17 @@ AP_DECLARE(void) ap_add_common_vars(requ
/**
* 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_er
/**
* 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_er
/**
* 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_er
/**
* 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_er
/**
* 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_er
* 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_he
/**
* 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_he
* 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_he
/**
* 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_er
/**
* 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_er
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 *),