Libx LZ4 ドキュメント

    このページの内容

    LZ4ライブラリのコマンドラインインターフェース

    ビルド

    lz4のコマンドラインインターフェース（CLI）は、追加のパラメーターを指定せず、makeコマンドで生成します。

    CLIは、LZ4で圧縮したフレームを生成・展開します。

    ビルド処理をさらに制御できるよう、Makefileスクリプトは標準の規約すべてに対応します。標準のターゲット（all、install、cleanなど）や変数（CC、CFLAGS、CPPFLAGSなど）も含みます。

    Makefileは、用途に応じた複数のターゲットを提供します。

    • lz4: gzipに似たコマンドライン構文を使う、既定のCLI。
    • lz4c: 旧来のlz4コマンドに対応します（gzipとは互換性がありません）。
    • lz4c32: lz4cと同じですが、32ビットの実行ファイルを生成します。
    • unlz4、lz4cat: lz4へのシンボリックリンクで、既定では展開と、圧縮ファイルのcatを行います。
    • man: Markdownソースのlz4.1.mdからmanページを生成します。

    Makefileのビルド変数

    • HAVE_MULTITHREAD: マルチスレッド対応でビルドします。通常は自動検出ですが、必要に応じて0または1へ強制できます。例えば、LinuxからWindows向けにクロスコンパイルする際に役立ちます。
    • HAVE_PTHREAD: <pthread>対応の有無を決めます。自動検出ですが、必要に応じて0または1へ強制できます。makeは、この結果を使い、マルチスレッド対応を自動的に有効にします。

    Cプリプロセッサーのビルド変数

    これらは、コンパイル時にプリプロセッサーが読む変数です。開始時の既定値など、実行ファイルの動作に影響し、programs/lz4conf.hで公開しています。どのビルドシステムからでも操作できます。代入方法は環境によって異なります。 通常のposix + gcc + make環境では、CPPFLAGS=-DVARIABLE=valueの代入で定義できます。

    • LZ4_CLEVEL_DEFAULT: 指定がない場合の既定の圧縮レベル。既定値は1です。
    • LZ4IO_MULTITHREAD: マルチスレッド対応を有効にします。既定では無効です。
    • LZ4_NBWORKERS_DEFAULT: マルチスレッドモードで使うワーカースレッド数の既定値（-T#コマンドで上書きできます）。既定値は0で、ローカルCPUに基づく「自動決定」を意味します。
    • LZ4_NBWORKERS_MAX: 実行時に要求できるワーカー数の絶対的な最大値。現在、既定値は200です。主に、百万スレッドなど、不合理で、おそらく誤った要求からシステムを保護するためです。
    • LZ4_BLOCKSIZEID_DEFAULT: lz4のブロックサイズコードの既定値。有効な値は[4-7]で、64 KB、256 KB、1 MB、4 MBに対応します。執筆時点の既定値は7で、4 MBのブロックサイズです。

    環境変数

    環境変数を通じて、lz4へ一部のパラメーターを渡せます。例えばスクリプト内から呼ぶなど、lz4の呼び出しは分かっていても、圧縮セッションに影響するパラメーターをlz4へ渡す手段がない場合に役立ちます。 環境変数は、実行ファイルの既定値より優先しますが、対応する実行時コマンドより優先順位は低くなります。グローバルな環境変数として設定すれば、実行ファイルの設定と異なる個人用の既定値を適用できます。

    LZ4_CLEVELは、コマンドラインで他の圧縮レベルを指定していない場合に、lz4が使う既定の圧縮レベルを指定できます。実行ファイルの既定値は、通常1です。

    LZ4_NBWORKERSは、lz4が圧縮で使うスレッド数の既定値を指定できます。実行ファイルの既定値は、通常0で、ローカルCPUに基づく自動決定を意味します。この機能が関係するのは、lz4をマルチスレッド対応でコンパイルした場合だけです。ワーカー数の上限はLZ4_NBWORKERS_MAXです（既定では200）。

    パラメーターの連結

    lz4 CLIは、短いコマンドの連結に対応します。例えば、-d、-q、-fは-dqfへまとめられます。 --long-commandsでは連結できず、必ず別々にしなければなりません。

    コマンドラインインターフェースのベンチマーク

    lz4 CLIは、メモリ内の圧縮ベンチマークモジュールを備え、-b#コマンドで開始します。#は圧縮レベルです。 ベンチマークは、渡したファイル名の一覧を対象に行います。I/Oの負荷をなくすため、ファイル全体をメモリへ読み込みます。 複数のファイルを渡すと、同じベンチマークセッションへまとめます（ただし、各ファイルの圧縮・展開は別々です）。-Sコマンドを使うと、ファイルごとに一セッションへ分けます。 ファイルを渡していない場合は、代わりに内部のLorem Ipsum生成器を使います。

    ベンチマークは、圧縮率、圧縮サイズ、圧縮速度、展開速度を測定します。-bから-eまで、昇順に複数の圧縮レベルを選べます。-iパラメーターは、各セッションに使う秒数を指定します。

    コマンドラインインターフェースの使い方

    コマンドの完全な一覧は、-hまたは-Hパラメーターで取得できます。

    Usage :
      lz4 [arg] [input] [output]

input   : a filename
          with no FILE, or when FILE is - or stdin, read standard input
Arguments :
 -1     : Fast compression (default)
 -9     : High compression
 -d     : decompression (default for .lz4 extension)
 -z     : force compression
 -D FILE: use FILE as dictionary
 -f     : overwrite output without prompting
 -k     : preserve source files(s)  (default)
--rm    : remove source file(s) after successful de/compression
 -h/-H  : display help/long help and exit

Advanced arguments :
 -V     : display Version number and exit
 -v     : verbose mode
 -q     : suppress warnings; specify twice to suppress errors too
 -c     : force write to standard output, even if it is the console
 -t     : test compressed file integrity
 -m     : multiple input files (implies automatic output filenames)
 -r     : operate recursively on directories (sets also -m)
 -l     : compress using Legacy format (Linux kernel compression)
 -B#    : cut file into blocks of size # bytes [32+]
                     or predefined block size [4-7] (default: 7)
 -BD    : Block dependency (improve compression ratio)
 -BX    : enable block checksum (default:disabled)
--no-frame-crc : disable stream checksum (default:enabled)
--content-size : compressed frame includes original size (default:not present)
--[no-]sparse  : sparse mode (default:enabled on file, disabled on stdout)
--favor-decSpeed: compressed files decompress faster, but are less compressed
--fast[=#]: switch to ultra fast compression level (default: 1)

Benchmark arguments :
 -b#    : benchmark file(s), using # compression level (default : 1)
 -e#    : test all compression levels from -bX to # (default : 1)
 -i#    : minimum evaluation time in seconds (default : 3s)```

    ライセンス

    このディレクトリの全ファイルは、GPL-v2の条件でライセンスされています。 詳細はCOPYINGを参照してください。 ライセンス本文は、各ソースファイルの先頭にも含まれています。