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 The following parameters must not be NULL: "h", "buf". For more
50 information see "Non-NULL parameters" in libnbd(3).
51
53 The handle must be connected with the server, otherwise this call will
54 return an error.
55
57 This function first appeared in libnbd 1.0.
58 If you need to test if this function is available at compile time check
60 if the following macro is defined:
61 #define LIBNBD_HAVE_NBD_PWRITE 1
63
65 This example is also available as examples/reads-and-writes.c in the
66 libnbd source code.
67 /* This example shows how to do synchronous reads
69 * and writes randomly over the first megabyte of an
70 * NBD server. Note this will destroy any existing
71 * content on the NBD server.
72 *
73 * To test it with nbdkit and a RAM disk:
74 *
75 * nbdkit -U - memory 1M \
76 * --run './simple-reads-and-writes $unixsocket'
77 */
78 #include <stdio.h>
80 #include <stdlib.h>
81 #include <inttypes.h>
82 #include <assert.h>
83 #include <time.h>
84 #include <libnbd.h>
86 int
88 main (int argc, char *argv[])
89 {
90 struct nbd_handle *nbd;
91 char buf[512];
92 size_t i;
93 int64_t exportsize;
94 uint64_t offset;
95 srand (time (NULL));
97 if (argc != 2) {
99 fprintf (stderr, "%s socket\n", argv[0]);
100 exit (EXIT_FAILURE);
101 }
102 /* Create the libnbd handle. */
104 nbd = nbd_create ();
105 if (nbd == NULL) {
106 fprintf (stderr, "%s\n", nbd_get_error ());
107 exit (EXIT_FAILURE);
108 }
109 /* Connect to the NBD server over a
111 * Unix domain socket.
112 */
113 if (nbd_connect_unix (nbd, argv[1]) == -1) {
114 fprintf (stderr, "%s\n", nbd_get_error ());
115 exit (EXIT_FAILURE);
116 }
117 /* Get the size of the disk and check
119 * it's large enough.
120 */
121 exportsize = nbd_get_size (nbd);
122 if (exportsize == -1) {
123 fprintf (stderr, "%s\n", nbd_get_error ());
124 exit (EXIT_FAILURE);
125 }
126 assert (exportsize >= sizeof buf);
127 /* Check that the server is writable. */
129 if (nbd_is_read_only (nbd) == 1) {
130 fprintf (stderr, "%s: "
131 "error: this NBD export is read-only\n",
132 argv[0]);
133 exit (EXIT_FAILURE);
134 }
135 for (i = 0; i < sizeof buf; ++i)
137 buf[i] = rand ();
138 /* 1000 writes. */
140 for (i = 0; i < 1000; ++i) {
141 offset = rand () % (exportsize - sizeof buf);
142 if (nbd_pwrite (nbd, buf, sizeof buf,
144 offset, 0) == -1) {
145 fprintf (stderr, "%s\n", nbd_get_error ());
146 exit (EXIT_FAILURE);
147 }
148 }
149 /* 1000 reads and writes. */
151 for (i = 0; i < 1000; ++i) {
152 offset = rand () % (exportsize - sizeof buf);
153 if (nbd_pread (nbd, buf, sizeof buf,
154 offset, 0) == -1) {
155 fprintf (stderr, "%s\n", nbd_get_error ());
156 exit (EXIT_FAILURE);
157 }
158 offset = rand () % (exportsize - sizeof buf);
160 if (nbd_pwrite (nbd, buf, sizeof buf,
161 offset, 0) == -1) {
162 fprintf (stderr, "%s\n", nbd_get_error ());
163 exit (EXIT_FAILURE);
164 }
165 }
166 /* Sends a graceful shutdown to the server. */
168 if (nbd_shutdown (nbd, 0) == -1) {
169 fprintf (stderr, "%s\n", nbd_get_error ());
170 exit (EXIT_FAILURE);
171 }
172 nbd_close (nbd);
174 exit (EXIT_SUCCESS);
176 }
177
179 nbd_aio_pwrite(3), nbd_can_fua(3), nbd_create(3),
180 nbd_get_block_size(3), nbd_is_read_only(3), nbd_set_strict_mode(3),
181 libnbd(3).
182
184 Eric Blake
185 Richard W.M. Jones
187
189 Copyright (C) 2019-2021 Red Hat Inc.
190
192 This library is free software; you can redistribute it and/or modify it
193 under the terms of the GNU Lesser General Public License as published
194 by the Free Software Foundation; either version 2 of the License, or
195 (at your option) any later version.
196 This library is distributed in the hope that it will be useful, but
198 WITHOUT ANY WARRANTY; without even the implied warranty of
199 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
200 Lesser General Public License for more details.
201 You should have received a copy of the GNU Lesser General Public
203 License along with this library; if not, write to the Free Software
204 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
205 02110-1301 USA
206libnbd-1.14.2 2023-01-03 nbd_pwrite(3)