CURLMOPT_MAX_HOST_CONNECTIONS(3)

1CURLMOPT_MAX_HOST_CONNECTIONS(3)    libcurl   CURLMOPT_MAX_HOST_CONNECTIONS(3)
2
3
4

NAME

6       CURLMOPT_MAX_HOST_CONNECTIONS  -  max number of connections to a single
7       host
8

SYNOPSIS

10       #include <curl/curl.h>
11
12       CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS,
13                                   long max);
14

DESCRIPTION

16       Pass a long to indicate max. The set number will be used as the maximum
17       amount  of simultaneously open connections to a single host (a host be‐
18       ing the same as a host name + port number pair). For each  new  session
19       to  a  host,  libcurl will open a new connection up to the limit set by
20       CURLMOPT_MAX_HOST_CONNECTIONS(3). When the limit is reached,  the  ses‐
21       sions  will  be  pending until a connection becomes available. If CURL‐
22       MOPT_PIPELINING(3) is enabled, libcurl will try to pipeline if the host
23       is capable of it.
24
25       The default max value is 0, unlimited.  However, for backwards compati‐
26       bility, setting it to 0 when CURLMOPT_PIPELINING(3) is 1  will  not  be
27       treated as unlimited. Instead it will open only 1 connection and try to
28       pipeline on it.
29
30       This set limit is also used for proxy connections, and then  the  proxy
31       is considered to be the host for which this limit counts.
32
33       When more transfers are added to the multi handle than what can be per‐
34       formed due to the set limit, they will be queued up waiting  for  their
35       chance.  When  that  happens, the CURLOPT_TIMEOUT_MS(3) timeout will be
36       counted inclusive of the waiting time, meaning that if you  set  a  too
37       narrow  timeout  in such a case the transfer might never even start be‐
38       fore it times out.
39
40       Even in the queued up situation, the CURLOPT_CONNECTTIMEOUT_MS(3) time‐
41       out is however treated as a per-connect timeout.
42

DEFAULT

44       0
45

PROTOCOLS

47       HTTP(S)
48

EXAMPLE

50       CURLM *m = curl_multi_init();
51       /* do no more than 2 connections per host */
52       curl_multi_setopt(m, CURLMOPT_MAX_HOST_CONNECTIONS, 2L);
53

AVAILABILITY

55       Added in 7.30.0
56

RETURN VALUE

58       Returns  CURLM_OK  if the option is supported, and CURLM_UNKNOWN_OPTION
59       if not.
60