.\" As its sole author, I explicitly place this file in the public domain.
.\" It may be used by anyone in any way for any purpose, though I would
.\" appreciate credit where it's due.
.\"		der Mouse, mouse@rodents.montreal.qc.ca, 2000-12-04
.Dd May 22, 2005
.Dt COPYTAPE 1
.Os NetBSD 1.4T
.Sh NAME
.Nm copytape
.Nd tape image-copy utility
.Sh SYNOPSIS
.Nm
.Op Fl f
.Op Fl t
.Op Fl T
.Op Fl s Ns Ar SKIP
.Op Fl l Ns Ar LIMIT
.Op Fl v
.Op Ar from Op Ar to
.Sh DESCRIPTION
.Nm
is a small utility designed for making copies of magnetic tapes,
preserving filemark and record size information.
.Pp
In its simplest form,
.Nm
copies
.Ar from
(default standard input)
to
.Ar to
(default standard output).  It automatically determines whether its
input and output (whether stdin and stdout or from the command line)
are tape drives or not.  When reading or writing tape drives, it
preserves record boundaries and filemarks; when reading or writing
other things (eg, data files or pipes), it uses a simple framing scheme
to represent record size and filemark information in an octet stream.
.Pp
It is possible to force
.Nm
to treat its input or output as real tape
drives even if they're not by using the
.Fl f
and
.Fl t
flags (which specify tape-drive-style access for the
.Cm f Ns No rom
or
.Cm t Ns No o
data streams, respectively).  You can also specify
.Fl T
which is just like
.Fl t
except that it suppresses both the file-format framing data and the
tape-drive attempts to use
.Dv MTWEOF
.Dv MTIOCTOP Ns s .
.Fl f
and
.Fl t
are not very useful;
.Fl T
is very useful in conjunction with
.Fl s
and
.Fl l
to extract a tape file from a
.Nm
data stream when you want just the content and aren't interested in
preserving record boundaries.
.Pp
.Fl s Ns Ar NSKIP
specifies a number of files to
.Cm s Ns No kip
in the input stream before beginning the copy;
.Fl l Ns Ar LIMIT
specifies a
.Cm l Ns No imit
on the number of files copied.  (The
.Fl s
value does not count against the
.Fl l
value.)  In each case, the argument is simply a number, and no space is
allowed between the flag and the argument.
.Pp
Normally,
.Nm
does its work silently (except, of course, for errors);
.Fl v
causes it to be verbose, printing lines at startup identifying the data
source and sink and printing a line for each record or filemark copied.
This output goes to the standard error stream.  (It is occasionally
useful to save -v output, particularly for use with
.Xr uniq 1 Ap s
.Fl c
option.)
.Pp
The exit status is 0 if all went well, or 1 (with a message on the
standard error) if there was a problem, most notably an output write
error.
.Sh BUGS
There is no explicit way to specify the converse of
.Fl f
and
.Fl t ;
fortunately, one rarely wants to save
.Nm
data streams
.Sq raw
to tapes, and if one does, all that's needed is to pipe the input or
output through another program, such as
.Xr cat 1
or
.Xr dd 1 .
.Pp
There is a hard limit on record sizes; at this writing, this limit is
256KB.  Records larger than this will either be truncated or cause
errors, depending on what the underlying tape driver does.
.Pp
There is no way to read past two consecutive filemarks on a real tape.
(Multiple consecutive filemarks in a data stream will not be mistaken
for an end-of-tape, though producing such a data stream usually
requires hand-hackery.)
.Pp
The data stream format is undocumented except for the source code.
.Sh AUTHOR
Originally, David S. Hayes, probably at the US Army AI Center.
Modified by der Mouse,
.Aq mouse@rodents.montreal.qc.ca .