Merge pull request #58 from Cyan4973/dev

Dev

Makefile

@@ -24,10 +24,18 @@
 # xxhsum : provides 32/64 bits hash of one or multiple files, or stdin
 # ################################################################
 
+# Version numbers
+LIBVER_MAJOR:=`sed -n '/define XXH_VERSION_MAJOR/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p' < xxhash.h`
+LIBVER_MINOR:=`sed -n '/define XXH_VERSION_MINOR/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p' < xxhash.h`
+LIBVER_PATCH:=`sed -n '/define XXH_VERSION_RELEASE/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p' < xxhash.h`
+LIBVER := $(LIBVER_MAJOR).$(LIBVER_MINOR).$(LIBVER_PATCH)
+
 CFLAGS ?= -O3
 CFLAGS += -std=c99 -Wall -Wextra -Wshadow -Wcast-qual -Wcast-align -Wstrict-prototypes -Wstrict-aliasing=1 -Wswitch-enum -Wundef -pedantic 
 FLAGS  := $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) $(MOREFLAGS)
-
+XXHSUM_VERSION=$(LIBVER)
+MD2ROFF  =ronn
+MD2ROFF_FLAGS  = --roff --warnings --manual="User Commands" --organization="xxhsum $(XXHSUM_VERSION)"
 
 # Define *.exe as extension for Windows systems
 ifneq (,$(filter Windows%,$(OS)))
@@ -71,6 +79,30 @@ test32: clean xxhsum32
 	@echo ---- test 32-bits ----
 	./xxhsum32 -bi1 xxhash.c
 
+test-xxhsum-c: xxhsum
+	# xxhsum to/from pipe
+	./xxhsum * | ./xxhsum -c -
+	./xxhsum -H0 * | ./xxhsum -c -
+	# xxhsum to/from file, shell redirection
+	./xxhsum * > .test.xxh64
+	./xxhsum -H0 * > .test.xxh32
+	./xxhsum -c .test.xxh64
+	./xxhsum -c .test.xxh32
+	./xxhsum -c < .test.xxh64
+	./xxhsum -c < .test.xxh32
+	# xxhsum -c warns improperly format lines.
+	cat .test.xxh64 .test.xxh32 | ./xxhsum -c -
+	cat .test.xxh32 .test.xxh64 | ./xxhsum -c -
+	# Expects "FAILED"
+	echo "0000000000000000  LICENSE" | ./xxhsum -c -; test $$? -eq 1
+	echo "00000000  LICENSE" | ./xxhsum -c -; test $$? -eq 1
+	# Expects "FAILED open or read"
+	echo "0000000000000000  test-expects-file-not-found" | ./xxhsum -c -; test $$? -eq 1
+	echo "00000000  test-expects-file-not-found" | ./xxhsum -c -; test $$? -eq 1
+
+clean-xxhsum-c:
+	@rm -f .test.xxh32 .test.xxh64
+
 armtest: clean
 	@echo ---- test ARM compilation ----
 	$(MAKE) xxhsum CC=arm-linux-gnueabi-gcc MOREFLAGS="-Werror"
@@ -91,9 +123,20 @@ staticAnalyze: clean
 	@echo ---- static analyzer - scan-build ----
 	CFLAGS="-g -Werror" scan-build --status-bugs -v $(MAKE) all
 
-test-all: clean all test test32 armtest clangtest gpptest sanitize staticAnalyze
+xxhsum.1: xxhsum.1.md
+	cat $^ | $(MD2ROFF) $(MD2ROFF_FLAGS) | sed -n '/^\.\\\".*/!p' > $@
+
+man: xxhsum.1
+
+clean-man:
+	rm xxhsum.1
+
+preview-man: clean-man man
+	man ./xxhsum.1
+
+test-all: clean all test test32 test-xxhsum-c clean-xxhsum-c armtest clangtest gpptest sanitize staticAnalyze
 
-clean:
+clean: clean-xxhsum-c
 	@rm -f core *.o xxhsum$(EXT) xxhsum32$(EXT) xxhsum_privateXXH$(EXT) xxh32sum xxh64sum
 	@echo cleaning completed
 

xxhash.h

@@ -140,7 +140,7 @@ regular symbol name will be automatically translated by this header.
 ***************************************/
 #define XXH_VERSION_MAJOR    0
 #define XXH_VERSION_MINOR    5
-#define XXH_VERSION_RELEASE  0
+#define XXH_VERSION_RELEASE  1
 #define XXH_VERSION_NUMBER  (XXH_VERSION_MAJOR *100*100 + XXH_VERSION_MINOR *100 + XXH_VERSION_RELEASE)
 XXH_PUBLIC_API unsigned XXH_versionNumber (void);
 

xxhsum.1

@@ -0,0 +1,115 @@
+.
+.TH "XXHSUM" "1" "February 2016" "xxhsum 0.5.0" "User Commands"
+.
+.SH "NAME"
+\fBxxhsum\fR \- print or check xxHash non\-cryptographic checksums
+.
+.SH "SYNOPSIS"
+\fBxxhsum\fR [\fIOPTION\fR] \.\.\. [\fIFILE\fR] \.\.\.
+.
+.SH "DESCRIPTION"
+Print or check xxHash (32 or 64bit) checksums\. When \fIFILE\fR is \fB\-\fR, read standard input\.
+.
+.P
+\fBxxhsum\fR supports a command line syntax similar but not indentical to md5sum(1)\. Differences are: \fBxxhsum\fR doesn\'t have text/binary mode switch (\fB\-b\fR, \fB\-t\fR); \fBxxhsum\fR always treats file as binary file; \fBxxhsum\fR has hash bit width switch (\fB\-H\fR);
+.
+.P
+Since xxHash is non\-cryptographic checksum algorithm, \fBxxhsum\fR should not be used any more for security related purposes\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-b\fR
+Benchmark mode
+.
+.TP
+\fB\-B\fR\fIBLOCKSIZE\fR
+\fIBLOCKSIZE\fR specifies benchmark mode\'s test data block size in bytes\. Default value is 102400
+.
+.TP
+\fB\-c\fR, \fB\-\-check\fR
+Read xxHash sums from the \fIFILE\fRs and check them
+.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display help and exit
+.
+.TP
+\fB\-H\fR\fIHASHTYPE\fR
+Hash selection\. \fIHASHTYPE\fR means \fB0\fR=32bits, \fB1\fR=64bits\. Default value is \fB1\fR (64bits)
+.
+.TP
+\fB\-\-little\-endian\fR
+Set output hexadecimal checksum value as little endian convention\. By default, value is displayed as big endian
+.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Display xxhsum version
+.
+.P
+\fBThe following four options are useful only when verifying checksums (\fB\-c\fR)\fR
+.
+.TP
+\fB\-\-quiet\fR
+Exit non\-zero for improperly formatted checksum lines
+.
+.TP
+\fB\-\-strict\fR
+Don\'t print OK for each successfully verified file
+.
+.TP
+\fB\-\-status\fR
+Don\'t output anything, status code shows success
+.
+.TP
+\fB\-w\fR, \fB\-\-warn\fR
+Warn about improperly formatted checksum lines
+.
+.SH "EXIT STATUS"
+\fBxxhsum\fR exit \fB0\fR on success, \fB1\fR if at least one file couldn\'t be read or doesn\'t have the same checksum as the \fB\-c\fR option\.
+.
+.SH "EXAMPLES"
+Output xxHash (64bit) checksum values of specific files to standard output
+.
+.IP "" 4
+.
+.nf
+
+$ xxhsum \-H1 foo bar baz
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Output xxHash (32bit and 64bit) checksum values of specific files to standard output, and redirect it to \fBxyz\.xxh32\fR and \fBqux\.xxh64\fR
+.
+.IP "" 4
+.
+.nf
+
+$ xxhsum \-H0 foo bar baz > xyz\.xxh32
+$ xxhsum \-H1 foo bar baz > qux\.xxh64
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Read xxHash sums from specific files and check them
+.
+.IP "" 4
+.
+.nf
+
+$ xxhsum \-c xyz\.xxh32 qux\.xxh64
+.
+.fi
+.
+.IP "" 0
+.
+.SH "BUGS"
+Report bugs at: https://github\.com/Cyan4973/xxHash/issues/
+.
+.SH "AUTHOR"
+Yann Collet

xxhsum.1.md

@@ -0,0 +1,119 @@
+xxhsum(1) -- print or check xxHash non-cryptographic checksums
+==============================================================
+
+SYNOPSIS
+--------
+
+`xxhsum` [<OPTION>] ... [<FILE>] ...<br/>
+`xxhsum -b` [<OPTION>] ...
+
+DESCRIPTION
+-----------
+
+Print or check xxHash (32 or 64bit) checksums.  When <FILE> is `-`, read
+standard input.
+
+`xxhsum` supports a command line syntax similar but not indentical to
+md5sum(1).  Differences are: `xxhsum` doesn't have text/binary mode switch
+(`-b`, `-t`);  `xxhsum` always treats file as binary file;  `xxhsum` has hash
+bit width switch (`-H`);
+
+Since xxHash is non-cryptographic checksum algorithm, `xxhsum` should not be
+used any more for security related purposes.
+
+`xxhsum -b` invokes benchmark mode. See [OPTIONS](#OPTIONS) and [EXAMPLES](#EXAMPLES) for details.
+
+OPTIONS
+-------
+
+* `-c`, `--check`:
+  Read xxHash sums from the <FILE>s and check them
+
+* `-h`, `--help`:
+  Display help and exit
+
+* `-H`<HASHTYPE>:
+  Hash selection.  <HASHTYPE> means `0`=32bits, `1`=64bits.
+  Default value is `1` (64bits)
+
+* `--little-endian`:
+  Set output hexadecimal checksum value as little endian convention.
+  By default, value is displayed as big endian
+
+* `-V`, `--version`:
+  Display xxhsum version
+
+**The following four options are useful only when verifying checksums (`-c`)**
+
+* `--quiet`:
+  Exit non-zero for improperly formatted checksum lines
+
+* `--strict`:
+  Don't print OK for each successfully verified file
+
+* `--status`:
+  Don't output anything, status code shows success
+
+* `-w`, `--warn`:
+  Warn about improperly formatted checksum lines
+
+**The following options are useful only benchmark purpose**
+
+* `-b`:
+  Benchmark mode.  See [EXAMPLES](#EXAMPLES) for details.
+
+* `-B`<BLOCKSIZE>:
+  Only useful for benchmark mode (`-b`). See [EXAMPLES](#EXAMPLES) for details.
+  <BLOCKSIZE> specifies benchmark mode's test data block size in bytes.
+  Default value is 102400
+
+* `-i`<ITERATIONS>:
+  Only useful for benchmark mode (`-b`). See [EXAMPLES](#EXAMPLES) for details.
+  <ITERATIONS> specifies number of iterations in benchmark. Single iteration
+  takes at least 2500 milliseconds. Default value is 3
+
+EXIT STATUS
+-----------
+
+`xxhsum` exit `0` on success, `1` if at least one file couldn't be read or
+doesn't have the same checksum as the `-c` option.
+
+EXAMPLES
+--------
+
+Output xxHash (64bit) checksum values of specific files to standard output
+
+    $ xxhsum -H1 foo bar baz
+
+Output xxHash (32bit and 64bit) checksum values of specific files to standard
+output, and redirect it to `xyz.xxh32` and `qux.xxh64`
+
+    $ xxhsum -H0 foo bar baz > xyz.xxh32
+    $ xxhsum -H1 foo bar baz > qux.xxh64
+
+Read xxHash sums from specific files and check them
+
+    $ xxhsum -c xyz.xxh32 qux.xxh64
+
+Benchmark xxHash algorithm for 16384 bytes data in 10 times. `xxhsum`
+benchmarks xxHash algorithm for 32-bit and 64-bit and output results to
+standard output.  First column means algorithm, second column is source data
+size in bytes, last column means hash generation speed in mega-bytes per
+seconds.
+
+    $ xxhsum -b -i10 -B16384
+
+BUGS
+----
+
+Report bugs at: https://github.com/Cyan4973/xxHash/issues/
+
+AUTHOR
+------
+
+Yann Collet
+
+SEE ALSO
+--------
+
+md5sum(1)