vbig.1

   1 \"
   2 \" This file is part of vbig.
   3 \" Copyright (C) 2011, 2013, 2014 Richard Kettlewell
   4 \" Copyright (C) 2013 Ian Jackson
   5 \"
   6 \" This program is free software: you can redistribute it and/or modify
   7 \" it under the terms of the GNU General Public License as published by
   8 \" the Free Software Foundation, either version 3 of the License, or
   9 \" (at your option) any later version.
  10 \"
  11 \" This program is distributed in the hope that it will be useful,
  12 \" but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 \" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 \" GNU General Public License for more details.
  15 \"
  16 \" You should have received a copy of the GNU General Public License
  17 \" along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18 \"
  19 .TH vbig 1
  20 .SH NAME
  21 vbig \- create or verify a large but pseudo-random file
  22 .SH SYNOPSIS
  23 \fBvbig \fR[\fB--seed \fRSEED\fR] [\fB--both\fR|\fB--create\fR|\fB--verify\fR] \fIPATH \fR[\fISIZE\fR]
  24 .br
  25 \fBvbig \-\-help
  26 .br
  27 \fBvbig \-\-version
  28 .SH DESCRIPTION
  29 \fBvbig\fR creates a file of specified size full of predictable
  30 pseudo-random data, and/or verifies that it has the expected contents.
  31 The intended use is to test whether storage media really do what they
  32 say on the tin.
  33 .PP
  34 By default vbig will generate a new random seed, write data to the
  35 specified file or device until the device is full, read the data back
  36 to check that everything written was properly stored, and report
  37 the device's size.  Ideally, if you have privilege to do so, you
  38 would also specify \fB-f\fR (to flush the operating system disk
  39 cache between the write and read).  Also you probably want \fB-p\fR.
  40 .PP
  41 \fIPATH\fR can refer to an ordinary file on a mounted file system,
  42 which vbig will create or truncate as necessary, or a block device.
  43 Note that if it's a file, vbig won't delete it after it's done.  Also,
  44 be careful when specifying a block device - don't accidentally
  45 overwrite a filesystem you care about!  vbig doesn't do sanity checks
  46 and is as dangerous as \fBdd\fR.
  47 .PP
  48 \fISIZE\fR may end with \fBK\fR, \fBM\fR or \fBG\fR to select (binary)
  49 kilobytes, megabytes or gigabytes.
  50 The size is mandatory when creating a file but optional when verifying
  51 it, unless \fB\-\-entire\fR is specified.  If \fISIZE\fR not specified when
  52 writing-then-verifying, it is as if \fB\-\-entire\fR was specified.
  53 .PP
  54 If no seed or seed file is specified:
  55 in \fB--both\fR mode a fresh random seed is read from the system's
  56 random number generator; in other modes a fixed default seed is used.
  57 .SH OPTIONS
  58 .TP
  59 .B --seed\fR, \fB-s \fISEED
  60 Specifies the random seed to use.
  61 Optional.
  62 .TP
  63 .B --seed-file\fR, \fB-S \fISEED-FILE
  64 Specifies where the random seed should be read from.  The
  65 first \fISEED-LENGTH\fR bytes will be used, or the whole file
  66 if it is shorter.
  67 .TP
  68 .B --seed-length\fR, \fB-L \fISEED-LENGTH
  69 Specifies the (maximum) seed length in bytes.
  70 Optional; default is 2048.
  71 .TP
  72 .B --both\fR, \fB-b
  73 Selects both mode.
  74 \fIPATH\fR will be filled with \fISIZE\fR pseudo-random bytes and
  75 then read to check that it contains the data just written.
  76 This is the default.
  77 .TP
  78 .B --create\fR, \fB-c
  79 Selects create mode.
  80 \fIPATH\fR will be filled with \fISIZE\fR pseudo-random bytes.
  81 .TP
  82 .B --verify\fR, \fB-v
  83 Selects verify mode.
  84 Checks that \fIPATH\fR has exactly the contents that would be produced
  85 by the equivalent \fB--create\fR call.
  86 .TP
  87 .B --flush\fR, \fB-f
  88 Flush cached data after creating the file or before verifying it.
  89 On some platforms, only root can use this option.
  90 .TP
  91 .B --progress\fR, \fB-p
  92 Show the progress (in bytes) on stdout.
  93 .TP
  94 .B --entire\fR, \fB-e
  95 When writing, keep going until the device is full (No space left
  96 on device).  When reading, keep going until the end of the file
  97 or device.  \fISIZE\fR should not be specified.  The actual size
  98 written or verified will be printed to stdout.
  99 .TP
 100 .B --help\fR, \fB-h
 101 Displays a usage message.
 102 .TP
 103 .B --version\fR, \fB-V
 104 Displays the version strings.
 105 .SH AUTHOR
 106 Richard Kettlewell <rjk@greenend.org.uk>