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