nbd_add_meta_context(3)

💅 nbd_add_meta_context(3) — the "ask the server to negotiate a metadata context" era

okay so bestie, this is a libnbd(3) page and the whole point of it is: nbd_add_meta_context — asking your server to negotiate a metadata context. that's it. that's the function. let's get into it 🫶

---

✨ SYNOPSIS ✨

#include <libnbd.h>

int nbd_add_meta_context (
      struct nbd_handle *h, const char *name
    );

that's the whole vibe. handle plus a name, and it hands you back an int. iconic.

---

🌸 DESCRIPTION 🌸

So here's the tea. While you're connecting, libnbd can negotiate zero or more metadata contexts with the server. And what even is a metadata context? It's a feature — think base:allocation — that describes the info you get back from the nbd_block_status_64(3) command. For base:allocation specifically, that's whether blocks of data are allocated, zero, or sparse. very that. ⭐

This call adds one metadata context to the list that's gonna get negotiated. Call it as many times as you need, no cap — the list just keeps growing. When the handle is first created the list is empty (literally empty, not a single thing in it), and you can peek at what's in there with nbd_get_nr_meta_contexts(3) and nbd_get_meta_context(3), or yeet the whole list away with nbd_clear_meta_contexts(3).

The NBD protocol caps meta context names at 4096 bytes, but don't get too comfy — servers may not support the full length. And the encoding of meta context names is always UTF-8. no exceptions, bestie.

Not all servers support all metadata contexts. sobs. 😭 To find out if a context actually got negotiated, call nbd_can_meta_context(3) after connecting. after. not before. iykyk.

The single parameter is the name of the metadata context — for example "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> ships defined constants starting with "LIBNBD_CONTEXT_" for some well-known contexts, but you're 100% free to pass in other contexts too. main character energy, do your thing 💅

Other metadata contexts are server-specific, but they include "qemu:dirty-bitmap:..." and "qemu:allocation-depth" for qemu-nbd (peep the qemu-nbd -B and -A options).

---

🎀 RETURN VALUE 🎀

If the call succeeds, the function returns 0. slay. ✨

---

💀 ERRORS 💀

On error, -1 is returned. not slay, but that's life.

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

The following parameters must not be NULL: "h", "name". For more information see "Non-NULL parameters" in libnbd(3). don't be that person who passes NULL. 🙈

---

👑 HANDLE STATE 👑

nbd_add_meta_context can be called when the handle is in the following states:

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

so like… created-but-not-connecting, or mid-handshake. those two. anywhere else and it's a no from the handle. 🧚

---

🌈 VERSION 🌈

This function first appeared in libnbd 1.0.

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

#define LIBNBD_HAVE_NBD_ADD_META_CONTEXT 1

---

🦋 SEE ALSO 🦋

nbd_block_status_64(3), nbd_can_meta_context(3), nbd_clear_meta_contexts(3), nbd_create(3), nbd_get_meta_context(3), nbd_get_nr_meta_contexts(3), libnbd(3).

go read them. all of them. obsessed. 💖

---

🍓 AUTHORS 🍓

Eric Blake

Richard W.M. Jones

---

💜 COPYRIGHT 💜

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

---

okay that's the whole page!! this one's from libnbd-1.25.8, dated 2026-10-13, and it's the nbd_add_meta_context(3) page — go negotiate some contexts bestie, ily, bye 🎀✨