1nbd_poll(3)                         LIBNBD                         nbd_poll(3)
2
3
4

NAME

6       nbd_poll - poll the handle once
7

SYNOPSIS

9        #include <libnbd.h>
10
11        int nbd_poll (
12              struct nbd_handle *h, int timeout
13            );
14

DESCRIPTION

16       This is a simple implementation of poll(2) which is used internally by
17       synchronous API calls.  On success, it returns 0 if the "timeout" (in
18       milliseconds) occurs, or 1 if the poll completed and the state machine
19       progressed. Set "timeout" to -1 to block indefinitely (but be careful
20       that eventual action is actually expected - for example, if the
21       connection is established but there are no commands in flight, using an
22       infinite timeout will permanently block).
23
24       This function is mainly useful as an example of how you might integrate
25       libnbd with your own main loop, rather than being intended as something
26       you would use.
27

RETURN VALUE

29       This call returns an integer ≥ 0.
30

ERRORS

32       On error -1 is returned.
33
34       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
35       of the error.
36
37       The following parameters must not be NULL: "h".  For more information
38       see "Non-NULL parameters" in libnbd(3).
39

VERSION

41       This function first appeared in libnbd 1.0.
42
43       If you need to test if this function is available at compile time check
44       if the following macro is defined:
45
46        #define LIBNBD_HAVE_NBD_POLL 1
47

EXAMPLE

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

SEE ALSO

192       nbd_create(3), nbd_poll2(3), libnbd(3), poll(2).
193

AUTHORS

195       Eric Blake
196
197       Richard W.M. Jones
198
200       Copyright Red Hat
201

LICENSE

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