1nbd_pread(3)                        LIBNBD                        nbd_pread(3)
2
3
4

NAME

6       nbd_pread - read from the NBD server
7

SYNOPSIS

9        #include <libnbd.h>
10
11        int nbd_pread (struct nbd_handle *h, void *buf,
12                       size_t count, uint64_t offset,
13                       uint32_t flags);
14

DESCRIPTION

16       Issue a read command to the NBD server for the range starting at
17       "offset" and ending at "offset" + "count" - 1.  NBD can only read all
18       or nothing using this call.  The call returns when the data has been
19       read fully into "buf" or there is an error.  See also
20       nbd_pread_structured(3), if finer visibility is required into the
21       server's replies, or if you want to use "LIBNBD_CMD_FLAG_DF".
22
23       The "flags" parameter must be 0 for now (it exists for future NBD
24       protocol extensions).
25
26       By default, libnbd will reject attempts to use this function with
27       parameters that are likely to result in server failure, such as
28       requesting an unknown command flag.  The nbd_set_strict_mode(3)
29       function can be used to alter which scenarios should await a server
30       reply rather than failing fast.
31

RETURN VALUE

33       If the call is successful the function returns 0.
34

ERRORS

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

HANDLE STATE

42       The handle must be connected with the server, otherwise this call will
43       return an error.
44

VERSION

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

EXAMPLE

54       This example is also available as examples/fetch-first-sector.c in the
55       libnbd source code.
56
57        /* This example shows how to connect to an NBD server
58         * and fetch and print the first sector (usually the
59         * boot sector or partition table or filesystem
60         * superblock).
61         *
62         * You can test it with nbdkit like this:
63         *
64         * nbdkit -U - floppy . \
65         *   --run './fetch-first-sector $unixsocket'
66         *
67         * The nbdkit floppy plugin creates an MBR disk so the
68         * first sector is the partition table.
69         */
70
71        #include <stdio.h>
72        #include <stdlib.h>
73
74        #include <libnbd.h>
75
76        int
77        main (int argc, char *argv[])
78        {
79          struct nbd_handle *nbd;
80          char buf[512];
81          FILE *pp;
82
83          if (argc != 2) {
84            fprintf (stderr, "%s socket\n", argv[0]);
85            exit (EXIT_FAILURE);
86          }
87
88          /* Create the libnbd handle. */
89          nbd = nbd_create ();
90          if (nbd == NULL) {
91            fprintf (stderr, "%s\n", nbd_get_error ());
92            exit (EXIT_FAILURE);
93          }
94
95          /* Connect to the NBD server over a
96           * Unix domain socket.
97           */
98          if (nbd_connect_unix (nbd, argv[1]) == -1) {
99            fprintf (stderr, "%s\n", nbd_get_error ());
100            exit (EXIT_FAILURE);
101          }
102
103          /* Read the first sector synchronously. */
104          if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
105            fprintf (stderr, "%s\n", nbd_get_error ());
106            exit (EXIT_FAILURE);
107          }
108
109          /* Close the libnbd handle. */
110          nbd_close (nbd);
111
112          /* Print the first sector. */
113          pp = popen ("hexdump -C", "w");
114          if (pp == NULL) {
115            perror ("popen: hexdump");
116            exit (EXIT_FAILURE);
117          }
118          fwrite (buf, sizeof buf, 1, pp);
119          pclose (pp);
120
121          exit (EXIT_SUCCESS);
122        }
123

SEE ALSO

125       nbd_aio_pread(3), nbd_create(3), nbd_get_block_size(3),
126       nbd_pread_structured(3), nbd_set_strict_mode(3), libnbd(3).
127

AUTHORS

129       Eric Blake
130
131       Richard W.M. Jones
132

134       Copyright (C) 2019-2021 Red Hat Inc.
135

LICENSE

137       This library is free software; you can redistribute it and/or modify it
138       under the terms of the GNU Lesser General Public License as published
139       by the Free Software Foundation; either version 2 of the License, or
140       (at your option) any later version.
141
142       This library is distributed in the hope that it will be useful, but
143       WITHOUT ANY WARRANTY; without even the implied warranty of
144       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
145       Lesser General Public License for more details.
146
147       You should have received a copy of the GNU Lesser General Public
148       License along with this library; if not, write to the Free Software
149       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
150       02110-1301 USA
151
152
153
154libnbd-1.10.1                     2021-10-25                      nbd_pread(3)
Impressum