curl/docs/libcurl/curl_easy_header.3

.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 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 https://curl.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
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_header 3 "13 March 2022" "libcurl" "libcurl"
.SH NAME
curl_easy_header - get an HTTP header
.SH SYNOPSIS
.nf
#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);
.fi
.SH DESCRIPTION
\fIcurl_easy_header(3)\fP returns a pointer to a "curl_header" struct in
\fBhout\fP with data for the HTTP response header \fIname\fP. The case
insensitive null-terminated header name should be specified without colon.

\fIindex\fP 0 means asking for the first instance of the header. If the
returned header struct has \fBamount\fP 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 \fBCURLHE_BADINDEX\fP get returned.

The \fIorigin\fP 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 \fIorigin\fP is a bitmask for what header sources you
want. See the descriptions below.

The \fIrequest\fP 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 is provided. If the first header survives the
second, then only the first one is provided. An application using this API
does not have to bother about multiple headers used wrongly.

The memory for the returned struct is associated with the easy handle and
subsequent calls to \fIcurl_easy_header(3)\fP 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 \fIcurl_easy_cleanup(3)\fP 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 returns the state of the headers at
the time it is called.
.SH "The header struct"
.nf
struct curl_header {
   char *name;
   char *value;
   size_t amount;
   size_t index;
   unsigned int origin;
   void *anchor;
};
.fi

The data \fBname\fP field points to, is the same as the requested name, but
might have a different case.

The data \fBvalue\fP field points to, comes exactly as delivered over the
network but with leading and trailing whitespace and newlines stripped
off. The `value` data is null-terminated. For legacy HTTP/1 "folded headers",
this API provides the full single value in an unfolded manner with a single
whitespace between the lines.

\fBamount\fP is how many headers using this name that exist, within the origin
and request scope asked for.

\fBindex\fP 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 \fBamount\fP.

The \fBorigin\fP 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 remaining bits are
reserved for future use and must not be assumed to have any particular value.

\fBanchor\fP is a private handle used by libcurl internals. Do not modify.
.SH ORIGINS
.IP CURLH_HEADER
The header arrived as a header from the server.
.IP CURLH_TRAILER
The header arrived as a trailer. A header that arrives after the body.
.IP CURLH_CONNECT
The header arrived in a CONNECT response. A CONNECT request is being done to
setup a transfer "through" an HTTP(S) proxy.
.IP CURLH_1XX
The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate"
response that might happen before the "real" response.
.IP CURLH_PSEUDO
The header is an HTTP/2 or HTTP/3 pseudo header
.SH EXAMPLE
.nf
int main(void)
{
  struct curl_header *type;
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLHcode h;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
    curl_easy_perform(curl);
    h = curl_easy_header(curl, "Content-Type", 0, CURLH_HEADER, -1, &type);
    curl_easy_cleanup(curl);
  }
}
.fi
.SH AVAILABILITY
Added in 7.83.0. Officially supported since 7.84.0.
.SH RETURN VALUE
This function returns a CURLHcode indicating success or error.
.SH "SEE ALSO"
.BR curl_easy_nextheader (3),
.BR curl_easy_perform (3),
.BR CURLINFO_CONTENT_TYPE (3),
.BR CURLOPT_HEADERFUNCTION (3),
.BR libcurl-errors (3)