1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
|
=head1 NAME
nbd_zero - send write zeroes command to the NBD server
=head1 SYNOPSIS
#include <libnbd.h>
int nbd_zero (
struct nbd_handle *h, uint64_t count,
uint64_t offset, uint32_t flags
);
=head1 DESCRIPTION
Issue a write zeroes command to the NBD server,
which if supported
by the server causes a zeroes to be written efficiently
starting at C<offset> and ending at C<offset> + C<count> - 1.
The call returns when the command has been acknowledged by the server,
or there is an error. Note this will generally return an error if
L<nbd_can_zero(3)> is false or L<nbd_is_read_only(3)> is true.
Note that not all servers can support a C<count> of 4GiB or larger;
L<nbd_get_extended_headers_negotiated(3)> indicates which servers
will parse a request larger than 32 bits.
The NBD protocol does not yet have a way for a client to learn if
the server will enforce an even smaller maximum zero size, although
a future extension may add a constraint visible in
L<nbd_get_block_size(3)>. Also, some servers may permit a larger
zero request only when the C<LIBNBD_CMD_FLAG_FAST_ZERO> is in use.
The C<flags> parameter may be C<0> for no flags, or may contain
C<LIBNBD_CMD_FLAG_FUA> meaning that the server should not
return until the data has been committed to permanent storage
(if that is supported - some servers cannot do this, see
L<nbd_can_fua(3)>), C<LIBNBD_CMD_FLAG_NO_HOLE> meaning that
the server should favor writing actual allocated zeroes over
punching a hole, and/or C<LIBNBD_CMD_FLAG_FAST_ZERO> meaning
that the server must fail quickly if writing zeroes is no
faster than a normal write (if that is supported - some servers
cannot do this, see L<nbd_can_fast_zero(3)>).
By default, libnbd will reject attempts to use this function with
parameters that are likely to result in server failure, such as
requesting an unknown command flag. The L<nbd_set_strict_mode(3)>
function can be used to alter which scenarios should await a server
reply rather than failing fast.
=head1 RETURN VALUE
If the call is successful the function returns C<0>.
=head1 ERRORS
On error C<-1> is returned.
Refer to L<libnbd(3)/ERROR HANDLING>
for how to get further details of the error.
The following parameters must not be NULL: C<h>.
For more information see L<libnbd(3)/Non-NULL parameters>.
=head1 HANDLE STATE
nbd_zero
can be called when the handle is in the following state:
┌─────────────────────────────────────┬─────────────────────────┐
│ Handle created, before connecting │ ❌ error │
│ Connecting │ ❌ error │
│ Connecting & handshaking (opt_mode) │ ❌ error │
│ Connected to the server │ ✅ allowed │
│ Connection shut down │ ❌ error │
│ Handle dead │ ❌ error │
└─────────────────────────────────────┴─────────────────────────┘
=head1 VERSION
This function first appeared in libnbd 1.0.
If you need to test if this function is available at compile time
check if the following macro is defined:
#define LIBNBD_HAVE_NBD_ZERO 1
=head1 SEE ALSO
L<nbd_aio_zero(3)>,
L<nbd_can_fast_zero(3)>,
L<nbd_can_fua(3)>,
L<nbd_can_zero(3)>,
L<nbd_create(3)>,
L<nbd_get_block_size(3)>,
L<nbd_get_extended_headers_negotiated(3)>,
L<nbd_is_read_only(3)>,
L<nbd_set_strict_mode(3)>,
L<libnbd(3)>.
=head1 AUTHORS
Eric Blake
Richard W.M. Jones
=head1 COPYRIGHT
Copyright Red Hat
|
