Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_HTTPHEADER.3, revision 1.1.1.1
1.1 misho 1: .\" **************************************************************************
2: .\" * _ _ ____ _
3: .\" * Project ___| | | | _ \| |
4: .\" * / __| | | | |_) | |
5: .\" * | (__| |_| | _ <| |___
6: .\" * \___|\___/|_| \_\_____|
7: .\" *
8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
9: .\" *
10: .\" * This software is licensed as described in the file COPYING, which
11: .\" * you should have received as part of this distribution. The terms
12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
13: .\" *
14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
15: .\" * copies of the Software, and permit persons to whom the Software is
16: .\" * furnished to do so, under the terms of the COPYING file.
17: .\" *
18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19: .\" * KIND, either express or implied.
20: .\" *
21: .\" **************************************************************************
22: .\"
23: .TH CURLOPT_HTTPHEADER 3 "March 23, 2020" "libcurl 7.70.0" "curl_easy_setopt options"
24:
25: .SH NAME
26: CURLOPT_HTTPHEADER \- set custom HTTP headers
27: .SH SYNOPSIS
28: #include <curl/curl.h>
29:
30: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPHEADER, struct curl_slist *headers);
31: .SH DESCRIPTION
32: Pass a pointer to a linked list of HTTP headers to pass to the server and/or
33: proxy in your HTTP request. The same list can be used for both host and proxy
34: requests!
35:
36: The linked list should be a fully valid list of \fBstruct curl_slist\fP
37: structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list
38: and \fIcurl_slist_free_all(3)\fP to clean up an entire list. If you add a
39: header that is otherwise generated and used by libcurl internally, your added
40: one will be used instead. If you add a header with no content as in 'Accept:'
41: (no data on the right side of the colon), the internally used header will get
42: disabled. With this option you can add new headers, replace internal headers
43: and remove internal headers. To add a header with no content (nothing to the
44: right side of the colon), use the form 'MyHeader;' (note the ending
45: semicolon).
46:
47: The headers included in the linked list \fBmust not\fP be CRLF-terminated,
48: because libcurl adds CRLF after each header item. Failure to comply with this
49: will result in strange bugs because the server will most likely ignore part of
50: the headers you specified.
51:
52: The first line in a request (containing the method, usually a GET or POST) is
53: not a header and cannot be replaced using this option. Only the lines
54: following the request-line are headers. Adding this method line in this list
55: of headers will only cause your request to send an invalid header. Use
56: \fICURLOPT_CUSTOMREQUEST(3)\fP to change the method.
57:
58: When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl will not copy
59: the entire list so you \fBmust\fP keep it around until you no longer use this
60: \fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on
61: the list.
62:
63: Pass a NULL to this option to reset back to no custom headers.
64:
65: The most commonly replaced headers have "shortcuts" in the options
66: \fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP and
67: \fICURLOPT_REFERER(3)\fP. We recommend using those.
68:
69: There's an alternative option that sets or replaces headers only for requests
70: that are sent with CONNECT to a proxy: \fICURLOPT_PROXYHEADER(3)\fP. Use
71: \fICURLOPT_HEADEROPT(3)\fP to control the behavior.
72: .SH SECURITY CONCERNS
73: By default, this option makes libcurl send the given headers in all HTTP
74: requests done by this handle. You should therefore use this option with
75: caution if you for example connect to the remote site using a proxy and a
76: CONNECT request, you should to consider if that proxy is supposed to also get
77: the headers. They may be private or otherwise sensitive to leak.
78:
79: Use \fICURLOPT_HEADEROPT(3)\fP to make the headers only get sent to where you
80: intend them to get sent.
81:
82: Custom headers are sent in all requests done by the easy handles, which
83: implies that if you tell libcurl to follow redirects
84: (\fICURLOPT_FOLLOWLOCATION(3)\fP), the same set of custom headers will be sent
85: in the subsequent request. Redirects can of course go to other hosts and thus
86: those servers will get all the contents of your custom headers too.
87:
88: Starting in 7.58.0, libcurl will specifically prevent "Authorization:" headers
89: from being sent to other hosts than the first used one, unless specifically
90: permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option.
91:
92: Starting in 7.64.0, libcurl will specifically prevent "Cookie:" headers
93: from being sent to other hosts than the first used one, unless specifically
94: permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option.
95: .SH DEFAULT
96: NULL
97: .SH PROTOCOLS
98: HTTP
99: .SH EXAMPLE
100: .nf
101: CURL *curl = curl_easy_init();
102:
103: struct curl_slist *list = NULL;
104:
105: if(curl) {
106: curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
107:
108: list = curl_slist_append(list, "Shoesize: 10");
109: list = curl_slist_append(list, "Accept:");
110:
111: curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list);
112:
113: curl_easy_perform(curl);
114:
115: curl_slist_free_all(list); /* free the list again */
116: }
117: .fi
118:
119: .SH AVAILABILITY
120: As long as HTTP is enabled
121: .SH RETURN VALUE
122: Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
123: .SH "SEE ALSO"
124: .BR CURLOPT_CUSTOMREQUEST "(3), " CURLOPT_HEADEROPT "(3), "
125: .BR CURLOPT_PROXYHEADER "(3), " CURLOPT_HEADER "(3)"
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>