1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_ACCEPT_ENCODING
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_HTTPHEADER (3)
9  - CURLOPT_HTTP_CONTENT_DECODING (3)
10  - CURLOPT_TRANSFER_ENCODING (3)
11Protocol:
12  - HTTP
13Added-in: 7.21.6
14---
15
16# NAME
17
18CURLOPT_ACCEPT_ENCODING - automatic decompression of HTTP downloads
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24
25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPT_ENCODING, char *enc);
26~~~
27
28# DESCRIPTION
29
30Pass a char pointer argument specifying what encoding you would like.
31
32Sets the contents of the Accept-Encoding: header sent in an HTTP request, and
33enables decoding of a response when a Content-Encoding: header is received.
34
35libcurl potentially supports several different compressed encodings depending
36on what support that has been built-in.
37
38To aid applications not having to bother about what specific algorithms this
39particular libcurl build supports, libcurl allows a zero-length string to be
40set ("") to ask for an Accept-Encoding: header to be used that contains all
41built-in supported encodings.
42
43Alternatively, you can specify exactly the encoding or list of encodings you
44want in the response. The following encodings are supported: *identity*,
45meaning non-compressed, *deflate* which requests the server to compress its
46response using the zlib algorithm, *gzip* which requests the gzip algorithm,
47(since curl 7.57.0) *br* which is brotli and (since curl 7.72.0) *zstd* which
48is zstd. Provide them in the string as a comma-separated list of accepted
49encodings, like: **"br, gzip, deflate"**.
50
51Set CURLOPT_ACCEPT_ENCODING(3) to NULL to explicitly disable it, which makes
52libcurl not send an Accept-Encoding: header and not decompress received
53contents automatically.
54
55You can also opt to just include the Accept-Encoding: header in your request
56with CURLOPT_HTTPHEADER(3) but then there is no automatic decompressing when
57receiving data.
58
59This is a request, not an order; the server may or may not do it. This option
60must be set (to any non-NULL value) or else any unsolicited encoding done by
61the server is ignored.
62
63Servers might respond with Content-Encoding even without getting a
64Accept-Encoding: in the request. Servers might respond with a different
65Content-Encoding than what was asked for in the request.
66
67The Content-Length: servers send for a compressed response is supposed to
68indicate the length of the compressed content so when auto decoding is enabled
69it may not match the sum of bytes reported by the write callbacks (although,
70sending the length of the non-compressed content is a common server mistake).
71
72The application does not have to keep the string around after setting this
73option.
74
75Using this option multiple times makes the last set string override the
76previous ones.
77
78# HISTORY
79
80This option was called CURLOPT_ENCODING before 7.21.6
81
82# NOTES
83
84The specific libcurl you are using must have been built with zlib to be able to
85decompress gzip and deflate responses, with the brotli library to
86decompress brotli responses and with the zstd library to decompress zstd
87responses.
88
89# DEFAULT
90
91NULL
92
93# %PROTOCOLS%
94
95# EXAMPLE
96
97~~~c
98int main(void)
99{
100  CURL *curl = curl_easy_init();
101  if(curl) {
102    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
103
104    /* enable all supported built-in compressions */
105    curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, "");
106
107    /* Perform the request */
108    curl_easy_perform(curl);
109  }
110}
111~~~
112
113# %AVAILABILITY%
114
115# RETURN VALUE
116
117Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
118CURLE_OUT_OF_MEMORY if there was insufficient heap space.
119