nbd_block_status_64(3)

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

✨ nbd_block_status_64 — the libnbd page, but make it make sense ✨

okay so before we even start: this is a libnbd(3) manual page, section 3, and it's about sending a block status command with a 64-bit callback. yes i know that sounds like a lot. it's fine. we're gonna get through it together 💖

💅 NAME

nbd_block_status_64 — send block status command, with 64-bit callback

🎀 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_64 (
      struct nbd_handle *h, uint64_t count,
      uint64_t offset,
      nbd_extent64_callback extent64_callback,
      uint32_t flags
    );

like, copy that verbatim bestie, don't be creative with a function signature 🙈

🌸 DESCRIPTION

So you're issuing the block status command to the NBD server. If the server supports it, this makes metadata context info about blocks beginning from the specified offset come back to you. 🦋

Real talk about count: it's a hint. The server may choose to return less status, and the final block may extend beyond the requested range. And when multiple contexts are supported? The number of blocks and the cumulative length of those blocks need not be identical between contexts. This command generally returns the status of all negotiated contexts — though some servers also support a filtered request (peep nbd_can_block_status_payload(3) and nbd_block_status_filter(3)).

⚠️ not all servers can support a count of 4GiB or larger. nbd_get_extended_headers_negotiated(3) tells you which servers will actually parse a request bigger than 32 bits. The NBD protocol does not yet have a way for a client to learn if the server will enforce an even smaller maximum block status size, although a future extension may add a constraint visible in nbd_get_block_size(3). so like... be aware 😭

Depending on which metadata contexts were enabled before connecting (see nbd_add_meta_context(3)) and which ones the server supports (see nbd_can_meta_context(3)), this call returns extent info by calling back to the extent64 function.

💀 Important vibe check: the callback cannot call nbd_* APIs on the same handle — it holds the handle lock, so that's a deadlock, not a cute look.

If the callback returns -1, and no earlier error has been detected, then the whole block status command fails with whatever non-zero value got stored into the callback's error parameter (default is EPROTO). But — and this is the icon behavior — any further contexts will still invoke the callback. 🫶

🧚 the callback, explained

The extent64 function is called once per type of metadata available, with the user_data you passed to this function.

  • metacontext — a string like base:allocation.
  • entries — an array of nbd_extent structs, each holding the length (in bytes) of the block and a status/flags field that's specific to the metadata context.
  • nr_entries — the number of array entries passed to the function.
  • error — on entry to the callback, this contains the errno value of any previously detected error.

The NBD protocol document, in the section about NBD_REPLY_TYPE_BLOCK_STATUS, describes the meaning of this array. For contexts known to libnbd, <libnbd.h> contains constants beginning with LIBNBD_STATE_ that may help you decipher the values. ⭐

🙈 also: it is possible for the extent function to be called more times than you expect (if the server is buggy), so always check the metacontext field to make sure you're getting the data you expect. And it's also possible the extent function is not called at all, even for metadata contexts you requested — which means either the server doesn't support the context or for some other reason can't return the data.

🔥 the flags parameter

flags may be 0 for no flags, or may contain LIBNBD_CMD_FLAG_REQ_ONE, meaning the server should return only one extent per metadata context where that extent does not exceed count bytes. However — and say it with me — libnbd does not validate that the server obeyed the flag. 👑

💜 RETURN VALUE

If the call is successful, the function returns 0. that's it. that's the whole vibe.

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

🌈 NOTES

Strict call

By default, libnbd will reject attempts to use this function with parameters that are likely to result in server failure — things like requesting an unknown command flag. The nbd_set_strict_mode(3) function can be used to alter which scenarios should await a server reply rather than failing fast. no cap, it's just looking out for you 🎀

👑 HANDLE STATE

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

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

so basically: connect first. main character energy only happens after the handshake, bestie 💅

🍓 VERSION

This function first appeared in libnbd 1.18.

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

#define LIBNBD_HAVE_NBD_BLOCK_STATUS_64 1

🦋 SEE ALSO

nbd_add_meta_context(3), nbd_aio_block_status_64(3), nbd_block_status(3), nbd_block_status_filter(3), nbd_can_block_status_payload(3), nbd_can_meta_context(3), nbd_create(3), nbd_get_block_size(3), nbd_get_extended_headers_negotiated(3), nbd_set_strict_mode(3), libnbd(3).

🌸 AUTHORS

Eric Blake

Richard W.M. Jones

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, you ate that 🫶✨ this was libnbd-1.25.8, dated 2026-10-13, and yes it's nbd_block_status_64(3) — go forth and query those extents, bestie 💅👑

📦 where this page comes from