From b676b66f4ddc68a0e357fc4cf79b9adb981c8df5 Mon Sep 17 00:00:00 2001 From: Michael Kaufmann Date: Sat, 11 Aug 2018 13:52:18 +0200 Subject: docs: Improve the manual pages of some callbacks - CURLOPT_HEADERFUNCTION: add newlines - CURLOPT_INTERLEAVEFUNCTION: fix the description of 'userdata' - CURLOPT_READDATA: mention crashes, same as in CURLOPT_WRITEDATA - CURLOPT_READFUNCTION: rename 'instream' to 'userdata' and explain how to set it Closes https://github.com/curl/curl/pull/2868 --- docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 | 15 +++++++++------ docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 | 4 ++-- docs/libcurl/opts/CURLOPT_READDATA.3 | 5 +++-- docs/libcurl/opts/CURLOPT_READFUNCTION.3 | 10 ++++++---- docs/libcurl/opts/CURLOPT_WRITEDATA.3 | 2 +- 5 files changed, 21 insertions(+), 15 deletions(-) (limited to 'docs/libcurl/opts') diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 index 6633dbad1..0ecbfb3db 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 @@ -41,12 +41,15 @@ data. The header callback will be called once for each header and only complete header lines are passed on to the callback. Parsing headers is very easy using this. The size of the data pointed to by \fIbuffer\fP is \fIsize\fP multiplied with \fInmemb\fP. Do not assume that the header line is zero -terminated! The pointer named \fIuserdata\fP is the one you set with the -\fICURLOPT_HEADERDATA(3)\fP option. This callback function must return the -number of bytes actually taken care of. If that amount differs from the amount -passed in to your function, it'll signal an error to the library. This will -cause the transfer to get aborted and the libcurl function in progress will -return \fICURLE_WRITE_ERROR\fP. +terminated! + +The pointer named \fIuserdata\fP is the one you set with the +\fICURLOPT_HEADERDATA(3)\fP option. + +This callback function must return the number of bytes actually taken care of. +If that amount differs from the amount passed in to your function, it'll signal +an error to the library. This will cause the transfer to get aborted and the +libcurl function in progress will return \fICURLE_WRITE_ERROR\fP. A complete HTTP header that is passed to this function can be up to \fICURL_MAX_HTTP_HEADER\fP (100K) bytes. diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 index 20f1c218d..b5776ed2c 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 @@ -55,8 +55,8 @@ service RTP data when no requests are desired. If the application makes a request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler will process any pending RTP data before marking the request as finished. -The \fICURLOPT_WRITEDATA(3)\fP is passed in the \fIuserdata\fP argument in the -callback. +The \fICURLOPT_INTERLEAVEDATA(3)\fP is passed in the \fIuserdata\fP argument in +the callback. .SH DEFAULT NULL, the interleave data is then passed to the regular write function: \fICURLOPT_WRITEFUNCTION(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_READDATA.3 b/docs/libcurl/opts/CURLOPT_READDATA.3 index ef51264c6..b1fff4c42 100644 --- a/docs/libcurl/opts/CURLOPT_READDATA.3 +++ b/docs/libcurl/opts/CURLOPT_READDATA.3 @@ -35,8 +35,9 @@ input in the 4th argument to the callback. If you don't specify a read callback but instead rely on the default internal read function, this data must be a valid readable FILE * (cast to 'void *'). -If you're using libcurl as a win32 DLL, you MUST use a -\fICURLOPT_READFUNCTION(3)\fP if you set this option. +If you're using libcurl as a win32 DLL, you \fBMUST\fP use a +\fICURLOPT_READFUNCTION(3)\fP if you set this option or you will experience +crashes. .SH DEFAULT By default, this is a FILE * to stdin. .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_READFUNCTION.3 b/docs/libcurl/opts/CURLOPT_READFUNCTION.3 index 096312d28..0f2fb359d 100644 --- a/docs/libcurl/opts/CURLOPT_READFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_READFUNCTION.3 @@ -26,7 +26,7 @@ CURLOPT_READFUNCTION \- read callback for data uploads .SH SYNOPSIS #include -size_t read_callback(char *buffer, size_t size, size_t nitems, void *instream); +size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata); CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback); @@ -39,9 +39,11 @@ the server. The data area pointed at by the pointer \fIbuffer\fP should be filled up with at most \fIsize\fP multiplied with \fInitems\fP number of bytes by your function. -Your function must then return the actual number of bytes that it stored in -that memory area. Returning 0 will signal end-of-file to the library and cause -it to stop the current transfer. +Set the \fIuserdata\fP argument with the \fICURLOPT_READDATA(3)\fP option. + +Your function must return the actual number of bytes that it stored in the data +area pointed at by the pointer \fIbuffer\fP. Returning 0 will signal +end-of-file to the library and cause it to stop the current transfer. If you stop the current transfer by returning 0 "pre-maturely" (i.e before the server expected it, like when you've said you will upload N bytes and you diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 b/docs/libcurl/opts/CURLOPT_WRITEDATA.3 index fdb58863f..221e0e3ed 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 +++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.3 @@ -37,7 +37,7 @@ callback's 4th argument. If you don't use a write callback, you must make The internal \fICURLOPT_WRITEFUNCTION(3)\fP will write the data to the FILE * given with this option, or to stdout if this option hasn't been set. -If you're using libcurl as a win32 DLL, you \fBMUST\fP use the +If you're using libcurl as a win32 DLL, you \fBMUST\fP use a \fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you will experience crashes. .SH DEFAULT -- cgit v1.2.3