123 lines
4.6 KiB
Groff
123 lines
4.6 KiB
Groff
|
.\" **************************************************************************
|
||
|
|
.\" * _ _ ____ _
|
||
|
|
.\" * Project ___| | | | _ \| |
|
||
|
|
.\" * / __| | | | |_) | |
|
||
|
|
.\" * | (__| |_| | _ <| |___
|
||
|
|
.\" * \___|\___/|_| \_\_____|
|
||
|
|
.\" *
|
||
|
|
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
||
|
|
.\" *
|
||
|
|
.\" * This software is licensed as described in the file COPYING, which
|
||
|
|
.\" * you should have received as part of this distribution. The terms
|
||
|
|
.\" * are also available at https://curl.se/docs/copyright.html.
|
||
|
|
.\" *
|
||
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
||
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
||
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
||
|
|
.\" *
|
||
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
||
|
|
.\" * KIND, either express or implied.
|
||
|
|
.\" *
|
||
|
|
.\" * SPDX-License-Identifier: curl
|
||
|
|
.\" *
|
||
|
|
.\" **************************************************************************
|
||
|
|
.\"
|
||
|
|
.TH CURLOPT_READFUNCTION 3 "25 Jun 2020" libcurl 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
|
||
|
|
The default internal read callback is fread().
|
||
|
|
.SH PROTOCOLS
|
||
|
|
This is used for all protocols when doing uploads.
|
||
|
|
.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;
|
||
|
|
}
|
||
|
|
|
||
|
|
void setup(char *uploadthis)
|
||
|
|
{
|
||
|
|
FILE *file = fopen(uploadthis, "rb");
|
||
|
|
CURLcode result;
|
||
|
|
|
||
|
|
/* 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 AVAILABILITY
|
||
|
|
CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT
|
||
|
|
was added in 7.12.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)
|