nbd_aio_opt_li...context_queries(3)

💅 nbd_aio_opt_list_meta_context_queries(3) — like, the libnbd manual, but make it make sense

okay so real talk, bestie: this is a page out of the libnbd manual (section 3, the library-functions section, iykyk), and the function we're stanning today is nbd_aio_opt_list_meta_context_queries. long name, big energy, absolutely worth it. let's get into it 🎀

---

✨ NAME ✨

nbd_aio_opt_list_meta_context_queries — ask the server to spill the list of available meta contexts, and you get to bring your own explicit query list instead of vibing off an implicit one. it's giving "i know what i want." 💅

---

🌸 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_list_meta_context_queries (
      struct nbd_handle *h, char **queries,
      nbd_context_callback context_callback,
      nbd_completion_callback completion_callback
    );

two callback structs and one function, all copy-paste-ready. slay. ✨

---

🦋 DESCRIPTION 🦋

so here's the vibe: you're asking the server to list the meta contexts that are available and associated with the export you already picked out — the one you set with the most recent nbd_set_export_name(3) or nbd_connect_uri(3). and very importantly, you're handing over an explicit list of queries as a parameter. main character behavior, honestly.

🫶 quick side note: if you'd rather reuse an implicit query list instead, go see nbd_aio_opt_list_meta_context(3). different function, different vibe.

this function is only usable if nbd_set_opt_mode(3) turned option mode on. no option mode, no entry. periodt.

now, how do you know when the request is done? two ways, bestie:

• wait for nbd_aio_is_connecting(3) to return false, or
• supply the optional completion_callback, which gets invoked exactly as described in "Completion callbacks" in libnbd(3) — with one iconic twist: it is automatically retired regardless of return value.

💀 also ngl, important: figuring out whether the server returned 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 care about errors, bring the callback. no cap.

---

⭐ RETURN VALUE ⭐

this call returns an integer ≥ 0. cute, simple, we love that for us. 💖

---

💀 ERRORS 💀

on error, -1 is returned. 😭

for how to get further details of the error, refer to "ERROR HANDLING" in libnbd(3) — it's all laid out for you there.

these parameters must not be NULL: h, queries. for more info, see "Non-NULL parameters" in libnbd(3). don't try it. 🙈

---

👑 HANDLE STATE 👑

nbd_aio_opt_list_meta_context_queries 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: one green light, five red lights. the only window is connecting & handshaking with opt_mode. catch it at exactly the right moment, bestie. 🧚

---

🌈 VERSION 🌈

this function first appeared in libnbd 1.16. 🔥

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

#define LIBNBD_HAVE_NBD_AIO_OPT_LIST_META_CONTEXT_QUERIES 1

iykyk, that macro is your bestie at build time. 🫶

---

🍓 SEE ALSO 🍓

nbd_aio_is_connecting(3), nbd_aio_opt_list_meta_context(3), nbd_connect_uri(3), nbd_create(3), nbd_opt_list_meta_context_queries(3), nbd_set_export_name(3), nbd_set_opt_mode(3), libnbd(3).

go read all of them, i believe in you. 📚✨

---

💜 AUTHORS 💜

Eric Blake

Richard W.M. Jones

absolute icons, both of them. 👑

---

🎀 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

---

aaand that's the whole page, bestie — no notes, you ate that. 🫶 this was libnbd-1.25.8, dated 2026-10-1, and yes i remembered the date so you don't have to. now go forth and list those meta contexts. 💖🦋✨