nbd_pread(3)

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       Note that libnbd currently enforces a maximum read buffer of 64MiB,
24       even if the server would permit a larger buffer in a single
25       transaction; attempts to exceed this will result in an "ERANGE" error.
26       The server may enforce a smaller limit, which can be learned with
27       nbd_get_block_size(3).
28
29       The "flags" parameter must be 0 for now (it exists for future NBD
30       protocol extensions).
31
32       Note that if this command fails, and nbd_get_pread_initialize(3)
33       returns true, then libnbd sanitized "buf", but it is unspecified
34       whether the contents of "buf" will read as zero or as partial results
35       from the server.  If nbd_get_pread_initialize(3) returns false, then
36       libnbd did not sanitize "buf", and the contents are undefined on
37       failure.
38
39       By default, libnbd will reject attempts to use this function with
40       parameters that are likely to result in server failure, such as
41       requesting an unknown command flag.  The nbd_set_strict_mode(3)
42       function can be used to alter which scenarios should await a server
43       reply rather than failing fast.
44

RETURN VALUE

46       If the call is successful the function returns 0.
47

ERRORS

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

HANDLE STATE

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

VERSION

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

EXAMPLE

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

AUTHORS

146       Eric Blake
147
148       Richard W.M. Jones
149

COPYRIGHT

151       Copyright (C) 2019-2021 Red Hat Inc.
152

LICENSE

154       This library is free software; you can redistribute it and/or modify it
155       under the terms of the GNU Lesser General Public License as published
156       by the Free Software Foundation; either version 2 of the License, or
157       (at your option) any later version.
158
159       This library is distributed in the hope that it will be useful, but
160       WITHOUT ANY WARRANTY; without even the implied warranty of
161       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
162       Lesser General Public License for more details.
163
164       You should have received a copy of the GNU Lesser General Public
165       License along with this library; if not, write to the Free Software
166       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
167       02110-1301 USA
168
169
170
171libnbd-1.14.2                     2023-01-03                      nbd_pread(3)