=head1 NAME

nbdkit-indexed-gzip-filter - access .gz contents efficiently

=head1 SYNOPSIS

 nbdkit --filter=indexed-gzip PLUGIN gzip-index-path=PATH
                                     [gzip-index-span=SIZE]

=head1 DESCRIPTION

C<nbdkit-indexed-gzip-filter> is a filter for nbdkit that provides
fast and efficient random-access to gzip-compressed data.

The standard L<nbdkit-gzip-filter(1)> decompresses the entire archive
to a temporary file, which means you need to have enough storage or
memory to store the complete uncompressed input.

With this filter, the entire archive still needs to be decompressed
once, but only an index file needs to be stored in storage or memory,
which (depending on user-specified distance between index points) may
be 0.3% to 3% of the size of the uncompressed archive.

=head1 PARAMETERS

=over 4

=item B<gzip-index-path=>PATH

Path to the complete gzip index file (created if it doesn't exist,
reused if it does).

This parameter is required.

=item B<gzip-index-span=>SIZE

Number of bytes between index points. Eg. 1M, 10M etc. (default: 1MB)

A span of 10M produces an index file of eg, ~0.3% of uncompressed input

A span of 1M produces an index file of eg, ~3% of uncompressed input.

Smaller span improves random-access performance, since on average it
means fewer bytes to decompress until reaching the requested byte
(with the trade-off of a larger index file).

=back

=head1 FILES

=over 4

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

The filter.

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

=back

=head1 VERSION

L<nbdkit-indexed-gzip-filter> first appeared in nbdkit 1.46.

=head1 SEE ALSO

L<nbdkit(1)>, L<nbdkit-filter(3)>, L<nbdkit-gzip-filter(1)>

=head1 AUTHORS

Shasheen Ediriweera

Mark Adler

=head1 COPYRIGHT

Copyright (C) 2025 Shasheen Ediriweera

Copyright (C) 2005, 2012, 2018, 2023, 2024 Mark Adler

=cut
