Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3, revision 1.1.1.1
1.1 misho 1: .\" **************************************************************************
2: .\" * _ _ ____ _
3: .\" * Project ___| | | | _ \| |
4: .\" * / __| | | | |_) | |
5: .\" * | (__| |_| | _ <| |___
6: .\" * \___|\___/|_| \_\_____|
7: .\" *
8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
9: .\" *
10: .\" * This software is licensed as described in the file COPYING, which
11: .\" * you should have received as part of this distribution. The terms
12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
13: .\" *
14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
15: .\" * copies of the Software, and permit persons to whom the Software is
16: .\" * furnished to do so, under the terms of the COPYING file.
17: .\" *
18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19: .\" * KIND, either express or implied.
20: .\" *
21: .\" **************************************************************************
22: .\"
23: .TH CURLOPT_WRITEFUNCTION 3 "April 06, 2020" "libcurl 7.70.0" "curl_easy_setopt options"
24:
25: .SH NAME
26: CURLOPT_WRITEFUNCTION \- set callback for writing received data
27: .SH SYNOPSIS
28: .nf
29: #include <curl/curl.h>
30:
31: size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);
32:
33: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback);
34: .SH DESCRIPTION
35: Pass a pointer to your callback function, which should match the prototype
36: shown above.
37:
38: This callback function gets called by libcurl as soon as there is data
39: received that needs to be saved. For most transfers, this callback gets called
40: many times and each invoke delivers another chunk of data. \fIptr\fP points to
41: the delivered data, and the size of that data is \fInmemb\fP; \fIsize\fP is
42: always 1.
43:
44: The callback function will be passed as much data as possible in all invokes,
45: but you must not make any assumptions. It may be one byte, it may be
46: thousands. The maximum amount of body data that will be passed to the write
47: callback is defined in the curl.h header file: \fICURL_MAX_WRITE_SIZE\fP (the
48: usual default is 16K). If \fICURLOPT_HEADER(3)\fP is enabled, which makes
49: header data get passed to the write callback, you can get up to
50: \fICURL_MAX_HTTP_HEADER\fP bytes of header data passed into it. This usually
51: means 100K.
52:
53: This function may be called with zero bytes data if the transferred file is
54: empty.
55:
56: The data passed to this function will not be zero terminated!
57:
58: Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option.
59:
60: Your callback should return the number of bytes actually taken care of. If
61: that amount differs from the amount passed to your callback function, it'll
62: signal an error condition to the library. This will cause the transfer to get
63: aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP.
64:
65: If your callback function returns CURL_WRITEFUNC_PAUSE it will cause this
66: transfer to become paused. See \fIcurl_easy_pause(3)\fP for further details.
67:
68: Set this option to NULL to get the internal default function used instead of
69: your callback. The internal default function will write the data to the FILE *
70: given with \fICURLOPT_WRITEDATA(3)\fP.
71: .SH DEFAULT
72: libcurl will use 'fwrite' as a callback by default.
73: .SH PROTOCOLS
74: For all protocols
75: .SH AVAILABILITY
76: Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
77: .SH RETURN VALUE
78: This will return CURLE_OK.
79: .SH EXAMPLE
80: .NF
81: struct memory {
82: char *response;
83: size_t size;
84: };
85:
86: static size_t cb(void *data, size_t size, size_t nmemb, void *userp)
87: {
88: size_t realsize = size * nmemb;
89: struct memory *mem = (struct memory *)userp;
90:
91: char *ptr = realloc(mem->response, mem->size + realsize + 1);
92: if(ptr == NULL)
93: return 0; /* out of memory! */
94:
95: mem->response = ptr;
96: memcpy(&(mem->response[mem->size]), data, realsize);
97: mem->size += realsize;
98: mem->response[mem->size] = 0;
99:
100: return realsize;
101: }
102:
103: struct memory chunk;
104:
105: /* send all data to this function */
106: curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, cb);
107:
108: /* we pass our 'chunk' struct to the callback function */
109: curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)&chunk);
110: .FI
111: .SH "SEE ALSO"
112: .BR CURLOPT_WRITEDATA "(3), " CURLOPT_READFUNCTION "(3), "
113: .BR CURLOPT_HEADERFUNCTION "(3), "
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>