curl/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3

.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2014, 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 http://curl.haxx.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.
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_WRITEFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_WRITEFUNCTION \- set 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, as the prototype shows above.

This callback function gets called by libcurl as soon as there is data
received that needs to be saved.  \fIptr\fP points to the delivered data, and
the size of that data is \fIsize\fP multiplied with \fInmemb\fP.

The received data will not be zero terminated!

Return the number of bytes actually taken care of. If that amount differs from
the amount passed to your callback function, it'll signal an error condition
to the library. This will cause the transfer to get aborted and return
\fICURLE_WRITE_ERROR\fP.

The callback function can return CURL_WRITEFUNC_PAUSE which then will cause
writing to this connection to become paused. See \fIcurl_easy_pause(3)\fP for
further details.

This function may be called with zero bytes data if the transferred file is
empty.

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.

Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option.

The callback function will be passed as much data as possible in all invokes,
but you cannot possibly make any assumptions. It may be one byte, it may be
thousands. The maximum amount of body data that can be passed to the write
callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE (the usual
default is 16K). If you however have \fICURLOPT_HEADER(3)\fP set, which sends
header data 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.
.SH DEFAULT
libcurl will use 'fwrite' as a callback by default.
.SH PROTOCOLS
For all protocols
.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 EXAMPLE
A common technique is to use this callback to store the incoming data into a
dynamically growing allocated buffer. Like in the getinmemory example:
http://curl.haxx.se/libcurl/c/getinmemory.html
.SH "SEE ALSO"
.BR CURLOPT_WRITEDATA "(3), " CURLOPT_READFUNCTION "(3), "