1nbd_aio_connect_unix(3)             LIBNBD             nbd_aio_connect_unix(3)
2
3
4

NAME

6       nbd_aio_connect_unix - connect to the NBD server over a Unix domain
7       socket
8

SYNOPSIS

10        #include <libnbd.h>
11
12        int nbd_aio_connect_unix (struct nbd_handle *h,
13                                  const char *unixsocket);
14

DESCRIPTION

16       Begin connecting to the NBD server over Unix domain socket
17       ("unixsocket").  Parameters behave as documented in
18       nbd_connect_unix(3).
19
20       You can check if the connection is still connecting by calling
21       nbd_aio_is_connecting(3), or if it has connected to the server and
22       completed the NBD handshake by calling nbd_aio_is_ready(3), on the
23       connection.
24

RETURN VALUE

26       If the call is successful the function returns 0.
27

ERRORS

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

HANDLE STATE

35       The handle must be newly created, otherwise this call will return an
36       error.
37

VERSION

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

EXAMPLE

47       This example is also available as examples/aio-connect-read.c in the
48       libnbd source code.
49
50        /* This example shows how to use the AIO (asynchronous) low
51         * level API to connect to a server and read the disk.
52         *
53         * Here are a few ways to try this example:
54         *
55         * nbdkit -U - linuxdisk . \
56         *   --run './aio-connect-read $unixsocket'
57         *
58         * nbdkit -U - floppy . \
59         *   --run './aio-connect-read $unixsocket'
60         *
61         * nbdkit -U - pattern size=1M \
62         *   --run './aio-connect-read $unixsocket'
63         */
64
65        #include <stdio.h>
66        #include <stdlib.h>
67        #include <stdint.h>
68        #include <inttypes.h>
69        #include <assert.h>
70
71        #include <libnbd.h>
72
73        #define NR_SECTORS 32
74        #define SECTOR_SIZE 512
75
76        struct data {
77          uint64_t offset;
78          char sector[SECTOR_SIZE];
79        };
80
81        static int
82        hexdump (void *user_data, int *error)
83        {
84          struct data *data = user_data;
85          FILE *pp;
86
87          printf ("sector at offset 0x%" PRIx64 ":\n",
88                  data->offset);
89          pp = popen ("hexdump -C", "w");
90          if (pp == NULL) {
91            perror ("popen: hexdump");
92            exit (EXIT_FAILURE);
93          }
94          fwrite (data->sector, SECTOR_SIZE, 1, pp);
95          pclose (pp);
96          printf ("\n");
97
98          /* Returning 1 from the callback automatically retires
99           * the command.
100           */
101          return 1;
102        }
103
104        int
105        main (int argc, char *argv[])
106        {
107          struct nbd_handle *nbd;
108          struct data data[NR_SECTORS];
109          size_t i;
110
111          if (argc != 2) {
112            fprintf (stderr, "%s socket\n", argv[0]);
113            exit (EXIT_FAILURE);
114          }
115
116          /* Create the libnbd handle. */
117          nbd = nbd_create ();
118          if (nbd == NULL) {
119            fprintf (stderr, "%s\n", nbd_get_error ());
120            exit (EXIT_FAILURE);
121          }
122
123          /* Connect to the NBD server over a Unix domain socket.
124           * This only starts the connection.
125           */
126          if (nbd_aio_connect_unix (nbd, argv[1]) == -1) {
127            fprintf (stderr, "%s\n", nbd_get_error ());
128            exit (EXIT_FAILURE);
129          }
130
131          /* Wait for the connection to complete.  The use of
132           * nbd_poll here is only as an example.  You could also
133           * integrate this with poll(2), glib or another main
134           * loop.  Read libnbd(3) and the source file lib/poll.c.
135           */
136          while (!nbd_aio_is_ready (nbd)) {
137            if (nbd_poll (nbd, -1) == -1) {
138              fprintf (stderr, "%s\n", nbd_get_error ());
139              exit (EXIT_FAILURE);
140            }
141          }
142
143          assert (nbd_get_size (nbd) >= NR_SECTORS * SECTOR_SIZE);
144
145          /* Issue read commands for the first NR sectors. */
146          for (i = 0; i < NR_SECTORS; ++i) {
147            data[i].offset = i * SECTOR_SIZE;
148
149            /* The callback (hexdump) is called when the command
150             * completes.  The buffer must continue to exist while
151             * the command is running.
152             */
153            if (nbd_aio_pread (nbd, data[i].sector, SECTOR_SIZE,
154                               data[i].offset,
155                               (nbd_completion_callback) {
156                                 .callback = hexdump,
157                                 .user_data = &data[i],
158                               }, 0) == -1) {
159              fprintf (stderr, "%s\n", nbd_get_error ());
160              exit (EXIT_FAILURE);
161            }
162          }
163
164          /* Run the main loop until all the commands have
165           * completed and retired.  Again the use of nbd_poll
166           * here is only as an example.
167           */
168          while (nbd_aio_in_flight (nbd) > 0) {
169            if (nbd_poll (nbd, -1) == -1) {
170              fprintf (stderr, "%s\n", nbd_get_error ());
171              exit (EXIT_FAILURE);
172            }
173          }
174
175          /* Close the libnbd handle. */
176          nbd_close (nbd);
177
178          exit (EXIT_SUCCESS);
179        }
180

SEE ALSO

182       nbd_aio_is_connecting(3), nbd_aio_is_ready(3), nbd_connect_unix(3),
183       nbd_create(3), libnbd(3).
184

AUTHORS

186       Eric Blake
187
188       Richard W.M. Jones
189
191       Copyright (C) 2019-2021 Red Hat Inc.
192

LICENSE

194       This library is free software; you can redistribute it and/or modify it
195       under the terms of the GNU Lesser General Public License as published
196       by the Free Software Foundation; either version 2 of the License, or
197       (at your option) any later version.
198
199       This library is distributed in the hope that it will be useful, but
200       WITHOUT ANY WARRANTY; without even the implied warranty of
201       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
202       Lesser General Public License for more details.
203
204       You should have received a copy of the GNU Lesser General Public
205       License along with this library; if not, write to the Free Software
206       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
207       02110-1301 USA
208
209
210
211libnbd-1.7.12                     2021-05-29           nbd_aio_connect_unix(3)
Impressum