Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

CURLOPT_READFUNCTION documentation return value confuses bytes with objects #10328

Closed
briangreenery opened this issue Jan 20, 2023 · 6 comments
Closed

CURLOPT_READFUNCTION documentation return value confuses bytes with objects #10328

briangreenery opened this issue Jan 20, 2023 · 6 comments
Labels
documentation

Comments

@briangreenery
Copy link

briangreenery commented Jan 20, 2023 •
edited

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
Copy link
Author

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
Copy link
Member

jay commented Jan 21, 2023

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
Copy link
Member

bagder commented Jan 28, 2023

Agreed. Adding this to the docs would be good.

bagder added a commit that referenced this issue Jan 28, 2023
@bagder
CURLOPT_READFUNCTION.3: the callback 'size' arg is always 1
c336515 
Reported-by: Brian Green
Fixes #10328
@bagder bagder mentioned this issue Jan 28, 2023
Closed
@bagder bagder closed this as completed in ee51f58 Jan 29, 2023
@briangreenery
Copy link
Author

Thank you!

bch pushed a commit to bch/curl that referenced this issue Jul 19, 2023
@bagder @bch
CURLOPT_READFUNCTION.3: the callback 'size' arg is always 1
674ca6d 
Reported-by: Brian Green
Fixes curl#10328
Closes curl#10355
@thcrt
Copy link

thcrt commented Dec 13, 2023

@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
Copy link
Contributor

dfandrich commented Dec 13, 2023 via email •
edited

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

CURLOPT_READFUNCTION.3: the callback 'size' arg is always 1 curl/curl
5 participants
@bagder @dfandrich @briangreenery @jay @thcrt