docs: clarify CURLOPT_MAXFILESIZE and CURLOPT_MAXFILESIZE_LARGE

The bounds of the size parameter were not specified, and nor was it
specified how to disable the maximum file size check.

The documentation also incorrectly stated that CURLOPT_MAXFILESIZE
always returns CURLE_OK and that CURLOPT_MAXFILESIZE_LARGE only returns
CURLE_OK or CURLE_UNKNOWN_OPTION.

It also did not mention what the default value is, which is zero. This
commit updates the documentation to make note of all these things.

Closes #13372

diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md
index 36159709a1840e5533b717ed027a1ee0fc63e4eb..14f95f8cb809bbe163c488b46a64ed82502244bc 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md
+++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md
@@ -28,6 +28,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE, long size);
 Pass a long as parameter. This specifies the maximum accepted *size* (in
 bytes) of a file to download. If the file requested is found larger than this
 value, the transfer is aborted and *CURLE_FILESIZE_EXCEEDED* is returned.
+Passing a zero *size* disables this, and passing a negative *size* yields a
+*CURLE_BAD_FUNCTION_ARGUMENT*.
 
 The file size is not always known prior to the download start, and for such
 transfers this option has no effect - even if the file transfer eventually
@@ -40,7 +42,7 @@ threshold.
 
 # DEFAULT
 
-None
+0, meaning disabled.
 
 # EXAMPLE
 
@@ -64,4 +66,5 @@ Always
 
 # RETURN VALUE
 
-Returns CURLE_OK
+Returns CURLE_OK if the size passed is valid or CURLE_BAD_FUNCTION_ARGUMENT if
+not.

diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md
index d11a56225f1ca4dbf537492c5997620629cc3f0c..9ace0d6eca095f1d3572c54e18b135da88c1ae47 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md
+++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md
@@ -31,7 +31,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE_LARGE,
 Pass a curl_off_t as parameter. This specifies the maximum accepted *size*
 (in bytes) of a file to download. If the file requested is found larger than
 this value, the transfer is aborted and *CURLE_FILESIZE_EXCEEDED* is
-returned.
+returned. Passing a zero *size* disables this, and passing a negative *size*
+yields a *CURLE_BAD_FUNCTION_ARGUMENT*.
 
 The file size is not always known prior to the download start, and for such
 transfers this option has no effect - even if the file transfer eventually
@@ -42,7 +43,7 @@ threshold.
 
 # DEFAULT
 
-None
+0, meaning disabled.
 
 # EXAMPLE
 
@@ -67,4 +68,5 @@ Added in 7.11.0
 
 # RETURN VALUE
 
-Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
+CURLE_BAD_FUNCTION_ARGUMENT if the size passed is invalid.