Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_HTTPHEADER.3, revision 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>