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