xref: /curl/docs/libcurl/opts/CURLOPT_ALTSVC.md (revision c4ab3337)
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_ALTSVC
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_ALTSVC_CTRL (3)
9  - CURLOPT_CONNECT_TO (3)
10  - CURLOPT_COOKIEFILE (3)
11  - CURLOPT_RESOLVE (3)
12Protocol:
13  - HTTP
14Added-in: 7.64.1
15---
16<!-- markdown-link-check-disable -->
17# NAME
18
19CURLOPT_ALTSVC - alt-svc cache filename
20
21# SYNOPSIS
22
23~~~c
24#include <curl/curl.h>
25
26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC, char *filename);
27~~~
28
29# DESCRIPTION
30
31Pass in a pointer to a *filename* to instruct libcurl to use that file as
32the Alt-Svc cache to read existing cache contents from and possibly also write
33it back to after a transfer, unless **CURLALTSVC_READONLYFILE** is set in
34CURLOPT_ALTSVC_CTRL(3).
35
36Specify a blank filename ("") to make libcurl not load from a file at all.
37
38The application does not have to keep the string around after setting this
39option.
40
41Using this option multiple times makes the last set string override the
42previous ones. Set it to NULL to disable its use again.
43
44# DEFAULT
45
46NULL. The alt-svc cache is not read nor written to file.
47
48# %PROTOCOLS%
49
50# EXAMPLE
51
52~~~c
53int main(void)
54{
55  CURL *curl = curl_easy_init();
56  if(curl) {
57    curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, CURLALTSVC_H1);
58    curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt");
59    curl_easy_perform(curl);
60  }
61}
62~~~
63
64# FILE FORMAT
65
66A text based file with one line per alt-svc entry and each line consists of
67nine space-separated fields.
68
69An example line could look like
70
71    h2 www.example.com 8443 h3 second.example.com 443 "20190808 06:18:37" 1 0
72
73The fields of that line are:
74
75## h2
76
77ALPN id for the source origin
78
79## www.example.comp
80
81Hostname for the source origin
82
83## 8443
84
85Port number for the source origin
86
87## h3
88
89ALPN id for the destination host
90
91## second.example.com
92
93Hostname for the destination host
94
95## 443
96
97Port number for the destination host
98
99## 2019*
100
101Expiration date and time of this entry within double quotes. The date format
102is "YYYYMMDD HH:MM:SS" and the time zone is GMT.
103
104## 1
105
106Boolean (1 or 0) if "persist" was set for this entry
107
108## 0
109
110Integer priority value (not currently used)
111
112# %AVAILABILITY%
113
114# RETURN VALUE
115
116Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
117