1nbd_aio_pread(3)                    LIBNBD                    nbd_aio_pread(3)
2
3
4

NAME

6       nbd_aio_pread - read from the NBD server
7

SYNOPSIS

9        #include <libnbd.h>
10
11        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
17        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

DESCRIPTION

23       Issue a read command to the NBD server.
24
25       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
29       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
38       Other parameters behave as documented in nbd_pread(3).
39
40       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

RETURN VALUE

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

ERRORS

51       On error "-1" is returned.
52
53       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
54       of the error.
55
56       The following parameters must not be NULL: "h", "buf".  For more
57       information see "Non-NULL parameters" in libnbd(3).
58

HANDLE STATE

60       The handle must be connected with the server, otherwise this call will
61       return an error.
62

VERSION

64       This function first appeared in libnbd 1.0.
65
66       If you need to test if this function is available at compile time check
67       if the following macro is defined:
68
69        #define LIBNBD_HAVE_NBD_AIO_PREAD 1
70

EXAMPLE

72       This example is also available as examples/aio-connect-read.c in the
73       libnbd source code.
74
75        /* 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
90        #include <stdio.h>
91        #include <stdlib.h>
92        #include <stdint.h>
93        #include <inttypes.h>
94        #include <errno.h>
95        #include <assert.h>
96
97        #include <libnbd.h>
98
99        #define NR_SECTORS 32
100        #define SECTOR_SIZE 512
101
102        struct data {
103          uint64_t offset;
104          char sector[SECTOR_SIZE];
105        };
106
107        static int
108        hexdump (void *user_data, int *error)
109        {
110          struct data *data = user_data;
111          FILE *pp;
112
113          if (*error) {
114            errno = *error;
115            perror ("failed to read");
116            exit (EXIT_FAILURE);
117          }
118
119          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
130          /* Returning 1 from the callback automatically retires
131           * the command.
132           */
133          return 1;
134        }
135
136        static struct data data[NR_SECTORS];
137
138        int
139        main (int argc, char *argv[])
140        {
141          struct nbd_handle *nbd;
142          size_t i;
143
144          if (argc != 2) {
145            fprintf (stderr, "%s socket\n", argv[0]);
146            exit (EXIT_FAILURE);
147          }
148
149          /* 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
156          /* 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
164          /* 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
176          assert (nbd_get_size (nbd) >= NR_SECTORS * SECTOR_SIZE);
177
178          /* Issue read commands for the first NR sectors. */
179          for (i = 0; i < NR_SECTORS; ++i) {
180            data[i].offset = i * SECTOR_SIZE;
181
182            /* 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
197          /* 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
208          /* Close the libnbd handle. */
209          nbd_close (nbd);
210
211          exit (EXIT_SUCCESS);
212        }
213

SEE ALSO

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

AUTHORS

221       Eric Blake
222
223       Richard W.M. Jones
224
226       Copyright (C) 2019-2021 Red Hat Inc.
227

LICENSE

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
234       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
239       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
243
244
245
246libnbd-1.14.2                     2023-01-03                  nbd_aio_pread(3)
Impressum