mirror of https://github.com/moparisthebest/curl
opts docs: 3 more options in their own man pages
This commit is contained in:
Daniel Stenberg
parent
7ad9cb12b2
commit
28b698858c
|
|
@ -0,0 +1,52 @@
|
|||
.\" **************************************************************************
|
||||
.\" * _ _ ____ _
|
||||
.\" * 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_READDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
|
||||
.SH NAME
|
||||
CURLOPT_READDATA \- custom pointer passed to the read callback
|
||||
.SH SYNOPSIS
|
||||
#include <curl/curl.h>
|
||||
|
||||
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READDATA, void *pointer);
|
||||
.SH DESCRIPTION
|
||||
Data \fIpointer\fP to pass to the file read function. If you use the
|
||||
\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you'll get as
|
||||
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.
|
||||
.SH DEFAULT
|
||||
By default, this is a FILE * to stdin.
|
||||
.SH PROTOCOLS
|
||||
This is used for all protocls when sending data.
|
||||
.SH EXAMPLE
|
||||
TODO
|
||||
.SH AVAILABILITY
|
||||
This option was once known by the older name \fICURLOPT_INFILE\fP, the name
|
||||
\fICURLOPT_READDATA\fP was introduced in 7.9.7.
|
||||
.SH RETURN VALUE
|
||||
This will return CURLE_OK.
|
||||
.SH "SEE ALSO"
|
||||
.BR CURLOPT_READFUNCTION "(3), " CURLOPT_WRITEDATA "(3), "
|
||||
|
|
@ -0,0 +1,77 @@
|
|||
.\" **************************************************************************
|
||||
.\" * _ _ ____ _
|
||||
.\" * 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_READFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
|
||||
.SH NAME
|
||||
CURLOPT_READFUNCTION \- [short desc]
|
||||
.SH SYNOPSIS
|
||||
#include <curl/curl.h>
|
||||
|
||||
size_t read_callback(char *buffer, size_t size, size_t nitems, void *instream);
|
||||
|
||||
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_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 it needs to read data
|
||||
in order to send it to the peer. The data area pointed at by the pointer
|
||||
\fIbuffer\fP should be filled up with at most \fIsize\fP multiplied with
|
||||
\fInmemb\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.
|
||||
|
||||
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
|
||||
upload less than N bytes), you may experience that the server "hangs" waiting
|
||||
for the rest of the data that won't come.
|
||||
|
||||
The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
|
||||
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
|
||||
code from the transfer.
|
||||
|
||||
The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
|
||||
connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
|
||||
|
||||
\fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data
|
||||
that the callback wants, or it will be considered the final packet by the
|
||||
server end and the transfer will end there.
|
||||
|
||||
If you set this callback pointer to NULL, or don't set it at all, the default
|
||||
internal read function will be used. It is doing an fread() on the FILE *
|
||||
userdata set with \fICURLOPT_READDATA(3)\fP.
|
||||
.SH DEFAULT
|
||||
The default internal read callback is fread().
|
||||
.SH PROTOCOLS
|
||||
This is used for all protocols when doing uploads.
|
||||
.SH EXAMPLE
|
||||
Here's an example setting a read callback for reading that to upload to an FTP
|
||||
site: http://curl.haxx.se/libcurl/c/ftpupload.html
|
||||
.SH AVAILABILITY
|
||||
CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT
|
||||
was added in 7.12.1.
|
||||
.SH RETURN VALUE
|
||||
This will return CURLE_OK.
|
||||
.SH "SEE ALSO"
|
||||
.BR CURLOPT_READDATA "(3), " CURLOPT_WRITEFUNCTION "(3), "
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
.\" **************************************************************************
|
||||
.\" * _ _ ____ _
|
||||
.\" * 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_WRITEDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
|
||||
.SH NAME
|
||||
CURLOPT_WRITEDATA \- custom pointer passed to the write callback
|
||||
.SH SYNOPSIS
|
||||
#include <curl/curl.h>
|
||||
|
||||
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEDATA, void *pointer);
|
||||
.SH DESCRIPTION
|
||||
A data \fIpointer\fP to pass to the write callback. If you use the
|
||||
\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you'll get in that
|
||||
callback's 4th argument. If you don't use a write callback, you must make
|
||||
\fIpointer\fP a 'FILE *' (cast to 'void *') as libcurl will pass this to
|
||||
\fIfwrite(3)\fP when writing data.
|
||||
|
||||
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
|
||||
\fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience
|
||||
crashes.
|
||||
|
||||
This option is also known with the older name \fICURLOPT_FILE\fP, the name
|
||||
\fICURLOPT_WRITEDATA\fP was introduced in 7.9.7.
|
||||
.SH DEFAULT
|
||||
By default, this is a FILE * to stdout.
|
||||
.SH PROTOCOLS
|
||||
Used for all protocols.
|
||||
.SH EXAMPLE
|
||||
A common technique is to use the write callback to store the incoming data
|
||||
into a dynamically growing allocated buffer, and then this CURLOPT_WRITEDATA
|
||||
is used to point to a struct or the buffer to store data in. Like in the
|
||||
getinmemory example: http://curl.haxx.se/libcurl/c/getinmemory.html
|
||||
.SH AVAILABILITY
|
||||
Available in all libcurl versions
|
||||
.SH RETURN VALUE
|
||||
This will return CURLE_OK.
|
||||
.SH "SEE ALSO"
|
||||
.BR CURLOPT_WRITEFUNCTION "(3), " CURLOPT_READDATA "(3), "
|
||||
Loading…
Reference in New Issue