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), "
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>