nvlzcat usage guide#

nvlzcat is a command-line utility shipped with nvCOMP that streams Gzip processing on the GPU. By default it decompresses a single Gzip bitstream from a file or the standard input and writes the raw uncompressed data to the standard output or a file. With the -c / --compress flag it instead compresses: it reads raw bytes and writes a Gzip-compliant bitstream using nvCOMP’s GPU Gzip compressor.

nvlzcat was first introduced in nvCOMP 5.2.0 (decompression only); streaming compression (-c) was added in nvCOMP 5.3.0. See the release notes.

The tool is intended for large files where streaming GPU (de)compression 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.

  • Decompression only: the GPU and driver must support concurrent managed memory access (concurrentManagedAccess device property), used for host/device data exchange during streaming decompression. Compression (-c) does not require it.

  • In the default decompression mode the input must be valid Gzip data. In compression mode (-c) the input is arbitrary raw bytes and the output is a Gzip stream.

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.

-d / --decompress

(none)

Explicitly select decompression mode. This is the default when neither -c nor -d is given.

-c / --compress

(none)

Switch to compression mode: read raw bytes and write a Gzip-compliant stream. Without this flag nvlzcat decompresses.

-a / --algorithm

level

Compression level (integer 0–5, default 1); only meaningful in compression mode (-c). Higher levels trade throughput for a better compression ratio:

  • 0 – highest-throughput, lowest ratio (entropy-only).

  • 1 – high-throughput, low ratio (default).

  • 2 – mid-throughput, mid ratio; beats Zlib level 1.

  • 3 – placeholder; currently maps to level 2.

  • 4 – lower-throughput, higher ratio; beats Zlib level 6.

  • 5 – lowest-throughput, highest ratio.

Values outside 0–5 cause an error.

-f / --input_file

path

Read input from path (Gzip when decompressing, raw bytes with -c). The referred path must exist at startup. If omitted, input is stdin (see below).

-o / --output_file

path

Write output to path (raw bytes when decompressing, Gzip with -c). 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 processing (compression or decompression). Only available with -f. The progress bar is output via stderr to avoid mixing with the data 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

Compression (-c)#

Add -c to compress instead of decompress. Input is raw bytes; output is a Gzip stream.

Compress a file (raw -> Gzip):

nvlzcat -c -f data.bin -o data.bin.gz

Compress from a pipe (stdin -> stdout):

cat data.bin | nvlzcat -c > data.bin.gz

Compress at a higher ratio (-a selects the level, see the options table):

nvlzcat -c -a 5 -f data.bin -o data.bin.gz

Round-trip (compress, then decompress, and compare):

nvlzcat -c -f data.bin | nvlzcat | cmp - data.bin

Stdin and piping#

If -f is not specified, nvlzcat reads from standard input (Gzip data when decompressing, raw data when compressing with -c).

If stdin is a TTY (interactive terminal), the program exits with an error. 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 – Processing finished successfully – decompression, or compression with -c (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.