From 22de81e87e7281bb62c9225000b82616dc2686d6 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Fri, 28 Oct 2016 13:58:31 -0700 Subject: [PATCH] updated man page --- NEWS | 1 + examples/simple_decompression.c | 2 +- examples/streaming_decompression.c | 5 +- programs/zstd.1 | 89 ++++++++++++++++++++++++++---- programs/zstdcli.c | 41 +++++++------- 5 files changed, 107 insertions(+), 31 deletions(-) diff --git a/NEWS b/NEWS index 2c2585f00..1b0c3d6c1 100644 --- a/NEWS +++ b/NEWS @@ -5,6 +5,7 @@ Improved : slightly better compression ratio at --ultra levels (>= 20) Added : ZSTD_initCStream_usingCDict(), ZSTD_initDStream_usingDDict() (experimental section) Added : example/multiple_streaming_compression Changed : zstd_errors.h is now part of include installation +Updated man page Fixed : zstd-small, zstd-compress and zstd-decompress compilation targets v1.1.0 diff --git a/examples/simple_decompression.c b/examples/simple_decompression.c index 907ee3387..62a881fcb 100644 --- a/examples/simple_decompression.c +++ b/examples/simple_decompression.c @@ -65,7 +65,7 @@ static void decompress(const char* fname) void* const cBuff = loadFile_X(fname, &cSize); unsigned long long const rSize = ZSTD_getDecompressedSize(cBuff, cSize); if (rSize==0) { - printf("%s : original size unknown \n", fname); + printf("%s : original size unknown. Use streaming decompression instead. \n", fname); exit(5); } void* const rBuff = malloc_X((size_t)rSize); diff --git a/examples/streaming_decompression.c b/examples/streaming_decompression.c index 1ba1a3d81..400aa673d 100644 --- a/examples/streaming_decompression.c +++ b/examples/streaming_decompression.c @@ -71,9 +71,12 @@ static void decompressFile_orDie(const char* fname) ZSTD_DStream* const dstream = ZSTD_createDStream(); if (dstream==NULL) { fprintf(stderr, "ZSTD_createDStream() error \n"); exit(10); } + + /* In more complex scenarios, a file may consist of multiple appended frames (ex : pzstd). + * The following example decompresses only the first frame. + * It is compatible with other provided streaming examples */ size_t const initResult = ZSTD_initDStream(dstream); if (ZSTD_isError(initResult)) { fprintf(stderr, "ZSTD_initDStream() error : %s \n", ZSTD_getErrorName(initResult)); exit(11); } - size_t read, toRead = initResult; while ( (read = fread_orDie(buffIn, toRead, fin)) ) { ZSTD_inBuffer input = { buffIn, read, 0 }; diff --git a/programs/zstd.1 b/programs/zstd.1 index c262a0c6a..812883717 100644 --- a/programs/zstd.1 +++ b/programs/zstd.1 @@ -35,22 +35,85 @@ It also features a very fast decoder, with speed > 500 MB/s per core. \fBzstd\fR command line is generally similar to gzip, but features the following differences : - Source files are preserved by default It's possible to remove them automatically by using \fB--rm\fR command - - By default, when compressing a single file, \fBzstd\fR displays progress notifications and result summary. + - When compressing a single file, \fBzstd\fR displays progress notifications and result summary by default. Use \fB-q\fR to turn them off .SH OPTIONS + +. +.SS "Integer suffixes and special values" +In most places where an integer argument is expected, +an optional suffix is supported to easily indicate large integers. +There must be no space between the integer and the suffix. +.TP +.B KiB +Multiply the integer by 1,024 (2^10). +.BR Ki , +.BR K , +and +.B KB +are accepted as synonyms for +.BR KiB . +.TP +.B MiB +Multiply the integer by 1,048,576 (2^20). +.BR Mi , +.BR M , +and +.B MB +are accepted as synonyms for +.BR MiB . + +. +.SS "Operation mode" +If multiple operation mode options are given, +the last one takes effect. +.TP +.BR \-z ", " \-\-compress +Compress. +This is the default operation mode when no operation mode option +is specified and no other operation mode is implied from +the command name (for example, +.B unzstd +implies +.BR \-\-decompress ). +.TP +.BR \-d ", " \-\-decompress ", " \-\-uncompress +Decompress. +.TP +.BR \-t ", " \-\-test +Test the integrity of compressed +.IR files . +This option is equivalent to +.B "\-\-decompress \-\-stdout" +except that the decompressed data is discarded instead of being +written to standard output. +No files are created or removed. +.TP +.B \-b# + benchmark file(s) using compression level # +.TP +.B \--train FILEs + use FILEs as training set to create a dictionary. The training set should contain a lot of small files (> 100). + +. +.SS "Operation modifiers" .TP .B \-# - # compression level [1-22] (default:3) + # compression level [1-19] (default:3) .TP -.BR \-d ", " --decompress - decompression +.BR \--ultra + unlocks high compression levels 20+ (maximum 22), using a lot more memory .TP .B \-D file use `file` as Dictionary to compress or decompress FILE(s) .TP +.BR \--no-dictID + do not store dictionary ID within frame header (dictionary compression). + the decoder will have to rely on implicit knowledge about which dictionary to use, it won't be able to check if it's correct. +.TP .B \-o file save result into `file` (only possible with a single INPUT-FILE) .TP @@ -60,6 +123,11 @@ It also features a very fast decoder, with speed > 500 MB/s per core. .BR \-c ", " --stdout force write to standard output, even if it is the console .TP +.BR \--[no-]sparse + enable / disable sparse FS support, to make files with many zeroes smaller on disk. + default : enabled when output is into a file, and disabled when output is stdout. + This setting overrides default and can force sparse mode over stdout. +.TP .BR \--rm remove source file(s) after successful compression or decompression .TP @@ -83,8 +151,8 @@ It also features a very fast decoder, with speed > 500 MB/s per core. suppress warnings, interactivity and notifications. specify twice to suppress errors too. .TP -.BR \-C ", " --check - add integrity check computed from uncompressed data +.BR \-C ", " --[no-]check + add integrity check computed from uncompressed data (default : enabled) .TP .BR \-t ", " --test Test the integrity of compressed files. This option is equivalent to \fB--decompress --stdout > /dev/null\fR. @@ -103,10 +171,8 @@ It will improve compression ratio of small files. Typical gains range from ~10% (at 64KB) to x5 better (at <1KB). .TP .B \--train FILEs - use FILEs as training set to create a dictionary. - The training set should contain a lot of small files (> 100). - and weight typically 100x the target dictionary size - (for example, 10 MB for a 100 KB dictionary) + use FILEs as training set to create a dictionary. The training set should contain a lot of small files (> 100), +and weight typically 100x the target dictionary size (for example, 10 MB for a 100 KB dictionary) .TP .B \-o file dictionary saved into `file` (default: dictionary) @@ -131,6 +197,9 @@ Typical gains range from ~10% (at 64KB) to x5 better (at <1KB). .B \-b# benchmark file(s) using compression level # .TP +.B \-e# + benchmark file(s) using multiple compression levels, from -b# to -e# (included). +.TP .B \-i# minimum evaluation time, in seconds (default : 3s), benchmark mode only .TP diff --git a/programs/zstdcli.c b/programs/zstdcli.c index 9aa97cdd2..c9d2cf5db 100644 --- a/programs/zstdcli.c +++ b/programs/zstdcli.c @@ -199,26 +199,24 @@ static unsigned longCommandWArg(const char** stringPtr, const char* longCommand) return result; } +typedef enum { zom_compress, zom_decompress, zom_test, zom_bench, zom_train } zstd_operation_mode; #define CLEAN_RETURN(i) { operationResult = (i); goto _end; } int main(int argCount, const char* argv[]) { int argNb, - bench=0, - decode=0, - testmode=0, forceStdout=0, main_pause=0, nextEntryIsDictionary=0, operationResult=0, - dictBuild=0, nextArgumentIsOutFileName=0, nextArgumentIsMaxDict=0, nextArgumentIsDictID=0, nextArgumentIsFile=0, ultra=0, lastCommand = 0; + zstd_operation_mode operation = zom_compress; int cLevel = ZSTDCLI_CLEVEL_DEFAULT; int cLevelLast = 1; unsigned recursive = 0; @@ -241,7 +239,7 @@ int main(int argCount, const char* argv[]) /* init */ (void)recursive; (void)cLevelLast; /* not used when ZSTD_NOBENCH set */ (void)dictCLevel; (void)dictSelect; (void)dictID; /* not used when ZSTD_NODICT set */ - (void)decode; (void)cLevel; (void)testmode; /* not used when ZSTD_NOCOMPRESS set */ + (void)cLevel; /* not used when ZSTD_NOCOMPRESS set */ (void)ultra; (void)memLimit; /* not used when ZSTD_NODECOMPRESS set */ if (filenameTable==NULL) { DISPLAY("zstd: %s \n", strerror(errno)); exit(1); } filenameTable[0] = stdinmark; @@ -253,8 +251,8 @@ int main(int argCount, const char* argv[]) } /* preset behaviors */ - if (!strcmp(programName, ZSTD_UNZSTD)) decode=1; - if (!strcmp(programName, ZSTD_CAT)) { decode=1; forceStdout=1; displayLevel=1; outFileName=stdoutmark; } + if (!strcmp(programName, ZSTD_UNZSTD)) operation=zom_decompress; + if (!strcmp(programName, ZSTD_CAT)) { operation=zom_decompress; forceStdout=1; displayLevel=1; outFileName=stdoutmark; } /* command switches */ for (argNb=1; argNb