1
0
mirror of https://github.com/moparisthebest/curl synced 2024-11-14 21:45:13 -05:00

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
This commit is contained in:
Jay Satiro 2019-12-26 02:26:08 -05:00
parent 68da0b8b86
commit 97934a2f71

View File

@ -39,9 +39,9 @@ shown above.
This function gets called by libcurl as soon as it has received header 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 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 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 easy using this. \fIbuffer\fP points to the delivered data, and the size of
multiplied with \fInitems\fP. Do not assume that the header line is zero that data is \fInitems\fP; \fIsize\fP is always 1. Do not assume that the
terminated! header line is zero terminated!
The pointer named \fIuserdata\fP is the one you set with the The pointer named \fIuserdata\fP is the one you set with the
\fICURLOPT_HEADERDATA(3)\fP option. \fICURLOPT_HEADERDATA(3)\fP option.