=head1 NAME

nbdkit-offset-filter - nbdkit offset filter

=head1 SYNOPSIS

 nbdkit --filter=offset plugin offset=OFFSET range=LENGTH [plugin-args...]

=head1 DESCRIPTION

C<nbdkit-offset-filter> is a filter that limits requests to the byte
range C<[offset .. offset+range-1]> within another plugin.

=head1 PARAMETERS

=over 4

=item B<offset=>OFFSET

The start offset.  The offset must be E<ge> 0.

This parameter is optional.  If not given then C<offset=0> is assumed.

=item B<range=>LENGTH

The length of data to serve.

This parameter is optional.  If not given then the range is served
starting from the offset through to the end of the underlying
file/device.

=back

Note it is an error if the offset and/or range specify data which lies
beyond the end of the underlying device.  Use
L<nbdkit-truncate-filter(1)> to truncate or extend the size of
plugins.

=head1 EXAMPLES

=head2 Serve part of a file

Using L<nbdkit-file-plugin(1)>, serve the file C<disk.img> starting at
offset C<1M>.  The total length served is C<100M> (the underlying file
must therefore be at least C<101M> in length):

 nbdkit --filter=offset file disk.img offset=1M range=100M

=head2 Serve a single partition

I<An easier way to do this is with L<nbdkit-partition-filter(1)>.>

One way to serve a single partition from a disk is to find the start
and length of the partition, eg using:

 $ parted disk.img -- unit b print
 ...
 Number  Start   End         Size        Type     File system  Flags
  1      65536B  104792575B  104727040B  primary  ext2

You can then serve the partition only using:

 nbdkit --filter=offset file disk.img offset=65536 range=104727040

=head1 FILES

=over 4

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

The filter.

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

=back

=head1 VERSION

C<nbdkit-offset-filter> first appeared in nbdkit 1.2.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-file-plugin(1)>,
L<nbdkit-filter(3)>,
L<nbdkit-partition-filter(1)>,
L<nbdkit-protect-filter(1)>,
L<nbdkit-tar-filter(1)>,
L<nbdkit-truncate-filter(1)>.

=head1 AUTHORS

Eric Blake

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
