aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl
diff options
context:
space:
mode:
authorJay Satiro <raysatiro@yahoo.com>2019-12-26 02:26:08 -0500
committerJay Satiro <raysatiro@yahoo.com>2019-12-26 02:26:08 -0500
commit97934a2f7129d286bf57c90cd2394a5c48dd1fa8 (patch)
treeac11ba2bce7211ef1d1308804ba7ece831382fef /docs/libcurl
parent68da0b8b8694328b214e687a6cff5cbb744dcfd5 (diff)
CURLOPT_HEADERFUNCTION.3: Document that size is always 1
For compatibility with `fwrite`, the `CURLOPT_HEADERFUNCTION` callback is passed two `size_t` parameters which, when multiplied, designate the number of bytes of data passed in. In practice, CURL always sets the first parameter (`size`) to 1. This practice is also enshrined in documentation and cannot be changed in future. The documentation states that the default callback is `fwrite`, which means `fwrite` must be a suitable function for this purpose. However, the documentation also states that the callback must return the number of *bytes* it successfully handled, whereas ISO C `fwrite` returns the number of items (each of size `size`) which it wrote. The only way these numbers can be equal is if `size` is 1. Since `size` is 1 and can never be changed in future anyway, document that fact explicitly and let users rely on it. Reported-by: Frank Gevaerts Commit-message-by: Christopher Head Ref: https://github.com/curl/curl/pull/2787 Fixes https://github.com/curl/curl/issues/4758
Diffstat (limited to 'docs/libcurl')
-rw-r--r--docs/libcurl/opts/CURLOPT_HEADERFUNCTION.36
1 files changed, 3 insertions, 3 deletions
diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3
index 732fa1719..1cab96ebd 100644
--- a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3
@@ -39,9 +39,9 @@ shown above.
This function gets called by libcurl as soon as it has received header
data. The header callback will be called once for each header and only
complete header lines are passed on to the callback. Parsing headers is very
-easy using this. The size of the data pointed to by \fIbuffer\fP is \fIsize\fP
-multiplied with \fInitems\fP. Do not assume that the header line is zero
-terminated!
+easy using this. \fIbuffer\fP points to the delivered data, and the size of
+that data is \fInitems\fP; \fIsize\fP is always 1. Do not assume that the
+header line is zero terminated!
The pointer named \fIuserdata\fP is the one you set with the
\fICURLOPT_HEADERDATA(3)\fP option.