=head1 NAME

nbdkit-checkwrite-filter - check writes match contents of plugin

=head1 SYNOPSIS

 nbdkit --filter=checkwrite PLUGIN

=head1 DESCRIPTION

C<nbdkit-checkwrite-filter> is an nbdkit filter that turns write
operations into checks that what is written matches the existing
content of the plugin.  If the content matches then the write
operation succeeds (doing nothing).  If not then the write operation
fails returning EIO Input/output error.

The purpose of this filter is to test copying tools as described
below.

The underlying plugin is opened read-only and is never written to.
All write-like operations are covered by this filter, such as trimming
and zeroing.  This filter tests the logical equivalence of the writes,
ignoring differences in sparseness.

=head2 Using this filter to test copying tools

You can check that a copying tool is copying data correctly by
creating an nbdkit instance containing some test data, overlaying this
filter, and copying from and to nbdkit at the same time:

 nbdkit --filter=checkwrite data "@32768 1" \
        --run 'nbdcopy "$uri" "$uri"'

=for paragraph

 nbdkit --filter=checkwrite file disk.img \
        --run 'nbdcopy "$uri" "$uri"'

=for paragraph

 nbdkit --filter=checkwrite linuxdisk testdir/ \
        --run 'qemu-img convert -n "$uri" "$uri"'

If the copying program is buggy then you will see EIO errors and (if
the copying program also handles errors correctly) it should exit with
an error.

=head2 Other plugins for testing NBD tools

If you are doing this kind of testing you will also want to look at
L<nbdkit-random-plugin(1)> and L<nbdkit-sparse-random-plugin(1)>.
These plugins already have this behaviour built in to them (because it
is more efficient to build it into the plugin) — you do B<not> need to
use this filter with those plugins.  This filter is useful for testing
with arbitrary plugins.

=head1 PARAMETERS

There are no parameters specific to this filter.  Parameters are
passed through to the underlying plugin.

=head1 FILES

=over 4

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

The filter.

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

=back

=head1 VERSION

C<nbdkit-checkwrite-filter> first appeared in nbdkit 1.24.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-random-plugin(1)>,
L<nbdkit-sparse-random-plugin(1)>,
L<nbdkit-filter(3)>,
L<nbdkit-plugin(3)>,
L<nbdcopy(1)>,
L<qemu-img(1)>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
