.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.