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 The following parameters must not be NULL: "h". For more information
46 see "Non-NULL parameters" in libnbd(3).
47
49 The handle must be connected with the server, otherwise this call will
50 return an error.
51
53 This function first appeared in libnbd 1.0.
54 If you need to test if this function is available at compile time check
56 if the following macro is defined:
57 #define LIBNBD_HAVE_NBD_SHUTDOWN 1
59
61 This example is also available as examples/reads-and-writes.c in the
62 libnbd source code.
63 /* This example shows how to do synchronous reads
65 * and writes randomly over the first megabyte of an
66 * NBD server. Note this will destroy any existing
67 * content on the NBD server.
68 *
69 * To test it with nbdkit and a RAM disk:
70 *
71 * nbdkit -U - memory 1M \
72 * --run './simple-reads-and-writes $unixsocket'
73 */
74 #include <stdio.h>
76 #include <stdlib.h>
77 #include <inttypes.h>
78 #include <assert.h>
79 #include <time.h>
80 #include <libnbd.h>
82 int
84 main (int argc, char *argv[])
85 {
86 struct nbd_handle *nbd;
87 char buf[512];
88 size_t i;
89 int64_t exportsize;
90 uint64_t offset;
91 srand (time (NULL));
93 if (argc != 2) {
95 fprintf (stderr, "%s socket\n", argv[0]);
96 exit (EXIT_FAILURE);
97 }
98 /* Create the libnbd handle. */
100 nbd = nbd_create ();
101 if (nbd == NULL) {
102 fprintf (stderr, "%s\n", nbd_get_error ());
103 exit (EXIT_FAILURE);
104 }
105 /* Connect to the NBD server over a
107 * Unix domain socket.
108 */
109 if (nbd_connect_unix (nbd, argv[1]) == -1) {
110 fprintf (stderr, "%s\n", nbd_get_error ());
111 exit (EXIT_FAILURE);
112 }
113 /* Get the size of the disk and check
115 * it's large enough.
116 */
117 exportsize = nbd_get_size (nbd);
118 if (exportsize == -1) {
119 fprintf (stderr, "%s\n", nbd_get_error ());
120 exit (EXIT_FAILURE);
121 }
122 assert (exportsize >= sizeof buf);
123 /* Check that the server is writable. */
125 if (nbd_is_read_only (nbd) == 1) {
126 fprintf (stderr, "%s: "
127 "error: this NBD export is read-only\n",
128 argv[0]);
129 exit (EXIT_FAILURE);
130 }
131 for (i = 0; i < sizeof buf; ++i)
133 buf[i] = rand ();
134 /* 1000 writes. */
136 for (i = 0; i < 1000; ++i) {
137 offset = rand () % (exportsize - sizeof buf);
138 if (nbd_pwrite (nbd, buf, sizeof buf,
140 offset, 0) == -1) {
141 fprintf (stderr, "%s\n", nbd_get_error ());
142 exit (EXIT_FAILURE);
143 }
144 }
145 /* 1000 reads and writes. */
147 for (i = 0; i < 1000; ++i) {
148 offset = rand () % (exportsize - sizeof buf);
149 if (nbd_pread (nbd, buf, sizeof buf,
150 offset, 0) == -1) {
151 fprintf (stderr, "%s\n", nbd_get_error ());
152 exit (EXIT_FAILURE);
153 }
154 offset = rand () % (exportsize - sizeof buf);
156 if (nbd_pwrite (nbd, buf, sizeof buf,
157 offset, 0) == -1) {
158 fprintf (stderr, "%s\n", nbd_get_error ());
159 exit (EXIT_FAILURE);
160 }
161 }
162 /* Sends a graceful shutdown to the server. */
164 if (nbd_shutdown (nbd, 0) == -1) {
165 fprintf (stderr, "%s\n", nbd_get_error ());
166 exit (EXIT_FAILURE);
167 }
168 nbd_close (nbd);
170 exit (EXIT_SUCCESS);
172 }
173
175 nbd_aio_disconnect(3), nbd_aio_in_flight(3), nbd_close(3),
176 nbd_create(3), libnbd(3).
177
179 Eric Blake
180 Richard W.M. Jones
182
184 Copyright (C) 2019-2021 Red Hat Inc.
185
187 This library is free software; you can redistribute it and/or modify it
188 under the terms of the GNU Lesser General Public License as published
189 by the Free Software Foundation; either version 2 of the License, or
190 (at your option) any later version.
191 This library is distributed in the hope that it will be useful, but
193 WITHOUT ANY WARRANTY; without even the implied warranty of
194 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
195 Lesser General Public License for more details.
196 You should have received a copy of the GNU Lesser General Public
198 License along with this library; if not, write to the Free Software
199 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
200 02110-1301 USA
201libnbd-1.14.2 2023-01-03 nbd_shutdown(3)