1nbd_shutdown(3)                     LIBNBD                     nbd_shutdown(3)
2
3
4

NAME

6       nbd_shutdown - disconnect from the NBD server
7

SYNOPSIS

9        #include <libnbd.h>
10
11        int nbd_shutdown (struct nbd_handle *h, uint32_t flags);
12

DESCRIPTION

14       Issue the disconnect command to the NBD server.  This is a nice way to
15       tell the server we are going away, but from the client's point of view
16       has no advantage over abruptly closing the connection (see
17       nbd_close(3)).
18
19       This function works whether or not the handle is ready for transmission
20       of commands. If more fine-grained control is needed, see
21       nbd_aio_disconnect(3).
22
23       The "flags" argument is a bitmask, including zero or more of the
24       following shutdown flags:
25
26       "LIBNBD_SHUTDOWN_ABANDON_PENDING" = 0x10000
27           If there are any pending requests which have not yet been sent to
28           the server (see nbd_aio_in_flight(3)), abandon them without sending
29           them to the server, rather than the usual practice of issuing those
30           commands before informing the server of the intent to disconnect.
31
32       For convenience, the constant "LIBNBD_SHUTDOWN_MASK" is available to
33       describe all shutdown flags recognized by this build of libnbd.  A
34       future version of the library may add new flags.
35

RETURN VALUE

37       If the call is successful the function returns 0.
38

ERRORS

40       On error "-1" is returned.
41
42       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
43       of the error.
44

HANDLE STATE

46       The handle must be connected with the server, otherwise this call will
47       return an error.
48

VERSION

50       This function first appeared in libnbd 1.0.
51
52       If you need to test if this function is available at compile time check
53       if the following macro is defined:
54
55        #define LIBNBD_HAVE_NBD_SHUTDOWN 1
56

EXAMPLE

58       This example is also available as examples/reads-and-writes.c in the
59       libnbd source code.
60
61        /* This example shows how to do synchronous reads
62         * and writes randomly over the first megabyte of an
63         * NBD server.  Note this will destroy any existing
64         * content on the NBD server.
65         *
66         * To test it with nbdkit and a RAM disk:
67         *
68         * nbdkit -U - memory 1M \
69         *     --run './simple-reads-and-writes $unixsocket'
70         */
71
72        #include <stdio.h>
73        #include <stdlib.h>
74        #include <inttypes.h>
75        #include <assert.h>
76        #include <time.h>
77
78        #include <libnbd.h>
79
80        int
81        main (int argc, char *argv[])
82        {
83          struct nbd_handle *nbd;
84          char buf[512];
85          size_t i;
86          int64_t exportsize;
87          uint64_t offset;
88
89          srand (time (NULL));
90
91          if (argc != 2) {
92            fprintf (stderr, "%s socket\n", argv[0]);
93            exit (EXIT_FAILURE);
94          }
95
96          /* Create the libnbd handle. */
97          nbd = nbd_create ();
98          if (nbd == NULL) {
99            fprintf (stderr, "%s\n", nbd_get_error ());
100            exit (EXIT_FAILURE);
101          }
102
103          /* Connect to the NBD server over a
104           * Unix domain socket.
105           */
106          if (nbd_connect_unix (nbd, argv[1]) == -1) {
107            fprintf (stderr, "%s\n", nbd_get_error ());
108            exit (EXIT_FAILURE);
109          }
110
111          /* Get the size of the disk and check
112           * it's large enough.
113           */
114          exportsize = nbd_get_size (nbd);
115          if (exportsize == -1) {
116            fprintf (stderr, "%s\n", nbd_get_error ());
117            exit (EXIT_FAILURE);
118          }
119          assert (exportsize >= sizeof buf);
120
121          /* Check that the server is writable. */
122          if (nbd_is_read_only (nbd) == 1) {
123            fprintf (stderr, "%s: "
124                     "error: this NBD export is read-only\n",
125                     argv[0]);
126            exit (EXIT_FAILURE);
127          }
128
129          for (i = 0; i < sizeof buf; ++i)
130            buf[i] = rand ();
131
132          /* 1000 writes. */
133          for (i = 0; i < 1000; ++i) {
134            offset = rand () % (exportsize - sizeof buf);
135
136            if (nbd_pwrite (nbd, buf, sizeof buf,
137                            offset, 0) == -1) {
138              fprintf (stderr, "%s\n", nbd_get_error ());
139              exit (EXIT_FAILURE);
140            }
141          }
142
143          /* 1000 reads and writes. */
144          for (i = 0; i < 1000; ++i) {
145            offset = rand () % (exportsize - sizeof buf);
146            if (nbd_pread (nbd, buf, sizeof buf,
147                           offset, 0) == -1) {
148              fprintf (stderr, "%s\n", nbd_get_error ());
149              exit (EXIT_FAILURE);
150            }
151
152            offset = rand () % (exportsize - sizeof buf);
153            if (nbd_pwrite (nbd, buf, sizeof buf,
154                            offset, 0) == -1) {
155              fprintf (stderr, "%s\n", nbd_get_error ());
156              exit (EXIT_FAILURE);
157            }
158          }
159
160          /* Sends a graceful shutdown to the server. */
161          if (nbd_shutdown (nbd, 0) == -1) {
162            fprintf (stderr, "%s\n", nbd_get_error ());
163            exit (EXIT_FAILURE);
164          }
165
166          nbd_close (nbd);
167
168          exit (EXIT_SUCCESS);
169        }
170

SEE ALSO

172       nbd_aio_disconnect(3), nbd_aio_in_flight(3), nbd_close(3),
173       nbd_create(3), libnbd(3).
174

AUTHORS

176       Eric Blake
177
178       Richard W.M. Jones
179
181       Copyright (C) 2019-2020 Red Hat Inc.
182

LICENSE

184       This library is free software; you can redistribute it and/or modify it
185       under the terms of the GNU Lesser General Public License as published
186       by the Free Software Foundation; either version 2 of the License, or
187       (at your option) any later version.
188
189       This library is distributed in the hope that it will be useful, but
190       WITHOUT ANY WARRANTY; without even the implied warranty of
191       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
192       Lesser General Public License for more details.
193
194       You should have received a copy of the GNU Lesser General Public
195       License along with this library; if not, write to the Free Software
196       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
197       02110-1301 USA
198
199
200
201libnbd-1.6.2                      2021-03-02                   nbd_shutdown(3)
Impressum