nbd_opt_abort(3)

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

✨ nbd_opt_abort ✨

okay bestie, welcome to libnbd's very own nbd_opt_abort(3) — the "we're done here, bye" button for NBD negotiation 💅

🎀 NAME

nbd_opt_abort — end negotiation and close the connection

🌸 SYNOPSIS

#include <libnbd.h>

int nbd_opt_abort (
      struct nbd_handle *h
    );

🦋 DESCRIPTION

So like, this one politely asks the server to finish negotiation — gracefully if it can — and then it closes the connection. That's it. That's the whole vibe. ✨

gate check 🚧: you can only use this if nbd_set_opt_mode(3) actually turned option mode on. No option mode, no abort. periodt.

💖 RETURN VALUE

If the call slays (i.e. succeeds), the function returns 0. 🫶

😭 ERRORS

If it does not slay, -1 comes back.

Need the whole tea on what went wrong? Go read "ERROR HANDLING" in libnbd(3) — that's where the deets live.

Also!! this parameter absolutely must not be NULL: "h". For more info see "Non-NULL parameters" in libnbd(3). Don't do it, bestie, it's giving crash energy 💀

👑 HANDLE STATE

nbd_opt_abort can be called when the handle is in these states, and here's the vibe check on each:

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

so basically: the only green light is mid-handshake in option mode. everything else is a no. 🚫

⭐ VERSION

This function first appeared in libnbd 1.4. iconic behavior honestly.

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

#define LIBNBD_HAVE_NBD_OPT_ABORT 1

🌈 EXAMPLE

This example is also available as examples/list-exports.c in the libnbd source code. Yes, the whole thing — here it is, character for character, no cap:

/* 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

and that's the whole page, bestie 🫶 this one's from libnbd-1.25.8, dated 2026-10-13 — go forth and abort your negotiations gracefully, mwah 💋

📦 where this page comes from