repo/core/curl/files/CURLOPT_MAXAGE_CONN.3

.\" generated by cd2nroff 0.1 from CURLOPT_MAXAGE_CONN.md
.TH CURLOPT_MAXAGE_CONN 3 "2024-11-09" libcurl
.SH NAME
CURLOPT_MAXAGE_CONN \- max idle time allowed for reusing a connection
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXAGE_CONN, long age);
.fi
.SH DESCRIPTION
Pass a long as parameter containing \fIage\fP \- the maximum time in seconds
allowed for an existing connection to have been idle to be considered for
reuse for this request.

The "connection cache" holds previously used connections. When a new request
is to be done, libcurl considers any connection that matches for reuse. The
\fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying too old
connections for reuse, since old connections have a higher risk of not working
and thus trying them is a performance loss and sometimes service loss due to
the difficulties to figure out the situation. If a connection is found in the
cache that is older than this set \fIage\fP, it is closed instead.
.SH DEFAULT
118 seconds
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");

    /* only allow 30 seconds idle time */
    curl_easy_setopt(curl, CURLOPT_MAXAGE_CONN, 30L);

    curl_easy_perform(curl);
  }
}
.fi
.SH AVAILABILITY
Added in curl 7.65.0
.SH RETURN VALUE
Returns CURLE_OK.
.SH SEE ALSO
.BR CURLOPT_FORBID_REUSE (3),
.BR CURLOPT_FRESH_CONNECT (3),
.BR CURLOPT_MAXLIFETIME_CONN (3),
.BR CURLOPT_TIMEOUT (3)