[src/trunk]: src/usr.bin/vndcompress Document the new vndcompress -w option a...

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/e0fb0648505b
branches:  trunk
changeset: 326214:e0fb0648505b
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Wed Jan 22 06:17:51 2014 +0000

description:
Document the new vndcompress -w option and nuke BUGS section.

Perhaps vndcompress and vnduncompress ought by default to choose a
limited window size (say, 8192 entries, i.e. 64k bytes, the default
MAXPHYS), and vnduncompress should fall back to an unlimited window
only if the input is nonseekable.

diffstat:

 usr.bin/vndcompress/vndcompress.1 |  49 ++++++++++++++++++++++++++++++--------
 1 files changed, 38 insertions(+), 11 deletions(-)

diffs (80 lines):

diff -r 104cb9496ca6 -r e0fb0648505b usr.bin/vndcompress/vndcompress.1
--- a/usr.bin/vndcompress/vndcompress.1 Wed Jan 22 06:17:42 2014 +0000
+++ b/usr.bin/vndcompress/vndcompress.1 Wed Jan 22 06:17:51 2014 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: vndcompress.1,v 1.11 2014/01/22 06:17:42 riastradh Exp $
+.\"    $NetBSD: vndcompress.1,v 1.12 2014/01/22 06:17:51 riastradh Exp $
 .\"
 .\" Copyright (c) 2013 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -42,11 +42,13 @@
 .Op Fl k Ar checkpoint-blocks
 .Op Fl l Ar length
 .Op Fl p Ar partial-offset
+.Op Fl w Ar winsize
 .Ar image
 .Ar compressed-image
 .Op Ar blocksize
 .Nm vnduncompress
 .Op Fl d
+.Op Fl w Ar winsize
 .Ar compressed-image
 .Ar image
 .Sh DESCRIPTION
@@ -126,6 +128,39 @@
 recognizable ways, or if the input file's size has changed, or if the
 block size does not match, and so on.
 .El
+.Pp
+The following option is available for both compression and
+decompression:
+.Bl -tag -width indent
+.It Fl w Ar winsize
+Use an in-memory window of
+.Ar winsize
+entries into the table of compressed block offsets.
+If
+.Fl w
+is not supplied or
+.Ar winsize
+is zero,
+.Nm
+will use memory proportional to the number of blocks in the
+uncompressed image, namely 64 bits or 8 bytes per block.
+If
+.Ar winsize
+is nonzero,
+.Nm
+will use memory proportional to
+.Ar winsize ,
+and independent of the size of the uncompressed image.
+.Pp
+A nonzero
+.Ar winsize
+requires the compressed image to be a seekable file, which compression
+requires anyway, in order to record the offsets of compressed blocks
+once they are compressed and written, but which is a limitation for
+decompression.
+Thus, decompressing from a pipe is incompatible with a nonzero
+.Ar winsize .
+.El
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
@@ -215,14 +250,6 @@
 .Nm
 command first appeared in
 .Nx 3.0 .
-It was rewritten to be more robust and to support restarting partial
-transfers in
+It was rewritten to be more robust, to support restarting partial
+transfers, and to support bounded memory usage in
 .Nx 7.0 .
-.Sh BUGS
-The amount of memory consumed by
-.Nm
-and
-.Nm vnduncompress
-is proportional to the number of compression blocks they process,
-because they store the whole offset table in memory at once.
-Instead, they should use a limited-size window into the offset table.