nbd_opt_list(3)

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

🌸 NAME 🌸

nbd_opt_list — request the server to list all exports during negotiation

This is the nbd_opt_list(3) page from the LIBNBD manual, bestie. It’s literally the group-chat move where you ask the server to spill the tea on every export it supports. 💅

✨ SYNOPSIS ✨

Here’s the exact shape, no cap:

        #include <libnbd.h>

        typedef struct {
          int (*callback) (void *user_data, const char *name,
                           const char *description);
          void *user_data;
          void (*free) (void *user_data);
        } nbd_list_callback;

        int nbd_opt_list (
              struct nbd_handle *h,
              nbd_list_callback list_callback
            );

💖 DESCRIPTION 💖

Okay so this call asks the server to list all the exports it supports. Important vibe check: you can only use it if nbd_set_opt_mode(3) enabled option mode. Periodt.

The "list" function gets called once per advertised export. It receives whatever "user_data" was passed to this function, plus "name" and "description" supplied by the server. Many servers omit descriptions, and in that case "description" will be an empty string. 🫶

⚠️ Do not call nbd_set_export_name(3) from within the context of the callback function — it is not safe. Your code must copy any "name" needed for later use after this function completes. At present, the return value of the callback is ignored, although a return of -1 should be avoided. 💀

For convenience, when this function succeeds, it returns the number of exports that were advertised by the server. Cute, right? 🎀

Not all servers understand this request, and even when it is understood, the server might intentionally send an empty list to avoid being an information leak, may encounter a failure after delivering partial results, or may refuse to answer more than one query per connection in the interest of avoiding negotiation that does not resolve. So yeah: this function may succeed even when no exports are reported, or may fail but have a non-empty list. 🙈

Likewise, the NBD protocol does not specify an upper bound for the number of exports that might be advertised, so client code should be aware that a server may send a lengthy list. It’s giving infinite scroll but make it negotiation. 😭

For nbd-server(1) you will need to allow clients to make list requests by adding "allowlist=true" to the "[generic]" section of /etc/nbd-server/config. For qemu-nbd(8), a description is set with -D. 🔥

👑 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 information see "Non-NULL parameters" in libnbd(3). Please don’t hand it a NULL, bestie — that’s not the vibe. 🫶

🦋 HANDLE STATE 🦋

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

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

⭐ VERSION ⭐

This function first appeared in libnbd 1.4.

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

#define LIBNBD_HAVE_NBD_OPT_LIST 1

🍓 EXAMPLE 🍓

This example is also available as examples/list-exports.c in the libnbd source code.

        /* This example shows how to list NBD exports.
         *
         * To test this with qemu-nbd:
         *   $ qemu-nbd -x "hello" -t -k /tmp/sock disk.img
         *   $ ./run examples/list-exports /tmp/sock
         *   [0] hello
         *   Which export to connect to (-1 to quit)? 0
         *   Connecting to hello ...
         *   /tmp/sock: hello: size = 2048 bytes
         *
         * To test this with nbdkit (requires 1.22):
         *   $ nbdkit -U /tmp/sock sh - <<\EOF
         *   case $1 in
         *     list_exports) echo NAMES; echo foo; echo foobar ;;
         *     open) echo "$3" ;;
         *     get_size) echo "$2" | wc -c ;;
         *     pread) echo "$2" | dd bs=1 skip=$4 count=$3 ;;
         *     *) exit 2 ;;
         *   esac
         *   EOF
         *   $ ./run examples/list-exports /tmp/sock
         *   [0] foo
         *   [1] foobar
         *   Which export to connect to (-1 to quit)? 1
         *   Connecting to foobar ...
         *   /tmp/sock: foobar: size = 7 bytes
         */

        #include <stdio.h>
        #include <stdlib.h>
        #include <stdbool.h>
        #include <stdint.h>
        #include <string.h>
        #include <inttypes.h>
        #include <errno.h>

        #include <libnbd.h>

        struct export_list {
          int i;
          char **names;
        };

        /* Callback function for nbd_opt_list */
        static int
        list_one (void *opaque, const char *name,
                  const char *description)
        {
          struct export_list *l = opaque;
          char **names;

          printf ("[%d] %s\n", l->i, name);
          if (*description)
            printf ("  (%s)\n", description);
          names = realloc (l->names,
                           (l->i + 1) * sizeof *names);
          if (!names) {
            perror ("realloc");
            exit (EXIT_FAILURE);
          }
          names[l->i] = strdup (name);
          if (!names[l->i]) {
            perror ("strdup");
            exit (EXIT_FAILURE);
          }
          l->names = names;
          l->i++;
          return 0;
        }

        int
        main (int argc, char *argv[])
        {
          struct nbd_handle *nbd;
          int i;
          const char *name;
          int64_t size;
          struct export_list list = { 0 };

          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);
          }

          /* Set opt mode. */
          nbd_set_opt_mode (nbd, true);

          /* Connect to the NBD server over a
           * Unix domain socket.  If we did not
           * end up in option mode, then a
           * listing is not possible.
           */
          if (nbd_connect_unix (nbd, argv[1]) == -1) {
            fprintf (stderr, "%s\n", nbd_get_error ());
            exit (EXIT_FAILURE);
          }
          if (!nbd_aio_is_negotiating (nbd)) {
            fprintf (stderr, "Server does not support "
                     "listing exports.\n");
            exit (EXIT_FAILURE);
          }

          /* Print the export list. */
          if (nbd_opt_list (nbd,
                            (nbd_list_callback) {
                              .callback = list_one,
                              .user_data = &list, }) == -1) {
            fprintf (stderr, "%s\n", nbd_get_error ());
            exit (EXIT_FAILURE);
          }

          /* Display the list of exports. */
          printf ("Which export to connect to? ");
          if (scanf ("%d", &i) != 1) exit (EXIT_FAILURE);
          if (i == -1) {
            if (nbd_opt_abort (nbd) == -1) {
              fprintf (stderr, "%s\n", nbd_get_error ());
              exit (EXIT_FAILURE);
            }
            nbd_close (nbd);
            exit (EXIT_SUCCESS);
          }
          if (i < 0 || i >= list.i) {
            fprintf (stderr, "index %d out of range", i);
            exit (EXIT_FAILURE);
          }
          name = list.names[i];
          printf ("Connecting to %s ...\n", name);

          /* Resume connecting to the chosen export. */
          if (nbd_set_export_name (nbd, name) == -1 ||
              nbd_opt_go (nbd) == -1) {
            fprintf (stderr, "%s\n", nbd_get_error ());
            exit (EXIT_FAILURE);
          }
          if (!nbd_aio_is_ready (nbd)) {
            fprintf (stderr, "server closed early\n");
            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: %s: size = %" PRIi64 " bytes\n",
                  argv[1], name, size);

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

          for (i = 0; i < list.i; i++)
            free (list.names[i]);
          free (list.names);

          exit (EXIT_SUCCESS);
        }

🌈 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

That’s the whole page, bestie — brought to you by libnbd-1.25.8, dated 2026-10-13. 💖✨

📦 where this page comes from