=head1 NAME

nbdkit-gzip-filter - decompress a .gz file

=head1 SYNOPSIS

 nbdkit file --filter=gzip FILENAME.gz

=head1 DESCRIPTION

C<nbdkit-gzip-filter> is a filter for L<nbdkit(1)> which transparently
decompresses a gzip-compressed file.  You can place this filter on top
of L<nbdkit-file-plugin(1)> to decompress a local F<.gz> file, or on
top of other plugins such as L<nbdkit-curl-plugin(1)>:

 nbdkit curl --filter=gzip https://example.com/disk.gz

With L<nbdkit-tar-filter(1)> it can be used to extract files from a
compressed tar file:

 nbdkit curl --filter=tar --filter=gzip \
        https://example.com/file.tar.gz tar-entry=disk.img

The filter only allows read-only connections.

B<Note> that gzip files are not very good for random access in large
files because seeking to a position in the gzip file involves
decompressing all data before that point in the file.
L<nbdkit-indexed-gzip-filter(1)> is an alternate filter to this one
which builds an index file, which can mitigate this problem.  Another
method to compress large disk images is to use L<xz(1)> or
L<plzip(1)>.  Both L<nbdkit-xz-filter(1)> and L<nbdkit-lzip-filter(1)>
support block-level decompression if the file was compressed using the
right options.

To allow seeking this filter has to keep the contents of the complete
uncompressed file, which it does in a hidden temporary file under
C<$TMPDIR>.

=head1 PARAMETERS

There are no parameters specific to this plugin.

=head1 ENVIRONMENT VARIABLES

=over 4

=item C<TMPDIR>

Because the gzip format is not seekable, this filter has to store the
complete contents of the compressed file in a temporary file located
in F</var/tmp> by default.  You can override this location by setting
the C<TMPDIR> environment variable before starting nbdkit.

=back

=head1 FILES

=over 4

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

The plugin.

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

=back

=head1 VERSION

C<nbdkit-gzip-filter> first appeared in nbdkit 1.22.  It is derived
from C<nbdkit-gzip-plugin> which first appeared in nbdkit 1.0.

=head1 SEE ALSO

L<nbdkit-bzip2-filter(1)>,
L<nbdkit-curl-plugin(1)>,
L<nbdkit-file-plugin(1)>,
L<nbdkit-indexed-gzip-filter(1)>,
L<nbdkit-lzip-filter(1)>,
L<nbdkit-tar-filter(1)>,
L<nbdkit-xz-filter(1)>,
L<nbdkit(1)>,
L<nbdkit-plugin(3)>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
