CURLOPT_READFUNCTION documentation return value confuses bytes with objects

[briangreenery]

I did this

I read the documentation at https://curl.se/libcurl/c/CURLOPT_READFUNCTION.html.

I expected the following

I expected to understand if the return value should be the number of bytes read, like the return value of read, or the number of objects read, like the return value of fread.

This is confusing because the documentation is not consistent with itself.

First, it says the return value should be the the number of bytes read:

curl/docs/libcurl/opts/CURLOPT_READFUNCTION.3

Lines 47 to 49 in c12fb3d

	Your function must return the actual number of bytes that it stored in the data
	area pointed at by the pointer \fIbuffer\fP. Returning 0 will signal
	end-of-file to the library and cause it to stop the current transfer.

However the example it provides uses fread, which returns the number of objects read:

curl/docs/libcurl/opts/CURLOPT_READFUNCTION.3

Line 88 in c12fb3d

size_t retcode = fread(ptr, size, nmemb, readhere);

If the return value is indeed bytes, then it seems the example should instead be something like:

    size_t retcode = fread(ptr, 1, size*nmemb, readhere); 

Scanning through the codebase, it looks like one of those arguments is always 1, so in practice the difference might not matter. If that's the case, explicitly saying that the size argument is always 1 would also be helpful to make it less ambiguous.

[briangreenery]

I went back and forth on whether this was a bug in the documentation, or something I should discuss on the mailing list. If this is the wrong place, I can move this over to the mailing list 🙇

[jay]

Internally we always call those callbacks with an element size of 1. We have already documented this for CURLOPT_WRITEFUNCTION and I can't think of a reason why we couldn't do the same for CURLOPT_READFUNCTION.

[bagder]

Agreed. Adding this to the docs would be good.

[briangreenery]

Thank you!

[thcrt]

@bagder Sorry for necro'ing this old issue, but this is one of the only search results I could find: why is it that size is always 1? Why pass it at all then?

[dfandrich]

For compatibility with fwrite(3) and fread(3).