1curl_easy_header(3) libcurl Manual curl_easy_header(3)
2
6 curl_easy_header - get an HTTP header
7
9 #include <curl/curl.h>
10 CURLHcode curl_easy_header(CURL *easy,
12 const char *name,
13 size_t index,
14 unsigned int origin,
15 int request,
16 struct curl_header **hout);
17
19 curl_easy_header(3) returns a pointer to a "curl_header" struct in hout
20 with data for the HTTP response header name. The case insensitive nul-
21 terminated header name should be specified without colon.
22 index 0 means asking for the first instance of the header. If the re‐
24 turned header struct has amount set larger than 1, it means there are
25 more instances of the same header name available to get. Asking for a
26 too big index makes CURLHE_BADINDEX get returned.
27 The origin argument is for specifying which headers to receive, as a
29 single HTTP transfer might provide headers from several different
30 places and they may then have different importance to the user and
31 headers using the same name might be used. The origin is a bitmask for
32 what header sources you want. See the descriptions below.
33 The request argument tells libcurl from which request you want headers
35 from. A single transfer might consist of a series of HTTP requests and
36 this argument lets you specify which particular individual request you
37 want the headers from. 0 being the first request and then the number
38 increases for further redirects or when multi-state authentication is
39 used. Passing in -1 is a shortcut to "the last" request in the series,
40 independently of the actual amount of requests used.
41 libcurl stores and provides the actually used "correct" headers. If for
43 example two headers with the same name arrive and the latter overrides
44 the former, then only the latter will be provided. If the first header
45 survives the second, then only the first one will be provided. An ap‐
46 plication using this API does not have to bother about multiple headers
47 used wrongly.
48 The memory for the returned struct is associated with the easy handle
50 and subsequent calls to curl_easy_header(3) will clobber the struct
51 used in the previous calls for the same easy handle. Applications need
52 to copy the data if it wants to keep it around. The memory used for the
53 struct gets freed with calling curl_easy_cleanup(3) of the easy handle.
54 The first line in an HTTP response is called the status line. It is not
56 considered a header by this function. Headers are the "name: value"
57 lines following the status.
58 This function can be used before (all) headers have been received and
60 is fine to call from within libcurl callbacks. It will always return
61 the state of the headers at the time it is called.
62
64 struct curl_header {
65 char *name;
66 char *value;
67 size_t amount;
68 size_t index;
69 unsigned int origin;
70 void *anchor;
71 };
72 The data name field points to, will be the same as the requested name
74 but it might have a different case.
75 The data value field points to, comes exactly as delivered over the
77 network but with leading and trailing whitespace and newlines stripped
78 off. The `value` data is nul-terminated. For legacy HTTP/1 "folded
79 headers", this API provides the full single value in an unfolded manner
80 with a single whitespace between the lines.
81 amount is how many headers using this name that exist, within the ori‐
83 gin and request scope asked for.
84 index is the zero based entry number of this particular header, which
86 in case this header was used more than once in the requested scope can
87 be larger than 0 but is always less than amount.
88 The origin field in the "curl_header" struct has one of the origin bits
90 set, indicating where from the header originates. At the time of this
91 writing, there are 5 bits with defined use. The undocumented 27 remain‐
92 ing bits are reserved for future use and must not be assumed to have
93 any particular value.
94 anchor is a private handle used by libcurl internals. Do not modify.
96
98 CURLH_HEADER
99 The header arrived as a header from the server.
100 CURLH_TRAILER
102 The header arrived as a trailer. A header that arrives after the
103 body.
104 CURLH_CONNECT
106 The header arrived in a CONNECT response. A CONNECT request is
107 being done to setup a transfer "through" an HTTP(S) proxy.
108 CURLH_1XX
110 The header arrived in an HTTP 1xx response. A 1xx response is an
111 "intermediate" response that might happen before the "real" re‐
112 sponse.
113 CURLH_PSUEDO
115 The header is an HTTP/2 or HTTP/3 pseudo header
116
118 struct curl_header *type;
119 CURLHcode h =
120 curl_easy_header(easy, "Content-Type", 0, CURLH_HEADER, -1, &type);
121
123 Added in 7.83.0. Officially supported since 7.84.0.
124
126 This function returns a CURLHcode indicating success or error.
127 CURLHE_BADINDEX (1)
129 There is no header with the requested index.
130 CURLHE_MISSING (2)
132 No such header exists.
133 CURLHE_NOHEADERS (3)
135 No headers at all have been recorded.
136 CURLHE_NOREQUEST (4)
138 There was no such request number.
139 CURLHE_OUT_OF_MEMORY (5)
141 Out of resources
142 CURLHE_BAD_ARGUMENT (6)
144 One or more of the given arguments are bad.
145 CURLHE_NOT_BUILT_IN (7)
147 HTTP or the header API has been disabled in the build.
148
150 curl_easy_nextheader(3), curl_easy_perform(3), CURLOPT_HEADERFUNC‐
151 TION(3), CURLINFO_CONTENT_TYPE(3)
152libcurl 7.85.0 May 17, 2022 curl_easy_header(3)