.TH RESTORSF 1csound CARL 
.SH NAME
restorsf 
- restore sound files from magtape
.SH SYNOPSIS
.B restorsf 
[flags] [-sSource -dDestination] files ...
.br
or
.br
.B restorsf 
[flags] < 
.I file
.br
where
.I file
contains 1 or 2 sound file names per line.
If one name per line, the named file is restored; if two,
the first name is restored as the second name.
.RS 1i
Flags:
.nf
-D  print the complete tape directory
-L  just list the file names in tape directory
-s  Source file
-d  Destination file
-V  Verify that the tape can be read by restorsf
N.B., you must supply a list of files to be verified.
-v  Verbose
-y  Answer yes in advance to request to overwrite file.
-n  Change mode of "contiguous" files on tape to be 
non-contiguous when restored.
.RE
.nf
.SH DESCRIPTION
.B restorsf 
reads a magtape written by dumpsf(1csound) and copies the named
files from the tape back to a sound file system.
.SH Nameing Names
There are three ways to name sound files to be restored.
.TP
.B File input:
Saying
.RS .5i
% restorsf < file
.RE
reads the contents of 
.I file
which it expects to be in one of two formats.  If 
.I file 
contains one filename per line, the named files are extracted from the
tape and are restored with that name.  If two names appear on one line,
the first name is used to find the file on the tape, and the second
specifies the name to restore it as.
.TP
.B Command Line
Files can be simply named on the command line.  E.g.,
.RS .5i
% restorsf fileX
.RE
restores
.I fileX
from the tape.
.PP
Alternately, source and destination names for a file can be given as
\-s and \-d pairs.
The file named after -s is the name of a source file on the tape,
and it must be immediately followed by a -d flag and the name that you
want to restore the file into.  Note: there is no space between the
-s and -d flags and the postpended filenames.
Normal 
.I csound
filename expansion is used.
For example, if dgl is running this program and his current sound
file directory is /snd/dgl,
.RS .5i
% restorsf -s/snd/frm/tone -dfoo
.RE
restores /snd/frm/tone to /snd/dgl/foo
.PP
A useful way to generate a list of all files on a tape is with
the command:
.RS .5i
% restorsf -L > file
.RE
which writes a list of all files on the 
.I dumpsf 
series to 
.I file.
An example of restoring all files from a dumpsf series
is:
.RS .5i
% restorsf -L > filename
% restorsf < filename
.RE
.PP
The -D flag prints the dump directory.
.PP
The -V flag causes restorsf to just read the tape down to check it for
readability.  It does not restore any files.  You must either
supply restorsf with all the filenames on the tape, or with the name
of the last file on the tape to get it to read.
.PP
The -n flag causes the mode of all files being restored to be set to
"non-contiguous" mode.  This comes in handy when there is not
enough room in a single block on the disk to bring back a file
from tape that was originally a contiguous file.
.SH AUTHOR
Gareth Loy
.SH SEE ALSO
dumpsf(1csound).
.SH DIAGNOSTICS
If a file already exists on the sound file system
and you own the file, you are asked if you want to overwrite it.
If you do not own the path for where you want to restore the file, it
will not be restored.  A message indicating all requested
files not restored for any reason is printed before 
.B restorsf 
exits.
Note that a single run of 
.I dumpsf
can generate multiple tapes.  
.B restorsf 
manages multi-file requests on multi-tape dumps, rewinding tapes and
telling you what tapes to mount.
If there is no room on the disk, you will get an error message
and 
.B restorsf 
will continue with the next file (which might be to a different disk).
.PP
The -L flag lists all files on the series.
When actually restoring them, 
.B restorsf
will prompt you to mount the proper tape.
Note, 
.B restorsf
does not have to begin on the first tape of a multi-tape sequence,
but can pick up with any tape.
.PP
A comment is included in the restored sound file indicating the source
from which it was restored.
.PP
If
.B restorsf
is requested to restore a file that already exists on the disk, it will
ask you if you really want to overwrite the file.
The -y flag will automatically answer yes to this question.
