.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2018, 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
-.\" * are also available at http://curl.haxx.se/docs/copyright.html.
+.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" *
.\" **************************************************************************
.\"
-.TH CURLOPT_HEADER 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
+.TH CURLOPT_HEADER 3 "February 16, 2018" "libcurl 7.59.0" "curl_easy_setopt options"
+
.SH NAME
CURLOPT_HEADER \- pass headers to the data stream
.SH SYNOPSIS
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADER, long onoff);
.SH DESCRIPTION
-Pass in \fIonoff\fP set to 1 to tell the library to include the header in the
-body output for requests with this \fIhandle\fP. This option is relevant for
-protocols that actually have headers or other meta-data (like HTTP and FTP).
+Pass the long value \fIonoff\fP set to 1 to ask libcurl to include the headers
+in the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP). This option is
+relevant for protocols that actually have headers or other meta-data (like
+HTTP and FTP).
-When asking to get the header info passed to the same callback as the body, it
-is not possible to accurately separate them again without detailed knowledge
+When asking to get the headers passed to the same callback as the body, it is
+not possible to accurately separate them again without detailed knowledge
about the protocol in use.
+Further: the \fCURLOPT_WRITEFUNCTION(3)\fP callback is limited to only ever
+get a maximum of \fICURL_MAX_WRITE_SIZE\fP bytes passed to it (16KB), while a
+header can be longer and the \fICURLOPT_HEADERFUNCTION(3)\fP supports getting
+called with headers up to \fICURL_MAX_HTTP_HEADER\fP bytes big (100KB).
+
It is often better to use \fICURLOPT_HEADERFUNCTION(3)\fP to get the header
data separately.
+
+While named confusingly similar, \fICURLOPT_HTTPHEADER(3)\fP is used to set
+custom HTTP headers!
.SH DEFAULT
0
+.SH PROTOCOLS
+Most
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+ curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+
+ curl_easy_setopt(curl, CURLOPT_HEADER, 1L);
+
+ curl_easy_perform(curl);
+}
+.fi
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HEADERFUNCTION "(3), "
+.BR CURLOPT_HTTPHEADER "(3), "