Return to CURLOPT_WRITEFUNCTION.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl / opts

Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3, revision 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), "