generic-library/curl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

opts: 7 more setopt options as individual man pages

Browse Source
This commit is contained in:
Daniel Stenberg
2014-06-17 11:39:26 +02:00
parent 0219d4e04e
commit d865376c1d
7 changed files with 404 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 Normal file
View File

@@ -0,0 +1,45 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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_CLOSESOCKETDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CLOSESOCKETDATA \- pointer passed to the socket close callback
.SH SYNOPSIS
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETDATA, void *pointer);
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
argument in the closesocket callback set with
\fICURLOPT_CLOSESOCKETFUNCTION(3)\fP.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
All except file:
.SH EXAMPLE
TODO
.SH AVAILABILITY
Added in 7.21.7
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CLOSESOCKETFUNCTION "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), "

56
docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 Normal file
View File

@@ -0,0 +1,56 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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_CLOSESOCKETFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CLOSESOCKETFUNCTION \- callback to socket close replacement function
.SH SYNOPSIS
#include <curl/curl.h>
int closesocket_callback(void *clientp, curl_socket_t item);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETFUNCTION, closesocket_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function gets called by libcurl instead of the \fIclose(3)\fP or
\fIclosesocket(3)\fP call when sockets are closed (not for any other file
descriptors). This is pretty much the reverse to the
\fICURLOPT_OPENSOCKETFUNCTION(3)\fP option. Return 0 to signal success and 1
if there was an error.
The \fIclientp\fP pointer is set with
\fICURLOPT_CLOSESOCKETDATA(3)\fP. \fIitem\fP is the socket libcurl wants to be
closed.
.SH DEFAULT
By default libcurl uses the standard socket close function.
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.SH AVAILABILITY
Added in 7.21.7
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CLOSESOCKETDATA "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), "

44
docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 Normal file
View File

@@ -0,0 +1,44 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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_OPENSOCKETDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_OPENSOCKETDATA \- custom pointer passed to open socket callback
.SH SYNOPSIS
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETDATA, void *pointer);
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION(3)\fP.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.SH AVAILABILITY
Added in 7.17.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_OPENSOCKETFUNCTION "(3), " CURLOPT_SOCKOPTFUNCTION "(3), "

87
docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 Normal file
View File

@@ -0,0 +1,87 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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_OPENSOCKETFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_OPENSOCKETFUNCTION \- set callback for openening socket
.SH SYNOPSIS
.nf
#include <curl/curl.h>
typedef enum {
CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */
CURLSOCKTYPE_ACCEPT, /* socket created by accept() call */
CURLSOCKTYPE_LAST /* never use */
} curlsocktype;
struct curl_sockaddr {
int family;
int socktype;
int protocol;
unsigned int addrlen;
struct sockaddr addr;
};
curl_socket_t opensocket_callback(void *clientp,
curlsocktype purpose,
struct curl_sockaddr *address);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETFUNCTION, opensocket_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function gets called by libcurl instead of the \fIsocket(2)\fP
call. The callback's \fIpurpose\fP argument identifies the exact purpose for
this particular socket: \fICURLSOCKTYPE_IPCXN\fP is for IP based connections
and \fICURLSOCKTYPE_ACCEPT\fP is for sockets created after accept() - such as
when doing active FTP. Future versions of libcurl may support more
purposes.
The callback gets the resolved peer address as the \fIaddress\fP argument and
is allowed to modify the address or refuse to connect completely. The callback
function should return the newly created socket or \fICURL_SOCKET_BAD\fP in
case no connection could be established or another error was detected. Any
additional \fIsetsockopt(2)\fP calls can of course be done on the socket at
the user's discretion. A \fICURL_SOCKET_BAD\fP return value from the callback
function will signal an unrecoverable error to libcurl and it will return
\fICURLE_COULDNT_CONNECT\fP from the function that triggered this callback.
This return code can be used for IP address blacklisting.
If you want to pass in a socket with an already established connection, pass
the socket back with this callback and then use
\fICURLOPT_SOCKOPTFUNCTION(3)\fP to signal that it already is connected.
.SH DEFAULT
The default behavior is the equivalent of this:
.nf
return socket(addr->family, addr->socktype, addr->protocol);
.fi
.SH PROTOCOLS
All
.SH EXAMPLE
.SH AVAILABILITY
Added in 7.17.1.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_OPENSOCKETDATA "(3), " CURLOPT_SOCKOPTFUNCTION "(3), "
.BR CURLOPT_CLOSESOCKETFUNCTION "(3), "

44
docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 Normal file
View File

@@ -0,0 +1,44 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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_PROGRESSDATA 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROGRESSDATA \- custom pointer passed to the progress callback
.SH SYNOPSIS
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSDATA, void *pointer);
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION(3)\fP.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
http://curl.haxx.se/libcurl/c/progressfunc.html
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_PROGRESSFUNCTION "(3), " CURLOPT_XFERINFOFUNCTION "(3), "

84
docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 Normal file
View File

@@ -0,0 +1,84 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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_PROGRESSFUNCTION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROGRESSFUNCTION \- callback to progress meter function
.SH SYNOPSIS
#include <curl/curl.h>
int progress_callback(void *clientp,
double dltotal,
double dlnow,
double ultotal,
double ulnow);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSFUNCTION, progress_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
We encourage users to use the newer \fICURLOPT_XFERINFOFUNCTION(3)\fP instead,
if you can.
This function gets called by libcurl instead of its internal equivalent with a
frequent interval. While data is being transferred it will be called very
frequently, and during slow periods like when nothing is being transferred it
can slow down to about one call per second.
\fIclientp\fP is the pointer set with \fICURLOPT_PROGRESSDATA(3)\fP, it is not
used by libcurl but is only passed along from the application to the callback.
The callback gets told how much data libcurl will transfer and has
transferred, in number of bytes. \fIdltotal\fP is the total number of bytes
libcurl expects to download in this transfer. \fIdlnow\fP is the number of
bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl
expects to upload in this transfer. \fIulnow\fP is the number of bytes
uploaded so far.
Unknown/unused argument values passed to the callback will be set to zero
(like if you only download data, the upload size will remain 0). Many times
the callback will be called one or more times first, before it knows the data
sizes so a program must be made to handle that.
Returning a non-zero value from this callback will cause libcurl to abort the
transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.
If you transfer data with the multi interface, this function will not be
called during periods of idleness unless you call the appropriate libcurl
function that performs transfers.
\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually
get called.
.SH DEFAULT
By default, libcurl has an internal progress meter. That's rarely wanted by
users.
.SH PROTOCOLS
All
.SH EXAMPLE
http://curl.haxx.se/libcurl/c/progressfunc.html
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_VERBOSE "(3), " CURLOPT_NOPROGRESS "(3), "

44
docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 Normal file
View File

@@ -0,0 +1,44 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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_SOCKOPTDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SOCKOPTDATA \- custom pointer to pass to sockopt callback
.SH SYNOPSIS
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTDATA, void *pointer);
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION(3)\fP.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.SH AVAILABILITY
Added in 7.16.0
.SH RETURN VALUE
Returns \fICURLE_OK\fP if the option is supported, and \fICURLE_UNKNOWN_OPTION\fP if not.
.SH "SEE ALSO"
.BR CURLOPT_SOCKOPTFUNCTION "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), "