[dump.git] / rmt / rmt.8.in

.\" Copyright (c) 1983, 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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. 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.
.\"
.\"     $Id: rmt.8.in,v 1.8 2002/04/15 11:57:29 stelian Exp $
.\"
.Dd __DATE__
.Dt RMT 8
.Os "rmt __VERSION__"
.Sh NAME
.Nm rmt
.Nd remote magtape protocol module
.Sh SYNOPSIS
.Nm rmt
.Sh DESCRIPTION
.Nm rmt
is a program used by the remote 
.Nm dump,
.Nm restore 
or
.Nm tar
programs in manipulating a magnetic tape drive through an interprocess
communication connection.
.Nm rmt
is normally started up with an
.Xr rexec 3
or
.Xr rcmd 3
call.
.Pp
The 
.Nm
program accepts requests specific to the manipulation of magnetic tapes, 
performs the commands, then responds with a status indication.  
All responses are in
.Tn ASCII
and in one of the following two forms.
.Pp
Successful commands have responses of:
.Bd -filled -offset indent
.Sm off
.Sy A Ar number No \en
.Sm on
.Ed
.Pp
where
.Ar number
is an
.Tn ASCII
representation of a decimal number.
.Pp
Unsuccessful commands are responded to with:
.Bd -filled -offset indent
.Sm off
.Xo Sy E Ar error-number
.No \en Ar error-message
.No \en
.Xc
.Sm on
.Ed
.Pp
where
.Ar error-number
is one of the possible error numbers described in
.Xr intro 2
and
.Ar error-message
is the corresponding error string as printed from a call to
.Xr perror 3 .
.Pp
The protocol is comprised of the
following commands, which are sent as indicated - no spaces are supplied
between the command and its arguments, or between its arguments, and
.Ql \en
indicates that a newline should be supplied:
.Bl -tag -width Ds
.Sm off
.It Xo Sy \&O Ar device
.No \en Ar mode No \en
.Xc
.Sm on
Open the specified 
.Ar device
using the indicated
.Ar mode .
.Ar Device
is a full pathname and
.Ar mode
is an
.Tn ASCII
representation of a decimal number suitable for passing to
.Xr open 2 .
If a device had already been opened, it is closed before a 
new open is performed.
.Sm off
.It Xo Sy C Ar device No \en
.Xc
.Sm on
Close the currently open device.  The
.Ar device
specified is ignored.
.Sm off
.It Xo Sy L
.Ar whence No \en
.Ar offset No \en
.Xc
.Sm on
Perform an
.Xr lseek 2
operation using the specified parameters.
The response value is that returned from the
.Xr lseek
call.
.Sm off
.It Sy W Ar count No \en
.Sm on
Write data onto the open device.
.Nm rmt
reads
.Ar count
bytes from the connection, aborting if a premature end-of-file is encountered.
The response value is that returned from the
.Xr write 2
call.
.Sm off
.It Sy R Ar count No \en
.Sm on
Read
.Ar count
bytes of data from the open device.
If
.Ar count
exceeds the size of the data buffer (10 kilobytes), it is
truncated to the data buffer size.
.Nm rmt
then performs the requested 
.Xr read 2
and responds with 
.Sm off
.Sy A Ar count-read No \en
.Sm on
if the read was successful; otherwise an error in the standard format 
is returned.  If the read was successful, the data read is then sent.
.Sm off
.It Xo Sy I Ar operation
.No \en Ar count No \en
.Xc
.Sm on
Perform a
.Dv MTIOCOP
.Xr ioctl 2
command using the specified parameters.  The parameters are interpreted as the
.Tn ASCII
representations of the decimal values to place in the 
.Ar mt_op
and
.Ar mt_count
fields of the structure used in the
.Xr ioctl
call.  The return value is the
.Ar count
parameter when the operation is successful.
.Pp
By issuing the
.Ql I-1\en0\en
command, a client will specify that he is using the VERSION 1 protocol.
.Pp
For a VERSION 0 client, the
.Ar operation
parameter is the platform 
.Ar mt_op
value (could be different if the client and the
.Nm
server are on two different platforms). For a VERSION 1 client,
the 
.Ar operation
parameter is standardized as below:
.Bl -tag -width Fl
.It Ic 0
Issue a MTWEOF command (write
.Ar count
end-of-file records).
.It Ic 1
Issue a MTFSF command (forward space over
.Ar count
file marks).
.It Ic 2
Issue a MTBSF command (backward space over
.Ar count
file marks).
.It Ic 3
Issue a MTFSR command (forward space
.Ar count
inter-record gaps).
.It Ic 4
Issue a MTBSR command (backward space
.Ar count
inter-record gaps).
.It Ic 5
Issue a MTREW command (rewind).
.It Ic 6
Issue a MTOFFL command (rewind and put the drive offline).
.It Ic 7
Issue a MTNOP command (no operation, set status only).
.El
.Sm off
.It Xo Sy i Ar operation
.No \en Ar count No \en
.Xc
.Sm on
Perform an extended
.Dv MTIOCOP
.Xr ioctl 2
command using the specified parameters.
The parameters are interpreted as the
.Tn ASCII
representations of the decimal values to place in the 
.Ar mt_op
and
.Ar mt_count
fields of the structure used in the
.Xr ioctl
call.  The return value is the
.Ar count
parameter when the operation is successful.
The possible operations are:
.Bl -tag -width Fl
.It Ic 0
Issue a MTCACHE command (switch cache on).
.It Ic 1
Issue a MTNOCACHE command (switch cache off).
.It Ic 2
Issue a MTRETEN command (retension the tape).
.It Ic 3
Issue a MTERASE command (erase the entire tape).
.It Ic 4
Issue a MTEOM command (position to end of media).
.It Ic 5
Issue a MTNBSF command (backward space count files to BOF).
.El
.ne 1i
.Sm off
.It Sy S
.Sm on
Return the status of the open device, as
obtained with a
.Dv MTIOCGET
.Xr ioctl
call.  If the operation was successful,
an ``ack'' is sent with the size of the
status buffer, then the status buffer is
sent (in binary, which is non-portable between different platforms).
.Sm off
.It Xo Sy s Ar sub-command
.Xc
.Sm on
This is a replacement for the previous S command, portable across different
platforms. If the open device is a magnetic tape, return members of the 
magnetic tape status structure, as obtained with a
.Dv MTIOCGET 
ioctl call. If the open device is not a magnetic tape, an error is returned.
If the 
.Dv MTIOCGET
operation was successful, the numerical value of the structure member is 
returned in decimal. The following sub commands are supported:
.Bl -tag -width Fl
.It Ic T
return the content of the structure member
.Ar mt_type
which contains the type of the magnetic tape device.
.It Ic D
return the content of the structure member
.Ar mt_dsreg
which contains the "drive status register".
.It Ic E
return the content of the structure member
.Ar mt_erreg
which contains the "error register". This structure member must be retrieved
first because it is cleared after each
.Dv MTIOCGET
ioctl call.
.It Ic R
return the content of the structure member
.Ar mt_resid
which contains the residual count of the last I/O.
.It Ic F
return the content of the structure member
.Ar mt_fileno
which contains the file number of the current tape position.
.It Ic B
return the content of the structure member
.Ar mt_blkno
which contains the block number of the current tape position.
.It Ic f
return the content of the structure member
.Ar mt_flags
which contains MTF_ flags from the driver.
.It Ic b
return the content of the structure member
.Ar mt_bf
which contains the optimum blocking factor.
.El
.El
.Sm on
.Pp
Any other command causes 
.Nm
to exit.
.Sh DIAGNOSTICS
All responses are of the form described above.
.Sh SEE ALSO
.Xr rcmd 3 ,
.Xr rexec 3 ,
.Xr /usr/include/sys/mtio.h ,
.Xr rdump 8 ,
.Xr rrestore 8
.Sh BUGS
People should be discouraged from using this for a remote
file access protocol.
.Sh AUTHOR
The
.Nm dump/restore
backup suit was ported to Linux's Second Extended File System
by Remy Card <card@Linux.EU.Org>. He maintained the initial versions
of dump (up and including 0.4b4, released in january 1997).
.Pp
Starting with 0.4b5, the new maintainer is Stelian Pop
.br
<stelian@popies.net>.
.Sh AVAILABILITY
The
.Nm dump/restore
backup suit is available from 
.br
http://dump.sourceforge.net
.Sh HISTORY
The
.Nm
command appeared in
.Bx 4.2 .
Commit	Line	Data
	1	.\" Copyright (c) 1983, 1991, 1993
	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by the University of
	15	.\" California, Berkeley and its contributors.
	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" $Id: rmt.8.in,v 1.8 2002/04/15 11:57:29 stelian Exp $
	33	.\"
	34	.Dd __DATE__
	35	.Dt RMT 8
	36	.Os "rmt __VERSION__"
	37	.Sh NAME
	38	.Nm rmt
	39	.Nd remote magtape protocol module
	40	.Sh SYNOPSIS
	41	.Nm rmt
	42	.Sh DESCRIPTION
	43	.Nm rmt
	44	is a program used by the remote
	45	.Nm dump,
	46	.Nm restore
	47	or
	48	.Nm tar
	49	programs in manipulating a magnetic tape drive through an interprocess
	50	communication connection.
	51	.Nm rmt
	52	is normally started up with an
	53	.Xr rexec 3
	54	or
	55	.Xr rcmd 3
	56	call.
	57	.Pp
	58	The
	59	.Nm
	60	program accepts requests specific to the manipulation of magnetic tapes,
	61	performs the commands, then responds with a status indication.
	62	All responses are in
	63	.Tn ASCII
	64	and in one of the following two forms.
	65	.Pp
	66	Successful commands have responses of:
	67	.Bd -filled -offset indent
	68	.Sm off
	69	.Sy A Ar number No \en
	70	.Sm on
	71	.Ed
	72	.Pp
	73	where
	74	.Ar number
	75	is an
	76	.Tn ASCII
	77	representation of a decimal number.
	78	.Pp
	79	Unsuccessful commands are responded to with:
	80	.Bd -filled -offset indent
	81	.Sm off
	82	.Xo Sy E Ar error-number
	83	.No \en Ar error-message
	84	.No \en
	85	.Xc
	86	.Sm on
	87	.Ed
	88	.Pp
	89	where
	90	.Ar error-number
	91	is one of the possible error numbers described in
	92	.Xr intro 2
	93	and
	94	.Ar error-message
	95	is the corresponding error string as printed from a call to
	96	.Xr perror 3 .
	97	.Pp
	98	The protocol is comprised of the
	99	following commands, which are sent as indicated - no spaces are supplied
	100	between the command and its arguments, or between its arguments, and
	101	.Ql \en
	102	indicates that a newline should be supplied:
	103	.Bl -tag -width Ds
	104	.Sm off
	105	.It Xo Sy \&O Ar device
	106	.No \en Ar mode No \en
	107	.Xc
	108	.Sm on
	109	Open the specified
	110	.Ar device
	111	using the indicated
	112	.Ar mode .
	113	.Ar Device
	114	is a full pathname and
	115	.Ar mode
	116	is an
	117	.Tn ASCII
	118	representation of a decimal number suitable for passing to
	119	.Xr open 2 .
	120	If a device had already been opened, it is closed before a
	121	new open is performed.
	122	.Sm off
	123	.It Xo Sy C Ar device No \en
	124	.Xc
	125	.Sm on
	126	Close the currently open device. The
	127	.Ar device
	128	specified is ignored.
	129	.Sm off
	130	.It Xo Sy L
	131	.Ar whence No \en
	132	.Ar offset No \en
	133	.Xc
	134	.Sm on
	135	Perform an
	136	.Xr lseek 2
	137	operation using the specified parameters.
	138	The response value is that returned from the
	139	.Xr lseek
	140	call.
	141	.Sm off
	142	.It Sy W Ar count No \en
	143	.Sm on
	144	Write data onto the open device.
	145	.Nm rmt
	146	reads
	147	.Ar count
	148	bytes from the connection, aborting if a premature end-of-file is encountered.
	149	The response value is that returned from the
	150	.Xr write 2
	151	call.
	152	.Sm off
	153	.It Sy R Ar count No \en
	154	.Sm on
	155	Read
	156	.Ar count
	157	bytes of data from the open device.
	158	If
	159	.Ar count
	160	exceeds the size of the data buffer (10 kilobytes), it is
	161	truncated to the data buffer size.
	162	.Nm rmt
	163	then performs the requested
	164	.Xr read 2
	165	and responds with
	166	.Sm off
	167	.Sy A Ar count-read No \en
	168	.Sm on
	169	if the read was successful; otherwise an error in the standard format
	170	is returned. If the read was successful, the data read is then sent.
	171	.Sm off
	172	.It Xo Sy I Ar operation
	173	.No \en Ar count No \en
	174	.Xc
	175	.Sm on
	176	Perform a
	177	.Dv MTIOCOP
	178	.Xr ioctl 2
	179	command using the specified parameters. The parameters are interpreted as the
	180	.Tn ASCII
	181	representations of the decimal values to place in the
	182	.Ar mt_op
	183	and
	184	.Ar mt_count
	185	fields of the structure used in the
	186	.Xr ioctl
	187	call. The return value is the
	188	.Ar count
	189	parameter when the operation is successful.
	190	.Pp
	191	By issuing the
	192	.Ql I-1\en0\en
	193	command, a client will specify that he is using the VERSION 1 protocol.
	194	.Pp
	195	For a VERSION 0 client, the
	196	.Ar operation
	197	parameter is the platform
	198	.Ar mt_op
	199	value (could be different if the client and the
	200	.Nm
	201	server are on two different platforms). For a VERSION 1 client,
	202	the
	203	.Ar operation
	204	parameter is standardized as below:
	205	.Bl -tag -width Fl
	206	.It Ic 0
	207	Issue a MTWEOF command (write
	208	.Ar count
	209	end-of-file records).
	210	.It Ic 1
	211	Issue a MTFSF command (forward space over
	212	.Ar count
	213	file marks).
	214	.It Ic 2
	215	Issue a MTBSF command (backward space over
	216	.Ar count
	217	file marks).
	218	.It Ic 3
	219	Issue a MTFSR command (forward space
	220	.Ar count
	221	inter-record gaps).
	222	.It Ic 4
	223	Issue a MTBSR command (backward space
	224	.Ar count
	225	inter-record gaps).
	226	.It Ic 5
	227	Issue a MTREW command (rewind).
	228	.It Ic 6
	229	Issue a MTOFFL command (rewind and put the drive offline).
	230	.It Ic 7
	231	Issue a MTNOP command (no operation, set status only).
	232	.El
	233	.Sm off
	234	.It Xo Sy i Ar operation
	235	.No \en Ar count No \en
	236	.Xc
	237	.Sm on
	238	Perform an extended
	239	.Dv MTIOCOP
	240	.Xr ioctl 2
	241	command using the specified parameters.
	242	The parameters are interpreted as the
	243	.Tn ASCII
	244	representations of the decimal values to place in the
	245	.Ar mt_op
	246	and
	247	.Ar mt_count
	248	fields of the structure used in the
	249	.Xr ioctl
	250	call. The return value is the
	251	.Ar count
	252	parameter when the operation is successful.
	253	The possible operations are:
	254	.Bl -tag -width Fl
	255	.It Ic 0
	256	Issue a MTCACHE command (switch cache on).
	257	.It Ic 1
	258	Issue a MTNOCACHE command (switch cache off).
	259	.It Ic 2
	260	Issue a MTRETEN command (retension the tape).
	261	.It Ic 3
	262	Issue a MTERASE command (erase the entire tape).
	263	.It Ic 4
	264	Issue a MTEOM command (position to end of media).
	265	.It Ic 5
	266	Issue a MTNBSF command (backward space count files to BOF).
	267	.El
	268	.ne 1i
	269	.Sm off
	270	.It Sy S
	271	.Sm on
	272	Return the status of the open device, as
	273	obtained with a
	274	.Dv MTIOCGET
	275	.Xr ioctl
	276	call. If the operation was successful,
	277	an ``ack'' is sent with the size of the
	278	status buffer, then the status buffer is
	279	sent (in binary, which is non-portable between different platforms).
	280	.Sm off
	281	.It Xo Sy s Ar sub-command
	282	.Xc
	283	.Sm on
	284	This is a replacement for the previous S command, portable across different
	285	platforms. If the open device is a magnetic tape, return members of the
	286	magnetic tape status structure, as obtained with a
	287	.Dv MTIOCGET
	288	ioctl call. If the open device is not a magnetic tape, an error is returned.
	289	If the
	290	.Dv MTIOCGET
	291	operation was successful, the numerical value of the structure member is
	292	returned in decimal. The following sub commands are supported:
	293	.Bl -tag -width Fl
	294	.It Ic T
	295	return the content of the structure member
	296	.Ar mt_type
	297	which contains the type of the magnetic tape device.
	298	.It Ic D
	299	return the content of the structure member
	300	.Ar mt_dsreg
	301	which contains the "drive status register".
	302	.It Ic E
	303	return the content of the structure member
	304	.Ar mt_erreg
	305	which contains the "error register". This structure member must be retrieved
	306	first because it is cleared after each
	307	.Dv MTIOCGET
	308	ioctl call.
	309	.It Ic R
	310	return the content of the structure member
	311	.Ar mt_resid
	312	which contains the residual count of the last I/O.
	313	.It Ic F
	314	return the content of the structure member
	315	.Ar mt_fileno
	316	which contains the file number of the current tape position.
	317	.It Ic B
	318	return the content of the structure member
	319	.Ar mt_blkno
	320	which contains the block number of the current tape position.
	321	.It Ic f
	322	return the content of the structure member
	323	.Ar mt_flags
	324	which contains MTF_ flags from the driver.
	325	.It Ic b
	326	return the content of the structure member
	327	.Ar mt_bf
	328	which contains the optimum blocking factor.
	329	.El
	330	.El
	331	.Sm on
	332	.Pp
	333	Any other command causes
	334	.Nm
	335	to exit.
	336	.Sh DIAGNOSTICS
	337	All responses are of the form described above.
	338	.Sh SEE ALSO
	339	.Xr rcmd 3 ,
	340	.Xr rexec 3 ,
	341	.Xr /usr/include/sys/mtio.h ,
	342	.Xr rdump 8 ,
	343	.Xr rrestore 8
	344	.Sh BUGS
	345	People should be discouraged from using this for a remote
	346	file access protocol.
	347	.Sh AUTHOR
	348	The
	349	.Nm dump/restore
	350	backup suit was ported to Linux's Second Extended File System
	351	by Remy Card <card@Linux.EU.Org>. He maintained the initial versions
	352	of dump (up and including 0.4b4, released in january 1997).
	353	.Pp
	354	Starting with 0.4b5, the new maintainer is Stelian Pop
	355	.br
	356	<stelian@popies.net>.
	357	.Sh AVAILABILITY
	358	The
	359	.Nm dump/restore
	360	backup suit is available from
	361	.br
	362	http://dump.sourceforge.net
	363	.Sh HISTORY
	364	The
	365	.Nm
	366	command appeared in
	367	.Bx 4.2 .