1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_HEADER
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_HEADERFUNCTION (3)
9  - CURLOPT_HTTPHEADER (3)
10---
11
12# NAME
13
14CURLOPT_HEADER - pass headers to the data stream
15
16# SYNOPSIS
17
18~~~c
19#include <curl/curl.h>
20
21CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADER, long onoff);
22~~~
23
24# DESCRIPTION
25
26Pass the long value *onoff* set to 1 to ask libcurl to include the headers
27in the write callback (CURLOPT_WRITEFUNCTION(3)). This option is
28relevant for protocols that actually have headers or other meta-data (like
29HTTP and FTP).
30
31When asking to get the headers passed to the same callback as the body, it is
32not possible to accurately separate them again without detailed knowledge
33about the protocol in use.
34
35Further: the CURLOPT_WRITEFUNCTION(3) callback is limited to only ever
36get a maximum of *CURL_MAX_WRITE_SIZE* bytes passed to it (16KB), while a
37header can be longer and the CURLOPT_HEADERFUNCTION(3) supports getting
38called with headers up to *CURL_MAX_HTTP_HEADER* bytes big (100KB).
39
40It is often better to use CURLOPT_HEADERFUNCTION(3) to get the header
41data separately.
42
43While named confusingly similar, CURLOPT_HTTPHEADER(3) is used to set
44custom HTTP headers!
45
46# DEFAULT
47
480
49
50# PROTOCOLS
51
52Most
53
54# EXAMPLE
55
56~~~c
57int main(void)
58{
59  CURL *curl = curl_easy_init();
60  if(curl) {
61    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
62
63    curl_easy_setopt(curl, CURLOPT_HEADER, 1L);
64
65    curl_easy_perform(curl);
66  }
67}
68~~~
69
70# AVAILABILITY
71
72Provided in all libcurl versions.
73
74# RETURN VALUE
75
76Returns CURLE_OK.
77