1nbd_pwrite(3) LIBNBD nbd_pwrite(3)
2
6 nbd_pwrite - write to the NBD server
7
9 #include <libnbd.h>
10 int nbd_pwrite (
12 struct nbd_handle *h, const void *buf, size_t count,
13 uint64_t offset, uint32_t flags
14 );
15
17 Issue a write command to the NBD server, writing the data in "buf" to
18 the range starting at "offset" and ending at "offset" + "count" - 1.
19 NBD can only write all or nothing using this call. The call returns
20 when the command has been acknowledged by the server, or there is an
21 error. Note this will generally return an error if nbd_is_read_only(3)
22 is true.
23 Note that libnbd defaults to enforcing a maximum write buffer of the
25 lesser of 64MiB or any maximum payload size advertised by the server;
26 attempts to exceed this will generally result in a client-side "ERANGE"
27 error, rather than a server-side disconnection. The actual limit can
28 be learned with nbd_get_block_size(3).
29 The "flags" parameter may be 0 for no flags, or may contain
31 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
32 the data has been committed to permanent storage (if that is supported
33 - some servers cannot do this, see nbd_can_fua(3)). For convenience,
34 unless nbd_set_strict_flags(3) was used to disable
35 "LIBNBD_STRICT_AUTO_FLAG", libnbd ignores the presence or absence of
36 the flag "LIBNBD_CMD_FLAG_PAYLOAD_LEN" in "flags", while correctly
37 using the flag over the wire according to whether extended headers were
38 negotiated.
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_PWRITE 1
69
71 This example is also available as examples/reads-and-writes.c in the
72 libnbd source code.
73 /* This example shows how to do synchronous reads
75 * and writes randomly over the first megabyte of an
76 * NBD server. Note this will destroy any existing
77 * content on the NBD server.
78 *
79 * To test it with nbdkit and a RAM disk:
80 *
81 * nbdkit -U - memory 1M \
82 * --run './simple-reads-and-writes $unixsocket'
83 */
84 #include <stdio.h>
86 #include <stdlib.h>
87 #include <inttypes.h>
88 #include <assert.h>
89 #include <time.h>
90 #include <libnbd.h>
92 int
94 main (int argc, char *argv[])
95 {
96 struct nbd_handle *nbd;
97 char buf[512];
98 size_t i;
99 int64_t exportsize;
100 uint64_t offset;
101 srand (time (NULL));
103 if (argc != 2) {
105 fprintf (stderr, "%s socket\n", argv[0]);
106 exit (EXIT_FAILURE);
107 }
108 /* Create the libnbd handle. */
110 nbd = nbd_create ();
111 if (nbd == NULL) {
112 fprintf (stderr, "%s\n", nbd_get_error ());
113 exit (EXIT_FAILURE);
114 }
115 /* Connect to the NBD server over a
117 * Unix domain socket.
118 */
119 if (nbd_connect_unix (nbd, argv[1]) == -1) {
120 fprintf (stderr, "%s\n", nbd_get_error ());
121 exit (EXIT_FAILURE);
122 }
123 /* Get the size of the disk and check
125 * it's large enough.
126 */
127 exportsize = nbd_get_size (nbd);
128 if (exportsize == -1) {
129 fprintf (stderr, "%s\n", nbd_get_error ());
130 exit (EXIT_FAILURE);
131 }
132 assert (exportsize >= sizeof buf);
133 /* Check that the server is writable. */
135 if (nbd_is_read_only (nbd) == 1) {
136 fprintf (stderr, "%s: "
137 "error: this NBD export is read-only\n",
138 argv[0]);
139 exit (EXIT_FAILURE);
140 }
141 for (i = 0; i < sizeof buf; ++i)
143 buf[i] = rand ();
144 /* 1000 writes. */
146 for (i = 0; i < 1000; ++i) {
147 offset = rand () % (exportsize - sizeof buf);
148 if (nbd_pwrite (nbd, buf, sizeof buf,
150 offset, 0) == -1) {
151 fprintf (stderr, "%s\n", nbd_get_error ());
152 exit (EXIT_FAILURE);
153 }
154 }
155 /* 1000 reads and writes. */
157 for (i = 0; i < 1000; ++i) {
158 offset = rand () % (exportsize - sizeof buf);
159 if (nbd_pread (nbd, buf, sizeof buf,
160 offset, 0) == -1) {
161 fprintf (stderr, "%s\n", nbd_get_error ());
162 exit (EXIT_FAILURE);
163 }
164 offset = rand () % (exportsize - sizeof buf);
166 if (nbd_pwrite (nbd, buf, sizeof buf,
167 offset, 0) == -1) {
168 fprintf (stderr, "%s\n", nbd_get_error ());
169 exit (EXIT_FAILURE);
170 }
171 }
172 /* Sends a graceful shutdown to the server. */
174 if (nbd_shutdown (nbd, 0) == -1) {
175 fprintf (stderr, "%s\n", nbd_get_error ());
176 exit (EXIT_FAILURE);
177 }
178 nbd_close (nbd);
180 exit (EXIT_SUCCESS);
182 }
183
185 nbd_aio_pwrite(3), nbd_can_fua(3), nbd_create(3),
186 nbd_get_block_size(3), nbd_is_read_only(3), nbd_set_strict_mode(3),
187 libnbd(3).
188
190 Eric Blake
191 Richard W.M. Jones
193
195 Copyright Red Hat
196
198 This library is free software; you can redistribute it and/or modify it
199 under the terms of the GNU Lesser General Public License as published
200 by the Free Software Foundation; either version 2 of the License, or
201 (at your option) any later version.
202 This library is distributed in the hope that it will be useful, but
204 WITHOUT ANY WARRANTY; without even the implied warranty of
205 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
206 Lesser General Public License for more details.
207 You should have received a copy of the GNU Lesser General Public
209 License along with this library; if not, write to the Free Software
210 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
211 02110-1301 USA
212libnbd-1.18.1 2023-10-31 nbd_pwrite(3)