xref: /dragonfly/usr.sbin/rmt/rmt.8 (revision dc71b7ab)
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. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)rmt.8	8.3 (Berkeley) 6/1/94
29.\" $FreeBSD: src/usr.sbin/rmt/rmt.8,v 1.5.2.5 2003/03/11 22:31:32 trhodes Exp $
30.\" $DragonFly: src/usr.sbin/rmt/rmt.8,v 1.5 2007/11/23 23:03:57 swildner Exp $
31.\"
32.Dd June 1, 1994
33.Dt RMT 8
34.Os
35.Sh NAME
36.Nm rmt
37.Nd remote magtape protocol module
38.Sh SYNOPSIS
39.Nm
40.Sh DESCRIPTION
41The
42.Nm
43utility is used by the remote dump and restore programs
44in manipulating a magnetic tape drive through an interprocess
45communication connection.  It is normally started up with an
46.Xr rcmd 3
47call.
48.Pp
49The
50.Nm
51utility accepts requests specific to the manipulation of
52magnetic tapes, performs the commands, then responds with
53a status indication.  All responses are in
54.Tn ASCII
55and in
56one of two forms.
57Successful commands have responses of:
58.Bd -ragged -offset indent
59.Sm off
60.Sy A Ar number No \en
61.Sm on
62.Ed
63.Pp
64.Ar Number
65is an
66.Tn ASCII
67representation of a decimal number.
68Unsuccessful commands are responded to with:
69.Bd -ragged -offset indent
70.Sm off
71.Xo Sy E Ar error-number
72.No \en Ar error-message
73.No \en
74.Xc
75.Sm on
76.Ed
77.Pp
78.Ar Error-number
79is one of the possible error
80numbers described in
81.Xr intro 2
82and
83.Ar error-message
84is the corresponding error string as printed
85from a call to
86.Xr perror 3 .
87The protocol is comprised of the
88following commands, which are sent as indicated - no spaces are supplied
89between the command and its arguments, or between its arguments, and
90.Ql \en
91indicates that a newline should be supplied:
92.Bl -tag -width Ds
93.Sm off
94.It Xo Sy \&O Ar device
95.No \en Ar mode No \en
96.Xc
97.Sm on
98Open the specified
99.Ar device
100using the indicated
101.Ar mode .
102.Ar Device
103is a full pathname and
104.Ar mode
105is an
106.Tn ASCII
107representation of a decimal
108number suitable for passing to
109.Xr open 2 .
110If a device had already been opened, it is
111closed before a new open is performed.
112.Sm off
113.It Xo Sy C Ar device No \en
114.Xc
115.Sm on
116Close the currently open device.  The
117.Ar device
118specified is ignored.
119.Sm off
120.It Xo Sy L
121.Ar whence No \en
122.Ar offset No \en
123.Xc
124.Sm on
125Perform an
126.Xr lseek 2
127operation using the specified parameters.
128The response value is that returned from the
129.Xr lseek 2
130call.
131.Sm off
132.It Sy W Ar count No \en
133.Sm on
134Write data onto the open device.
135The
136.Nm
137utility reads
138.Ar count
139bytes from the connection, aborting if
140a premature end-of-file is encountered.
141The response value is that returned from
142the
143.Xr write 2
144call.
145.Sm off
146.It Sy R Ar count No \en
147.Sm on
148Read
149.Ar count
150bytes of data from the open device.
151If
152.Ar count
153exceeds the size of the data buffer (10 kilobytes), it is
154truncated to the data buffer size.
155The
156.Nm
157utility then performs the requested
158.Xr read 2
159and responds with
160.Sm off
161.Sy A Ar count-read No \en
162.Sm on
163if the read was
164successful; otherwise an error in the
165standard format is returned.  If the read
166was successful, the data read is then sent.
167.Sm off
168.It Xo Sy I Ar operation
169.No \en Ar count No \en
170.Xc
171.Sm on
172Perform a
173.Dv MTIOCTOP
174.Xr ioctl 2
175command using the specified parameters.
176The parameters are interpreted as the
177.Tn ASCII
178representations of the decimal values
179to place in the
180.Ar mt_op
181and
182.Ar mt_count
183fields of the structure used in the
184.Xr ioctl 2
185call.  The return value is the
186.Ar count
187parameter when the operation is successful.
188.It Sy S
189Return the status of the open device, as
190obtained with a
191.Dv MTIOCGET
192.Xr ioctl 2
193call.  If the operation was successful,
194an ``ack'' is sent with the size of the
195status buffer, then the status buffer is
196sent (in binary).
197.El
198.Pp
199Any other command causes
200.Nm
201to exit.
202.Sh DIAGNOSTICS
203All responses are of the form described above.
204.Sh SEE ALSO
205.Xr rcmd 3 ,
206.Xr mtio 4 ,
207.Xr rdump 8 ,
208.Xr rrestore 8
209.Sh HISTORY
210The
211.Nm
212utility appeared in
213.Bx 4.2 .
214.Sh BUGS
215People should be discouraged from using this for a remote
216file access protocol.
217