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.
21
22       The "flags" parameter may be 0 for no flags, or may contain
23       "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
24       the data has been committed to permanent storage (if that is supported
25       - some servers cannot do this, see nbd_can_fua(3)).
26

RETURN VALUE

28       If the call is successful the function returns 0.
29

ERRORS

31       On error "-1" is returned.
32
33       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
34       of the error.
35

HANDLE STATE

37       The handle must be connected and finished handshaking with the server,
38       otherwise this call will return an error.
39

VERSION

41       This function first appeared in libnbd 1.0.
42
43       If you need to test if this function is available at compile time check
44       if the following macro is defined:
45
46        #define LIBNBD_HAVE_NBD_PWRITE 1
47

EXAMPLE

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

SEE ALSO

163       nbd_can_fua(3), nbd_can_write(3), nbd_aio_pwrite(3), nbd_create(3),
164       libnbd(3).
165

AUTHORS

167       Eric Blake
168
169       Richard W.M. Jones
170
172       Copyright (C) 2019 Red Hat Inc.
173

LICENSE

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