mirror of
https://github.com/curl/curl.git
synced 2024-12-15 06:40:09 +08:00
6d75115406
Prior to this change if the user wanted to signal an error from their write callbacks they would have to use logic to return a value different from the number of bytes (nmemb) passed to the callback. Also, the inclination of some users has been to just return 0 to signal error, which is incorrect as that may be the number of bytes passed to the callback. To remedy this the user can now return CURL_WRITEFUNC_ERROR instead. Ref: https://github.com/curl/curl/issues/9873 Closes https://github.com/curl/curl/pull/9874
120 lines
4.5 KiB
Groff
120 lines
4.5 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) 1998 - 2022, Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
.\" *
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
.\" * you should have received as part of this distribution. The terms
|
|
.\" * are also available at https://curl.se/docs/copyright.html.
|
|
.\" *
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
.\" *
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
.\" * KIND, either express or implied.
|
|
.\" *
|
|
.\" * SPDX-License-Identifier: curl
|
|
.\" *
|
|
.\" **************************************************************************
|
|
.\"
|
|
.TH CURLOPT_WRITEFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
|
|
.SH NAME
|
|
CURLOPT_WRITEFUNCTION \- callback for writing received data
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <curl/curl.h>
|
|
|
|
size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);
|
|
|
|
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback);
|
|
.SH DESCRIPTION
|
|
Pass a pointer to your callback function, which should match the prototype
|
|
shown above.
|
|
|
|
This callback function gets called by libcurl as soon as there is data
|
|
received that needs to be saved. For most transfers, this callback gets called
|
|
many times and each invoke delivers another chunk of data. \fIptr\fP points to
|
|
the delivered data, and the size of that data is \fInmemb\fP; \fIsize\fP is
|
|
always 1.
|
|
|
|
The callback function will be passed as much data as possible in all invokes,
|
|
but you must not make any assumptions. It may be one byte, it may be
|
|
thousands. The maximum amount of body data that will be passed to the write
|
|
callback is defined in the curl.h header file: \fICURL_MAX_WRITE_SIZE\fP (the
|
|
usual default is 16K). If \fICURLOPT_HEADER(3)\fP is enabled, which makes
|
|
header data get passed to the write callback, you can get up to
|
|
\fICURL_MAX_HTTP_HEADER\fP bytes of header data passed into it. This usually
|
|
means 100K.
|
|
|
|
This function may be called with zero bytes data if the transferred file is
|
|
empty.
|
|
|
|
The data passed to this function will not be null-terminated!
|
|
|
|
Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option.
|
|
|
|
Your callback should return the number of bytes actually taken care of. If
|
|
that amount differs from the amount passed to your callback function, it will
|
|
signal an error condition to the library. This will cause the transfer to get
|
|
aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP.
|
|
|
|
You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0)
|
|
|
|
If your callback function returns CURL_WRITEFUNC_PAUSE it will cause this
|
|
transfer to become paused. See \fIcurl_easy_pause(3)\fP for further details.
|
|
|
|
Set this option to NULL to get the internal default function used instead of
|
|
your callback. The internal default function will write the data to the FILE *
|
|
given with \fICURLOPT_WRITEDATA(3)\fP.
|
|
|
|
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
|
|
do that.
|
|
.SH DEFAULT
|
|
libcurl will use 'fwrite' as a callback by default.
|
|
.SH PROTOCOLS
|
|
For all protocols
|
|
.SH EXAMPLE
|
|
.nf
|
|
struct memory {
|
|
char *response;
|
|
size_t size;
|
|
};
|
|
|
|
static size_t cb(void *data, size_t size, size_t nmemb, void *userp)
|
|
{
|
|
size_t realsize = size * nmemb;
|
|
struct memory *mem = (struct memory *)userp;
|
|
|
|
char *ptr = realloc(mem->response, mem->size + realsize + 1);
|
|
if(ptr == NULL)
|
|
return 0; /* out of memory! */
|
|
|
|
mem->response = ptr;
|
|
memcpy(&(mem->response[mem->size]), data, realsize);
|
|
mem->size += realsize;
|
|
mem->response[mem->size] = 0;
|
|
|
|
return realsize;
|
|
}
|
|
|
|
struct memory chunk = {0};
|
|
|
|
/* send all data to this function */
|
|
curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, cb);
|
|
|
|
/* we pass our 'chunk' struct to the callback function */
|
|
curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)&chunk);
|
|
.fi
|
|
.SH AVAILABILITY
|
|
Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
|
|
.SH RETURN VALUE
|
|
This will return CURLE_OK.
|
|
.SH "SEE ALSO"
|
|
.BR CURLOPT_WRITEDATA "(3), " CURLOPT_READFUNCTION "(3), "
|
|
.BR CURLOPT_HEADERFUNCTION "(3), "
|