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