1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_MAXAGE_CONN
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_FORBID_REUSE (3)
9  - CURLOPT_FRESH_CONNECT (3)
10  - CURLOPT_MAXLIFETIME_CONN (3)
11  - CURLOPT_TIMEOUT (3)
12Protocol:
13  - All
14---
15
16# NAME
17
18CURLOPT_MAXAGE_CONN - max idle time allowed for reusing a connection
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24
25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXAGE_CONN, long age);
26~~~
27
28# DESCRIPTION
29
30Pass a long as parameter containing *age* - the maximum time in seconds
31allowed for an existing connection to have been idle to be considered for
32reuse for this request.
33
34The "connection cache" holds previously used connections. When a new request
35is to be done, libcurl considers any connection that matches for reuse. The
36CURLOPT_MAXAGE_CONN(3) limit prevents libcurl from trying too old
37connections for reuse, since old connections have a higher risk of not working
38and thus trying them is a performance loss and sometimes service loss due to
39the difficulties to figure out the situation. If a connection is found in the
40cache that is older than this set *age*, it is closed instead.
41
42# DEFAULT
43
44Default maximum age is set to 118 seconds.
45
46# EXAMPLE
47
48~~~c
49int main(void)
50{
51  CURL *curl = curl_easy_init();
52  if(curl) {
53    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
54
55    /* only allow 30 seconds idle time */
56    curl_easy_setopt(curl, CURLOPT_MAXAGE_CONN, 30L);
57
58    curl_easy_perform(curl);
59  }
60}
61~~~
62
63# AVAILABILITY
64
65Added in 7.65.0
66
67# RETURN VALUE
68
69Returns CURLE_OK.
70