nbd_get_size(3)

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

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

okay so bestie, this is a page from the LIBNBD manual set, and it's about one tiny little function that does one big important thing. buckle up 🎀

✨ NAME ✨

nbd_get_size — returns the size of the export. that's it. that's the whole personality. it tells you how big the thing is 💖

🌸 SYNOPSIS 🌸

#include <libnbd.h>

int64_t nbd_get_size (
          struct nbd_handle *h
        );

so you include the header, you hand it your handle, it hands you back an int64_t. simple. iconic. no notes 🫶

🦋 DESCRIPTION 🦋

bestie, it returns the size in bytes of the NBD export. that's the whole vibe. bytes. of the export. slay.

but listen — there's one lil caveat you need to know about. this call fails with EOVERFLOW in the extremely unlikely scenario where the server advertises a size that literally cannot fit in a 64-bit signed integer. like, imagine a disk so big it breaks math. yeah. that one server. 😭

also good to know: the --size option of nbdinfo(1) is the way to reach this API from shell scripts, so if you're scripting and not writing C, that's your girl 💅

🔥 RETURN VALUE 🔥

this call returns a 64 bit signed integer ≥ 0. non-negative, always. that's the promise ✨

💀 ERRORS 💀

on error, -1 is returned. yep, that classic.

if you want the actual details of what went wrong, check out "ERROR HANDLING" in libnbd(3) — that's where the real tea lives.

and heads up: the following parameters must not be NULL: "h". for more info check "Non-NULL parameters" in libnbd(3). don't be passing it a null handle, bestie, it will not go well 🙈

🌈 NOTES 🌈

⭐ Non-blocking call

this call does not block, because it returns data that's already saved in the handle from the NBD protocol handshake. so it's not making a whole round trip to the server — it's just reading what it already knows. fast. efficient. main character energy 👑

👑 HANDLE STATE 👑

you can call nbd_get_size when the handle is in these states:

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

so basically: once the handshake is happening, you're good. before that? nope. after it's dead? also nope 💅

🧚 VERSION 🧚

this function first appeared in libnbd 1.0. an OG, fr fr.

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

#define LIBNBD_HAVE_NBD_GET_SIZE 1

🍓 EXAMPLE 🍓

this example is also available as examples/get-size.c in the libnbd source code, so you can go grab it and poke at it yourself 🫶

/* This example shows how to connect to an NBD
 * server and read the size of the disk.
 *
 * You can test it with nbdkit like this:
 *
 * nbdkit -U - memory 1M \
 *   --run './get-size $unixsocket'
 */

#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <inttypes.h>

#include <libnbd.h>

int
main (int argc, char *argv[])
{
  struct nbd_handle *nbd;
  int64_t size;

  if (argc != 2) {
    fprintf (stderr, "%s socket\n", argv[0]);
    exit (EXIT_FAILURE);
  }

  /* Create the libnbd handle. */
  nbd = nbd_create ();
  if (nbd == NULL) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Connect to the NBD server over a
   * Unix domain socket.
   */
  if (nbd_connect_unix (nbd, argv[1]) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Read the size in bytes and print it. */
  size = nbd_get_size (nbd);
  if (size == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }
  printf ("%s: size = %" PRIi64 " bytes\n",
          argv[1], size);

  /* Close the libnbd handle. */
  nbd_close (nbd);

  exit (EXIT_SUCCESS);
}

like, look at her go. create the handle, connect over a unix domain socket, read the size, print it, close it, done. a full little story arc 😭💖

💜 SEE ALSO 💜

🎀 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

real talk: that license text is not a vibe, it's a whole legal document, but bestie we keep it verbatim because that's how licenses work 😤

and that's the page!! this one's from libnbd-1.25.8, dated 2026-10-13, and it lives in section 3 of the manual (nbd_get_size(3)). go forth and measure some disks 💖✨🦋

📦 where this page comes from