docs: better explain multi-part byte range behavior

- Better explain that if the requested range (--range or CURLOPT_RANGE)
  contains multiple ranges then the response contains meta information
  in addition to the requested bytes.

Prior to this change it was noted that a multiple part response was
returned as-is but not what that meant. In particular, meta information
is returned in addition to the requested bytes and that may have been
unexpected.

Reported-by: Ralf A. Timmermann
Fixes https://github.com/curl/curl/issues/16139
Closes https://github.com/curl/curl/pull/16150

diff --git a/docs/cmdline-opts/range.md b/docs/cmdline-opts/range.md
index 306998cd30c73634ece0e51bddb98b4573ff5f34..fcd4fe3bdf75ba83335d66429859703946fc87d4 100644 (file)
--- a/docs/cmdline-opts/range.md
+++ b/docs/cmdline-opts/range.md
@@ -41,9 +41,10 @@ specifies two separate 100-byte ranges(*) (HTTP)
 
 ##
 
-(*) = NOTE that these make the server reply with a multipart response, which
-is returned as-is by curl. Parsing or otherwise transforming this response is
-the responsibility of the caller.
+(*) = NOTE that if specifying multiple ranges and the server supports it then
+it replies with a multiple part response that curl returns as-is. It
+contains meta information in addition to the requested bytes. Parsing or
+otherwise transforming this response is the responsibility of the caller.
 
 Only digit characters (0-9) are valid in the 'start' and 'stop' fields of the
 'start-stop' range syntax. If a non-digit character is given in the range, the

diff --git a/docs/libcurl/opts/CURLOPT_RANGE.md b/docs/libcurl/opts/CURLOPT_RANGE.md
index c95916fb303ff8807853aec36c908e27211c4a55..389ea60a3857b3c958644ead4b11ffea51151df9 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_RANGE.md
+++ b/docs/libcurl/opts/CURLOPT_RANGE.md
@@ -39,9 +39,13 @@ left out and X and Y are byte indexes.
 HTTP transfers also support several intervals, separated with commas as in
 *"X-Y,N-M"*. Using this kind of multiple intervals causes the HTTP server
 to send the response document in pieces (using standard MIME separation
-techniques). Unfortunately, the HTTP standard (RFC 7233 section 3.1) allows
-servers to ignore range requests so even when you set CURLOPT_RANGE(3)
-for a request, you may end up getting the full response sent back.
+techniques) as a multiple part response which libcurl returns as-is. It
+contains meta information in addition to the requested bytes. Parsing or
+otherwise transforming this response is the responsibility of the caller.
+
+Unfortunately, the HTTP standard (RFC 7233 section 3.1) allows servers to
+ignore range requests so even when you set CURLOPT_RANGE(3) for a request, you
+may end up getting the full response sent back.
 
 For RTSP, the formatting of a range should follow RFC 2326 Section 12.29. For
 RTSP, byte ranges are **not** permitted. Instead, ranges should be given in