nbd_aio_opt_set_meta_context(3)

✨ nbd_aio_opt_set_meta_context ✨

okay bestie, welcome to the libnbd manual, and this one is genuinely such a niche little icon 💅 — it's nbd_aio_opt_set_meta_context, and yes, the name is a mouthful, but we're gonna get through it together fr fr.

🎀 NAME 🎀

nbd_aio_opt_set_meta_context — pick specific meta contexts, with an implicit query list. that's the whole vibe ✨

🦋 SYNOPSIS 🦋

#include <libnbd.h>

typedef struct {
  int (*callback) (void *user_data, const char *name);
  void *user_data;
  void (*free) (void *user_data);
} nbd_context_callback;

typedef struct {
  int (*callback) (void *user_data, int *error);
  void *user_data;
  void (*free) (void *user_data);
} nbd_completion_callback;

int nbd_aio_opt_set_meta_context (
      struct nbd_handle *h,
      nbd_context_callback context_callback,
      nbd_completion_callback completion_callback
    );

like, look at those callback structs. so structured. so demure. 🫶

🌸 DESCRIPTION 🌸

so what this cutie actually does: it asks the server to supply all the recognized meta contexts you registered through earlier calls to nbd_add_meta_context(3), and it does that in conjunction with the export you already set with the most recent nbd_set_export_name(3) or nbd_connect_uri(3). iykyk 💖

the one big caveat: you can only use this if nbd_set_opt_mode(3) turned option mode on. no option mode, no function, periodt.

and ngl, normally this function is redundant — because nbd_opt_go(3) already does the exact same task automatically if structured replies or extended headers have already been negotiated. like it's literally already doing it for you bestie 😭

but! manual control over meta context requests is genuinely useful when you want fine-grained testing of how a server handles unusual negotiation sequences. that's the main character energy use case 👑 and often you'll couple this function with nbd_set_request_meta_context(3) to bypass the automatic context request that nbd_opt_go(3) normally performs.

so how do you know when the request is done? two options, bestie:

• wait for nbd_aio_is_connecting(3) to return false, or
• supply the optional completion_callback, which gets invoked as described in "Completion callbacks" in libnbd(3) — except that it's automatically retired regardless of return value. yes, regardless. it just leaves. iconic 💅

⚠️ heads up: detecting whether the server returns an error (which is what the return value of the synchronous counterpart does for you) is only possible with a completion callback. so if you wanna know, you gotta supply one. no cap.

⭐ RETURN VALUE ⭐

this call returns an integer ≥ 0. slay 🎀

💀 ERRORS 💀

on error, -1 is returned. rough, but that's life.

refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error. that's where the lore lives.

also, the following parameters must not be NULL: "h". for more info, see "Non-NULL parameters" in libnbd(3). don't be handing it a NULL handle, bestie, i'm begging 🙈

🦋 HANDLE STATE 🦋

nbd_aio_opt_set_meta_context can be called when the handle is in the following state:

• 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 basically: it's giving "only during handshaking in opt_mode" and nowhere else. the vibes are extremely specific 🌈

🧚 VERSION 🧚

this function first appeared in libnbd 1.16. baby girl is a 1.16 era legend ⭐

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

#define LIBNBD_HAVE_NBD_AIO_OPT_SET_META_CONTEXT 1

🔥 SEE ALSO 🔥

nbd_add_meta_context(3), nbd_aio_is_connecting(3), nbd_aio_opt_set_meta_context_queries(3), nbd_connect_uri(3), nbd_create(3), nbd_opt_go(3), nbd_opt_set_meta_context(3), nbd_set_export_name(3), nbd_set_opt_mode(3), nbd_set_request_meta_context(3), libnbd(3).

the whole friend group, assembled 🫶

👑 AUTHORS 👑

Eric Blake

Richard W.M. Jones

💜 COPYRIGHT 💜

Copyright Red Hat

🎀 LICENSE 🎀

legal era, bestie, gotta keep it exact:

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, bestie 💖 this was libnbd-1.25.8, dated 2026-10-13, and honestly? it ate. go forth and negotiate those meta contexts responsibly ✨🦋🎀