nbd_poll(3)

💅 nbd_poll — poll the handle once

okay so you're reading nbd_poll(3), which lives in the LIBNBD manual, and honestly? it's a little guy with a big job. let's get into it bestie ✨

---

🌸 SYNOPSIS

#include <libnbd.h>

int nbd_poll (
      struct nbd_handle *h, int timeout
    );

that's it. that's the whole vibe check. 🫶

---

🦋 DESCRIPTION

so this is basically a cute lil baby version of poll(2) — a simple implementation that libnbd uses internally for its synchronous API calls. no cap, it's the plumbing. 🔧

here's the tea on the return values, bestie:

• on success, it returns 0 if the timeout (in milliseconds, jsyk) happens — like, time's up, nothing happened, we just waited
• or it returns 1 if the poll completed and the state machine progressed — iconic, something actually happened 💅

set timeout to -1 to block indefinitely. but hear me out: be careful that eventual action is actually expected 😭 like, if the connection is established but there are no commands in flight, using an infinite timeout will permanently block. permanently. forever. not the main character moment you want.

lowkey the whole point of this function is that it's mainly useful as an example of how you might integrate libnbd with your own main loop — it's not really intended as something you would use. it's giving "teaching tool," not "production bae." 🌈

---

⭐ RETURN VALUE

this call returns an integer ≥ 0. slay. 🎀

---

💀 ERRORS

on error, -1 is returned. sad. 🙈

refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error — that's where the actual explanations live, iykyk.

also! the following parameters must not be NULL: "h". for more info see "Non-NULL parameters" in libnbd(3). don't be passing nulls, bestie, it's not cute. 💅

---

🔥 VERSION

this function first appeared in libnbd 1.0. vintage. iconic. 👑

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

#define LIBNBD_HAVE_NBD_POLL 1

---

🌟 EXAMPLE

this example is also available as examples/aio-connect-read.c in the libnbd source code. it's a whole journey, buckle up 🧚

/* This example shows how to use the AIO (asynchronous) low
 * level API to connect to a server and read the disk.
 *
 * Here are a few ways to try this example:
 *
 * nbdkit -U - linuxdisk . \
 *   --run './aio-connect-read $unixsocket'
 *
 * nbdkit -U - floppy . \
 *   --run './aio-connect-read $unixsocket'
 *
 * nbdkit -U - pattern size=1M \
 *   --run './aio-connect-read $unixsocket'
 */

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

#include <libnbd.h>

#define NR_SECTORS 32
#define SECTOR_SIZE 512

struct data {
  uint64_t offset;
  char sector[SECTOR_SIZE];
};

static int
hexdump (void *user_data, int *error)
{
  struct data *data = user_data;
  FILE *pp;

  if (*error) {
    errno = *error;
    perror ("failed to read");
    exit (EXIT_FAILURE);
  }

  printf ("sector at offset 0x%" PRIx64 ":\n",
          data->offset);
  pp = popen ("hexdump -C", "w");
  if (pp == NULL) {
    perror ("popen: hexdump");
    exit (EXIT_FAILURE);
  }
  fwrite (data->sector, SECTOR_SIZE, 1, pp);
  pclose (pp);
  printf ("\n");

  /* Returning 1 from the callback automatically retires
   * the command.
   */
  return 1;
}

static struct data data[NR_SECTORS];

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

  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.
   * This only starts the connection.
   */
  if (nbd_aio_connect_unix (nbd, argv[1]) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Wait for the connection to complete.  The use of
   * nbd_poll here is only as an example.  You could also
   * integrate this with poll(2), glib or another main
   * loop.  Read libnbd(3) and the source file lib/poll.c.
   */
  while (!nbd_aio_is_ready (nbd)) {
    if (nbd_poll (nbd, -1) == -1) {
      fprintf (stderr, "%s\n", nbd_get_error ());
      exit (EXIT_FAILURE);
    }
  }

  assert (nbd_get_size (nbd) >= NR_SECTORS * SECTOR_SIZE);

  /* Issue read commands for the first NR sectors. */
  for (i = 0; i < NR_SECTORS; ++i) {
    data[i].offset = i * SECTOR_SIZE;

    /* The callback (hexdump) is called when the command
     * completes.  The buffer must continue to exist while
     * the command is running.
     */
    if (nbd_aio_pread (nbd, data[i].sector, SECTOR_SIZE,
                       data[i].offset,
                       (nbd_completion_callback) {
                         .callback = hexdump,
                         .user_data = &data[i],
                       }, 0) == -1) {
      fprintf (stderr, "%s\n", nbd_get_error ());
      exit (EXIT_FAILURE);
    }
  }

  /* Run the main loop until all the commands have
   * completed and retired.  Again the use of nbd_poll
   * here is only as an example.
   */
  while (nbd_aio_in_flight (nbd) > 0) {
    if (nbd_poll (nbd, -1) == -1) {
      fprintf (stderr, "%s\n", nbd_get_error ());
      exit (EXIT_FAILURE);
    }
  }

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

  exit (EXIT_SUCCESS);
}

like, look at her go 😭 the while (!nbd_aio_is_ready (nbd)) loop and the while (nbd_aio_in_flight (nbd) > 0) loop are both just nbd_poll doing its thing as an example. you could totally swap in poll(2), glib, or another main loop instead — the man page literally says to go read libnbd(3) and the source file lib/poll.c for more 🫶

---

🍓 SEE ALSO

nbd_create(3), nbd_poll2(3), libnbd(3), poll(2). go click around, bestie, it's a whole ecosystem ✨

---

💜 AUTHORS

• Eric Blake
• Richard W.M. Jones

legends, honestly 👑

---

🌸 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

fr fr read the license, it's not just decorative 💀

---

okay that's the whole page, mwah 💋 this was nbd_poll(3) from libnbd-1.25.8, dated 2026-10-13 — drink water, don't pass NULL handles, and go poll something responsibly 🌈🦋