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 The following parameters must not be NULL: "h", "unixsocket". For more
35 information see "Non-NULL parameters" in libnbd(3).
36
38 The handle must be newly created, otherwise this call will return an
39 error.
40
42 This function first appeared in libnbd 1.0.
43 If you need to test if this function is available at compile time check
45 if the following macro is defined:
46 #define LIBNBD_HAVE_NBD_AIO_CONNECT_UNIX 1
48
50 This example is also available as examples/aio-connect-read.c in the
51 libnbd source code.
52 /* This example shows how to use the AIO (asynchronous) low
54 * level API to connect to a server and read the disk.
55 *
56 * Here are a few ways to try this example:
57 *
58 * nbdkit -U - linuxdisk . \
59 * --run './aio-connect-read $unixsocket'
60 *
61 * nbdkit -U - floppy . \
62 * --run './aio-connect-read $unixsocket'
63 *
64 * nbdkit -U - pattern size=1M \
65 * --run './aio-connect-read $unixsocket'
66 */
67 #include <stdio.h>
69 #include <stdlib.h>
70 #include <stdint.h>
71 #include <inttypes.h>
72 #include <errno.h>
73 #include <assert.h>
74 #include <libnbd.h>
76 #define NR_SECTORS 32
78 #define SECTOR_SIZE 512
79 struct data {
81 uint64_t offset;
82 char sector[SECTOR_SIZE];
83 };
84 static int
86 hexdump (void *user_data, int *error)
87 {
88 struct data *data = user_data;
89 FILE *pp;
90 if (*error) {
92 errno = *error;
93 perror ("failed to read");
94 exit (EXIT_FAILURE);
95 }
96 printf ("sector at offset 0x%" PRIx64 ":\n",
98 data->offset);
99 pp = popen ("hexdump -C", "w");
100 if (pp == NULL) {
101 perror ("popen: hexdump");
102 exit (EXIT_FAILURE);
103 }
104 fwrite (data->sector, SECTOR_SIZE, 1, pp);
105 pclose (pp);
106 printf ("\n");
107 /* Returning 1 from the callback automatically retires
109 * the command.
110 */
111 return 1;
112 }
113 static struct data data[NR_SECTORS];
115 int
117 main (int argc, char *argv[])
118 {
119 struct nbd_handle *nbd;
120 size_t i;
121 if (argc != 2) {
123 fprintf (stderr, "%s socket\n", argv[0]);
124 exit (EXIT_FAILURE);
125 }
126 /* Create the libnbd handle. */
128 nbd = nbd_create ();
129 if (nbd == NULL) {
130 fprintf (stderr, "%s\n", nbd_get_error ());
131 exit (EXIT_FAILURE);
132 }
133 /* Connect to the NBD server over a Unix domain socket.
135 * This only starts the connection.
136 */
137 if (nbd_aio_connect_unix (nbd, argv[1]) == -1) {
138 fprintf (stderr, "%s\n", nbd_get_error ());
139 exit (EXIT_FAILURE);
140 }
141 /* Wait for the connection to complete. The use of
143 * nbd_poll here is only as an example. You could also
144 * integrate this with poll(2), glib or another main
145 * loop. Read libnbd(3) and the source file lib/poll.c.
146 */
147 while (!nbd_aio_is_ready (nbd)) {
148 if (nbd_poll (nbd, -1) == -1) {
149 fprintf (stderr, "%s\n", nbd_get_error ());
150 exit (EXIT_FAILURE);
151 }
152 }
153 assert (nbd_get_size (nbd) >= NR_SECTORS * SECTOR_SIZE);
155 /* Issue read commands for the first NR sectors. */
157 for (i = 0; i < NR_SECTORS; ++i) {
158 data[i].offset = i * SECTOR_SIZE;
159 /* The callback (hexdump) is called when the command
161 * completes. The buffer must continue to exist while
162 * the command is running.
163 */
164 if (nbd_aio_pread (nbd, data[i].sector, SECTOR_SIZE,
165 data[i].offset,
166 (nbd_completion_callback) {
167 .callback = hexdump,
168 .user_data = &data[i],
169 }, 0) == -1) {
170 fprintf (stderr, "%s\n", nbd_get_error ());
171 exit (EXIT_FAILURE);
172 }
173 }
174 /* Run the main loop until all the commands have
176 * completed and retired. Again the use of nbd_poll
177 * here is only as an example.
178 */
179 while (nbd_aio_in_flight (nbd) > 0) {
180 if (nbd_poll (nbd, -1) == -1) {
181 fprintf (stderr, "%s\n", nbd_get_error ());
182 exit (EXIT_FAILURE);
183 }
184 }
185 /* Close the libnbd handle. */
187 nbd_close (nbd);
188 exit (EXIT_SUCCESS);
190 }
191
193 nbd_aio_is_connecting(3), nbd_aio_is_ready(3), nbd_connect_unix(3),
194 nbd_create(3), libnbd(3).
195
197 Eric Blake
198 Richard W.M. Jones
200
202 Copyright (C) 2019-2021 Red Hat Inc.
203
205 This library is free software; you can redistribute it and/or modify it
206 under the terms of the GNU Lesser General Public License as published
207 by the Free Software Foundation; either version 2 of the License, or
208 (at your option) any later version.
209 This library is distributed in the hope that it will be useful, but
211 WITHOUT ANY WARRANTY; without even the implied warranty of
212 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
213 Lesser General Public License for more details.
214 You should have received a copy of the GNU Lesser General Public
216 License along with this library; if not, write to the Free Software
217 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
218 02110-1301 USA
219libnbd-1.14.2 2023-01-03 nbd_aio_connect_unix(3)