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