Return to CURLOPT_READFUNCTION.3 CVS log

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

Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_READFUNCTION.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_READFUNCTION 3 "March 23, 2020" "libcurl 7.70.0" "curl_easy_setopt options"
        !            24: 
        !            25: .SH NAME
        !            26: CURLOPT_READFUNCTION \- read callback for data uploads
        !            27: .SH SYNOPSIS
        !            28: #include <curl/curl.h>
        !            29: 
        !            30: size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata);
        !            31: 
        !            32: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback);
        !            33: 
        !            34: .SH DESCRIPTION
        !            35: Pass a pointer to your callback function, as the prototype shows above.
        !            36: 
        !            37: This callback function gets called by libcurl as soon as it needs to read data
        !            38: in order to send it to the peer - like if you ask it to upload or post data to
        !            39: the server. The data area pointed at by the pointer \fIbuffer\fP should be
        !            40: filled up with at most \fIsize\fP multiplied with \fInitems\fP number of bytes
        !            41: by your function.
        !            42: 
        !            43: Set the \fIuserdata\fP argument with the \fICURLOPT_READDATA(3)\fP option.
        !            44: 
        !            45: Your function must return the actual number of bytes that it stored in the data
        !            46: area pointed at by the pointer \fIbuffer\fP. Returning 0 will signal
        !            47: end-of-file to the library and cause it to stop the current transfer.
        !            48: 
        !            49: If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
        !            50: server expected it, like when you've said you will upload N bytes and you
        !            51: upload less than N bytes), you may experience that the server "hangs" waiting
        !            52: for the rest of the data that won't come.
        !            53: 
        !            54: The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
        !            55: operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
        !            56: code from the transfer.
        !            57: 
        !            58: The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
        !            59: connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
        !            60: 
        !            61: \fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data
        !            62: that the callback wants, or it will be considered the final packet by the
        !            63: server end and the transfer will end there.
        !            64: 
        !            65: If you set this callback pointer to NULL, or don't set it at all, the default
        !            66: internal read function will be used. It is doing an fread() on the FILE *
        !            67: userdata set with \fICURLOPT_READDATA(3)\fP.
        !            68: .SH DEFAULT
        !            69: The default internal read callback is fread().
        !            70: .SH PROTOCOLS
        !            71: This is used for all protocols when doing uploads.
        !            72: .SH EXAMPLE
        !            73: .nf
        !            74: size_t read_callback(void *ptr, size_t size, size_t nmemb, void *userdata)
        !            75: {
        !            76:   FILE *readhere = (FILE *)userdata;
        !            77:   curl_off_t nread;
        !            78: 
        !            79:   /* copy as much data as possible into the 'ptr' buffer, but no more than
        !            80:      'size' * 'nmemb' bytes! */
        !            81:   size_t retcode = fread(ptr, size, nmemb, readhere);
        !            82: 
        !            83:   nread = (curl_off_t)retcode;
        !            84: 
        !            85:   fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T
        !            86:           " bytes from file\\n", nread);
        !            87:   return retcode;
        !            88: }
        !            89: 
        !            90: void setup(char *uploadthis)
        !            91: {
        !            92:   FILE *file = fopen(uploadthis, "rb");
        !            93:   CURLcode result;
        !            94: 
        !            95:   /* set callback to use */
        !            96:   curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
        !            97: 
        !            98:   /* pass in suitable argument to callback */
        !            99:   curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file);
        !           100: 
        !           101:   result = curl_easy_perform(curl);
        !           102: }
        !           103: .fi
        !           104: .SH AVAILABILITY
        !           105: CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT
        !           106: was added in 7.12.1.
        !           107: .SH RETURN VALUE
        !           108: This will return CURLE_OK.
        !           109: .SH "SEE ALSO"
        !           110: .BR CURLOPT_READDATA "(3), " CURLOPT_WRITEFUNCTION "(3), "
        !           111: .BR CURLOPT_SEEKFUNCTION "(3), " CURLOPT_UPLOAD "(3), " CURLOPT_POST "(3), "
        !           112: .BR CURLOPT_UPLOAD_BUFFERSIZE "(3), "