curl_easy_header - get an HTTP header
#include <curl/curl.h> CURLHcode curl_easy_header(CURL *easy, const char *name, size_t index, unsigned int origin, int request, struct curl_header **hout);
curl_easy_header(3) libcurl Manual curl_easy_header(3)
NAME
curl_easy_header - get an HTTP header
SYNOPSIS
#include <curl/curl.h>
CURLHcode curl_easy_header(CURL *easy,
const char *name,
size_t index,
unsigned int origin,
int request,
struct curl_header **hout);
DESCRIPTION
EXPERIMENTAL feature!
curl_easy_header(3) returns a pointer to a "curl_header" struct in hout
with data for the HTTP response header name. The case insensitive nul-
terminated header name should be specified without colon.
index 0 means asking for the first instance of the header. If the
returned header struct has amount set larger than 1, it means there are
more instances of the same header name available to get. Asking for a
too big index makes CURLHE_BADINDEX get returned.
The origin argument is for specifying which headers to receive, as a
single HTTP transfer might provide headers from several different
places and they may then have different importance to the user and
headers using the same name might be used. The origin is a bitmask for
what header sources you want. See the descriptions below.
The request argument tells libcurl from which request you want headers
from. A single transfer might consist of a series of HTTP requests and
this argument lets you specify which particular individual request you
want the headers from. 0 being the first request and then the number
increases for further redirects or when multi-state authentication is
used. Passing in -1 is a shortcut to "the last" request in the series,
independently of the actual amount of requests used.
libcurl stores and provides the actually used "correct" headers. If for
example two headers with the same name arrive and the latter overrides
the former, then only the latter will be provided. If the first header
survives the second, then only the first one will be provided. An
application using this API does not have to bother about multiple head-
ers used wrongly.
The memory for the returned struct is associated with the easy handle
and subsequent calls to curl_easy_header(3) will clobber the struct
used in the previous calls for the same easy handle. Applications need
to copy the data if it wants to keep it around. The memory used for the
struct gets freed with calling curl_easy_cleanup(3) of the easy handle.
The first line in an HTTP response is called the status line. It is not
considered a header by this function. Headers are the "name: value"
lines following the status.
This function can be used before (all) headers have been received and
is fine to call from within libcurl callbacks. It will always return
the state of the headers at the time it is called.
The header struct
struct curl_header {
char *name;
char *value;
size_t amount;
size_t index;
unsigned int origin;
void *anchor;
};
The data name field points to, will be the same as the requested name
but it might have a different case.
The data value field points to, comes exactly as delivered over the
network but with leading and trailing whitespace and newlines stripped
off. The `value` data is nul-terminated.
amount is how many headers using this name that exist, within the ori-
gin and request scope asked for.
index is the zero based entry number of this particular header, which
in case this header was used more than once in the requested scope can
be larger than 0 but is always less than amount.
The origin field in the "curl_header" struct has one of the origin bits
set, indicating where from the header originates. At the time of this
writing, there are 5 bits with defined use. The undocumented 27 remain-
ing bits are reserved for future use and must not be assumed to have
any particular value.
anchor is a private handle used by libcurl internals. Do not modify.
ORIGINS
CURLH_HEADER
The header arrived as a header from the server.
CURLH_TRAILER
The header arrived as a trailer. A header that arrives after the
body.
CURLH_CONNECT
The header arrived in a CONNECT response. A CONNECT request is
being done to setup a transfer "through" an HTTP(S) proxy.
CURLH_1XX
The header arrived in an HTTP 1xx response. A 1xx response is an
"intermediate" response that might happen before the "real"
response.
CURLH_PSUEDO
The header is an HTTP/2 or HTTP/3 pseudo header
EXAMPLE
struct curl_header *type;
CURLHcode h =
curl_easy_header(easy, "Content-Type", 0, CURLH_HEADER, -1, &type);
AVAILABILITY
Added in 7.83.0
RETURN VALUE
This function returns a CURLHcode indicating success or error.
CURLHE_BADINDEX (1)
There is no header with the requested index.
CURLHE_MISSING (2)
No such header exists.
CURLHE_NOHEADERS (3)
No headers at all have been recorded.
CURLHE_NOREQUEST (4)
There was no such request number.
CURLHE_OUT_OF_MEMORY (5)
Out of resources
CURLHE_BAD_ARGUMENT (6)
One or more of the given arguments are bad.
CURLHE_NOT_BUILT_IN (7)
HTTP or the header API has been disabled in the build.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | web/curl |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
SEE ALSO
curl_easy_nextheader(3), curl_easy_perform(3), CURLOPT_HEADERFUNC-
TION(3), CURLINFO_CONTENT_TYPE(3)
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from https://curl.se/down-
load/curl-7.83.1.tar.bz2.
Further information about this software can be found on the open source
community website at http://curl.haxx.se/.
libcurl 7.83.1 April 11, 2022 curl_easy_header(3)