Return to CURLOPT_READFUNCTION.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl / opts

Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_READFUNCTION.3, revision 1.1.1.1

1.1       misho       1: .\" **************************************************************************
                      2: .\" *                                  _   _ ____  _
                      3: .\" *  Project                     ___| | | |  _ \| |
                      4: .\" *                             / __| | | | |_) | |
                      5: .\" *                            | (__| |_| |  _ <| |___
                      6: .\" *                             \___|\___/|_| \_\_____|
                      7: .\" *
                      8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
                      9: .\" *
                     10: .\" * This software is licensed as described in the file COPYING, which
                     11: .\" * you should have received as part of this distribution. The terms
                     12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
                     13: .\" *
                     14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
                     15: .\" * copies of the Software, and permit persons to whom the Software is
                     16: .\" * furnished to do so, under the terms of the COPYING file.
                     17: .\" *
                     18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
                     19: .\" * KIND, either express or implied.
                     20: .\" *
                     21: .\" **************************************************************************
                     22: .\"
                     23: .TH CURLOPT_READFUNCTION 3 "March 23, 2020" "libcurl 7.70.0" "curl_easy_setopt options"
                     24: 
                     25: .SH NAME
                     26: CURLOPT_READFUNCTION \- read callback for data uploads
                     27: .SH SYNOPSIS
                     28: #include <curl/curl.h>
                     29: 
                     30: size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata);
                     31: 
                     32: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback);
                     33: 
                     34: .SH DESCRIPTION
                     35: Pass a pointer to your callback function, as the prototype shows above.
                     36: 
                     37: This callback function gets called by libcurl as soon as it needs to read data
                     38: in order to send it to the peer - like if you ask it to upload or post data to
                     39: the server. The data area pointed at by the pointer \fIbuffer\fP should be
                     40: filled up with at most \fIsize\fP multiplied with \fInitems\fP number of bytes
                     41: by your function.
                     42: 
                     43: Set the \fIuserdata\fP argument with the \fICURLOPT_READDATA(3)\fP option.
                     44: 
                     45: Your function must return the actual number of bytes that it stored in the data
                     46: area pointed at by the pointer \fIbuffer\fP. Returning 0 will signal
                     47: end-of-file to the library and cause it to stop the current transfer.
                     48: 
                     49: If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
                     50: server expected it, like when you've said you will upload N bytes and you
                     51: upload less than N bytes), you may experience that the server "hangs" waiting
                     52: for the rest of the data that won't come.
                     53: 
                     54: The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
                     55: operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
                     56: code from the transfer.
                     57: 
                     58: The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
                     59: connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
                     60: 
                     61: \fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data
                     62: that the callback wants, or it will be considered the final packet by the
                     63: server end and the transfer will end there.
                     64: 
                     65: If you set this callback pointer to NULL, or don't set it at all, the default
                     66: internal read function will be used. It is doing an fread() on the FILE *
                     67: userdata set with \fICURLOPT_READDATA(3)\fP.
                     68: .SH DEFAULT
                     69: The default internal read callback is fread().
                     70: .SH PROTOCOLS
                     71: This is used for all protocols when doing uploads.
                     72: .SH EXAMPLE
                     73: .nf
                     74: size_t read_callback(void *ptr, size_t size, size_t nmemb, void *userdata)
                     75: {
                     76:   FILE *readhere = (FILE *)userdata;
                     77:   curl_off_t nread;
                     78: 
                     79:   /* copy as much data as possible into the 'ptr' buffer, but no more than
                     80:      'size' * 'nmemb' bytes! */
                     81:   size_t retcode = fread(ptr, size, nmemb, readhere);
                     82: 
                     83:   nread = (curl_off_t)retcode;
                     84: 
                     85:   fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T
                     86:           " bytes from file\\n", nread);
                     87:   return retcode;
                     88: }
                     89: 
                     90: void setup(char *uploadthis)
                     91: {
                     92:   FILE *file = fopen(uploadthis, "rb");
                     93:   CURLcode result;
                     94: 
                     95:   /* set callback to use */
                     96:   curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
                     97: 
                     98:   /* pass in suitable argument to callback */
                     99:   curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file);
                    100: 
                    101:   result = curl_easy_perform(curl);
                    102: }
                    103: .fi
                    104: .SH AVAILABILITY
                    105: CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT
                    106: was added in 7.12.1.
                    107: .SH RETURN VALUE
                    108: This will return CURLE_OK.
                    109: .SH "SEE ALSO"
                    110: .BR CURLOPT_READDATA "(3), " CURLOPT_WRITEFUNCTION "(3), "
                    111: .BR CURLOPT_SEEKFUNCTION "(3), " CURLOPT_UPLOAD "(3), " CURLOPT_POST "(3), "
                    112: .BR CURLOPT_UPLOAD_BUFFERSIZE "(3), "