[2/2] add manual for tool 'mksparse'

Message ID 1298860514-615-2-git-send-email-hao.bigrat@gmail.com
State Rejected, archived
Headers show

Commit Message

Robin Dong Feb. 28, 2011, 2:35 a.m.
From: Robin Dong <sanbai@taobao.com>

add manual for tool 'mksparse'.

Reviewed-by: Coly Li <bosong.ly@taobao.com>
Signed-off-by: Robing Dong <sanbai@taobao.com>
 misc/Makefile.in   |    5 +++
 misc/mksparse.8.in |   86 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+), 0 deletions(-)
 create mode 100644 misc/mksparse.8.in


diff --git a/misc/Makefile.in b/misc/Makefile.in
index fcd316e..acea909 100644
--- a/misc/Makefile.in
+++ b/misc/Makefile.in
@@ -18,6 +18,7 @@  INSTALL = @INSTALL@
@@ -365,6 +366,10 @@  e2image.8: $(DEP_SUBSTITUTE) $(srcdir)/e2image.8.in
 	$(E) "	SUBST $@"
 	$(Q) $(SUBSTITUTE_UPTIME) $(srcdir)/e2image.8.in e2image.8
+mksparse.8: $(DEP_SUBSTITUTE) $(srcdir)/mksparse.8.in
+	$(E) "	SUBST $@"
+	$(Q) $(SUBSTITUTE_UPTIME) $(srcdir)/mksparse.8.in mksparse.8
 e4defrag.8: $(DEP_SUBSTITUTE) $(srcdir)/e4defrag.8.in
 	$(E) "	SUBST $@"
 	$(Q) $(SUBSTITUTE_UPTIME) $(srcdir)/e4defrag.8.in e4defrag.8
diff --git a/misc/mksparse.8.in b/misc/mksparse.8.in
new file mode 100644
index 0000000..8bc9955
--- /dev/null
+++ b/misc/mksparse.8.in
@@ -0,0 +1,86 @@ 
+.\" -*- nroff -*-
+.\" Copyright 2011 by Taobao.  All Rights Reserved.
+.\" This file may be copied under the terms of the GNU Public License.
+mksparse \- Make sparse file from an input file or the standard input
+.B mksparse
+.B \-s
+.B \-i
+.I sparse-file
+.B mksparse
+makes sparse file from an input file or the standard input. Currently popular
+compressing tools like bzip2 or gunzip supports compressing a sparse file,
+but in decompressing they fill zero bytes into output other than make a sparse
+hole, which usually results a much larger file. If user downloads a
+compressed raw file system image built by
+.BR e2image (8)
+on a very large file system, it is almost impossible to decompress it on a
+desktop machine.
+.B mksparse
+can read the decompressed stream from standard input and make a sparse file
+which takes less bytes on storage media. Here is the example,
+\      \fBe2image \-r /dev/hda1 \- | bzip2 > hda1.bz2\fR
+\      \fBbunzip2 \-c hda1.bz2 | mksparse hda1_sparse.img\fR
+.I "sparse-file"
+The name specified to output file.
+.BI \-i " input-file"
+Other than from standard input,
+.B mksparse
+is also able to make a sparse file named by 
+.I sparse-file
+from a regular file or device file which is specified by
+.I input-file
+.BI \-s " buffer-size"
+By default
+.B mksparse
+reads 4KB bytes from input into its read buffer. If bytes in the buffer are
+all zero,
+.B mksparse
+makes a sparse hole to
+.I sparse-file
+by seeking
+.I buffer-size
+bytes from current possion of
+.I sparse-file
+, otherwise it writes the buffer to
+.I sparse-file
+. After a hole is made or the buffer is written,
+.B mksparse
+continues to read next
+.I buffer-size
+bytes from input file into its read buffer until the end of input. A larger
+.I buffer-size
+means better I/O performance but less chance to make more sparse space in
+.I sparse-file
+. In most cases, the default 4KB
+.I buffer-size
+works quite well.
+.B mksparse
+is written by Robin Dong <sanbai@taobao.com>.
+.B mksparse
+is part of the e2fsprogs package.
+.BR e2image (8)