=head1 NAME

nbdkit-ddrescue-filter - nbdkit filter for serving from ddrescue dump

=head1 SYNOPSIS

 nbdkit --filter=ddrescue plugin [plugin-args...]
                                 ddrescue-mapfile=file.map

=for paragraph

 nbdkit --filter=ddrescue file file=file.img ddrescue-mapfile=file.map
                               [plugin-args...]

=head1 DESCRIPTION

C<nbdkit-ddrescue-filter> is a filter for L<nbdkit(1)> which overlays
bad blocks according to a GNU L<ddrescue(1)> mapfile.  This is mainly useful
for testing disk images recovered with ddrescue, to detect which files
or filesystem structures are impacted, or attempting fsck on them.

Note that the current implementation is read-only.

=head1 EXAMPLES

=over 4

=item Expose a rescued disk image with detected bad sectors:

 nbdkit --filter=ddrescue file file=disk.img ddrescue-mapfile=disk.map

The above command serves the disk image disk.img and maps the bad
sectors listed in disk.img so that read attempts on them do not return
a valid block full of zeroes.

=back

=head1 PARAMETERS

The C<ddrescue-mapfile> parameter must point to a valid GNU ddrescue
mapfile.

=head1 DATA FORMAT

The file pointed to by the C<ddrescue-mapfile> parameter should
conform to the format of a GNU L<ddrescue(1)> mapfile.

=head1 FILES

=over 4

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

The filter.

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

=back

=head1 VERSION

C<nbdkit-ddrescue-filter> first appeared in nbdkit 1.22.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-file-plugin(1)>,
L<nbdkit-filter(3)>,
L<ddrescue(1)>,
L<https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html>.

=head1 AUTHORS

François Revol

=head1 COPYRIGHT

Copyright (C) 2020 François Revol
