1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_READFUNCTION 5Section: 3 6Source: libcurl 7See-also: 8 - CURLOPT_POST (3) 9 - CURLOPT_READDATA (3) 10 - CURLOPT_SEEKFUNCTION (3) 11 - CURLOPT_UPLOAD (3) 12 - CURLOPT_UPLOAD_BUFFERSIZE (3) 13 - CURLOPT_WRITEFUNCTION (3) 14Protocol: 15 - All 16--- 17 18# NAME 19 20CURLOPT_READFUNCTION - read callback for data uploads 21 22# SYNOPSIS 23 24~~~c 25#include <curl/curl.h> 26 27size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata); 28 29CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback); 30~~~ 31 32# DESCRIPTION 33 34Pass a pointer to your callback function, as the prototype shows above. 35 36This callback function gets called by libcurl as soon as it needs to read data 37in order to send it to the peer - like if you ask it to upload or post data to 38the server. The data area pointed at by the pointer *buffer* should be 39filled up with at most *size* multiplied with *nitems* number of bytes 40by your function. *size* is always 1. 41 42Set the *userdata* argument with the CURLOPT_READDATA(3) option. 43 44Your function must return the actual number of bytes that it stored in the 45data area pointed at by the pointer *buffer*. Returning 0 signals 46end-of-file to the library and causes it to stop the current transfer. 47 48If you stop the current transfer by returning 0 "pre-maturely" (i.e before the 49server expected it, like when you have said you would upload N bytes and you 50upload less than N bytes), you may experience that the server "hangs" waiting 51for the rest of the data that is not sent. 52 53The read callback may return *CURL_READFUNC_ABORT* to stop the current 54operation immediately, resulting in a *CURLE_ABORTED_BY_CALLBACK* error 55code from the transfer. 56 57The callback can return *CURL_READFUNC_PAUSE* to cause reading from this 58connection to pause. See curl_easy_pause(3) for further details. 59 60**Bugs**: when doing TFTP uploads, you must return the exact amount of data 61that the callback wants, or it is considered the final packet by the server 62end and the transfer ends there. 63 64If you set this callback pointer to NULL, or do not set it at all, the default 65internal read function is used. It is doing an fread() on the FILE * userdata 66set with CURLOPT_READDATA(3). 67 68You can set the total size of the data you are sending by using 69CURLOPT_INFILESIZE_LARGE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3), 70depending on the type of transfer. For some transfer types it may be required 71and it allows for better error checking. 72 73# DEFAULT 74 75The default internal read callback is fread(). 76 77# EXAMPLE 78 79~~~c 80size_t read_callback(char *ptr, size_t size, size_t nmemb, void *userdata) 81{ 82 FILE *readhere = (FILE *)userdata; 83 curl_off_t nread; 84 85 /* copy as much data as possible into the 'ptr' buffer, but no more than 86 'size' * 'nmemb' bytes! */ 87 size_t retcode = fread(ptr, size, nmemb, readhere); 88 89 nread = (curl_off_t)retcode; 90 91 fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T 92 " bytes from file\n", nread); 93 return retcode; 94} 95 96int main(int argc, char **argv) 97{ 98 FILE *file = fopen(argv[1], "rb"); 99 CURLcode result; 100 101 CURL *curl = curl_easy_init(); 102 if(curl) { 103 /* set callback to use */ 104 curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback); 105 106 /* pass in suitable argument to callback */ 107 curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file); 108 109 result = curl_easy_perform(curl); 110 } 111} 112~~~ 113 114# AVAILABILITY 115 116CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT 117was added in 7.12.1. 118 119# RETURN VALUE 120 121This returns CURLE_OK. 122