mirror/curl
2
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2025-02-17 14:59:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

opts: made stand-alone man-pages for several multi options

Browse Source
This commit is contained in:
Daniel Stenberg 2014-11-03 23:11:37 +01:00
parent 15c4d51d39
commit a14ccfffb8
9 changed files with 417 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/libcurl/curl_multi_setopt.3
View File

@ -27,14 +27,14 @@ curl_multi_setopt \- set options for a curl multi handle
CURLMcode curl_multi_setopt(CURLM * multi_handle, CURLMoption option, param);
.SH DESCRIPTION
curl_multi_setopt() is used to tell a libcurl multi handle how to behave. By
using the appropriate options to \fIcurl_multi_setopt(3)\fP, you can change
libcurl's behaviour when using that multi handle. All options are set with
the \fIoption\fP followed by the parameter \fIparam\fP. That parameter can be
a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject pointer\fP or a
\fBcurl_off_t\fP type, depending on what the specific option expects. Read
this manual carefully as bad input values may cause libcurl to behave badly!
You can only set one option in each function call.
\fIcurl_multi_setopt(3)\fP is used to tell a libcurl multi handle how to
behave. By using the appropriate options to \fIcurl_multi_setopt(3)\fP, you
can change libcurl's behaviour when using that multi handle. All options are
set with the \fIoption\fP followed by the parameter \fIparam\fP. That
parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject
pointer\fP or a \fBcurl_off_t\fP type, depending on what the specific option
expects. Read this manual carefully as bad input values may cause libcurl to
behave badly! You can only set one option in each function call.
.SH OPTIONS
.IP CURLMOPT_SOCKETFUNCTION

62
docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 Normal file
View File

@ -0,0 +1,62 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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 CURLMOPT_MAXCONNECTS 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_MAXCONNECTS \- set size of connection cache
.SH SYNOPSIS
#include <curl/curl.h>
CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_MAXCONNECTS, long max);
.SH DESCRIPTION
Pass a long indicating the \fBmax\fP. The set number will be used as the
maximum amount of simultaneously open connections that libcurl may keep in its
connection cache after completed use. By default libcurl will enlarge the size
for each added easy handle to make it fit 4 times the number of added easy
handles.
By setting this option, you can prevent the cache size from growing beyond the
limit set by you.
When the cache is full, curl closes the oldest one in the cache to prevent the
number of open connections from increasing.
This option is for the multi handle's use only, when using the easy interface
you should instead use the \fICURLOPT_MAXCONNECTS(3)\fP option.
See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP for limiting the number of active
connections.
.SH DEFAULT
See DESCRIPTION
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.SH AVAILABILITY
Added in 7.16.3
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_MAX_HOST_CONNECTIONS "(3), "
.BR CURLOPT_MAXCONNECTS "(3), "

54
docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 Normal file
View File

@ -0,0 +1,54 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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 CURLMOPT_MAX_HOST_CONNECTIONS 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_MAX_HOST_CONNECTIONS \- set max number of connections to a single host
.SH SYNOPSIS
#include <curl/curl.h>
CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_MAX_HOST_CONNECTIONS, long max);
.SH DESCRIPTION
Pass a long to indicate \fBmax\fP. The set number will be used as the maximum
amount of simultaneously open connections to a single host. For each new
session to a host, libcurl will open a new connection up to the limit set by
\fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. When the limit is reached, the
sessions will be pending until a connection becomes available. If
\fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl will try to pipeline if the
host is capable of it.
The default \fBmax\fP value is 0, unlimited. However, for backwards
compatibility, setting it to 0 when \fICURLMOPT_PIPELINING(3)\fP is 1 will not
be treated as unlimited. Instead it will open only 1 connection and try to
pipeline on it.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
TODO
.SH AVAILABILITY
Added in 7.30.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_MAXCONNECTS "(3), " CURLMOPT_MAX_TOTAL_CONNECTIONS "(3), "

57
docs/libcurl/opts/CURLMOPT_PIPELINING.3 Normal file
View File

@ -0,0 +1,57 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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 CURLMOPT_PIPELINING 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_PIPELINING \- enable/disable HTTP pipelining
.SH SYNOPSIS
#include <curl/curl.h>
CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_PIPELINING, bool onoff);
.SH DESCRIPTION
Set the \fBonoff\fP parameter to 1 to make libcurl use HTTP pipelining for
HTTP transfers done using this multi handle, as far as possible. This means
that if you add a second request that can use an already existing connection,
the second request will be \&"piped" on the same connection rather than being
executed in parallel.
When using pipelining, there are also several other related options that are
interesting to tweak and adjust to alter how libcurl spreads out requests on
different connections or not etc.
.SH DEFAULT
0 (off)
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
TODO
.SH AVAILABILITY
Added in 7.16.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_MAX_PIPELINE_LENGTH "(3), "
.BR CURLMOPT_PIPELINING_SITE_BL "(3), "
.BR CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE "(3), "
.BR CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE "(3), "
.BR CURLMOPT_MAX_HOST_CONNECTIONS "(3), "
.BR CURLMOPT_MAXCONNECTS "(3), "
.BR CURLMOPT_MAX_HOST_CONNECTIONS "(3), "

49
docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 Normal file
View File

@ -0,0 +1,49 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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 CURLMOPT_SOCKETDATA 3 "3 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_SOCKETDATA \- custom pointer passed to the socket callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_SOCKETDATA, void *pointer);
.SH DESCRIPTION
A data \fIpointer\fP to pass to the socket callback set with the
\fICURLMOPT_SOCKETFUNCTION(3)\fP option.
This pointer will not be touched by libcurl but will only be passed in to the
socket callbacks's \fBuserp\fP argument.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.SH AVAILABILITY
Added in 7.15.4
.SH RETURN VALUE
Returns CURLM_OK.
.SH "SEE ALSO"
.BR CURLMOPT_SOCKETFUNCTION "(3), " curl_multi_socket_action "(3), "
.BR CURLMOPT_TIMERFUNCTION "(3) "

62
docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 Normal file
View File

@ -0,0 +1,62 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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 CURLMOPT_SOCKETFUNCTION 3 "3 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_SOCKETFUNCTION \- callback informed about what to wait for
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int socket_callback(CURL *easy, /* easy handle */
curl_socket_t s, /* socket */
int what, /* see above */
void *userp, /* private callback pointer */
void *socketp); /* private socket pointer */
CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_SOCKETFUNCTION, socket_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
When the \fIcurl_multi_socket_action(3)\fP function runs, it informs the
application about updates in the socket (file descriptor) status by doing
none, one, or multiple calls to the \fBsocket_callback\fP. The callback gets
status updates with changes since the previous time the callback was called.
If the given callback pointer is NULL, no callback will be called. Set the
callback's \fBuserp\fP argument with \fICURLMOPT_SOCKETDATA(3)\fP. See
\fIcurl_multi_socket_action(3)\fP for more details on how the callback is used
and should work.
.SH DEFAULT
NULL (no callback)
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.SH AVAILABILITY
Added in 7.15.4
.SH RETURN VALUE
Returns CURLM_OK.
.SH "SEE ALSO"
.BR CURLMOPT_SOCKETDATA "(3), " curl_multi_socket_action "(3), "
.BR CURLMOPT_TIMERFUNCTION "(3) "

48
docs/libcurl/opts/CURLMOPT_TIMERDATA.3 Normal file
View File

@ -0,0 +1,48 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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 CURLMOPT_TIMERDATA 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_TIMERDATA \- custom pointer to pass to timer callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_TIMERDATA, void *pointer);
.SH DESCRIPTION
A data \fBpointer\fP to pass to the timer callback set with the
\fICURLMOPT_TIMERFUNCTION(3)\fP option.
This pointer will not be touched by libcurl but will only be passed in to the
timer callbacks's \fBuserp\fP argument.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.SH AVAILABILITY
Added in 7.16.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_TIMERFUNCTION "(3), " CURLMOPT_SOCKETFUNCTION "(3), "

63
docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 Normal file
View File

@ -0,0 +1,63 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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 CURLMOPT_TIMERFUNCTION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_TIMERFUNCTION \- set callback to receive timeout values
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int timer_callback(CURLM *multi, /* multi handle */
long timeout_ms, /* see above */
void *userp); /* private callback pointer */
CURLcode curl_multi_setopt(CURL *handle, CURLMOPT_TIMERFUNCTION, timer_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function will be called when the timeout value changes. The
\fBtimeout_ms\fP value is at what latest time the application should call one
of the \&"performing" functions of the multi interface
(\fIcurl_multi_socket_action(3)\fP and \fIcurl_multi_perform(3)\fP) - to allow
libcurl to keep timeouts and retries etc to work. A \fBtimeout_ms\fP value of
-1 means that there is no timeout at all, and 0 means that the timeout is
already expired. libcurl attempts to limit calling this only when the fixed
future timeout time actually changes.
The \fBuserp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP.
The timer callback should return 0 on success, and -1 on error. This callback
can be used instead of, or in addition to, \fIcurl_multi_timeout(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.SH AVAILABILITY
Added in 7.16.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_TIMERDATA "(3), " CURLMOPT_SOCKETFUNCTION "(3), "

17
docs/libcurl/opts/Makefile.am
View File

@ -103,7 +103,10 @@ man_MANS = CURLOPT_ACCEPT_ENCODING.3 CURLOPT_ACCEPTTIMEOUT_MS.3 \
CURLOPT_USERAGENT.3 CURLOPT_USERNAME.3 CURLOPT_USERPWD.3 \
CURLOPT_USE_SSL.3 CURLOPT_VERBOSE.3 CURLOPT_WILDCARDMATCH.3 \
CURLOPT_WRITEDATA.3 CURLOPT_WRITEFUNCTION.3 CURLOPT_XFERINFODATA.3 \
CURLOPT_XFERINFOFUNCTION.3 CURLOPT_XOAUTH2_BEARER.3
CURLOPT_XFERINFOFUNCTION.3 CURLOPT_XOAUTH2_BEARER.3 \
CURLMOPT_MAXCONNECTS.3 CURLMOPT_MAX_HOST_CONNECTIONS.3 \
CURLMOPT_PIPELINING.3 CURLMOPT_SOCKETDATA.3 CURLMOPT_SOCKETFUNCTION.3 \
CURLMOPT_TIMERDATA.3 CURLMOPT_TIMERFUNCTION.3
HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html \
CURLOPT_ADDRESS_SCOPE.html CURLOPT_APPEND.html \
@ -201,7 +204,11 @@ HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html \
CURLOPT_USERNAME.html CURLOPT_USERPWD.html CURLOPT_USE_SSL.html \
CURLOPT_VERBOSE.html CURLOPT_WILDCARDMATCH.html CURLOPT_WRITEDATA.html \
CURLOPT_WRITEFUNCTION.html CURLOPT_XFERINFODATA.html \
CURLOPT_XFERINFOFUNCTION.html CURLOPT_XOAUTH2_BEARER.html
CURLOPT_XFERINFOFUNCTION.html CURLOPT_XOAUTH2_BEARER.html \
CURLMOPT_MAXCONNECTS.html CURLMOPT_MAX_HOST_CONNECTIONS.html \
CURLMOPT_PIPELINING.html CURLMOPT_SOCKETDATA.html \
CURLMOPT_SOCKETFUNCTION.html CURLMOPT_TIMERDATA.html \
CURLMOPT_TIMERFUNCTION.html
PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf \
CURLOPT_ADDRESS_SCOPE.pdf CURLOPT_APPEND.pdf CURLOPT_AUTOREFERER.pdf \
@ -296,7 +303,11 @@ PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf \
CURLOPT_USE_SSL.pdf CURLOPT_VERBOSE.pdf CURLOPT_WILDCARDMATCH.pdf \
CURLOPT_WRITEDATA.pdf CURLOPT_WRITEFUNCTION.pdf \
CURLOPT_XFERINFODATA.pdf CURLOPT_XFERINFOFUNCTION.pdf \
CURLOPT_XOAUTH2_BEARER.pdf
CURLOPT_XOAUTH2_BEARER.pdf CURLMOPT_MAXCONNECTS.pdf \
CURLMOPT_MAX_HOST_CONNECTIONS.pdf CURLMOPT_PIPELINING.pdf \
CURLMOPT_SOCKETDATA.pdf CURLMOPT_SOCKETFUNCTION.pdf \
CURLMOPT_TIMERDATA.pdf CURLMOPT_TIMERFUNCTION.pdf
CLEANFILES = $(HTMLPAGES) $(PDFPAGES)