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 (struct nbd_handle *h, const void *buf,
12 size_t count, uint64_t offset,
13 uint32_t flags);
14
16 Issue a write command to the NBD server, writing the data in "buf" to
17 the range starting at "offset" and ending at "offset" + "count" - 1.
18 NBD can only write all or nothing using this call. The call returns
19 when the command has been acknowledged by the server, or there is an
20 error. Note this will generally return an error if nbd_is_read_only(3)
21 is true.
22 Note that libnbd currently enforces a maximum write 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 The "flags" parameter may be 0 for no flags, or may contain
30 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
31 the data has been committed to permanent storage (if that is supported
32 - some servers cannot do this, see nbd_can_fua(3)).
33 By default, libnbd will reject attempts to use this function with
35 parameters that are likely to result in server failure, such as
36 requesting an unknown command flag. The nbd_set_strict_mode(3)
37 function can be used to alter which scenarios should await a server
38 reply rather than failing fast.
39
41 If the call is successful the function returns 0.
42
44 On error "-1" is returned.
45 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
47 of the error.
48
50 The handle must be connected with the server, otherwise this call will
51 return an error.
52
54 This function first appeared in libnbd 1.0.
55 If you need to test if this function is available at compile time check
57 if the following macro is defined:
58 #define LIBNBD_HAVE_NBD_PWRITE 1
60
62 This example is also available as examples/reads-and-writes.c in the
63 libnbd source code.
64 /* This example shows how to do synchronous reads
66 * and writes randomly over the first megabyte of an
67 * NBD server. Note this will destroy any existing
68 * content on the NBD server.
69 *
70 * To test it with nbdkit and a RAM disk:
71 *
72 * nbdkit -U - memory 1M \
73 * --run './simple-reads-and-writes $unixsocket'
74 */
75 #include <stdio.h>
77 #include <stdlib.h>
78 #include <inttypes.h>
79 #include <assert.h>
80 #include <time.h>
81 #include <libnbd.h>
83 int
85 main (int argc, char *argv[])
86 {
87 struct nbd_handle *nbd;
88 char buf[512];
89 size_t i;
90 int64_t exportsize;
91 uint64_t offset;
92 srand (time (NULL));
94 if (argc != 2) {
96 fprintf (stderr, "%s socket\n", argv[0]);
97 exit (EXIT_FAILURE);
98 }
99 /* Create the libnbd handle. */
101 nbd = nbd_create ();
102 if (nbd == NULL) {
103 fprintf (stderr, "%s\n", nbd_get_error ());
104 exit (EXIT_FAILURE);
105 }
106 /* Connect to the NBD server over a
108 * Unix domain socket.
109 */
110 if (nbd_connect_unix (nbd, argv[1]) == -1) {
111 fprintf (stderr, "%s\n", nbd_get_error ());
112 exit (EXIT_FAILURE);
113 }
114 /* Get the size of the disk and check
116 * it's large enough.
117 */
118 exportsize = nbd_get_size (nbd);
119 if (exportsize == -1) {
120 fprintf (stderr, "%s\n", nbd_get_error ());
121 exit (EXIT_FAILURE);
122 }
123 assert (exportsize >= sizeof buf);
124 /* Check that the server is writable. */
126 if (nbd_is_read_only (nbd) == 1) {
127 fprintf (stderr, "%s: "
128 "error: this NBD export is read-only\n",
129 argv[0]);
130 exit (EXIT_FAILURE);
131 }
132 for (i = 0; i < sizeof buf; ++i)
134 buf[i] = rand ();
135 /* 1000 writes. */
137 for (i = 0; i < 1000; ++i) {
138 offset = rand () % (exportsize - sizeof buf);
139 if (nbd_pwrite (nbd, buf, sizeof buf,
141 offset, 0) == -1) {
142 fprintf (stderr, "%s\n", nbd_get_error ());
143 exit (EXIT_FAILURE);
144 }
145 }
146 /* 1000 reads and writes. */
148 for (i = 0; i < 1000; ++i) {
149 offset = rand () % (exportsize - sizeof buf);
150 if (nbd_pread (nbd, buf, sizeof buf,
151 offset, 0) == -1) {
152 fprintf (stderr, "%s\n", nbd_get_error ());
153 exit (EXIT_FAILURE);
154 }
155 offset = rand () % (exportsize - sizeof buf);
157 if (nbd_pwrite (nbd, buf, sizeof buf,
158 offset, 0) == -1) {
159 fprintf (stderr, "%s\n", nbd_get_error ());
160 exit (EXIT_FAILURE);
161 }
162 }
163 /* Sends a graceful shutdown to the server. */
165 if (nbd_shutdown (nbd, 0) == -1) {
166 fprintf (stderr, "%s\n", nbd_get_error ());
167 exit (EXIT_FAILURE);
168 }
169 nbd_close (nbd);
171 exit (EXIT_SUCCESS);
173 }
174
176 nbd_aio_pwrite(3), nbd_can_fua(3), nbd_create(3),
177 nbd_get_block_size(3), nbd_is_read_only(3), nbd_set_strict_mode(3),
178 libnbd(3).
179
181 Eric Blake
182 Richard W.M. Jones
184
186 Copyright (C) 2019-2021 Red Hat Inc.
187
189 This library is free software; you can redistribute it and/or modify it
190 under the terms of the GNU Lesser General Public License as published
191 by the Free Software Foundation; either version 2 of the License, or
192 (at your option) any later version.
193 This library is distributed in the hope that it will be useful, but
195 WITHOUT ANY WARRANTY; without even the implied warranty of
196 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
197 Lesser General Public License for more details.
198 You should have received a copy of the GNU Lesser General Public
200 License along with this library; if not, write to the Free Software
201 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
202 02110-1301 USA
203libnbd-1.12.5 2022-07-10 nbd_pwrite(3)