From: blankie <blankie@nixnetmail.com>
Date: Mon, 15 Apr 2024 09:35:14 +0000 (+1000)
Subject: docs: clarify CURLOPT_MAXFILESIZE and CURLOPT_MAXFILESIZE_LARGE
X-Git-Tag: curl-8_8_0~230
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e1f1ec028a110a50bb6c390cc0d64605b630e37a;p=thirdparty%2Fcurl.git

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 36159709a1..14f95f8cb8 100644
--- 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 d11a56225f..9ace0d6eca 100644
--- 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.