Imported Upstream version 7.44.0

[platform/upstream/curl.git] / docs / libcurl / opts / CURLOPT_HTTPHEADER.3

diff --git a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3
index 10fcf08..cd50431 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3
+++ b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -63,21 +63,48 @@ Pass a NULL to this option to reset back to no custom headers.
 
 The most commonly replaced headers have "shortcuts" in the options
 \fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP and
-\fICURLOPT_REFERER(3)\fP.
+\fICURLOPT_REFERER(3)\fP. We recommend using those.
 
 There's an alternative option that sets or replaces headers only for requests
 that are sent with CONNECT to a proxy: \fICURLOPT_PROXYHEADER(3)\fP. Use
 \fICURLOPT_HEADEROPT(3)\fP to control the behavior.
+.SH SECURITY CONCERNS
+By default, this option makes libcurl send the given headers in all HTTP
+requests done by this handle. You should therefore use this option with
+caution if you for example connect to the remote site using a proxy and a
+CONNECT request, you should to consider if that proxy is supposed to also get
+the headers. They may be private or otherwise sensitive to leak.
+
+Use \fICURLOPT_HEADEROPT(3)\fP to make the headers only get sent to where you
+intend them to get sent.
 .SH DEFAULT
 NULL
 .SH PROTOCOLS
 HTTP
 .SH EXAMPLE
-TODO
+.nf
+CURL *curl = curl_easy_init();
+
+struct curl_slist *list = NULL;
+
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+
+  list = curl_slist_append(list, "Shoesize: 10");
+  list = curl_slist_append(list, "Accept:");
+
+  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list);
+
+  curl_easy_perform(curl);
+
+  curl_slist_free_all(list); /* free the list again */
+}
+.fi
+
 .SH AVAILABILITY
 As long as HTTP is enabled
 .SH RETURN VALUE
 Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
 .SH "SEE ALSO"
 .BR CURLOPT_CUSTOMREQUEST "(3), " CURLOPT_HEADEROPT "(3), "
-.BR CURLOPT_PROXYHEADER "(3)"
+.BR CURLOPT_PROXYHEADER "(3), " CURLOPT_HEADER "(3)"