.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 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 https://curl.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.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_MAX_HOST_CONNECTIONS 3 "17 Jun 2014" libcurl libcurl
.SH NAME
CURLMOPT_MAX_HOST_CONNECTIONS \- max number of connections to a single host
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS,
                            long max);
.fi
.SH DESCRIPTION
Pass a long to indicate \fBmax\fP. The set number is used as the maximum
amount of simultaneously open connections to a single host (a host being the
same as a host name + port number pair). For each new session to a host,
libcurl might open a new connection up to the limit set by
\fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. When the limit is reached, new
sessions are kept pending until a connection becomes available.

The default \fBmax\fP value is 0, unlimited. This set limit is also used for
proxy connections, and then the proxy is considered to be the host for which
this limit counts.

When more transfers are added to the multi handle than what can be performed
due to the set limit, they are queued up waiting for their chance. When that
happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout is inclusive of the waiting
time, meaning that if you set a too narrow timeout in such a case the transfer
might never even start before it times out.

Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
timeout is however treated as a per-connect timeout.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
int main(void)
{
  CURLM *m = curl_multi_init();
  /* do no more than 2 connections per host */
  curl_multi_setopt(m, CURLMOPT_MAX_HOST_CONNECTIONS, 2L);
}
.fi
.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),
.BR CURLMOPT_MAX_TOTAL_CONNECTIONS (3)