curl_easy_nextheader(3)

💅 curl_easy_nextheader — get the next HTTP header 🎀

okay bestie, so this is a page from the libcurl manual, and honestly? it's a good one. let's get into it ✨

---

🌸 NAME 🌸

curl_easy_nextheader — literally just get the next HTTP header, that's the whole gig 💖

---

✨ SYNOPSIS ✨

#include <curl/curl.h>

struct curl_header *curl_easy_nextheader(CURL *easy,
                                         unsigned int origin,
                                         int request,
                                         struct curl_header *prev);

---

🦋 DESCRIPTION 🦋

okay so this function lets your app iterate over all the HTTP headers it already received. like, every single one. no cap. 🫶

The origin argument is there so you can say which headers you actually want, because a single HTTP transfer can pull headers from several different places, and those places might matter differently to you — plus headers with the same name might show up more than once. origin is a bitmask of the header sources you want. the origin descriptions live over in the curl_easy_header(3) man page, so go peek at that 💅

The request argument tells libcurl which request you want headers from. a single transfer can be a whole series of HTTP requests, and this arg lets you point at one specific individual request. 0 is the first request, and then the number goes up for further redirects or when multi-state authentication is used. passing in -1 is a shortcut for "the last" request in the series — independently of how many requests actually got used. iconic shortcut behavior, honestly 🌈

✨ pro tip from the man page itself: it's suggested that you pass in the same origin and request while iterating over a range of headers, because changing the value mid-loop might give you unexpected results. so don't do that 🙈

If prev is NULL, this function returns a pointer to the first header stored within the given scope (origin + request). 🍓

If prev is a pointer to a previously returned header struct, curl_easy_nextheader(3) returns a pointer to the next header stored within the given scope. that's how your app can iterate over all the available headers, one at a time. slay 💀

the memory for the struct this points to is owned and managed by libcurl, and it's associated with the easy handle. so applications must copy the data if they want it to survive subsequent API calls or the lifetime of the easy handle. fr fr, copy it if you're keeping it 👑

---

🌈 PROTOCOLS 🌈

This functionality affects http only. that's it. that's the protocol. 🎀

---

💖 EXAMPLE 💖

int main(void)
{
  struct curl_header *prev = NULL;
  struct curl_header *h;

  CURL *curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
    curl_easy_perform(curl);

    /* extract the normal headers from the first request */
    while((h = curl_easy_nextheader(curl, CURLH_HEADER, 0, prev))) {
      printf("%s: %s\n", h->name, h->value);
      prev = h;
    }

    /* extract the normal headers + 1xx + trailers from the last request */
    unsigned int origin = CURLH_HEADER | CURLH_1XX | CURLH_TRAILER;
    while((h = curl_easy_nextheader(curl, origin, -1, prev))) {
      printf("%s: %s\n", h->name, h->value);
      prev = h;
    }
  }
}

look at that loop go. main character energy, honestly 🔥

---

⭐ AVAILABILITY ⭐

Added in curl 7.83.0 — so if you're on anything older, sorry bestie 😭

---

🧚 RETURN VALUE 🧚

This function returns the next header, or NULL when there are no more (matching) headers or an error occurred. 💜

And if this function returns NULL when prev was set to NULL, then there are no headers available within the scope to return. vibe check: empty. 🌸

---

👑 SEE ALSO 👑

• curl_easy_header(3)
• curl_easy_perform(3)

---

that's the whole page, bestie — go forth and iterate 🦋

mwah 💋 — this one's from the libcurl manual, dated 2026-10-12. see you in the next header 🎀✨