1nbd_pwrite(3)                       LIBNBD                       nbd_pwrite(3)
2
3
4

NAME

6       nbd_pwrite - write to the NBD server
7

SYNOPSIS

9        #include <libnbd.h>
10
11        int nbd_pwrite (struct nbd_handle *h, const void *buf,
12                        size_t count, uint64_t offset,
13                        uint32_t flags);
14

DESCRIPTION

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
23       The "flags" parameter may be 0 for no flags, or may contain
24       "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
25       the data has been committed to permanent storage (if that is supported
26       - some servers cannot do this, see nbd_can_fua(3)).
27
28       By default, libnbd will reject attempts to use this function with
29       parameters that are likely to result in server failure, such as
30       requesting an unknown command flag.  The nbd_set_strict_mode(3)
31       function can be used to alter which scenarios should await a server
32       reply rather than failing fast.
33

RETURN VALUE

35       If the call is successful the function returns 0.
36

ERRORS

38       On error "-1" is returned.
39
40       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
41       of the error.
42

HANDLE STATE

44       The handle must be connected with the server, otherwise this call will
45       return an error.
46

VERSION

48       This function first appeared in libnbd 1.0.
49
50       If you need to test if this function is available at compile time check
51       if the following macro is defined:
52
53        #define LIBNBD_HAVE_NBD_PWRITE 1
54

EXAMPLE

56       This example is also available as examples/reads-and-writes.c in the
57       libnbd source code.
58
59        /* This example shows how to do synchronous reads
60         * and writes randomly over the first megabyte of an
61         * NBD server.  Note this will destroy any existing
62         * content on the NBD server.
63         *
64         * To test it with nbdkit and a RAM disk:
65         *
66         * nbdkit -U - memory 1M \
67         *     --run './simple-reads-and-writes $unixsocket'
68         */
69
70        #include <stdio.h>
71        #include <stdlib.h>
72        #include <inttypes.h>
73        #include <assert.h>
74        #include <time.h>
75
76        #include <libnbd.h>
77
78        int
79        main (int argc, char *argv[])
80        {
81          struct nbd_handle *nbd;
82          char buf[512];
83          size_t i;
84          int64_t exportsize;
85          uint64_t offset;
86
87          srand (time (NULL));
88
89          if (argc != 2) {
90            fprintf (stderr, "%s socket\n", argv[0]);
91            exit (EXIT_FAILURE);
92          }
93
94          /* Create the libnbd handle. */
95          nbd = nbd_create ();
96          if (nbd == NULL) {
97            fprintf (stderr, "%s\n", nbd_get_error ());
98            exit (EXIT_FAILURE);
99          }
100
101          /* Connect to the NBD server over a
102           * Unix domain socket.
103           */
104          if (nbd_connect_unix (nbd, argv[1]) == -1) {
105            fprintf (stderr, "%s\n", nbd_get_error ());
106            exit (EXIT_FAILURE);
107          }
108
109          /* Get the size of the disk and check
110           * it's large enough.
111           */
112          exportsize = nbd_get_size (nbd);
113          if (exportsize == -1) {
114            fprintf (stderr, "%s\n", nbd_get_error ());
115            exit (EXIT_FAILURE);
116          }
117          assert (exportsize >= sizeof buf);
118
119          /* Check that the server is writable. */
120          if (nbd_is_read_only (nbd) == 1) {
121            fprintf (stderr, "%s: "
122                     "error: this NBD export is read-only\n",
123                     argv[0]);
124            exit (EXIT_FAILURE);
125          }
126
127          for (i = 0; i < sizeof buf; ++i)
128            buf[i] = rand ();
129
130          /* 1000 writes. */
131          for (i = 0; i < 1000; ++i) {
132            offset = rand () % (exportsize - sizeof buf);
133
134            if (nbd_pwrite (nbd, buf, sizeof buf,
135                            offset, 0) == -1) {
136              fprintf (stderr, "%s\n", nbd_get_error ());
137              exit (EXIT_FAILURE);
138            }
139          }
140
141          /* 1000 reads and writes. */
142          for (i = 0; i < 1000; ++i) {
143            offset = rand () % (exportsize - sizeof buf);
144            if (nbd_pread (nbd, buf, sizeof buf,
145                           offset, 0) == -1) {
146              fprintf (stderr, "%s\n", nbd_get_error ());
147              exit (EXIT_FAILURE);
148            }
149
150            offset = rand () % (exportsize - sizeof buf);
151            if (nbd_pwrite (nbd, buf, sizeof buf,
152                            offset, 0) == -1) {
153              fprintf (stderr, "%s\n", nbd_get_error ());
154              exit (EXIT_FAILURE);
155            }
156          }
157
158          /* Sends a graceful shutdown to the server. */
159          if (nbd_shutdown (nbd, 0) == -1) {
160            fprintf (stderr, "%s\n", nbd_get_error ());
161            exit (EXIT_FAILURE);
162          }
163
164          nbd_close (nbd);
165
166          exit (EXIT_SUCCESS);
167        }
168

SEE ALSO

170       nbd_aio_pwrite(3), nbd_can_fua(3), nbd_create(3),
171       nbd_get_block_size(3), nbd_is_read_only(3), nbd_set_strict_mode(3),
172       libnbd(3).
173

AUTHORS

175       Eric Blake
176
177       Richard W.M. Jones
178
180       Copyright (C) 2019-2020 Red Hat Inc.
181

LICENSE

183       This library is free software; you can redistribute it and/or modify it
184       under the terms of the GNU Lesser General Public License as published
185       by the Free Software Foundation; either version 2 of the License, or
186       (at your option) any later version.
187
188       This library is distributed in the hope that it will be useful, but
189       WITHOUT ANY WARRANTY; without even the implied warranty of
190       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
191       Lesser General Public License for more details.
192
193       You should have received a copy of the GNU Lesser General Public
194       License along with this library; if not, write to the Free Software
195       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
196       02110-1301 USA
197
198
199
200libnbd-1.6.2                      2021-03-02                     nbd_pwrite(3)
Impressum