nbd_set_opt_mode(3)

💅 nbd_set_opt_mode — libnbd's pause button for option negotiation

Okay bestie, so this page lives in libnbd(3) and it's about one tiny function with main-character energy: nbd_set_opt_mode. It lets you stop mid-handshake and actually pick your own options instead of letting the server speedrun everything for you. Obsessed. 🎀

---

✨ NAME ✨

nbd_set_opt_mode — control option mode, for pausing during option negotiation

---

🦋 SYNOPSIS 🦋

#include <libnbd.h>

int nbd_set_opt_mode (
      struct nbd_handle *h, bool enable
    );

---

🌸 DESCRIPTION 🌸

Set this flag to true when you want a connection command "nbd_connect_*" to pause for negotiation options instead of just zooming all the way to the ready state — this works when you're talking to a newstyle server. 💖

Heads up: this setting has no effect when connecting to an oldstyle server. Like, none. Zero. Gone. 😭

Now, the tea ☕: libnbd by default tries "NBD_OPT_STARTTLS", "NBD_OPT_EXTENDED_HEADERS", and "NBD_OPT_STRUCTURED_REPLY" before it lets you control the remaining negotiation steps. So if you want control over those steps too, you gotta do this first:

• set nbd_set_tls(3) to "LIBNBD_TLS_DISABLE"
• set nbd_set_request_extended_headers(3) or nbd_set_request_structured_replies(3) to false

…and do all of that before you start the connection attempt. Timing matters, bestie. ⏰

When option mode is enabled, you get fine-grained control over which options get negotiated — versus the default where the server negotiates literally everything on your behalf using the settings you made before starting the connection. To leave the mode and proceed on to the ready state, you must use nbd_opt_go(3) successfully. And if nbd_opt_go(3) fails? No stress — it returns to the negotiating state so you can change the export name and try again. 🫶

You may also use nbd_opt_abort(3) or nbd_shutdown(3) to end the connection without finishing negotiation. Bail era. 💀

---

⭐ RETURN VALUE ⭐

If the call is successful the function returns 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). Don't be that person who passes NULL, okay? 🥺

---

👑 HANDLE STATE 👑

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

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

So basically: only before you connect. One shot. Make it count. ✨

---

🌈 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_SET_OPT_MODE 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 🔥

nbd_aio_connect(3), nbd_aio_is_negotiating(3), nbd_create(3), nbd_get_opt_mode(3), nbd_opt_abort(3), nbd_opt_go(3), nbd_opt_info(3), nbd_opt_list(3), nbd_opt_list_meta_context(3), nbd_opt_set_meta_context(3), nbd_opt_starttls(3), nbd_opt_structured_reply(3), nbd_set_request_extended_headers(3), nbd_set_request_structured_replies(3), nbd_set_tls(3), nbd_shutdown(3), libnbd(3).

---

💜 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

---

Okay that's the whole page, bestie — this one's from libnbd-1.25.8 and it's dated 2026-10-13. Go forth and negotiate your own options, you gorgeous nerd. 🫶✨