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 (
13 struct nbd_handle *h, const char *unixsocket
14 );
15
17 Begin connecting to the NBD server over Unix domain socket
18 ("unixsocket"). Parameters behave as documented in
19 nbd_connect_unix(3).
20 You can check if the connection attempt is still underway by calling
22 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the
23 connection is ready for manual option negotiation once
24 nbd_aio_is_negotiating(3) returns true; otherwise, the connection
25 attempt will include the NBD handshake, and is ready for use once
26 nbd_aio_is_ready(3) returns true.
27
29 If the call is successful the function returns 0.
30
32 On error -1 is returned.
33 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
35 of the error.
36 The following parameters must not be NULL: "h", "unixsocket". For more
38 information see "Non-NULL parameters" in libnbd(3).
39
41 The handle must be newly created, otherwise this call will return an
42 error.
43
45 This function first appeared in libnbd 1.0.
46 If you need to test if this function is available at compile time check
48 if the following macro is defined:
49 #define LIBNBD_HAVE_NBD_AIO_CONNECT_UNIX 1
51
53 This example is also available as examples/aio-connect-read.c in the
54 libnbd source code.
55 /* This example shows how to use the AIO (asynchronous) low
57 * level API to connect to a server and read the disk.
58 *
59 * Here are a few ways to try this example:
60 *
61 * nbdkit -U - linuxdisk . \
62 * --run './aio-connect-read $unixsocket'
63 *
64 * nbdkit -U - floppy . \
65 * --run './aio-connect-read $unixsocket'
66 *
67 * nbdkit -U - pattern size=1M \
68 * --run './aio-connect-read $unixsocket'
69 */
70 #include <stdio.h>
72 #include <stdlib.h>
73 #include <stdint.h>
74 #include <inttypes.h>
75 #include <errno.h>
76 #include <assert.h>
77 #include <libnbd.h>
79 #define NR_SECTORS 32
81 #define SECTOR_SIZE 512
82 struct data {
84 uint64_t offset;
85 char sector[SECTOR_SIZE];
86 };
87 static int
89 hexdump (void *user_data, int *error)
90 {
91 struct data *data = user_data;
92 FILE *pp;
93 if (*error) {
95 errno = *error;
96 perror ("failed to read");
97 exit (EXIT_FAILURE);
98 }
99 printf ("sector at offset 0x%" PRIx64 ":\n",
101 data->offset);
102 pp = popen ("hexdump -C", "w");
103 if (pp == NULL) {
104 perror ("popen: hexdump");
105 exit (EXIT_FAILURE);
106 }
107 fwrite (data->sector, SECTOR_SIZE, 1, pp);
108 pclose (pp);
109 printf ("\n");
110 /* Returning 1 from the callback automatically retires
112 * the command.
113 */
114 return 1;
115 }
116 static struct data data[NR_SECTORS];
118 int
120 main (int argc, char *argv[])
121 {
122 struct nbd_handle *nbd;
123 size_t i;
124 if (argc != 2) {
126 fprintf (stderr, "%s socket\n", argv[0]);
127 exit (EXIT_FAILURE);
128 }
129 /* Create the libnbd handle. */
131 nbd = nbd_create ();
132 if (nbd == NULL) {
133 fprintf (stderr, "%s\n", nbd_get_error ());
134 exit (EXIT_FAILURE);
135 }
136 /* Connect to the NBD server over a Unix domain socket.
138 * This only starts the connection.
139 */
140 if (nbd_aio_connect_unix (nbd, argv[1]) == -1) {
141 fprintf (stderr, "%s\n", nbd_get_error ());
142 exit (EXIT_FAILURE);
143 }
144 /* Wait for the connection to complete. The use of
146 * nbd_poll here is only as an example. You could also
147 * integrate this with poll(2), glib or another main
148 * loop. Read libnbd(3) and the source file lib/poll.c.
149 */
150 while (!nbd_aio_is_ready (nbd)) {
151 if (nbd_poll (nbd, -1) == -1) {
152 fprintf (stderr, "%s\n", nbd_get_error ());
153 exit (EXIT_FAILURE);
154 }
155 }
156 assert (nbd_get_size (nbd) >= NR_SECTORS * SECTOR_SIZE);
158 /* Issue read commands for the first NR sectors. */
160 for (i = 0; i < NR_SECTORS; ++i) {
161 data[i].offset = i * SECTOR_SIZE;
162 /* The callback (hexdump) is called when the command
164 * completes. The buffer must continue to exist while
165 * the command is running.
166 */
167 if (nbd_aio_pread (nbd, data[i].sector, SECTOR_SIZE,
168 data[i].offset,
169 (nbd_completion_callback) {
170 .callback = hexdump,
171 .user_data = &data[i],
172 }, 0) == -1) {
173 fprintf (stderr, "%s\n", nbd_get_error ());
174 exit (EXIT_FAILURE);
175 }
176 }
177 /* Run the main loop until all the commands have
179 * completed and retired. Again the use of nbd_poll
180 * here is only as an example.
181 */
182 while (nbd_aio_in_flight (nbd) > 0) {
183 if (nbd_poll (nbd, -1) == -1) {
184 fprintf (stderr, "%s\n", nbd_get_error ());
185 exit (EXIT_FAILURE);
186 }
187 }
188 /* Close the libnbd handle. */
190 nbd_close (nbd);
191 exit (EXIT_SUCCESS);
193 }
194
196 nbd_aio_is_connecting(3), nbd_aio_is_negotiating(3),
197 nbd_aio_is_ready(3), nbd_connect_unix(3), nbd_create(3),
198 nbd_set_opt_mode(3), libnbd(3).
199
201 Eric Blake
202 Richard W.M. Jones
204
206 Copyright Red Hat
207
209 This library is free software; you can redistribute it and/or modify it
210 under the terms of the GNU Lesser General Public License as published
211 by the Free Software Foundation; either version 2 of the License, or
212 (at your option) any later version.
213 This library is distributed in the hope that it will be useful, but
215 WITHOUT ANY WARRANTY; without even the implied warranty of
216 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
217 Lesser General Public License for more details.
218 You should have received a copy of the GNU Lesser General Public
220 License along with this library; if not, write to the Free Software
221 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
222 02110-1301 USA
223libnbd-1.16.5 2023-09-26 nbd_aio_connect_unix(3)