1nbd_opt_go(3)                       LIBNBD                       nbd_opt_go(3)
2
3
4

NAME

6       nbd_opt_go - end negotiation and move on to using an export
7

SYNOPSIS

9        #include <libnbd.h>
10
11        int nbd_opt_go (struct nbd_handle *h);
12

DESCRIPTION

14       Request that the server finish negotiation and move on to serving the
15       export previously specified by the most recent nbd_set_export_name(3)
16       or nbd_connect_uri(3).  This can only be used if nbd_set_opt_mode(3)
17       enabled option mode.
18
19       If this fails, the server may still be in negotiation, where it is
20       possible to attempt another option such as a different export name;
21       although older servers will instead have killed the connection.
22

RETURN VALUE

24       If the call is successful the function returns 0.
25

ERRORS

27       On error "-1" is returned.
28
29       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
30       of the error.
31

HANDLE STATE

33       The handle must be negotiating, otherwise this call will return an
34       error.
35

VERSION

37       This function first appeared in libnbd 1.4.
38
39       If you need to test if this function is available at compile time check
40       if the following macro is defined:
41
42        #define LIBNBD_HAVE_NBD_OPT_GO 1
43

EXAMPLE

45       This example is also available as examples/list-exports.c in the libnbd
46       source code.
47
48        /* This example shows how to list NBD exports.
49         *
50         * To test this with qemu-nbd:
51         *   $ qemu-nbd -x "hello" -t -k /tmp/sock disk.img
52         *   $ ./run examples/list-exports /tmp/sock
53         *   [0] hello
54         *   Which export to connect to (-1 to quit)? 0
55         *   Connecting to hello ...
56         *   /tmp/sock: hello: size = 2048 bytes
57         *
58         * To test this with nbdkit (requires 1.22):
59         *   $ nbdkit -U /tmp/sock sh - <<\EOF
60         *   case $1 in
61         *     list_exports) echo NAMES; echo foo; echo foobar ;;
62         *     open) echo "$3" ;;
63         *     get_size) echo "$2" | wc -c ;;
64         *     pread) echo "$2" | dd bs=1 skip=$4 count=$3 ;;
65         *     *) exit 2 ;;
66         *   esac
67         *   EOF
68         *   $ ./run examples/list-exports /tmp/sock
69         *   [0] foo
70         *   [1] foobar
71         *   Which export to connect to (-1 to quit)? 1
72         *   Connecting to foobar ...
73         *   /tmp/sock: foobar: size = 7 bytes
74         */
75
76        #include <stdio.h>
77        #include <stdlib.h>
78        #include <stdint.h>
79        #include <string.h>
80        #include <inttypes.h>
81        #include <errno.h>
82
83        #include <libnbd.h>
84
85        struct export_list {
86          int i;
87          char **names;
88        };
89
90        /* Callback function for nbd_opt_list */
91        static int
92        list_one (void *opaque, const char *name,
93                  const char *description)
94        {
95          struct export_list *l = opaque;
96          char **names;
97
98          printf ("[%d] %s\n", l->i, name);
99          if (*description)
100            printf("  (%s)\n", description);
101          names = realloc (l->names,
102                           (l->i + 1) * sizeof *names);
103          if (!names) {
104            perror ("realloc");
105            exit (EXIT_FAILURE);
106          }
107          names[l->i] = strdup (name);
108          if (!names[l->i]) {
109            perror ("strdup");
110            exit (EXIT_FAILURE);
111          }
112          l->names = names;
113          l->i++;
114          return 0;
115        }
116
117        int
118        main (int argc, char *argv[])
119        {
120          struct nbd_handle *nbd;
121          int i;
122          const char *name;
123          int64_t size;
124          struct export_list list = { 0 };
125
126          if (argc != 2) {
127            fprintf (stderr, "%s socket\n", argv[0]);
128            exit (EXIT_FAILURE);
129          }
130
131          /* Create the libnbd handle. */
132          nbd = nbd_create ();
133          if (nbd == NULL) {
134            fprintf (stderr, "%s\n", nbd_get_error ());
135            exit (EXIT_FAILURE);
136          }
137
138          /* Set opt mode. */
139          nbd_set_opt_mode (nbd, true);
140
141          /* Connect to the NBD server over a
142           * Unix domain socket.  If we did not
143           * end up in option mode, then a
144           * listing is not possible.
145           */
146          if (nbd_connect_unix (nbd, argv[1]) == -1) {
147            fprintf (stderr, "%s\n", nbd_get_error ());
148            exit (EXIT_FAILURE);
149          }
150          if (!nbd_aio_is_negotiating (nbd)) {
151            fprintf (stderr, "Server does not support "
152                     "listing exports.\n");
153            exit (EXIT_FAILURE);
154          }
155
156          /* Print the export list. */
157          if (nbd_opt_list (nbd,
158                            (nbd_list_callback) {
159                              .callback = list_one,
160                              .user_data = &list, }) == -1) {
161            fprintf (stderr, "%s\n", nbd_get_error ());
162            exit (EXIT_FAILURE);
163          }
164
165          /* Display the list of exports. */
166          printf ("Which export to connect to? ");
167          if (scanf ("%d", &i) != 1) exit (EXIT_FAILURE);
168          if (i == -1) {
169            if (nbd_opt_abort (nbd) == -1) {
170              fprintf (stderr, "%s\n", nbd_get_error ());
171              exit (EXIT_FAILURE);
172            }
173            nbd_close (nbd);
174            exit (EXIT_SUCCESS);
175          }
176          if (i < 0 || i >= list.i) {
177            fprintf (stderr, "index %d out of range", i);
178            exit (EXIT_FAILURE);
179          }
180          name = list.names[i];
181          printf ("Connecting to %s ...\n", name);
182
183          /* Resume connecting to the chosen export. */
184          if (nbd_set_export_name (nbd, name) == -1 ||
185              nbd_opt_go (nbd) == -1) {
186            fprintf (stderr, "%s\n", nbd_get_error ());
187            exit (EXIT_FAILURE);
188          }
189          if (!nbd_aio_is_ready (nbd)) {
190            fprintf (stderr, "server closed early\n");
191            exit (EXIT_FAILURE);
192          }
193
194          /* Read the size in bytes and print it. */
195          size = nbd_get_size (nbd);
196          if (size == -1) {
197            fprintf (stderr, "%s\n", nbd_get_error ());
198            exit (EXIT_FAILURE);
199          }
200          printf ("%s: %s: size = %" PRIi64 " bytes\n",
201                  argv[1], name, size);
202
203          /* Close the libnbd handle. */
204          nbd_close (nbd);
205
206          for (i = 0; i < list.i; i++)
207            free (list.names[i]);
208          free (list.names);
209
210          exit (EXIT_SUCCESS);
211        }
212

SEE ALSO

214       nbd_aio_opt_go(3), nbd_connect_uri(3), nbd_create(3), nbd_opt_abort(3),
215       nbd_opt_info(3), nbd_set_export_name(3), nbd_set_opt_mode(3),
216       libnbd(3).
217

AUTHORS

219       Eric Blake
220
221       Richard W.M. Jones
222
224       Copyright (C) 2019-2021 Red Hat Inc.
225

LICENSE

227       This library is free software; you can redistribute it and/or modify it
228       under the terms of the GNU Lesser General Public License as published
229       by the Free Software Foundation; either version 2 of the License, or
230       (at your option) any later version.
231
232       This library is distributed in the hope that it will be useful, but
233       WITHOUT ANY WARRANTY; without even the implied warranty of
234       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
235       Lesser General Public License for more details.
236
237       You should have received a copy of the GNU Lesser General Public
238       License along with this library; if not, write to the Free Software
239       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
240       02110-1301 USA
241
242
243
244libnbd-1.7.12                     2021-05-29                     nbd_opt_go(3)
Impressum