CURLOPT_HTTPHEADER.md (6740B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: CURLOPT_HTTPHEADER 5 Section: 3 6 Source: libcurl 7 Protocol: 8 - HTTP 9 - SMTP 10 - IMAP 11 See-also: 12 - CURLOPT_CUSTOMREQUEST (3) 13 - CURLOPT_HEADER (3) 14 - CURLOPT_HEADEROPT (3) 15 - CURLOPT_MIMEPOST (3) 16 - CURLOPT_PROXYHEADER (3) 17 - curl_mime_init (3) 18 Added-in: 7.1 19 --- 20 21 # NAME 22 23 CURLOPT_HTTPHEADER - set of HTTP headers 24 25 # SYNOPSIS 26 27 ~~~c 28 #include <curl/curl.h> 29 30 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPHEADER, 31 struct curl_slist *headers); 32 ~~~ 33 34 # DESCRIPTION 35 36 Pass a pointer to a linked list of HTTP headers to pass to the server and/or 37 proxy in your HTTP request. The same list can be used for both host and proxy 38 requests. 39 40 When used within an IMAP or SMTP request to upload a MIME mail, the given 41 header list establishes the document-level MIME headers to prepend to the 42 uploaded document described by CURLOPT_MIMEPOST(3). This does not affect raw 43 mail uploads. 44 45 When used with HTTP, this option can add new headers, replace internal headers 46 and remove internal headers. 47 48 The linked list should be a valid list of **struct curl_slist** entries 49 properly filled in. Use curl_slist_append(3) to create the list and 50 curl_slist_free_all(3) to free it again after use. 51 52 If you provide a header that is otherwise generated and used by libcurl 53 internally, your header alternative is used instead. If you provide a header 54 without content (no data on the right side of the colon) as in `Accept:`, the 55 internally used header is removed. To forcibly add a header without content 56 (nothing after the colon), use the form `name;` (using a trailing semicolon). 57 58 The headers included in the linked list **must not** be CRLF-terminated, since 59 libcurl adds CRLF after each header item itself. Failure to comply with this 60 might result in strange behavior. libcurl passes on the verbatim strings you 61 give it, without any filter or other safe guards. That includes white space 62 and control characters. 63 64 The first line in an HTTP request (containing the method, usually a GET or 65 POST) is not a header and cannot be replaced using this option. Only the lines 66 following the request-line are headers. Adding this method line in this list 67 of headers only causes your request to send an invalid header. Use 68 CURLOPT_CUSTOMREQUEST(3) to change the method. 69 70 When this option is passed to curl_easy_setopt(3), libcurl does not copy the 71 entire list so you **must** keep it around until you no longer use this 72 *handle* for a transfer before you call curl_slist_free_all(3) on the list. 73 74 Using this option multiple times makes the last set list override the previous 75 ones. Set it to NULL to disable its use again. 76 77 The most commonly replaced HTTP headers have "shortcuts" in the options 78 CURLOPT_COOKIE(3), CURLOPT_USERAGENT(3) and CURLOPT_REFERER(3). We recommend 79 using those. 80 81 There is an alternative option that sets or replaces headers only for requests 82 that are sent with CONNECT to a proxy: CURLOPT_PROXYHEADER(3). Use 83 CURLOPT_HEADEROPT(3) to control the behavior. 84 85 # SPECIFIC HTTP HEADERS 86 87 Setting some specific headers causes libcurl to act differently. 88 89 ## Host: 90 91 The specified hostname is used for cookie matching if the cookie engine is 92 also enabled for this transfer. If the request is done over HTTP/2 or HTTP/3, 93 the custom hostname is instead used in the ":authority" header field and 94 Host: is not sent at all over the wire. 95 96 ## Transfer-Encoding: chunked 97 98 Tells libcurl the upload is to be done using this chunked encoding instead of 99 providing the Content-Length: field in the request. 100 101 # SPECIFIC MIME HEADERS 102 103 When used to build a MIME email for IMAP or SMTP, the following document-level 104 headers can be set to override libcurl-generated values: 105 106 ## Mime-Version: 107 108 Tells the parser at the receiving site how to interpret the MIME framing. 109 It defaults to "1.0" and should normally not be altered. 110 111 ## Content-Type: 112 113 Indicates the document's global structure type. By default, libcurl sets it 114 to "multipart/mixed", describing a document made of independent parts. When a 115 MIME mail is only composed of alternative representations of the same data 116 (i.e.: HTML and plain text), this header must be set to "multipart/alternative". 117 In all cases the value must be of the form "multipart/*" to respect the 118 document structure and may not include the "boundary=" parameter. 119 120 ## 121 122 Other specific headers that do not have a libcurl default value but are 123 strongly desired by mail delivery and user agents should also be included. 124 These are `From:`, `To:`, `Date:` and `Subject:` among others and their 125 presence and value is generally checked by anti-spam utilities. 126 127 # SECURITY CONCERNS 128 129 By default, this option makes libcurl send the given headers in all HTTP 130 requests done by this handle. You should therefore use this option with 131 caution if you for example connect to the remote site using a proxy and a 132 CONNECT request, you should to consider if that proxy is supposed to also get 133 the headers. They may be private or otherwise sensitive to leak. 134 135 Use CURLOPT_HEADEROPT(3) to make the headers only get sent to where you 136 intend them to get sent. 137 138 Custom headers are sent in all requests done by the easy handle, which implies 139 that if you tell libcurl to follow redirects 140 (CURLOPT_FOLLOWLOCATION(3)), the same set of custom headers is sent in 141 the subsequent request. Redirects can of course go to other hosts and thus 142 those servers get all the contents of your custom headers too. 143 144 Starting in 7.58.0, libcurl specifically prevents "Authorization:" headers 145 from being sent to other hosts than the first used one, unless specifically 146 permitted with the CURLOPT_UNRESTRICTED_AUTH(3) option. 147 148 Starting in 7.64.0, libcurl specifically prevents "Cookie:" headers from being 149 sent to other hosts than the first used one, unless specifically permitted 150 with the CURLOPT_UNRESTRICTED_AUTH(3) option. 151 152 # DEFAULT 153 154 NULL 155 156 # %PROTOCOLS% 157 158 # EXAMPLE 159 160 ~~~c 161 int main(void) 162 { 163 CURL *curl = curl_easy_init(); 164 165 struct curl_slist *list = NULL; 166 167 if(curl) { 168 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 169 170 /* add this header */ 171 list = curl_slist_append(list, "Shoesize: 10"); 172 173 /* remove this header */ 174 list = curl_slist_append(list, "Accept:"); 175 176 /* change this header */ 177 list = curl_slist_append(list, "Host: example.net"); 178 179 curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list); 180 181 curl_easy_perform(curl); 182 183 curl_slist_free_all(list); /* free the list */ 184 } 185 } 186 ~~~ 187 188 # HISTORY 189 190 Use for MIME mail added in 7.56.0. 191 192 # %AVAILABILITY% 193 194 # RETURN VALUE 195 196 curl_easy_setopt(3) returns a CURLcode indicating success or error. 197 198 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see 199 libcurl-errors(3).