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

       Plugins and filters can call exit(3) in the configuration phase (before and including ".get_ready", but
       not in connected callbacks).

       Once nbdkit has started serving connections, plugins and filters should not call exit(3).  However they
       may instruct nbdkit to shut down by calling "nbdkit_shutdown", or to disconnect a single client by
       calling "nbdkit_disconnect".

   nbdkit_shutdown
       "nbdkit_shutdown" requests nbdkit to shut down asynchronously and returns (note that it does not exit the
       process immediately).

       It ensures that the plugin and all filters are unloaded cleanly which may take some time.  Further
       callbacks from nbdkit into the plugin or filter may occur after you have called this.

   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.

       It is only useful from connected callbacks — that is, after (but not including) ".open", and before
       ".close".  To reject a client in ".preconnect", ".open" or ".list_exports" you should return an error
       instead.

       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.  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.  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.

SEE ALSO

       nbdkit(1), nbdkit-plugin(3), nbdkit-filter(3).

AUTHORS

       Eric Blake

       Richard W.M. Jones

COPYRIGHT

       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.

nbdkit-1.42.2                                      2025-04-02                                 nbdkit_shutdown(3)