filters/offset/nbdkit-offset-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-offset-filter - nbdkit offset filter
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=offset plugin offset=OFFSET range=LENGTH [plugin-args...]
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-offset-filter> is a filter that limits requests to the byte
  12 range C<[offset .. offset+range-1]> within another plugin.
  13
  14 =head1 PARAMETERS
  15
  16 =over 4
  17
  18 =item B<offset=>OFFSET
  19
  20 The start offset.  The offset must be E<ge> 0.
  21
  22 This parameter is optional.  If not given then C<offset=0> is assumed.
  23
  24 =item B<range=>LENGTH
  25
  26 The length of data to serve.
  27
  28 This parameter is optional.  If not given then the range is served
  29 starting from the offset through to the end of the underlying
  30 file/device.
  31
  32 =back
  33
  34 Note it is an error if the offset and/or range specify data which lies
  35 beyond the end of the underlying device.  Use
  36 L<nbdkit-truncate-filter(1)> to truncate or extend the size of
  37 plugins.
  38
  39 =head1 EXAMPLES
  40
  41 =head2 Serve part of a file
  42
  43 Using L<nbdkit-file-plugin(1)>, serve the file C<disk.img> starting at
  44 offset C<1M>.  The total length served is C<100M> (the underlying file
  45 must therefore be at least C<101M> in length):
  46
  47  nbdkit --filter=offset file disk.img offset=1M range=100M
  48
  49 =head2 Serve a single partition
  50
  51 I<An easier way to do this is with L<nbdkit-partition-filter(1)>.>
  52
  53 One way to serve a single partition from a disk is to find the start
  54 and length of the partition, eg using:
  55
  56  $ parted disk.img -- unit b print
  57  ...
  58  Number  Start   End         Size        Type     File system  Flags
  59   1      65536B  104792575B  104727040B  primary  ext2
  60
  61 You can then serve the partition only using:
  62
  63  nbdkit --filter=offset file disk.img offset=65536 range=104727040
  64
  65 =head1 FILES
  66
  67 =over 4
  68
  69 =item F<$filterdir/nbdkit-offset-filter.so>
  70
  71 The filter.
  72
  73 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
  74
  75 =back
  76
  77 =head1 VERSION
  78
  79 C<nbdkit-offset-filter> first appeared in nbdkit 1.2.
  80
  81 =head1 SEE ALSO
  82
  83 L<nbdkit(1)>,
  84 L<nbdkit-file-plugin(1)>,
  85 L<nbdkit-filter(3)>,
  86 L<nbdkit-partition-filter(1)>,
  87 L<nbdkit-protect-filter(1)>,
  88 L<nbdkit-tar-filter(1)>,
  89 L<nbdkit-truncate-filter(1)>.
  90
  91 =head1 AUTHORS
  92
  93 Eric Blake
  94
  95 Richard W.M. Jones
  96
  97 =head1 COPYRIGHT
  98
  99 Copyright Red Hat