.\" Copyright (c) 1985, 1990, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd December 20, 2006
.Dt TCOPY 1
.Os
.Sh NAME
.Nm tcopy
.Nd read, write, copy and verify tapes
.Sh SYNOPSIS
.Nm
.Op Fl crvx
.Op Fl l Ar logfile
.Op Fl s Ar maxblk
.Oo Ar src Op Ar dest
.Oc
.Sh DESCRIPTION
The
.Nm
utility is designed to read, write and copy tapes.
.Pp
The only assumption made
about the tape layout is that there are two sequential EOF marks
at the end.
.Pp
The
.Ar src
argument can be a tape device and defaults to
.Pa /dev/sa0
or it can be data in SIMH-TAP format.
If
.Ar src
is
.Dq Cm -
the standard input is read.
.Pp
If the
.Ar dest
argument is also specified, a copy of the
.Ar src
will be made onto the
.Ar dest .
If
.Ar dest
is
.Dq Cm -
standard output will be written to.
.Pp
If
.Ar dest
is a tape device, the file and record structure will be the same.
.Pp
If
.Ar dest
is a filename ending in
.Dq Cm .000
the contents each file on
.Ar src
will be written to sequentially numbered files
.Dq Cm .000 ,
.Dq Cm .001 ,
.Dq Cm .002
etc.
Information about record sizes will be lost.
.Pp
If the
.Fl r
flag is specified, only the data will be written, information about
file and record layout is lost.
.Pp
Otherwise the data, file and record structure of
.Ar src
will be written in SIMH-TAP format.
.Pp
The
.Nm
utility will report information about the layout of
.Ar src
like this on standard output:
.Bd -literal -offset indent
file 0: block size 80: 6 records
file 0: eof after 6 records: 480 bytes
file 1: block size 3072: records 0 to 262
file 1: block size 612: record 262
file 1: eof after 263 records: 805476 bytes
[…]
eot
total length: 972851280 bytes time: 41 s rate: 22934.8 kB/s
.Ed
.Pp
If
.Ar dest
is
.Dq Cm -
or if
.Fl x
is specified this goes to standard error instead,
and can also be redirected with
.Fl l Ar logfile ,
in which case the final total line will also be reported on standard error.
.Pp
If
.Nm
receives a
.Dv SIGINFO
signal, current counts are reported on standard error.
.Pp
The following options are available:
.Bl -tag -width ".Fl s Ar maxblk"
.It Fl c
Rewind both tapes, copy
.Ar src
to
.Ar dest ,
rewind again and verify that the two tapes are now identical.
.It Fl l Ar logfile
Output all informational messages to
.Ar logfile .
.It Fl r
Write only the contents of all data blocks to the output.
The file and record structure of the input will be lost.
.It Fl s Ar maxblk
Specify a maximum block size,
.Ar maxblk .
The default is
.Va kern.maxphys .
.It Fl v
Verify that
.Ar src
and
.Ar dest
are identical.
Note that the tapes are not rewound prior to the comparison.
.It Fl x
Output all informational messages to the standard error
instead of the standard output.
This option is automatic if
.Ar dest
is given as
.Dq Cm - .
.El
.Sh EXIT STATUS
Unfortunately all over the place, but zero always means succeess.
.Sh EXAMPLES
Verify that the tape in /dev/sa0 can be read and see the layout
of its content:
.Bd -literal -offset indent
tcopy
.Ed
.Pp
Copy a tape using two tape drives:
.Bd -literal -offset indent
tcopy  /dev/sa0 /dev/sa1
.Ed
.Pp
Copy a tape using only a single tape drive, and verify the result:
.Bd -literal -offset indent
tcopy /dev/sa0 /tmp/temp.tapfile
# change tape
tcopy -c /tmp/temp.tapfile /dev/sa0
.Ed
.Pp
Make a cryptographic hash of both the contents and the layout of the tape in
/dev/sa1:
.Pp
.Bd -literal -offset indent
tcopy /dev/sa1 - | sha256
.Ed
.Pp
Copy a tape to a tape drive on another machine:
.Bd -literal -offset indent
tcopy /dev/sa0 - | ssh otherhost tcopy - /dev/sa0
.Ed
.Pp
Extract the tape files into individual files:
.Bd -literal -offset indent
tcopy /dev/sa0 /tmp/_.tape.000
.Ed
.Pp
Ignore all structure on the tape and feed all data to
.Xr tar 1 :
.Bd -literal -offset indent
tcopy -l /dev/null -r /dev/sa0 - | tar tvf -
.Ed
.Sh SEE ALSO
.Xr mt 1 ,
.Xr sa 4 ,
.Xr mtio 4
.Sh STANDARDS
The SIMH-TAP format is documented in the open-simh github repos:
.Pa https://github.com/open-simh/simh/blob/master/doc/simh_magtape.doc
.Sh HISTORY
The
.Nm
command appeared in
.Bx 4.3 .
.Sh BUGS
.Bl -item
.It
Modern tape drives may return a SCSI "Incorrect Length Indicator (ILI)"
for each read with a different block size that what is on the
tape, and that slows
.Nm
down a lot.
This can be disabled with the
.Xr mt 1
command:
.Bd -literal -offset indent
mt param sili -s 1
.Ed
.It
End of data (EOD) is determined by two sequential EOF marks
with no data between them.
There used to be old systems which typically wrote three EOF's between tape
files.
The
.Nm
utility will erroneously stop copying early in this case.
.It
With
.Fl c
the tape drives are not rewound at the same time, but one after the other.
.El