1nbd_aio_pread(3) LIBNBD nbd_aio_pread(3)
2
6 nbd_aio_pread - read from the NBD server
7
9 #include <libnbd.h>
10 typedef struct {
12 int (*callback) (void *user_data, int *error);
13 void *user_data;
14 void (*free) (void *user_data);
15 } nbd_completion_callback;
16 int64_t nbd_aio_pread (struct nbd_handle *h, void *buf,
18 size_t count, uint64_t offset,
19 nbd_completion_callback completion_callback,
20 uint32_t flags);
21
23 Issue a read command to the NBD server.
24 To check if the command completed, call nbd_aio_command_completed(3).
26 Or supply the optional "completion_callback" which will be invoked as
27 described in "Completion callbacks" in libnbd(3).
28 Note that you must ensure "buf" is valid until the command has
30 completed. Furthermore, if the "error" parameter to
31 "completion_callback" is set or if nbd_aio_command_completed(3) reports
32 failure, and if nbd_get_pread_initialize(3) returns true, then libnbd
33 sanitized "buf", but it is unspecified whether the contents of "buf"
34 will read as zero or as partial results from the server. If
35 nbd_get_pread_initialize(3) returns false, then libnbd did not sanitize
36 "buf", and the contents are undefined on failure.
37 Other parameters behave as documented in nbd_pread(3).
39 By default, libnbd will reject attempts to use this function with
41 parameters that are likely to result in server failure, such as
42 requesting an unknown command flag. The nbd_set_strict_mode(3)
43 function can be used to alter which scenarios should await a server
44 reply rather than failing fast.
45
47 This call returns the 64 bit cookie of the command. The cookie is ≥ 1.
48 Cookies are unique (per libnbd handle, not globally).
49
51 On error "-1" is returned.
52 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
54 of the error.
55
57 The handle must be connected with the server, otherwise this call will
58 return an error.
59
61 This function first appeared in libnbd 1.0.
62 If you need to test if this function is available at compile time check
64 if the following macro is defined:
65 #define LIBNBD_HAVE_NBD_AIO_PREAD 1
67
69 This example is also available as examples/aio-connect-read.c in the
70 libnbd source code.
71 /* This example shows how to use the AIO (asynchronous) low
73 * level API to connect to a server and read the disk.
74 *
75 * Here are a few ways to try this example:
76 *
77 * nbdkit -U - linuxdisk . \
78 * --run './aio-connect-read $unixsocket'
79 *
80 * nbdkit -U - floppy . \
81 * --run './aio-connect-read $unixsocket'
82 *
83 * nbdkit -U - pattern size=1M \
84 * --run './aio-connect-read $unixsocket'
85 */
86 #include <stdio.h>
88 #include <stdlib.h>
89 #include <stdint.h>
90 #include <inttypes.h>
91 #include <errno.h>
92 #include <assert.h>
93 #include <libnbd.h>
95 #define NR_SECTORS 32
97 #define SECTOR_SIZE 512
98 struct data {
100 uint64_t offset;
101 char sector[SECTOR_SIZE];
102 };
103 static int
105 hexdump (void *user_data, int *error)
106 {
107 struct data *data = user_data;
108 FILE *pp;
109 if (*error) {
111 errno = *error;
112 perror ("failed to read");
113 exit (EXIT_FAILURE);
114 }
115 printf ("sector at offset 0x%" PRIx64 ":\n",
117 data->offset);
118 pp = popen ("hexdump -C", "w");
119 if (pp == NULL) {
120 perror ("popen: hexdump");
121 exit (EXIT_FAILURE);
122 }
123 fwrite (data->sector, SECTOR_SIZE, 1, pp);
124 pclose (pp);
125 printf ("\n");
126 /* Returning 1 from the callback automatically retires
128 * the command.
129 */
130 return 1;
131 }
132 static struct data data[NR_SECTORS];
134 int
136 main (int argc, char *argv[])
137 {
138 struct nbd_handle *nbd;
139 size_t i;
140 if (argc != 2) {
142 fprintf (stderr, "%s socket\n", argv[0]);
143 exit (EXIT_FAILURE);
144 }
145 /* Create the libnbd handle. */
147 nbd = nbd_create ();
148 if (nbd == NULL) {
149 fprintf (stderr, "%s\n", nbd_get_error ());
150 exit (EXIT_FAILURE);
151 }
152 /* Connect to the NBD server over a Unix domain socket.
154 * This only starts the connection.
155 */
156 if (nbd_aio_connect_unix (nbd, argv[1]) == -1) {
157 fprintf (stderr, "%s\n", nbd_get_error ());
158 exit (EXIT_FAILURE);
159 }
160 /* Wait for the connection to complete. The use of
162 * nbd_poll here is only as an example. You could also
163 * integrate this with poll(2), glib or another main
164 * loop. Read libnbd(3) and the source file lib/poll.c.
165 */
166 while (!nbd_aio_is_ready (nbd)) {
167 if (nbd_poll (nbd, -1) == -1) {
168 fprintf (stderr, "%s\n", nbd_get_error ());
169 exit (EXIT_FAILURE);
170 }
171 }
172 assert (nbd_get_size (nbd) >= NR_SECTORS * SECTOR_SIZE);
174 /* Issue read commands for the first NR sectors. */
176 for (i = 0; i < NR_SECTORS; ++i) {
177 data[i].offset = i * SECTOR_SIZE;
178 /* The callback (hexdump) is called when the command
180 * completes. The buffer must continue to exist while
181 * the command is running.
182 */
183 if (nbd_aio_pread (nbd, data[i].sector, SECTOR_SIZE,
184 data[i].offset,
185 (nbd_completion_callback) {
186 .callback = hexdump,
187 .user_data = &data[i],
188 }, 0) == -1) {
189 fprintf (stderr, "%s\n", nbd_get_error ());
190 exit (EXIT_FAILURE);
191 }
192 }
193 /* Run the main loop until all the commands have
195 * completed and retired. Again the use of nbd_poll
196 * here is only as an example.
197 */
198 while (nbd_aio_in_flight (nbd) > 0) {
199 if (nbd_poll (nbd, -1) == -1) {
200 fprintf (stderr, "%s\n", nbd_get_error ());
201 exit (EXIT_FAILURE);
202 }
203 }
204 /* Close the libnbd handle. */
206 nbd_close (nbd);
207 exit (EXIT_SUCCESS);
209 }
210
212 nbd_aio_command_completed(3), nbd_aio_pread_structured(3),
213 nbd_create(3), nbd_get_pread_initialize(3), nbd_pread(3),
214 nbd_set_pread_initialize(3), nbd_set_strict_mode(3), "Issuing
215 asynchronous commands" in libnbd(3), libnbd(3).
216
218 Eric Blake
219 Richard W.M. Jones
221
223 Copyright (C) 2019-2021 Red Hat Inc.
224
226 This library is free software; you can redistribute it and/or modify it
227 under the terms of the GNU Lesser General Public License as published
228 by the Free Software Foundation; either version 2 of the License, or
229 (at your option) any later version.
230 This library is distributed in the hope that it will be useful, but
232 WITHOUT ANY WARRANTY; without even the implied warranty of
233 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
234 Lesser General Public License for more details.
235 You should have received a copy of the GNU Lesser General Public
237 License along with this library; if not, write to the Free Software
238 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
239 02110-1301 USA
240libnbd-1.12.5 2022-07-10 nbd_aio_pread(3)