curl_easy_header(3)

✨ NAME ✨

curl_easy_header — get an HTTP header, bestie. This is the curl_easy_header(3) page from the Library Functions Manual, and that's the whole NAME section. 🎀

---

🌸 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 🦋

Okay so curl_easy_header(3) hands you a pointer to a "curl_header" struct in hout, and that struct has the data for the HTTP response header name. The header name is case insensitive, null-terminated, and you specify it without the colon. Slay. 💅

index starts at 0, which means "gimme the first instance of this header." If the returned header struct has amount set larger than 1, that means there are more instances of the same header name available to get. Ask for a too big index and CURLHE_BADINDEX gets returned. 😭

The origin argument is for specifying which headers to receive, because a single HTTP transfer might provide headers from several different places. Those headers can have different importance to you, and headers using the same name might be used. origin is a bitmask for what header sources you want — descriptions are right below, bestie. 🫶

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 is the first request, 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. So an application using this API does not have to bother about multiple headers used wrongly. No cap. 👑

The memory for the returned struct is associated with the easy handle, and subsequent calls to curl_easy_header(3) clobber the struct used in the previous calls for the same easy handle. The application needs 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. Ngl, that cleanup detail is important. 🧚

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. 🎀

🧚 The header struct 🧚

struct curl_header {
   char *name;
   char *value;
   size_t amount;
   size_t index;
   unsigned int origin;
   void *anchor;
};

The name field points to the same name you requested, but it might have a different case. 🌈

The value field points to data that 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. 🍓

amount is how many headers using this name exist, within the origin and request scope asked for. 🔥

index is the zero based entry number of this particular header. If this header was used more than once in the requested scope, it can be larger than 0, but it 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 remaining 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 it. 🚫

🔥 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_PSEUDO — the header is an HTTP/2 or HTTP/3 pseudo header. 🌸

🌈 PROTOCOLS 🌈

This functionality affects http only. That's the vibe check, bestie — http only. 💅

💖 EXAMPLE 💖

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);
  }
}

🦋 AVAILABILITY 🦋

Added in curl 7.83.0. Iconic. 🎀

💜 RETURN VALUE 💜

This function returns a CURLHcode indicating success or error. CURLHE_OK (0) means everything was OK, non-zero means an error occurred — see libcurl-errors(3). Fr fr. 😭

👑 SEE ALSO 👑

CURLINFO_CONTENT_TYPE(3), CURLOPT_HEADERFUNCTION(3), curl_easy_nextheader(3), curl_easy_perform(3), libcurl-errors(3). 🫶

---

💖 That's the whole page, bestie! Source/version: libcurl, date: 2026-10-12 — curl_easy_header(3) signing off! 🎀✨