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