CURLOPT_STREAM_DEPENDS(3)

📦
version 8.18.0 · 25 versions
, in fedora 44

💅 CURLOPT_STREAM_DEPENDS(3) — the "stream this transfer depends on" one

ok so this page lives in the Library Functions Manual section of the libcurl docs, and honestly bestie, it's a little bit of a sad story (deprecation arc 😭) but we're gonna get through it together.

🌸 NAME 🌸

CURLOPT_STREAM_DEPENDS — literally "stream this transfer depends on". that's the whole vibe. a stream that has a dependency.

✨ SYNOPSIS ✨

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_DEPENDS,
                          CURL *dephandle);

look at that signature. two handles. one of them is the dependee, one is the depender. bestie energy fr fr 🫶

💖 DESCRIPTION 💖

So here's the tea. You pass a CURL pointer in dephandle to identify the stream — within the same connection — that this stream is depending upon. it's giving "you're my emotional support stream" 💅

Important bits, no cap:

  • This option clears the exclusive bit.
  • It is mutually exclusive to the CURLOPT_STREAM_DEPENDS_E(3) option. like, pick one. you can't have both. that's not the vibe.

The spec says — and I'm quoting here because it's iconic — "Including a dependency expresses a preference to allocate resources to the identified stream rather than to the dependent stream." so basically you're telling the server "hey, feed my friend first 🍓".

You can set this option during transfer. it's flexible like that ✨

⚠️ okay so the rules, and these are real rules: dephandle must not be the same as handle — if it is, this function returns an error. periodt. It must be another easy handle, and it also needs to be a handle of a transfer that's about to be sent over the same HTTP/2 connection for this option to have an actual effect. otherwise it's just screaming into the void 😭

And now the sad part 🙈 — since version 8.21.0 setting this option no longer has an effect. HTTP/2 stream dependencies were introduced in RFC 7540 and then later deprecated in RFC 9113. they really said "we don't do that anymore". rip to a real one 💀

🎀 DEFAULT 🎀

NULL

like, nothing. nobody's depending on anybody. independent queen behavior 👑

🌈 PROTOCOLS 🌈

This functionality affects http only. just http. that's it. that's the list.

🦋 EXAMPLE 🦋

int main(void)
{
  CURL *curl = curl_easy_init();
  CURL *curl2 = curl_easy_init(); /* a second handle */
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one");

    /* the second depends on the first */
    curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two");
    curl_easy_setopt(curl2, CURLOPT_STREAM_DEPENDS, curl);

    /* then add both to a multi handle and transfer them */
  }
}

see how curl2 is like "I depend on curl"? cute. very sibling energy. the comment even says it: the second depends on the first 🫶 (and yes, you do have to add both to a multi handle and transfer them yourself — the comment says so, I don't make the rules)

💀 DEPRECATED 💀

Deprecated since 8.21.0. she's retired but she's still iconic, okay? 👑

⭐ AVAILABILITY ⭐

Added in curl 7.46.0. so she had a good run, ngl.

🔥 RETURN VALUE 🔥

curl_easy_setopt(3) returns a CURLcode indicating success or error.

  • CURLE_OK (0) means everything was OK 🎉
  • non-zero means an error occurred 😭 — see libcurl-errors(3) for the whole encyclopedia of what went wrong.

👑 SEE ALSO 👑

that's the whole page bestie, you ate that 💅✨

🧚 signing off: this was libcurl, dated 2026-10-12, page CURLOPT_STREAM_DEPENDS(3). streams may come and go but the manual page remains 🎀
📦 where this page comes from