mirror of
https://codeberg.org/kiss-community/repo
synced 2024-12-23 07:40:11 -07:00
105 lines
3.6 KiB
Groff
105 lines
3.6 KiB
Groff
.\" generated by cd2nroff 0.1 from CURLOPT_READFUNCTION.md
|
|
.TH CURLOPT_READFUNCTION 3 "2024-08-02" libcurl
|
|
.SH NAME
|
|
CURLOPT_READFUNCTION \- read callback for data uploads
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <curl/curl.h>
|
|
|
|
size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata);
|
|
|
|
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
Pass a pointer to your callback function, as the prototype shows above.
|
|
|
|
This callback function gets called by libcurl as soon as it needs to read data
|
|
in order to send it to the peer \- like if you ask it to upload or post data to
|
|
the server. The data area pointed at by the pointer \fIbuffer\fP should be
|
|
filled up with at most \fIsize\fP multiplied with \fInitems\fP number of bytes
|
|
by your function. \fIsize\fP is always 1.
|
|
|
|
Set the \fIuserdata\fP argument with the \fICURLOPT_READDATA(3)\fP option.
|
|
|
|
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 signals
|
|
end\-of\-file to the library and causes it to stop the current transfer.
|
|
|
|
If you stop the current transfer by returning 0 "pre\-maturely" (i.e before the
|
|
server expected it, like when you have said you would upload N bytes and you
|
|
upload less than N bytes), you may experience that the server "hangs" waiting
|
|
for the rest of the data that is not sent.
|
|
|
|
The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
|
|
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
|
|
code from the transfer.
|
|
|
|
The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
|
|
connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
|
|
|
|
\fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data
|
|
that the callback wants, or it is considered the final packet by the server
|
|
end and the transfer ends there.
|
|
|
|
If you set this callback pointer to NULL, or do not set it at all, the default
|
|
internal read function is used. It is doing an fread() on the FILE * userdata
|
|
set with \fICURLOPT_READDATA(3)\fP.
|
|
|
|
You can set the total size of the data you are sending by using
|
|
\fICURLOPT_INFILESIZE_LARGE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP,
|
|
depending on the type of transfer. For some transfer types it may be required
|
|
and it allows for better error checking.
|
|
.SH DEFAULT
|
|
fread(3)
|
|
.SH PROTOCOLS
|
|
This functionality affects all supported protocols
|
|
.SH EXAMPLE
|
|
.nf
|
|
size_t read_callback(char *ptr, size_t size, size_t nmemb, void *userdata)
|
|
{
|
|
FILE *readhere = (FILE *)userdata;
|
|
curl_off_t nread;
|
|
|
|
/* copy as much data as possible into the 'ptr' buffer, but no more than
|
|
'size' * 'nmemb' bytes! */
|
|
size_t retcode = fread(ptr, size, nmemb, readhere);
|
|
|
|
nread = (curl_off_t)retcode;
|
|
|
|
fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T
|
|
" bytes from file\\n", nread);
|
|
return retcode;
|
|
}
|
|
|
|
int main(int argc, char **argv)
|
|
{
|
|
FILE *file = fopen(argv[1], "rb");
|
|
CURLcode result;
|
|
|
|
CURL *curl = curl_easy_init();
|
|
if(curl) {
|
|
/* set callback to use */
|
|
curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
|
|
|
|
/* pass in suitable argument to callback */
|
|
curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file);
|
|
|
|
result = curl_easy_perform(curl);
|
|
}
|
|
}
|
|
.fi
|
|
.SH HISTORY
|
|
CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT
|
|
was added in 7.12.1.
|
|
.SH AVAILABILITY
|
|
Added in curl 7.1
|
|
.SH RETURN VALUE
|
|
This returns CURLE_OK.
|
|
.SH SEE ALSO
|
|
.BR CURLOPT_POST (3),
|
|
.BR CURLOPT_READDATA (3),
|
|
.BR CURLOPT_SEEKFUNCTION (3),
|
|
.BR CURLOPT_UPLOAD (3),
|
|
.BR CURLOPT_UPLOAD_BUFFERSIZE (3),
|
|
.BR CURLOPT_WRITEFUNCTION (3)
|