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