nbd_opt_list_meta_context(3)

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

✨ nbd_opt_list_meta_context — list available meta contexts, using implicit query list ✨

okay bestie, this is nbd_opt_list_meta_context(3) from the libnbd manual, and no cap it's a whole vibe once you get it. let's go 💅

🫶 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;

int nbd_opt_list_meta_context (
      struct nbd_handle *h,
      nbd_context_callback context_callback
    );

like, that's the whole signature. iconic. copy it exactly, don't @ me 💖

🌸 DESCRIPTION

so here's the tea ☕ — you're asking the server to list the available meta contexts associated with the export you already picked, i.e. the one from the most recent nbd_set_export_name(3) or nbd_connect_uri(3). and the queries it uses? those come from your prior calls to nbd_add_meta_context(3).

ngl if you wanted to hand in your own explicit query list instead of reusing the accumulated one, you want nbd_opt_list_meta_context_queries(3). different function, different vibe.

⚠️ this one only works if nbd_set_opt_mode(3) turned option mode on. no option mode, no listing. periodt.

the whole implicit-query-list situation, explained 🧚

the NBD protocol lets the client decide how many queries to throw at the server. rather than taking that query list as a parameter right here, libnbd literally reuses the current list of requested meta contexts that nbd_add_meta_context(3) set up. want a totally different list of queries? call nbd_clear_meta_contexts(3) first and rebuild it, bestie.

  • when the list is empty, a server will typically reply with all the contexts it supports 🌈
  • when the list is non-empty, the server replies only with the supported contexts that match what you asked for 🎯

and here's the sneaky part 🐍 — a server reply might be encoded to represent several feasible contexts within one string, rather than giving you multiple strings per actual context name that would genuinely succeed during nbd_opt_go(3). so yeah, it's still necessary to use nbd_can_meta_context(3) after connecting to find out which contexts are actually supported. don't skip that step fr fr.

the callback ✨

the "context" function gets called once per server reply, with whatever "user_data" you passed to this function, and with "name" supplied by the server.

😭 important warning: it is NOT safe to call nbd_add_meta_context(3) from within the context of the callback function. instead, your code must copy any "name" it needs for later use after this function completes. do that.

at present, the return value of the callback is ignored — although a return of -1 should be avoided 🙈.

the convenient bit 🎀

for convenience, when this function succeeds, it returns the number of replies returned by the server. cute, right?

reality check 💀

not all servers understand this request. and even when they do understand it, a server might:

  • intentionally send an empty list, because it doesn't support the requested context, or
  • hit a failure after delivering partial results

so this function may succeed even when no contexts are reported, or may fail but have a non-empty list. both are valid, bestie. breathe.

likewise, the NBD protocol does not specify an upper bound for the number of replies that might be advertised — so client code should be aware that a server may send a lengthy list 🔥. like, pack a snack.

⭐ RETURN VALUE

this call returns an integer ≥ 0. slay.

💀 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 info see "Non-NULL parameters" in libnbd(3).

👑 HANDLE STATE

nbd_opt_list_meta_context can be called when the handle is in the following state — vibe check time 🦋:

  • 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, only during handshaking with opt_mode on. main character window only 💅

🧚 VERSION

this function first appeared in libnbd 1.6 ⭐

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

#define LIBNBD_HAVE_NBD_OPT_LIST_META_CONTEXT 1

🌈 SEE ALSO

nbd_add_meta_context(3), nbd_aio_opt_list_meta_context(3), nbd_can_meta_context(3), nbd_clear_meta_contexts(3), nbd_connect_uri(3), nbd_create(3), nbd_opt_go(3), nbd_opt_list_meta_context_queries(3), nbd_opt_set_meta_context(3), nbd_set_export_name(3), nbd_set_opt_mode(3), libnbd(3).

go read them all, i believe in you 🫶

💜 AUTHORS

  • Eric Blake
  • Richard W.M. Jones

absolute legends, both of them 👑

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 whole page bestie!! this drop is from libnbd-1.25.8, dated 2026-10-13, and it's nbd_opt_list_meta_context(3) — go forth and list those contexts 💖✨🎀

📦 where this page comes from