nbdkit_shutdown(3)

📦
version 1.48.1 · 10 versions
, in fedora 44

💅 nbdkit_shutdown(3) — the nbdkit manual page, bestie edition

okay so this is the nbdkit_shutdown(3) page, and it's literally about two little functions that let your plugin or filter say "bestie, we're done here" — either shut the whole server down, or yeet one single client. ✨

🎀 NAME 🎀

nbdkit_shutdown, nbdkit_disconnect — request shutdown or client disconnection

🌸 SYNOPSIS 🌸

#include <nbdkit-plugin.h>

void nbdkit_shutdown (void);
void nbdkit_disconnect (int force);

✨ DESCRIPTION ✨

So here's the tea 🫖 — plugins and filters are allowed to call exit(3) in the configuration phase, which means before and including .get_ready, but not in connected callbacks.

Once nbdkit has actually started serving connections, plugins and filters should not call exit(3). No ma'am. Instead they can tell nbdkit to shut down by calling nbdkit_shutdown, or disconnect a single client by calling nbdkit_disconnect. That's the whole vibe. 👑

🦋 nbdkit_shutdown 🦋

nbdkit_shutdown requests that nbdkit shuts down asynchronously and then returns — and ngl, key detail: it does not exit the process immediately. It's giving "I sent the text, now I wait" energy. 💌

It ensures that the plugin and all filters are unloaded cleanly, which may take some time. And heads up — further callbacks from nbdkit into the plugin or filter may still occur after you've called this. So don't be shocked when it comes back around. 🙈

🌈 nbdkit_disconnect 🌈

nbdkit_disconnect requests that the current client connection be disconnected. It does not affect other connections, and it does not stop the same client from trying to reconnect. So basically it's a "not you specifically forever, just not right now" situation. 💅

It is only useful from connected callbacks — that is, after (but not including) .open, and before .close. If you want to reject a client in .preconnect, .open or .list_exports, you should return an error instead. Different tool, different job, iykyk.

If force is true, nbdkit will disconnect the client immediately, and the client will not receive any response to the current command or any other commands in flight in parallel threads. That's the hard yeet 💀. If force is false, nbdkit will not accept any new commands from the client (failing all commands other than NBD_CMD_DISC with ESHUTDOWN), but will allow existing commands to complete gracefully. That's the soft yeet 🧚. Either way, the next callback for the current connection should be .close.

💖 LANGUAGE BINDINGS 💖

In nbdkit-ocaml-plugin(3):

NBDKit.shutdown : unit -> unit
NBDKit.disconnect : bool -> unit

In nbdkit-python-plugin(3):

import nbdkit
nbdkit.shutdown()
nbdkit.disconnect(force)

In nbdkit-rust-plugin(3):

use nbdkit::*;
pub fn shutdown()
pub fn disconnect(force: bool)

In nbdkit-sh-plugin(3), there are various magic error codes that can be returned to indicate that shutdown or disconnection is needed. See that documentation for a full description. ✨

📜 HISTORY 📜

nbdkit_shutdown was added in nbdkit 1.20. nbdkit_disconnect was added in nbdkit 1.34. glow up timeline fr fr 🫶

👀 SEE ALSO 👀

✍️ AUTHORS ✍️

Eric Blake

Richard W.M. Jones

Copyright Red Hat

📄 LICENSE 📄

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

and that's the whole page bestie!! 💖 this lil legend came from nbdkit-1.48.1, dated 2026-08-29, and it's the nbdkit_shutdown(3) manual — periodt. ✨🎀🦋

📦 where this page comes from