nvlzcat usage guide#

nvlzcat is a command-line utility shipped with nvCOMP that decompresses a single gzip bitstream on the GPU using the library’s lookahead gzip algorithm. It reads deflate/gzip-compressed bytes from a file or standard input and writes the raw uncompressed data to standard output or a file. nvlzcat was first introduced in nvCOMP 5.2.0; see the release notes.

The tool is intended for large gzip files where streaming GPU decompression is useful; it is not a general replacement for every gzip / zcat workflow.

Note

The nvlzcat executable is built for Linux only. Official Linux installers obtained from the nvCOMP downloads page install nvlzcat to /usr/bin/. To verify installation use nvlzcat -h.

Requirements#

  • A CUDA-capable NVIDIA GPU and a driver compatible with your nvCOMP build.

  • The GPU and driver must support concurrent managed memory access (concurrentManagedAccess device property). This is required for host/device data exchange during streaming decompression.

  • Input must be valid gzip data.

Command-line options#

Options are parsed in order; each flag is either a boolean switch or takes the next argument as its value.

Short / long

Argument

Description

-h / --help

(none)

Print usage to stdout and exit successfully.

-f / --input_file

path

Read gzip from path. The referred path must exist at startup. If omitted, input is stdin (see below).

-o / --output_file

path

Write decompressed data to path. If omitted, output is stdout.

-g / --gpu

device_id

CUDA device index (integer, default 0). Must be a valid device for the current process.

-p / --progress

(none)

Show read progress while decompressing. Only available with -f. The progress bar is output via stderr to avoid mixing with decompressed output.

Unknown flags cause an error and exit with non-zero status.

Basic examples#

Decompress a file to stdout:

nvlzcat -f archive.gz

Decompress to a file:

nvlzcat -f archive.gz -o archive.bin

Use a specific GPU:

nvlzcat -f huge.log.gz -g 1 -o huge.log

Pipe gzip data (stdin -> stdout):

cat archive.gz | nvlzcat | wc -c

Progress bar (file input only):

nvlzcat -f archive.gz -p -o archive.bin

More advanced piping (network -> file):

curl -s https://example.com/archive.gz | nvlzcat > archive.bin

Stdin and piping#

If -f is not specified, nvlzcat reads from standard input.

If stdin is a TTY (interactive terminal), the program exits with an error. Compressed binary data must be piped or redirected, not typed interactively.

Combine with shell redirection when you do not use -f:

nvlzcat < archive.gz > archive.bin

Exit status and errors#

  • 0 – Decompression finished successfully (or help was requested with -h).

  • Non-zero – Failure (bad arguments, missing file, CUDA/nvCOMP error, invalid gzip stream, etc.).

Messages are printed to stderr in the form:

nvlzcat: <message>

Limitations#

  • One gzip stream per invocation; no multi-file batch mode in the tool itself.

  • Decompression only; nvlzcat does not compress.