nbd_block_status_filter(3)

✨ nbd_block_status_filter(3) ✨

okay so real talk — this is a page from the LIBNBD manual, section 3 (library functions, iykyk). Pull up a chair bestie, we're learning about filtered block status with a big 64-bit callback 💅

---

🎀 NAME 🎀

nbd_block_status_filter — send a filtered block status command, with a 64-bit callback. that's the whole vibe fr fr.

---

🌸 SYNOPSIS 🌸

#include <libnbd.h>

typedef struct {
  int (*callback) (void *user_data,
                   const char *metacontext,
                   uint64_t offset, nbd_extent *entries,
                   size_t nr_entries, int *error);
  void *user_data;
  void (*free) (void *user_data);
} nbd_extent64_callback;

int nbd_block_status_filter (
      struct nbd_handle *h, uint64_t count,
      uint64_t offset, char **contexts,
      nbd_extent64_callback extent64_callback,
      uint32_t flags
    );

look at that struct. immaculate. no notes 👑

---

🦋 DESCRIPTION 🦋

so you issue a filtered block status command to the NBD server. if the server actually supports this (peep nbd_can_block_status_payload(3) for that), you get metadata context info about the blocks starting at the offset you specified — and the results are limited to just the contexts you listed in filter ✨. lowkey important: every single string in filter has to be supported by nbd_can_meta_context(3), no exceptions.

every other parameter on this function behaves exactly like it does in nbd_block_status_64(3). one cute lil convenience though: unless you used <nbd_set_strict_flags(3)> to disable LIBNBD_STRICT_AUTO_FLAG, libnbd just ignores whether you did or didn't put LIBNBD_CMD_FLAG_PAYLOAD_LEN in flags — while still correctly using that flag over the wire. so it's forgiving, not sloppy. periodt 💅

---

⭐ RETURN VALUE ⭐

if the call goes well, the function returns 0. slay.

---

💀 ERRORS 💀

on error, -1 comes back at you. 😭

for the deets on how to actually get the details of that error, go read ERROR HANDLING in libnbd(3).

also!! these parameters must not be NULL: h, contexts. for more on that, see Non-NULL parameters in libnbd(3). don't test it. 🙈

---

🌈 NOTES 🌈

✨ Strict call ✨

by default, libnbd will straight up reject attempts to use this function with parameters that are likely to make the server fail — like requesting a command flag nobody knows about, bestie, why would you. the nbd_set_strict_mode(3) function is how you alter which scenarios should wait for a server reply instead of failing fast. choose your own adventure 🧚

---

🫶 HANDLE STATE 🫶

nbd_block_status_filter can be called when the handle is in these states:

• Handle created, before connecting — ❌ error
• Connecting — ❌ error
• Connecting & handshaking (opt_mode) — ❌ error
• Connected to the server — ✅ allowed (this is the one!! the main character state 👑)
• Connection shut down — ❌ error
• Handle dead — ❌ error

---

🔥 VERSION 🔥

this function first appeared in libnbd 1.18. iconic behavior.

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

#define LIBNBD_HAVE_NBD_BLOCK_STATUS_FILTER 1

---

💜 SEE ALSO 💜

nbd_aio_block_status_filter(3), nbd_block_status_64(3), nbd_can_block_status_payload(3), nbd_can_meta_context(3), nbd_create(3), nbd_set_strict_mode(3), libnbd(3).

go read them. i'll wait. 🍓

---

🌟 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

---

and that's the whole page babes 💖 this lil beauty is from libnbd-1.25.8, dated 2026-10-13 — screenshot it, cite it, love it. bye bestie, go get that block status 🌸✨🦋