Return to CURLOPT_HTTPHEADER.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl / opts

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)"