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 (struct nbd_handle *h, uint32_t flags);
12
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 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 The "flags" argument is a bitmask, including zero or more of the
24 following shutdown flags:
25 "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 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
37 If the call is successful the function returns 0.
38
40 On error "-1" is returned.
41 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
43 of the error.
44
46 The handle must be connected with the server, otherwise this call will
47 return an error.
48
50 This function first appeared in libnbd 1.0.
51 If you need to test if this function is available at compile time check
53 if the following macro is defined:
54 #define LIBNBD_HAVE_NBD_SHUTDOWN 1
56
58 This example is also available as examples/reads-and-writes.c in the
59 libnbd source code.
60 /* 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 #include <stdio.h>
73 #include <stdlib.h>
74 #include <inttypes.h>
75 #include <assert.h>
76 #include <time.h>
77 #include <libnbd.h>
79 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 srand (time (NULL));
90 if (argc != 2) {
92 fprintf (stderr, "%s socket\n", argv[0]);
93 exit (EXIT_FAILURE);
94 }
95 /* 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 /* 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 /* 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 /* 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 for (i = 0; i < sizeof buf; ++i)
130 buf[i] = rand ();
131 /* 1000 writes. */
133 for (i = 0; i < 1000; ++i) {
134 offset = rand () % (exportsize - sizeof buf);
135 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 /* 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 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 /* 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 nbd_close (nbd);
167 exit (EXIT_SUCCESS);
169 }
170
172 nbd_aio_disconnect(3), nbd_aio_in_flight(3), nbd_close(3),
173 nbd_create(3), libnbd(3).
174
176 Eric Blake
177 Richard W.M. Jones
179
181 Copyright (C) 2019-2021 Red Hat Inc.
182
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 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 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
198libnbd-1.7.12 2021-05-29 nbd_shutdown(3)