1nbd_shutdown(3) LIBNBD nbd_shutdown(3)
2
6 nbd_shutdown - disconnect from the NBD server
7
9 #include <libnbd.h>
10 int nbd_shutdown (
12 struct nbd_handle *h, uint32_t flags
13 );
14
16 Issue the disconnect command to the NBD server. This is a nice way to
17 tell the server we are going away, but from the client's point of view
18 has no advantage over abruptly closing the connection (see
19 nbd_close(3)).
20 This function works whether or not the handle is ready for transmission
22 of commands. If more fine-grained control is needed, see
23 nbd_aio_disconnect(3).
24 The "flags" argument is a bitmask, including zero or more of the
26 following shutdown flags:
27 "LIBNBD_SHUTDOWN_ABANDON_PENDING" = 0x10000
29 If there are any pending requests which have not yet been sent to
30 the server (see nbd_aio_in_flight(3)), abandon them without sending
31 them to the server, rather than the usual practice of issuing those
32 commands before informing the server of the intent to disconnect.
33 For convenience, the constant "LIBNBD_SHUTDOWN_MASK" is available to
35 describe all shutdown flags recognized by this build of libnbd. A
36 future version of the library may add new flags.
37
39 If the call is successful the function returns 0.
40
42 On error -1 is returned.
43 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
45 of the error.
46 The following parameters must not be NULL: "h". For more information
48 see "Non-NULL parameters" in libnbd(3).
49
51 The handle must be connected with the server, otherwise this call will
52 return an error.
53
55 This function first appeared in libnbd 1.0.
56 If you need to test if this function is available at compile time check
58 if the following macro is defined:
59 #define LIBNBD_HAVE_NBD_SHUTDOWN 1
61
63 This example is also available as examples/reads-and-writes.c in the
64 libnbd source code.
65 /* This example shows how to do synchronous reads
67 * and writes randomly over the first megabyte of an
68 * NBD server. Note this will destroy any existing
69 * content on the NBD server.
70 *
71 * To test it with nbdkit and a RAM disk:
72 *
73 * nbdkit -U - memory 1M \
74 * --run './simple-reads-and-writes $unixsocket'
75 */
76 #include <stdio.h>
78 #include <stdlib.h>
79 #include <inttypes.h>
80 #include <assert.h>
81 #include <time.h>
82 #include <libnbd.h>
84 int
86 main (int argc, char *argv[])
87 {
88 struct nbd_handle *nbd;
89 char buf[512];
90 size_t i;
91 int64_t exportsize;
92 uint64_t offset;
93 srand (time (NULL));
95 if (argc != 2) {
97 fprintf (stderr, "%s socket\n", argv[0]);
98 exit (EXIT_FAILURE);
99 }
100 /* Create the libnbd handle. */
102 nbd = nbd_create ();
103 if (nbd == NULL) {
104 fprintf (stderr, "%s\n", nbd_get_error ());
105 exit (EXIT_FAILURE);
106 }
107 /* Connect to the NBD server over a
109 * Unix domain socket.
110 */
111 if (nbd_connect_unix (nbd, argv[1]) == -1) {
112 fprintf (stderr, "%s\n", nbd_get_error ());
113 exit (EXIT_FAILURE);
114 }
115 /* Get the size of the disk and check
117 * it's large enough.
118 */
119 exportsize = nbd_get_size (nbd);
120 if (exportsize == -1) {
121 fprintf (stderr, "%s\n", nbd_get_error ());
122 exit (EXIT_FAILURE);
123 }
124 assert (exportsize >= sizeof buf);
125 /* Check that the server is writable. */
127 if (nbd_is_read_only (nbd) == 1) {
128 fprintf (stderr, "%s: "
129 "error: this NBD export is read-only\n",
130 argv[0]);
131 exit (EXIT_FAILURE);
132 }
133 for (i = 0; i < sizeof buf; ++i)
135 buf[i] = rand ();
136 /* 1000 writes. */
138 for (i = 0; i < 1000; ++i) {
139 offset = rand () % (exportsize - sizeof buf);
140 if (nbd_pwrite (nbd, buf, sizeof buf,
142 offset, 0) == -1) {
143 fprintf (stderr, "%s\n", nbd_get_error ());
144 exit (EXIT_FAILURE);
145 }
146 }
147 /* 1000 reads and writes. */
149 for (i = 0; i < 1000; ++i) {
150 offset = rand () % (exportsize - sizeof buf);
151 if (nbd_pread (nbd, buf, sizeof buf,
152 offset, 0) == -1) {
153 fprintf (stderr, "%s\n", nbd_get_error ());
154 exit (EXIT_FAILURE);
155 }
156 offset = rand () % (exportsize - sizeof buf);
158 if (nbd_pwrite (nbd, buf, sizeof buf,
159 offset, 0) == -1) {
160 fprintf (stderr, "%s\n", nbd_get_error ());
161 exit (EXIT_FAILURE);
162 }
163 }
164 /* Sends a graceful shutdown to the server. */
166 if (nbd_shutdown (nbd, 0) == -1) {
167 fprintf (stderr, "%s\n", nbd_get_error ());
168 exit (EXIT_FAILURE);
169 }
170 nbd_close (nbd);
172 exit (EXIT_SUCCESS);
174 }
175
177 nbd_aio_disconnect(3), nbd_aio_in_flight(3), nbd_close(3),
178 nbd_create(3), libnbd(3).
179
181 Eric Blake
182 Richard W.M. Jones
184
186 Copyright Red Hat
187
189 This library is free software; you can redistribute it and/or modify it
190 under the terms of the GNU Lesser General Public License as published
191 by the Free Software Foundation; either version 2 of the License, or
192 (at your option) any later version.
193 This library is distributed in the hope that it will be useful, but
195 WITHOUT ANY WARRANTY; without even the implied warranty of
196 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
197 Lesser General Public License for more details.
198 You should have received a copy of the GNU Lesser General Public
200 License along with this library; if not, write to the Free Software
201 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
202 02110-1301 USA
203libnbd-1.16.5 2023-09-26 nbd_shutdown(3)