CURLOPT_HEADER.3: clarify problems with different data sizes

diff --git a/docs/libcurl/opts/CURLOPT_HEADER.3 b/docs/libcurl/opts/CURLOPT_HEADER.3
index b650163d183d8e7a4d06475f7b8f3a812b20e125..76dea467e693d3ad9be8769f4aca716dd10257c8 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_HEADER.3
+++ b/docs/libcurl/opts/CURLOPT_HEADER.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -28,14 +28,20 @@ CURLOPT_HEADER \- pass headers to the data stream
 
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADER, long onoff);
 .SH DESCRIPTION
-Pass in \fIonoff\fP set to 1 to tell the library to include the header in the
-body output for requests with this \fIhandle\fP. This option is relevant for
-protocols that actually have headers or other meta-data (like HTTP and FTP).
+Pass the long value \fIonoff\fP set to 1 to ask libcurl to include the headers
+in the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP). This option is
+relevant for protocols that actually have headers or other meta-data (like
+HTTP and FTP).
 
-When asking to get the header info passed to the same callback as the body, it
-is not possible to accurately separate them again without detailed knowledge
+When asking to get the headers passed to the same callback as the body, it is
+not possible to accurately separate them again without detailed knowledge
 about the protocol in use.
 
+Further: the \fCURLOPT_WRITEFUNCTION(3)\fP callback is limited to only ever
+get a maximum of \fICURL_MAX_WRITE_SIZE\fP bytes passed to it (16KB), while a
+header can be longer and the \fICURLOPT_HEADERFUNCTION(3)\fP supports getting
+called with headers up to \fICURL_MAX_HTTP_HEADER\fP bytes big (100KB).
+
 It is often better to use \fICURLOPT_HEADERFUNCTION(3)\fP to get the header
 data separately.