1nbd_pread(3) LIBNBD nbd_pread(3)
2
6 nbd_pread - read from the NBD server
7
9 #include <libnbd.h>
10 int nbd_pread (
12 struct nbd_handle *h, void *buf, size_t count,
13 uint64_t offset, uint32_t flags
14 );
15
17 Issue a read command to the NBD server for the range starting at
18 "offset" and ending at "offset" + "count" - 1. NBD can only read all
19 or nothing using this call. The call returns when the data has been
20 read fully into "buf" or there is an error. See also
21 nbd_pread_structured(3), if finer visibility is required into the
22 server's replies, or if you want to use "LIBNBD_CMD_FLAG_DF".
23 Note that libnbd currently enforces a maximum read buffer of 64MiB,
25 even if the server would permit a larger buffer in a single
26 transaction; attempts to exceed this will result in an "ERANGE" error.
27 The server may enforce a smaller limit, which can be learned with
28 nbd_get_block_size(3).
29 The "flags" parameter must be 0 for now (it exists for future NBD
31 protocol extensions).
32 Note that if this command fails, and nbd_get_pread_initialize(3)
34 returns true, then libnbd sanitized "buf", but it is unspecified
35 whether the contents of "buf" will read as zero or as partial results
36 from the server. If nbd_get_pread_initialize(3) returns false, then
37 libnbd did not sanitize "buf", and the contents are undefined on
38 failure.
39 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
47 If the call is successful the function returns 0.
48
50 On error -1 is returned.
51 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
53 of the error.
54 The following parameters must not be NULL: "h", "buf". For more
56 information see "Non-NULL parameters" in libnbd(3).
57
59 The handle must be connected with the server, otherwise this call will
60 return an error.
61
63 This function first appeared in libnbd 1.0.
64 If you need to test if this function is available at compile time check
66 if the following macro is defined:
67 #define LIBNBD_HAVE_NBD_PREAD 1
69
71 This example is also available as examples/fetch-first-sector.c in the
72 libnbd source code.
73 /* This example shows how to connect to an NBD server
75 * and fetch and print the first sector (usually the
76 * boot sector or partition table or filesystem
77 * superblock).
78 *
79 * You can test it with nbdkit like this:
80 *
81 * nbdkit -U - floppy . \
82 * --run './fetch-first-sector $unixsocket'
83 *
84 * The nbdkit floppy plugin creates an MBR disk so the
85 * first sector is the partition table.
86 */
87 #include <stdio.h>
89 #include <stdlib.h>
90 #include <libnbd.h>
92 int
94 main (int argc, char *argv[])
95 {
96 struct nbd_handle *nbd;
97 char buf[512];
98 FILE *pp;
99 if (argc != 2) {
101 fprintf (stderr, "%s socket\n", argv[0]);
102 exit (EXIT_FAILURE);
103 }
104 /* Create the libnbd handle. */
106 nbd = nbd_create ();
107 if (nbd == NULL) {
108 fprintf (stderr, "%s\n", nbd_get_error ());
109 exit (EXIT_FAILURE);
110 }
111 /* Connect to the NBD server over a
113 * Unix domain socket.
114 */
115 if (nbd_connect_unix (nbd, argv[1]) == -1) {
116 fprintf (stderr, "%s\n", nbd_get_error ());
117 exit (EXIT_FAILURE);
118 }
119 /* Read the first sector synchronously. */
121 if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
122 fprintf (stderr, "%s\n", nbd_get_error ());
123 exit (EXIT_FAILURE);
124 }
125 /* Close the libnbd handle. */
127 nbd_close (nbd);
128 /* Print the first sector. */
130 pp = popen ("hexdump -C", "w");
131 if (pp == NULL) {
132 perror ("popen: hexdump");
133 exit (EXIT_FAILURE);
134 }
135 fwrite (buf, sizeof buf, 1, pp);
136 pclose (pp);
137 exit (EXIT_SUCCESS);
139 }
140
142 nbd_aio_pread(3), nbd_create(3), nbd_get_block_size(3),
143 nbd_get_pread_initialize(3), nbd_pread_structured(3),
144 nbd_set_pread_initialize(3), nbd_set_strict_mode(3), libnbd(3).
145
147 Eric Blake
148 Richard W.M. Jones
150
152 Copyright Red Hat
153
155 This library is free software; you can redistribute it and/or modify it
156 under the terms of the GNU Lesser General Public License as published
157 by the Free Software Foundation; either version 2 of the License, or
158 (at your option) any later version.
159 This library is distributed in the hope that it will be useful, but
161 WITHOUT ANY WARRANTY; without even the implied warranty of
162 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
163 Lesser General Public License for more details.
164 You should have received a copy of the GNU Lesser General Public
166 License along with this library; if not, write to the Free Software
167 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
168 02110-1301 USA
169libnbd-1.16.5 2023-09-26 nbd_pread(3)