1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLMOPT_MAX_HOST_CONNECTIONS
5Section: 3
6Source: libcurl
7See-also:
8  - CURLMOPT_MAXCONNECTS (3)
9  - CURLMOPT_MAX_TOTAL_CONNECTIONS (3)
10Protocol:
11  - All
12Added-in: 7.30.0
13---
14
15# NAME
16
17CURLMOPT_MAX_HOST_CONNECTIONS - max number of connections to a single host
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS,
25                            long max);
26~~~
27
28# DESCRIPTION
29
30Pass a long to indicate **max**, the maximum amount of simultaneously open
31connections libcurl may hold a single host (a host being the same as a
32hostname + port number pair). For each new transfer to the same host, libcurl
33might open a new connection up to the limit set by
34CURLMOPT_MAX_HOST_CONNECTIONS(3). When the limit is reached, new sessions are
35kept pending until a connection becomes available.
36
37The default **max** value is 0, unlimited. This set limit is also used for
38proxy connections, and then the proxy is considered to be the host for which
39this limit counts.
40
41When more transfers are added to the multi handle than what can be performed
42due to the set limit, they are queued up waiting for their chance.
43
44While a transfer is queued up internally waiting for a connection, the
45CURLOPT_TIMEOUT_MS(3) timeout is counted inclusive of the waiting time,
46meaning that if you set a too narrow timeout the transfer might never even
47start before it times out. The CURLOPT_CONNECTTIMEOUT_MS(3) time is also
48similarly still treated as a per-connect timeout and might expire even before
49making a new connection is permitted.
50
51Changing this value while there are transfers in progress is possible. The new
52value is then used the next time checks are performed. Lowering the value does
53not close down any active transfers, it simply does not allow new ones to get
54made.
55
56# DEFAULT
57
580
59
60# %PROTOCOLS%
61
62# EXAMPLE
63
64~~~c
65int main(void)
66{
67  CURLM *m = curl_multi_init();
68  /* do no more than 2 connections per host */
69  curl_multi_setopt(m, CURLMOPT_MAX_HOST_CONNECTIONS, 2L);
70}
71~~~
72
73# %AVAILABILITY%
74
75# RETURN VALUE
76
77Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
78