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.  Other parameters behave as documented in nbd_pread(3).
31

RETURN VALUE

33       This call returns the 64 bit cookie of the command.  The cookie is ≥ 1.
34       Cookies are unique (per libnbd handle, not globally).
35

ERRORS

37       On error "-1" is returned.
38
39       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
40       of the error.
41

HANDLE STATE

43       The handle must be connected and finished handshaking with the server,
44       otherwise this call will return an error.
45

VERSION

47       This function first appeared in libnbd 1.0.
48
49       If you need to test if this function is available at compile time check
50       if the following macro is defined:
51
52        #define LIBNBD_HAVE_NBD_AIO_PREAD 1
53

EXAMPLE

55       This example is also available as examples/aio-connect-read.c in the
56       libnbd source code.
57
58        /* This example shows how to use the AIO (asynchronous) low
59         * level API to connect to a server and read the disk.
60         *
61         * Here are a few ways to try this example:
62         *
63         * nbdkit -U - linuxdisk . \
64         *   --run './aio-connect-read $unixsocket'
65         *
66         * nbdkit -U - floppy . \
67         *   --run './aio-connect-read $unixsocket'
68         *
69         * nbdkit -U - pattern size=1M \
70         *   --run './aio-connect-read $unixsocket'
71         */
72
73        #include <stdio.h>
74        #include <stdlib.h>
75        #include <stdint.h>
76        #include <inttypes.h>
77        #include <assert.h>
78
79        #include <libnbd.h>
80
81        #define NR_SECTORS 32
82        #define SECTOR_SIZE 512
83
84        struct data {
85          uint64_t offset;
86          char sector[SECTOR_SIZE];
87        };
88
89        static int
90        hexdump (void *user_data, int *error)
91        {
92          struct data *data = user_data;
93          FILE *pp;
94
95          printf ("sector at offset 0x%" PRIx64 ":\n",
96                  data->offset);
97          pp = popen ("hexdump -C", "w");
98          if (pp == NULL) {
99            perror ("popen: hexdump");
100            exit (EXIT_FAILURE);
101          }
102          fwrite (data->sector, SECTOR_SIZE, 1, pp);
103          pclose (pp);
104          printf ("\n");
105
106          /* Returning 1 from the callback automatically retires
107           * the command.
108           */
109          return 1;
110        }
111
112        int
113        main (int argc, char *argv[])
114        {
115          struct nbd_handle *nbd;
116          struct data data[NR_SECTORS];
117          size_t i;
118
119          if (argc != 2) {
120            fprintf (stderr, "%s socket\n", argv[0]);
121            exit (EXIT_FAILURE);
122          }
123
124          /* Create the libnbd handle. */
125          nbd = nbd_create ();
126          if (nbd == NULL) {
127            fprintf (stderr, "%s\n", nbd_get_error ());
128            exit (EXIT_FAILURE);
129          }
130
131          /* Connect to the NBD server over a Unix domain socket.
132           * This only starts the connection.
133           */
134          if (nbd_aio_connect_unix (nbd, argv[1]) == -1) {
135            fprintf (stderr, "%s\n", nbd_get_error ());
136            exit (EXIT_FAILURE);
137          }
138
139          /* Wait for the connection to complete.  The use of
140           * nbd_poll here is only as an example.  You could also
141           * integrate this with poll(2), glib or another main
142           * loop.  Read libnbd(3) and the source file lib/poll.c.
143           */
144          while (!nbd_aio_is_ready (nbd)) {
145            if (nbd_poll (nbd, -1) == -1) {
146              fprintf (stderr, "%s\n", nbd_get_error ());
147              exit (EXIT_FAILURE);
148            }
149          }
150
151          assert (nbd_get_size (nbd) >= NR_SECTORS * SECTOR_SIZE);
152
153          /* Issue read commands for the first NR sectors. */
154          for (i = 0; i < NR_SECTORS; ++i) {
155            data[i].offset = i * SECTOR_SIZE;
156
157            /* The callback (hexdump) is called when the command
158             * completes.  The buffer must continue to exist while
159             * the command is running.
160             */
161            if (nbd_aio_pread (nbd, data[i].sector, SECTOR_SIZE,
162                               data[i].offset,
163                               (nbd_completion_callback) {
164                                 .callback = hexdump,
165                                 .user_data = &data[i],
166                               }, 0) == -1) {
167              fprintf (stderr, "%s\n", nbd_get_error ());
168              exit (EXIT_FAILURE);
169            }
170          }
171
172          /* Run the main loop until all the commands have
173           * completed and retired.  Again the use of nbd_poll
174           * here is only as an example.
175           */
176          while (nbd_aio_in_flight (nbd) > 0) {
177            if (nbd_poll (nbd, -1) == -1) {
178              fprintf (stderr, "%s\n", nbd_get_error ());
179              exit (EXIT_FAILURE);
180            }
181          }
182
183          /* Close the libnbd handle. */
184          nbd_close (nbd);
185
186          exit (EXIT_SUCCESS);
187        }
188

SEE ALSO

190       "Issuing asynchronous commands" in libnbd(3),
191       nbd_aio_pread_structured(3), nbd_pread(3), nbd_create(3), libnbd(3).
192

AUTHORS

194       Eric Blake
195
196       Richard W.M. Jones
197
199       Copyright (C) 2019 Red Hat Inc.
200

LICENSE

202       This library is free software; you can redistribute it and/or modify it
203       under the terms of the GNU Lesser General Public License as published
204       by the Free Software Foundation; either version 2 of the License, or
205       (at your option) any later version.
206
207       This library is distributed in the hope that it will be useful, but
208       WITHOUT ANY WARRANTY; without even the implied warranty of
209       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
210       Lesser General Public License for more details.
211
212       You should have received a copy of the GNU Lesser General Public
213       License along with this library; if not, write to the Free Software
214       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
215       02110-1301 USA
216
217
218
219libnbd-1.2.1                      2019-11-14                  nbd_aio_pread(3)
Impressum