diff options
Diffstat (limited to 'static/v10/man8/worm.8')
| -rw-r--r-- | static/v10/man8/worm.8 | 436 |
1 files changed, 436 insertions, 0 deletions
diff --git a/static/v10/man8/worm.8 b/static/v10/man8/worm.8 new file mode 100644 index 00000000..004f4a05 --- /dev/null +++ b/static/v10/man8/worm.8 @@ -0,0 +1,436 @@ +.TH WORM 8 "wild" +.CT 1 sa_nonmortals +.SH NAME +worm, jukebox \- optical disk utilities +.SH SYNOPSIS +.B "worm mkfs" +[ +.BI -f device +] [ +.BI -c comments +] [ +.BI -b blksz +] [ +.BI -n nblks +] [ +.BI -v newvol_id +] +.I vol_id +.PP +.B "worm stat" +[ +.BI -f device +] [ +.BI -F n +] [ +.B -v +] [ +.I vol_id +] +.PP +.B "worm ls" +[ +.BI -f device +] [ +.B -l +] [ +.I file ... +] +.PP +.B "worm rm" +[ +.BI -f device +] +.I vol_id +[ +.I file ... +] +.PP +.B "worm mv" +[ +.BI -f device +] +.I vol_id +.I "src dest" +.PP +.B "worm write" +[ +.BI -f device +] +.I vol_id +[ +.I file ... +] +.PP +.B "worm read" +[ +.BI -f device +] [ +.B -dm +] +.I vol_id +[ +.I file ... +] +.PP +.B "worm cat" +[ +.BI -f device +] +.I vol_id +.I file +.PP +.B "worm copy" +[ +.B -v +] [ +.BI -m min_free +] [ +.BI -f src_dev +] +.I src_vol_id +.I dest_dev +.I dest_vol_id +.PP +.B "worm offline" +[ +.BI -f device +] +.PP +.B "worm btree" +[ +.BI -f device +] +.I vol_id +.PP +.B "worm dir" +[ +.BI -f device +] +.I vol_id +.PP +.B "worm tmpdir" +[ +.BI -f device +] +.I vol_id +.PP +.B "worm mount" +[ +.BI -w secs +] [ +.I vol_id +] +.PP +.B "jukebox" +[ +.B -aemprsuU +] [ +.BI -w secs +] [ +.I vol_id +] +.SH DESCRIPTION +The +.I worm +programs manipulate arbitrary files. +They are intended for use with the raw device associated +with a Write-Once Read-Many (WORM) optical disk. +The default device is +.FR /dev/worm0 . +Other devices are specified by +.BI -f device +and a device name of a single digit +.I n +is taken as an abbreviation for +.FR /dev/worm \f2n\fP. +Most of the commands implement a simple file system. +Programs just wanting a raw device should still use +.B "worm mkfs" +so that the disk is properly labeled. +The +.IR vol_id , +or label, +should be unique and by convention, the vol_id's +for the A and B sides of a disk should be the same string suffixed by +a lowercase +.B a +and +.B b +respectively. +.PP +.I "Worm mkfs" +labels an optical disk. +The +.I comments +field is limited to 256 chars. +It is purely descriptive and is printed by +.IR "worm stat \-v" . +The (default) blocksize is 1024 for our SONY disks. +The number of blocks on a disk can be found by +.IR ra (4) +or +.IR scsish (8); +the default size +(1,600,000 for single density, 3,250,000 for double density) +sets aside 30MB or so as a hedge against oversights. +If the disk has already been initialised, its vol_id must match +.IR vol_id . +A new vol_id can be set with +.BR -v . +.PP +.I "Worm stat" +prints out labeling information +including the amount of free space left on the disk. +Option +.I vol_id +turns off all output except exit status: zero if +.I vol_id +matches that of the disk, +one otherwise. +Option +.B -F +similarly exits with status zero if the disk has more than +.I n +free blocks, otherwise three. +Option +.B -v +produces more output. +.PP +.I "Worm ls" +simulates an emasculated +.IR ls (1). +.PP +.I "Worm rm" +makes the specifed files unavailable to the rest of the +.I worm +commands. +.PP +.I "Worm mv" +renames +.I src +to +.IR dest . +.PP +.I "Worm write" +copies files onto the WORM. +If no file arguments are given, +filenames are read one per line from standard input. +The total number of files and bytes is printed on standard output. +.PP +.I "Worm read" +restores files from the WORM. +If no file arguments are given, +filenames are read one per line from standard input. +Option +.B -d +causes directories to be created as needed. +Option +.B -m +restores the original modification times. +.PP +.I "Worm cat" +copies the named file from the WORM to the standard output. +.PP +.I "Worm copy" +copies files directly from one disk to another. +The names of the files to be copied are taken from standard input; +groups (separated by blank lines) will be kept together. +The names are typically generated by +.BR "worm ls" . +The +.B -v +option prints out progress and summary information. +The copy will terminate before copying a group that would leave the destination +volume with less than +.I minfree +(deafult value is 40000) blocks free. +.PP +.I "Worm offline" +makes the WORM go offline, ready for ejecting. +This command is harmless; +accessing an offline drive will cause it to spin up and go online +without operator intervention. +.I "Worm offline" +only takes effect after the last close of the WORM +and as a bonus, applies to any MSCP device such as an RA81. +.PP +.I "Worm tmpdir" +saves a copy of the directory in +.BI /usr/worm/tmp/ vol_id +if the directory +.F /usr/worm/tmp +exists. +This will speed up subsequent access substantially, +although it will still be slower than +.I "worm btree" +below. +On the other hand, +.I worm tmpdir +typically takes 5 minutes to run (on a VAX 11/750) +whereas +.I worm btree +takes about 45 minutes. +.PP +.I "Worm btree" +constructs a new directory for the whole disk (in the form of a +.IR cbt (1) +database). +The new superblock is at zero. +All the worm commands go faster with such an index but it is intended to be done +just once, after the disk is complete. +The directory occupies of the order of 10MB but may be more. +If you really have to add more files to the disk, +you need to write zeros on the first 1K block of the WORM before using +.IR "worm write" . +.PP +.I "Worm dir" +takes the btree directory from the disk and stores in +.FR /usr/worm/dirs . +Future uses of the disk will be much faster. +.PP +.I "Worm mount" +returns the device on which the disk labelled +.I vol_id +is mounted. +If the drive(s) are busy and you have a jukebox, the +.BI -w s +option tells how many seconds to wait before failing. +The default is wait forever. +If no +.I vol_id +is given, print the drive status. +.PP +.I "Jukebox" +manages the disks in the SONY jukebox. +There are several options (default is +.BR -s ): +.TP 10 +.B -a +Allocate a blank disk and label it +.IR vol_id . +Use +.I "worm mkfs" +to change any fields from their default value. +.TP +.B -e +Eject the disk labeled +.I vol_id. +To physically retrieve the disk, +press the +.B OUT +button (the +.B "OUT READY" +light should be on). +Repeat until the +.B "IN READY" +light goes on. +.TP +.B -m +Mount the disk labelled +.I vol_id +in some drive and print the drive number on standard output. +.TP +.B -p +Print the list of disks in the jukebox. +.TP +.B -r +Rebuild the list of disks by examining each disk in the jukebox. +Do not do this unless you are sure you need to. +If +.I vol_id +is given, it should be one of the following letters and governs +how disks are assigned shelf numbers. +The default is to leave the shelf number unchanged. +Other options (mainly useful for demos) are +.B c +(compresses the disks in the jukebox towards the bottom or lower numbered shelves), +.B r +(distributes the disks randomly), and +.B s +(sorts the disks by vol_id). +.TP +.B -s +Print the status of the jukebox. +.TP +.B -u +Unload offline disks back onto their shelves. +.TP +.B -U +Unload all disks (offline or not) back onto their shelves. +.TP +.BI -w secs +This option only affects the behavior of +.BR -m . +If all drives are busy, try again for +.I secs +seconds before failing. +.PP +To load a disk into the jukebox, press the +.B IN +button on the jukebox when the +.B "IN READY" +light is on. +After the shutter opens, push the disk in firmly. +The disk (blank or initialised) is not examined immediately but on demand. +.SS Etiquette +Vol_ids should be unique as discussed above. +The file +.F /n/wild/usr/worm/vol_ids +contains known vol_ids. +The commands for reading and writing require vol_id's +to guard against accessing the wrong disk. +.PP +The recommended protocol for changing disks is +if no one appears to be using the drive +(by using +.IR ps (1)), +execute +.I "worm offline" +and go to the drive. +If, and only if, the drive has the DRIVE OFF (middle) light on, +hit the EJECT button and change disks. +If the light is not on, then +someone is still using the disk and you should wait until they are done +before hitting EJECT. +.SS Programming considerations +Programs should not depend on writing any block more than once; however, +our SONY optical disks implement a small number of multiple writes +via bad block replacement. +A +.IR read (2) +of an unwritten block returns with an errno of +.BR ENXIO . +On Vaxes, the WORM is an MSCP device; +thus geometry information can be fetched as in +.IR ra (4). +.PP +For maximum speed, read and write in large blocks (preferably 63K) +and avoid seeks. +A seek across the whole disk takes about 1 second. +.PP +The device +.F /dev/worm? +is simply an appropriate raw +.IR ra (4) +device, partition 7 (the whole disk). +.SH EXAMPLES +.EX +worm mkfs -c"512x512x24 movies" tdmoviesa +worm write tdmoviesa < filenames +worm read -d tdmoviesa bumblebee/act2/frame1 +.EE +.SH FILES +.F /dev/worm? +.br +.F /n/wild/usr/worm/vol_ids +.br +.F /n/wild/usr/worm/jukedir +.SH SEE ALSO +.IR backup (8), +.IR scsish (8), +.IR backup (1) +.SH BUGS +The output of +.I "worm ls" +is not necessarily sorted. |