nbd_opt_extended_headers(3)

📦
version 1.25.8 · 16 versions
, in centos-stream 10

💅 nbd_opt_extended_headers(3) — libnbd, bestie edition

Okay so literally the whole vibe of this page is nbd_opt_extended_headers, a libnbd function, and yes it's a whole thing and we're gonna get into it. Grab a snack. 🍓

✨ NAME ✨

nbd_opt_extended_headers — politely (or not so politely) asking the server to enable extended headers.

🎀 SYNOPSIS 🎀

#include <libnbd.h>

int nbd_opt_extended_headers (
      struct nbd_handle *h
    );

🌸 DESCRIPTION 🌸

So basically: you're requesting that the server use extended headers, by sending NBD_OPT_EXTENDED_HEADERS. That's the whole errand. 🫶

Now the important caveats, because there are layers to this:

  • This can only be used if nbd_set_opt_mode(3) enabled option mode. No opt mode, no service, periodt.
  • Furthermore, libnbd defaults to automatically requesting this unless you use nbd_set_request_extended_headers(3) or nbd_set_request_structured_replies(3) prior to connecting. So like, it's already doing it for you unless you intervened. Main character energy of libnbd tbh.
  • This function is mainly useful for integration testing of corner cases in server handling. It's giving "lab coat", not "everyday use".

Here's how the return values go, no cap:

  • This function returns true if the server replies with success.
  • It returns false if the server replies with an error.
  • It fails only if the server does not reply (such as for a loss of connection). 😭
Also, heads up: some servers fail a second request as redundant. Not a libnbd problem, just how it is. libnbd assumes that once one request has succeeded, then extended headers are supported (as visible by nbd_get_extended_headers_negotiated(3)) regardless if later calls to this function return false. So don't spiral if a repeat call says false — the negotiation already ate. 💀

And one more gem: if this function returns true, the use of structured replies is implied. Implied! Like it doesn't even have to say it out loud. 💅

⭐ RETURN VALUE ⭐

This call returns a boolean value. That's it, that's the section. Simple, iconic, done.

😭 ERRORS 😭

On error -1 is returned.

Refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error.

The following parameters must not be NULL: "h". For more information see "Non-NULL parameters" in libnbd(3).

🔥 HANDLE STATE 🔥

nbd_opt_extended_headers can be called when the handle is in the following state — this is the vibe check and honestly only one row passes:

  • Handle created, before connecting — ❌ error
  • Connecting — ❌ error
  • Connecting & handshaking (opt_mode) — ✅ allowed
  • Connected to the server — ❌ error
  • Connection shut down — ❌ error
  • Handle dead — ❌ error

So yeah, opt mode handshaking only. It's a very exclusive club, iykyk. 👑

🦋 VERSION 🦋

This function first appeared in libnbd 1.18.

If you need to test if this function is available at compile time check if the following macro is defined:

#define LIBNBD_HAVE_NBD_OPT_EXTENDED_HEADERS 1

🌈 SEE ALSO 🌈

The whole friend group fr fr. 🫶

💖 AUTHORS 💖

Eric Blake

Richard W.M. Jones

Copyright Red Hat

📜 LICENSE 📜

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

And that's the page!! 🧚 Signing off from libnbd-1.25.8, dated 2026-10-13, still living at nbd_opt_extended_headers(3). Go forth and negotiate those extended headers, bestie. 💜✨

📦 where this page comes from