--- name: "nbd_shutdown" section: "3" platform: "linux" package: "libnbd" version: "1.24.4-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/nbd_shutdown" --- # nbd\_shutdown(3) disconnect from the NBD server ## NAME nbd\_shutdown - disconnect from the NBD server ## SYNOPSIS ``` #include int nbd_shutdown ( struct nbd_handle *h, uint32_t flags ); ``` ## DESCRIPTION Issue the disconnect command to the NBD server. This is a nice way to tell the server we are going away, but from the client's point of view has no advantage over abruptly closing the connection (see [**nbd\_close**(3)](/nbd_close/3.md)). This function works whether or not the handle is ready for transmission of commands. If more fine-grained control is needed, see [**nbd\_aio\_opt\_abort**(3)](/nbd_aio_opt_abort/3.md) and [**nbd\_aio\_disconnect**(3)](/nbd_aio_disconnect/3.md). The `"flags"` argument is a bitmask, including zero or more of the following shutdown flags: - "LIBNBD\_SHUTDOWN\_ABANDON\_PENDING" = 0x10000 If there are any pending requests which have not yet been sent to the server (see [**nbd\_aio\_in\_flight**(3)](/nbd_aio_in_flight/3.md)), abandon them without sending them to the server, rather than the usual practice of issuing those commands before informing the server of the intent to disconnect. For convenience, the constant `"LIBNBD_SHUTDOWN_MASK"` is available to describe all shutdown flags recognized by this build of libnbd. A future version of the library may add new flags. ## RETURN VALUE If the call is successful the function returns `0`. ## ERRORS On error `-1` is returned. Refer to "ERROR HANDLING" in [**libnbd**(3)](/libnbd/3.md) 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)](/libnbd/3.md). ## HANDLE STATE nbd\_shutdown can be called when the handle is in the following states: ``` ┌─────────────────────────────────────┬─────────────────────────┐ │ Handle created, before connecting │ ❌ error │ │ Connecting │ ❌ error │ │ Connecting & handshaking (opt_mode) │ ✅ allowed │ │ Connected to the server │ ✅ allowed │ │ Connection shut down │ ❌ error │ │ Handle dead │ ❌ error │ └─────────────────────────────────────┴─────────────────────────┘ ``` ## VERSION This function first appeared in libnbd 1.0. If you need to test if this function is available at compile time check if the following macro is defined: ``` #define LIBNBD_HAVE_NBD_SHUTDOWN 1 ``` ## EXAMPLE This example is also available as *examples/reads-and-writes.c* in the libnbd source code. ``` /* This example shows how to do synchronous reads * and writes randomly over the first megabyte of an * NBD server. Note this will destroy any existing * content on the NBD server. * * To test it with nbdkit and a RAM disk: * * nbdkit -U - memory 1M \ * --run './simple-reads-and-writes $unixsocket' */ #include #include #include #include #include #include #include int main (int argc, char *argv[]) { struct nbd_handle *nbd; char buf[512]; size_t i; int64_t exportsize; uint64_t offset; srand (time (NULL)); 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); } /* Get the size of the disk and check * it's large enough. */ exportsize = nbd_get_size (nbd); if (exportsize == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } assert (exportsize >= sizeof buf); /* Check that the server is writable. */ if (nbd_is_read_only (nbd) == 1) { fprintf (stderr, "%s: " "error: this NBD export is read-only\n", argv[0]); exit (EXIT_FAILURE); } for (i = 0; i < sizeof buf; ++i) buf[i] = rand (); /* 1000 writes. */ for (i = 0; i < 1000; ++i) { offset = rand () % (exportsize - sizeof buf); if (nbd_pwrite (nbd, buf, sizeof buf, offset, 0) == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } } /* 1000 reads and writes. */ for (i = 0; i < 1000; ++i) { offset = rand () % (exportsize - sizeof buf); if (nbd_pread (nbd, buf, sizeof buf, offset, 0) == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } offset = rand () % (exportsize - sizeof buf); if (nbd_pwrite (nbd, buf, sizeof buf, offset, 0) == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } } /* Sends a graceful shutdown to the server. */ if (nbd_shutdown (nbd, 0) == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } nbd_close (nbd); exit (EXIT_SUCCESS); } ``` ## SEE ALSO [**nbd\_aio\_disconnect**(3)](/nbd_aio_disconnect/3.md), [**nbd\_aio\_in\_flight**(3)](/nbd_aio_in_flight/3.md), [**nbd\_aio\_opt\_abort**(3)](/nbd_aio_opt_abort/3.md), [**nbd\_close**(3)](/nbd_close/3.md), [**nbd\_create**(3)](/nbd_create/3.md), [**libnbd**(3)](/libnbd/3.md). ## 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