1nbd_aio_connect_unix(3) LIBNBD nbd_aio_connect_unix(3)
2
6 nbd_aio_connect_unix - connect to the NBD server over a Unix domain
7 socket
8
10 #include <libnbd.h>
11 int nbd_aio_connect_unix (struct nbd_handle *h,
13 const char *unixsocket);
14
16 Begin connecting to the NBD server over Unix domain socket
17 ("unixsocket"). Parameters behave as documented in
18 nbd_connect_unix(3).
19 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
26 If the call is successful the function returns 0.
27
29 On error "-1" is returned.
30 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
32 of the error.
33
35 The handle must be newly created, otherwise this call will return an
36 error.
37
39 This function first appeared in libnbd 1.0.
40 If you need to test if this function is available at compile time check
42 if the following macro is defined:
43 #define LIBNBD_HAVE_NBD_AIO_CONNECT_UNIX 1
45
47 This example is also available as examples/aio-connect-read.c in the
48 libnbd source code.
49 /* 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 #include <stdio.h>
66 #include <stdlib.h>
67 #include <stdint.h>
68 #include <inttypes.h>
69 #include <assert.h>
70 #include <libnbd.h>
72 #define NR_SECTORS 32
74 #define SECTOR_SIZE 512
75 struct data {
77 uint64_t offset;
78 char sector[SECTOR_SIZE];
79 };
80 static int
82 hexdump (void *user_data, int *error)
83 {
84 struct data *data = user_data;
85 FILE *pp;
86 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 /* Returning 1 from the callback automatically retires
99 * the command.
100 */
101 return 1;
102 }
103 int
105 main (int argc, char *argv[])
106 {
107 struct nbd_handle *nbd;
108 struct data data[NR_SECTORS];
109 size_t i;
110 if (argc != 2) {
112 fprintf (stderr, "%s socket\n", argv[0]);
113 exit (EXIT_FAILURE);
114 }
115 /* 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 /* 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 /* 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 assert (nbd_get_size (nbd) >= NR_SECTORS * SECTOR_SIZE);
144 /* Issue read commands for the first NR sectors. */
146 for (i = 0; i < NR_SECTORS; ++i) {
147 data[i].offset = i * SECTOR_SIZE;
148 /* 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 /* 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 /* Close the libnbd handle. */
176 nbd_close (nbd);
177 exit (EXIT_SUCCESS);
179 }
180
182 nbd_aio_is_connecting(3), nbd_aio_is_ready(3), nbd_connect_unix(3),
183 nbd_create(3), libnbd(3).
184
186 Eric Blake
187 Richard W.M. Jones
189
191 Copyright (C) 2019 Red Hat Inc.
192
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 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 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
208libnbd-1.3.7 2020-04-23 nbd_aio_connect_unix(3)