1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_WRITEFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_HEADERFUNCTION (3)
9  - CURLOPT_READFUNCTION (3)
10  - CURLOPT_WRITEDATA (3)
11Protocol:
12  - All
13---
14
15# NAME
16
17CURLOPT_WRITEFUNCTION - callback for writing received data
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);
25
26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback);
27~~~
28
29# DESCRIPTION
30
31Pass a pointer to your callback function, which should match the prototype
32shown above.
33
34This callback function gets called by libcurl as soon as there is data
35received that needs to be saved. For most transfers, this callback gets called
36many times and each invoke delivers another chunk of data. *ptr* points to the
37delivered data, and the size of that data is *nmemb*; *size* is always 1.
38
39The data passed to this function is not null-terminated.
40
41The callback function is passed as much data as possible in all invokes, but
42you must not make any assumptions. It may be one byte, it may be
43thousands. The maximum amount of body data that is passed to the write
44callback is defined in the curl.h header file: *CURL_MAX_WRITE_SIZE* (the
45usual default is 16K). If CURLOPT_HEADER(3) is enabled, which makes header
46data get passed to the write callback, you can get up to
47*CURL_MAX_HTTP_HEADER* bytes of header data passed into it. This usually means
48100K.
49
50This function may be called with zero bytes data if the transferred file is
51empty.
52
53Set the *userdata* argument with the CURLOPT_WRITEDATA(3) option.
54
55Your callback should return the number of bytes actually taken care of. If
56that amount differs from the amount passed to your callback function, it
57signals an error condition to the library. This causes the transfer to get
58aborted and the libcurl function used returns *CURLE_WRITE_ERROR*.
59
60You can also abort the transfer by returning CURL_WRITEFUNC_ERROR (added in
617.87.0), which makes *CURLE_WRITE_ERROR* get returned.
62
63If the callback function returns CURL_WRITEFUNC_PAUSE it pauses this
64transfer. See curl_easy_pause(3) for further details.
65
66Set this option to NULL to get the internal default function used instead of
67your callback. The internal default function writes the data to the FILE *
68given with CURLOPT_WRITEDATA(3).
69
70This option does not enable HSTS, you need to use CURLOPT_HSTS_CTRL(3) to
71do that.
72
73# DEFAULT
74
75libcurl uses 'fwrite' as a callback by default.
76
77# EXAMPLE
78
79~~~c
80#include <stdlib.h> /* for realloc */
81#include <string.h> /* for memcpy */
82
83struct memory {
84  char *response;
85  size_t size;
86};
87
88static size_t cb(void *data, size_t size, size_t nmemb, void *clientp)
89{
90  size_t realsize = size * nmemb;
91  struct memory *mem = (struct memory *)clientp;
92
93  char *ptr = realloc(mem->response, mem->size + realsize + 1);
94  if(!ptr)
95    return 0;  /* out of memory! */
96
97  mem->response = ptr;
98  memcpy(&(mem->response[mem->size]), data, realsize);
99  mem->size += realsize;
100  mem->response[mem->size] = 0;
101
102  return realsize;
103}
104
105int main(void)
106{
107  struct memory chunk = {0};
108  CURLcode res;
109  CURL *curl = curl_easy_init();
110  if(curl) {
111    /* send all data to this function  */
112    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, cb);
113
114    /* we pass our 'chunk' struct to the callback function */
115    curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);
116
117    /* send a request */
118    res = curl_easy_perform(curl);
119
120    /* remember to free the buffer */
121    free(chunk.response);
122
123    curl_easy_cleanup(curl);
124  }
125}
126~~~
127
128# AVAILABILITY
129
130Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
131
132# RETURN VALUE
133
134This returns CURLE_OK.
135