=head1 NAME

nbdkit-nozero-filter - nbdkit nozero filter

=head1 SYNOPSIS

 nbdkit --filter=nozero plugin [plugin-args...] \
   [zero-mode=MODE] [fast-zero-mode=MODE]

=head1 DESCRIPTION

C<nbdkit-nozero-filter> is a filter that intentionally disables
efficient handling of sparse file holes (ranges of all-zero bytes)
across the NBD protocol.  It is mainly useful for evaluating timing
differences between naive vs. sparse-aware connections, and for
testing client or server fallbacks.

=head1 PARAMETERS

The parameters C<zero-mode> and C<fast-zero-mode> are optional and
control which mode the filter will use.

=over 4

=item B<zero-mode=none>

=item B<zeromode=none>

Zero support is not advertised to the client; clients must explicitly
write any regions of zero like any other normal write.

This is the default if the C<zeromode> parameter is not specified.

=item B<zero-mode=emulate>

=item B<zeromode=emulate>

Zero support is advertised, but emulated by the filter by using the
plugin's C<pwrite> callback, regardless of whether the plugin itself
has a more efficient C<zero> callback.

=item B<zero-mode=notrim>

=item B<zeromode=notrim>

(nbdkit E<ge> 1.14)

Zero requests are forwarded on to the plugin, except that the plugin
will never see the C<NBDKIT_MAY_TRIM> flag.  This can help determine
if the client permitting trimming during zero operations makes a
difference.  It is an error to request this mode if the plugin lacks
the C<zero> callback.

=item B<zero-mode=plugin>

=item B<zeromode=plugin>

(nbdkit E<ge> 1.16)

Zero requests are forwarded on to the plugin, unchanged by the filter;
this mode is helpful when experimenting with the C<fastzeromode>
parameter.  It is an error to request this mode if the plugin lacks
the C<zero> callback.

=item B<fast-zero-mode=none>

=item B<fastzeromode=none>

(nbdkit E<ge> 1.16)

Support for fast zeroing is not advertised to the client.

=item B<fast-zero-mode=slow>

=item B<fastzeromode=slow>

(nbdkit E<ge> 1.16)

Fast zero support is advertised to the client, but all fast zero
requests result in an immediate C<ENOTSUP> failure rather than
performing any fallback attempts.

=item B<fast-zero-mode=ignore>

=item B<fastzeromode=ignore>

(nbdkit E<ge> 1.16)

B<This mode is unsafe>: Fast zero support is advertised to the client,
but all fast zero requests behave as if the fast zero flag had not
been included.  This behavior is typically contrary to the NBD
specification, but can be useful for comparison against the actual
fast zero implementation to see if fast zeroes make a difference.

=item B<fast-zero-mode=default>

=item B<fastzeromode=default>

(nbdkit E<ge> 1.16)

This mode is the default.  When paired with C<zero-mode=emulate>, fast
zeroes are advertised but fast zero requests always fail (similar to
C<slow>); when paired with C<zero-mode=notrim> or C<zero-mode=plugin>,
fast zero support is left to the plugin (although in the latter case,
the nozero filter could be omitted for the same behavior).

=back

=head1 EXAMPLES

Serve the file F<disk.img>, but force the client to write zeroes
explicitly rather than with C<NBD_CMD_WRITE_ZEROES>:

 nbdkit --filter=nozero file disk.img

Serve the file F<disk.img>, allowing the client to take advantage of
less network traffic via C<NBD_CMD_WRITE_ZEROES>, but fail any fast
zero requests up front and force all other zero requests to write data
explicitly rather than punching any holes:

 nbdkit --filter=nozero file zero-mode=emulate disk.img

Serve the file F<disk.img>, but do not advertise fast zero support to
the client even if the plugin supports it:

 nbdkit --filter=nozero file zero-mode=plugin fast-zero-mode=none disk.img

=head1 FILES

=over 4

=item F<$filterdir/nbdkit-nozero-filter.so>

The filter.

Use C<nbdkit --dump-config> to find the location of C<$filterdir>.

=back

=head1 VERSION

C<nbdkit-nozero-filter> first appeared in nbdkit 1.4.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-file-plugin(1)>,
L<nbdkit-filter(3)>,
L<nbdkit-fua-filter(1)>,
L<nbdkit-multi-conn-filter(1)>,
L<nbdkit-nocache-filter(1)>,
L<nbdkit-noparallel-filter(1)>,
L<nbdkit-noextents-filter(1)>.

=head1 AUTHORS

Eric Blake

=head1 COPYRIGHT

Copyright Red Hat
