X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=vbig.1;h=134caae80b0f4d3831667bb398b56f1f9b715b7d;hb=393a419e4e8e6523166dedf482bc714fe9d8c16b;hp=11cd637d02905f82d0798cbeea2f25ada8796281;hpb=d4fe83d3165d27e101448bfaa8261e0c4bb72385;p=vbig.git

diff --git a/vbig.1 b/vbig.1
index 11cd637..134caae 100644
--- a/vbig.1
+++ b/vbig.1
@@ -1,26 +1,80 @@
+\"
+\" This file is part of vbig.
+\" Copyright (C) 2011 Richard Kettlewell
+\" Copyright (C) 2013 Ian Jackson
+\"
+\" This program is free software: you can redistribute it and/or modify
+\" it under the terms of the GNU General Public License as published by
+\" the Free Software Foundation, either version 3 of the License, or
+\" (at your option) any later version.
+\"
+\" This program is distributed in the hope that it will be useful,
+\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+\" GNU General Public License for more details.
+\"
+\" You should have received a copy of the GNU General Public License
+\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
+\"
 .TH vbig 1
 .SH NAME
 vbig \- create or verify a large but pseudo-random file
 .SH SYNOPSIS
-\fBvbig \fR[\fB--seed \fRSEED\fR] \fB--create\fR|\fB--verify \fIPATH SIZE
+\fBvbig \fR[\fB--seed \fRSEED\fR] [\fB--both\fR|\fB--create\fR|\fB--verify\fR] \fIPATH \fR[\fISIZE\fR]
 .br
-\fBvbig --help
+\fBvbig \-\-help
 .br
-\fBvbig --version
+\fBvbig \-\-version
 .SH DESCRIPTION
-\fBvbig\fR either creates a file of specified size full of predictable
-psuedo-random data, or verifies that it has the expected contents.
+\fBvbig\fR creates a file of specified size full of predictable
+psuedo-random data, and/or verifies that it has the expected contents.
 The intended use is to test whether storage media really do what they
 say on the tin.
 .PP
+By default vbig will generate a new random seed, write data to the
+specified file or device until the device is full, read the data back
+to check that everything written was properly stored, and report
+the device's size.  Ideally, if you have privilege to do so, you
+would also specify \fB-f\fR (to flush the operating system disk
+cache between the write and read).  Also you probably want \fB-p\fR.
+.PP
+\fIPATH\fR can refer to an ordinary file on a mounted file system,
+which vbig will create or truncate as necessary, or a block device.
+Note that if it's a file, vbig won't delete it after it's done.  Also,
+be careful when specifying a block device - don't accidentally
+overwrite a filesystem you care about!  vbig doesn't do sanity checks
+and is as dangerous as \fBdd\fR.
+.PP
 \fISIZE\fR may end with \fBK\fR, \fBM\fR or \fBG\fR to select (binary)
 kilobytes, megabytes or gigabytes.
+The size is mandatory when creating a file but optional when verifying
+it, unless \-\-entire is specified.  If \fISIZE\fR not specified when
+writing-then-verifying, it is as if \fB\-\-entire\fR was specified.
+.PP
+If no seed or seed file is specified:
+in \fB--both\fR mode a fresh random seed is read from the system's
+random number generator; in other modes a fixed default seed is used.
 .SH OPTIONS
 .TP
 .B --seed\fR, \fB-s \fISEED
 Specifies the random seed to use.
 Optional.
 .TP
+.B --seed-file\fR, \fB-S \fISEED-FILE
+Specifies wehre the random seed should be read from.  The
+first \fISEED-LENGTH\fR bytes will be used, or the whole file
+if it is shorter.
+.TP
+.B --seed-length\fR, \fB-L \fISEED-LENGTH
+Specifies the (maximum) seed length in bytes.
+Optional; default is 2048.
+.TP
+.B --both\fR, \fB-b
+Selects both mode.
+\fIPATH\fR will be filled with \fISIZE\fR psuedo-random bytes and
+then read to check that it contains the data just written.
+This is the default.
+.TP
 .B --create\fR, \fB-c
 Selects create mode.
 \fIPATH\fR will be filled with \fISIZE\fR psuedo-random bytes.
@@ -32,12 +86,21 @@ by the equivalent \fB--create\fR call.
 .TP
 .B --flush\fR, \fB-f
 Flush cached data after creating the file or before verifying it.
-Only root can use this option.
+On some platforms, only root can use this option.
+.TP
+.B --progress\fR, \fB-p
+Show the progress (in bytes) on stdout.
+.TP
+.B --entire\fR, \fB-e
+When writing, keep going until the device is full (No space left
+on device).  When reading, keep going until the end of the file
+or device.  \fISIZE\fR should not be specified.  The actual size
+written or verified will be printed to stdout.
 .TP
 .B --help\fR, \fB-h
 Displays a usage message.
 .TP
-.B --version\fR, \fB-h
+.B --version\fR, \fB-V
 Displays the version strings.
 .SH AUTHOR
 Richard Kettlewell <rjk@greenend.org.uk>