1---
2c: Copyright (C) Daniel Stenberg, <daniel.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)
10---
11
12# NAME
13
14CURLMOPT_MAX_HOST_CONNECTIONS - max number of connections to a single host
15
16# SYNOPSIS
17
18~~~c
19#include <curl/curl.h>
20
21CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS,
22                            long max);
23~~~
24
25# DESCRIPTION
26
27Pass a long to indicate **max**. The set number is used as the maximum amount
28of simultaneously open connections to a single host (a host being the same as
29a hostname + port number pair). For each new session to a host, libcurl might
30open a new connection up to the limit set by
31CURLMOPT_MAX_HOST_CONNECTIONS(3). When the limit is reached, new sessions are
32kept pending until a connection becomes available.
33
34The default **max** value is 0, unlimited. This set limit is also used for
35proxy connections, and then the proxy is considered to be the host for which
36this limit counts.
37
38When more transfers are added to the multi handle than what can be performed
39due to the set limit, they are queued up waiting for their chance. When that
40happens, the CURLOPT_TIMEOUT_MS(3) timeout is inclusive of the waiting
41time, meaning that if you set a too narrow timeout in such a case the transfer
42might never even start before it times out.
43
44Even in the queued up situation, the CURLOPT_CONNECTTIMEOUT_MS(3)
45timeout is however treated as a per-connect timeout.
46
47# DEFAULT
48
490
50
51# PROTOCOLS
52
53HTTP(S)
54
55# EXAMPLE
56
57~~~c
58int main(void)
59{
60  CURLM *m = curl_multi_init();
61  /* do no more than 2 connections per host */
62  curl_multi_setopt(m, CURLMOPT_MAX_HOST_CONNECTIONS, 2L);
63}
64~~~
65
66# AVAILABILITY
67
68Added in 7.30.0
69
70# RETURN VALUE
71
72Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
73