=head1 NAME

nbd_shutdown - disconnect from the NBD server

=head1 SYNOPSIS

 #include <libnbd.h>

 int nbd_shutdown (
       struct nbd_handle *h, uint32_t flags
     );

=head1 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 L<nbd_close(3)>).

This function works whether or not the handle is ready for
transmission of commands. If more fine-grained control is
needed, see L<nbd_aio_opt_abort(3)> and L<nbd_aio_disconnect(3)>.

The C<flags> argument is a bitmask, including zero or more of the
following shutdown flags:

=over 4

=item C<LIBNBD_SHUTDOWN_ABANDON_PENDING> = 0x10000

If there are any pending requests which have not yet been sent to
the server (see L<nbd_aio_in_flight(3)>), 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.

=back

For convenience, the constant C<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.

=head1 RETURN VALUE

If the call is successful the function returns C<0>.

=head1 ERRORS

On error C<-1> is returned.

Refer to L<libnbd(3)/ERROR HANDLING>
for how to get further details of the error.

The following parameters must not be NULL: C<h>.
For more information see L<libnbd(3)/Non-NULL parameters>.

=head1 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                │
 └─────────────────────────────────────┴─────────────────────────┘

=head1 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

=head1 EXAMPLE

This example is also available as F<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 <stdio.h>
 #include <stdlib.h>
 #include <stdint.h>
 #include <inttypes.h>
 #include <assert.h>
 #include <time.h>

 #include <libnbd.h>

 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);
 }

=head1 SEE ALSO

L<nbd_aio_disconnect(3)>,
L<nbd_aio_in_flight(3)>,
L<nbd_aio_opt_abort(3)>,
L<nbd_close(3)>,
L<nbd_create(3)>,
L<libnbd(3)>.

=head1 AUTHORS

Eric Blake

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
