1nbd_set_opt_mode(3) LIBNBD nbd_set_opt_mode(3)
2
6 nbd_set_opt_mode - control option mode, for pausing during option
7 negotiation
8
10 #include <libnbd.h>
11 int nbd_set_opt_mode (
13 struct nbd_handle *h, bool enable
14 );
15
17 Set this flag to true in order to request that a connection command
18 "nbd_connect_*" will pause for negotiation options rather than
19 proceeding all the way to the ready state, when communicating with a
20 newstyle server. This setting has no effect when connecting to an
21 oldstyle server.
22 Note that libnbd defaults to attempting "NBD_OPT_STARTTLS",
24 "NBD_OPT_EXTENDED_HEADERS", and "NBD_OPT_STRUCTURED_REPLY" before
25 letting you control remaining negotiation steps; if you need control
26 over these steps as well, first set nbd_set_tls(3) to
27 "LIBNBD_TLS_DISABLE", and nbd_set_request_extended_headers(3) or
28 nbd_set_request_structured_replies(3) to false, before starting the
29 connection attempt.
30 When option mode is enabled, you have fine-grained control over which
32 options are negotiated, compared to the default of the server
33 negotiating everything on your behalf using settings made before
34 starting the connection. To leave the mode and proceed on to the ready
35 state, you must use nbd_opt_go(3) successfully; a failed nbd_opt_go(3)
36 returns to the negotiating state to allow a change of export name
37 before trying again. You may also use nbd_opt_abort(3) or
38 nbd_shutdown(3) to end the connection without finishing negotiation.
39
41 If the call is successful the function returns 0.
42
44 On error -1 is returned.
45 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
47 of the error.
48 The following parameters must not be NULL: "h". For more information
50 see "Non-NULL parameters" in libnbd(3).
51
53 The handle must be newly created, otherwise this call will return an
54 error.
55
57 This function first appeared in libnbd 1.4.
58 If you need to test if this function is available at compile time check
60 if the following macro is defined:
61 #define LIBNBD_HAVE_NBD_SET_OPT_MODE 1
63
65 This example is also available as examples/list-exports.c in the libnbd
66 source code.
67 /* This example shows how to list NBD exports.
69 *
70 * To test this with qemu-nbd:
71 * $ qemu-nbd -x "hello" -t -k /tmp/sock disk.img
72 * $ ./run examples/list-exports /tmp/sock
73 * [0] hello
74 * Which export to connect to (-1 to quit)? 0
75 * Connecting to hello ...
76 * /tmp/sock: hello: size = 2048 bytes
77 *
78 * To test this with nbdkit (requires 1.22):
79 * $ nbdkit -U /tmp/sock sh - <<\EOF
80 * case $1 in
81 * list_exports) echo NAMES; echo foo; echo foobar ;;
82 * open) echo "$3" ;;
83 * get_size) echo "$2" | wc -c ;;
84 * pread) echo "$2" | dd bs=1 skip=$4 count=$3 ;;
85 * *) exit 2 ;;
86 * esac
87 * EOF
88 * $ ./run examples/list-exports /tmp/sock
89 * [0] foo
90 * [1] foobar
91 * Which export to connect to (-1 to quit)? 1
92 * Connecting to foobar ...
93 * /tmp/sock: foobar: size = 7 bytes
94 */
95 #include <stdio.h>
97 #include <stdlib.h>
98 #include <stdint.h>
99 #include <string.h>
100 #include <inttypes.h>
101 #include <errno.h>
102 #include <libnbd.h>
104 struct export_list {
106 int i;
107 char **names;
108 };
109 /* Callback function for nbd_opt_list */
111 static int
112 list_one (void *opaque, const char *name,
113 const char *description)
114 {
115 struct export_list *l = opaque;
116 char **names;
117 printf ("[%d] %s\n", l->i, name);
119 if (*description)
120 printf (" (%s)\n", description);
121 names = realloc (l->names,
122 (l->i + 1) * sizeof *names);
123 if (!names) {
124 perror ("realloc");
125 exit (EXIT_FAILURE);
126 }
127 names[l->i] = strdup (name);
128 if (!names[l->i]) {
129 perror ("strdup");
130 exit (EXIT_FAILURE);
131 }
132 l->names = names;
133 l->i++;
134 return 0;
135 }
136 int
138 main (int argc, char *argv[])
139 {
140 struct nbd_handle *nbd;
141 int i;
142 const char *name;
143 int64_t size;
144 struct export_list list = { 0 };
145 if (argc != 2) {
147 fprintf (stderr, "%s socket\n", argv[0]);
148 exit (EXIT_FAILURE);
149 }
150 /* Create the libnbd handle. */
152 nbd = nbd_create ();
153 if (nbd == NULL) {
154 fprintf (stderr, "%s\n", nbd_get_error ());
155 exit (EXIT_FAILURE);
156 }
157 /* Set opt mode. */
159 nbd_set_opt_mode (nbd, true);
160 /* Connect to the NBD server over a
162 * Unix domain socket. If we did not
163 * end up in option mode, then a
164 * listing is not possible.
165 */
166 if (nbd_connect_unix (nbd, argv[1]) == -1) {
167 fprintf (stderr, "%s\n", nbd_get_error ());
168 exit (EXIT_FAILURE);
169 }
170 if (!nbd_aio_is_negotiating (nbd)) {
171 fprintf (stderr, "Server does not support "
172 "listing exports.\n");
173 exit (EXIT_FAILURE);
174 }
175 /* Print the export list. */
177 if (nbd_opt_list (nbd,
178 (nbd_list_callback) {
179 .callback = list_one,
180 .user_data = &list, }) == -1) {
181 fprintf (stderr, "%s\n", nbd_get_error ());
182 exit (EXIT_FAILURE);
183 }
184 /* Display the list of exports. */
186 printf ("Which export to connect to? ");
187 if (scanf ("%d", &i) != 1) exit (EXIT_FAILURE);
188 if (i == -1) {
189 if (nbd_opt_abort (nbd) == -1) {
190 fprintf (stderr, "%s\n", nbd_get_error ());
191 exit (EXIT_FAILURE);
192 }
193 nbd_close (nbd);
194 exit (EXIT_SUCCESS);
195 }
196 if (i < 0 || i >= list.i) {
197 fprintf (stderr, "index %d out of range", i);
198 exit (EXIT_FAILURE);
199 }
200 name = list.names[i];
201 printf ("Connecting to %s ...\n", name);
202 /* Resume connecting to the chosen export. */
204 if (nbd_set_export_name (nbd, name) == -1 ||
205 nbd_opt_go (nbd) == -1) {
206 fprintf (stderr, "%s\n", nbd_get_error ());
207 exit (EXIT_FAILURE);
208 }
209 if (!nbd_aio_is_ready (nbd)) {
210 fprintf (stderr, "server closed early\n");
211 exit (EXIT_FAILURE);
212 }
213 /* Read the size in bytes and print it. */
215 size = nbd_get_size (nbd);
216 if (size == -1) {
217 fprintf (stderr, "%s\n", nbd_get_error ());
218 exit (EXIT_FAILURE);
219 }
220 printf ("%s: %s: size = %" PRIi64 " bytes\n",
221 argv[1], name, size);
222 /* Close the libnbd handle. */
224 nbd_close (nbd);
225 for (i = 0; i < list.i; i++)
227 free (list.names[i]);
228 free (list.names);
229 exit (EXIT_SUCCESS);
231 }
232
234 nbd_aio_connect(3), nbd_aio_is_negotiating(3), nbd_create(3),
235 nbd_get_opt_mode(3), nbd_opt_abort(3), nbd_opt_go(3), nbd_opt_info(3),
236 nbd_opt_list(3), nbd_opt_list_meta_context(3),
237 nbd_opt_set_meta_context(3), nbd_opt_starttls(3),
238 nbd_opt_structured_reply(3), nbd_set_request_extended_headers(3),
239 nbd_set_request_structured_replies(3), nbd_set_tls(3), nbd_shutdown(3),
240 libnbd(3).
241
243 Eric Blake
244 Richard W.M. Jones
246
248 Copyright Red Hat
249
251 This library is free software; you can redistribute it and/or modify it
252 under the terms of the GNU Lesser General Public License as published
253 by the Free Software Foundation; either version 2 of the License, or
254 (at your option) any later version.
255 This library is distributed in the hope that it will be useful, but
257 WITHOUT ANY WARRANTY; without even the implied warranty of
258 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
259 Lesser General Public License for more details.
260 You should have received a copy of the GNU Lesser General Public
262 License along with this library; if not, write to the Free Software
263 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
264 02110-1301 USA
265libnbd-1.18.1 2023-10-31 nbd_set_opt_mode(3)