usr.sbin/rmt/rmt.8

   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 .\"     @(#)rmt.8       8.3 (Berkeley) 6/1/94
  33 .\" $FreeBSD: src/usr.sbin/rmt/rmt.8,v 1.5.2.5 2003/03/11 22:31:32 trhodes Exp $
  34 .\"
  35 .Dd June 1, 1994
  36 .Dt RMT 8
  37 .Os
  38 .Sh NAME
  39 .Nm rmt
  40 .Nd remote magtape protocol module
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility is used by the remote dump and restore programs
  47 in manipulating a magnetic tape drive through an interprocess
  48 communication connection.  It is normally started up with an
  49 .Xr rexec 3
  50 or
  51 .Xr rcmd 3
  52 call.
  53 .Pp
  54 The
  55 .Nm
  56 utility accepts requests specific to the manipulation of
  57 magnetic tapes, performs the commands, then responds with
  58 a status indication.  All responses are in
  59 .Tn ASCII
  60 and in
  61 one of two forms.
  62 Successful commands have responses of:
  63 .Bd -ragged -offset indent
  64 .Sm off
  65 .Sy A Ar number No \en
  66 .Sm on
  67 .Ed
  68 .Pp
  69 .Ar Number
  70 is an
  71 .Tn ASCII
  72 representation of a decimal number.
  73 Unsuccessful commands are responded to with:
  74 .Bd -ragged -offset indent
  75 .Sm off
  76 .Xo Sy E Ar error-number
  77 .No \en Ar error-message
  78 .No \en
  79 .Xc
  80 .Sm on
  81 .Ed
  82 .Pp
  83 .Ar Error-number
  84 is one of the possible error
  85 numbers described in
  86 .Xr intro 2
  87 and
  88 .Ar error-message
  89 is the corresponding error string as printed
  90 from a call to
  91 .Xr perror 3 .
  92 The protocol is comprised of the
  93 following commands, which are sent as indicated - no spaces are supplied
  94 between the command and its arguments, or between its arguments, and
  95 .Ql \en
  96 indicates that a newline should be supplied:
  97 .Bl -tag -width Ds
  98 .Sm off
  99 .It Xo Sy \&O Ar device
 100 .No \en Ar mode No \en
 101 .Xc
 102 .Sm on
 103 Open the specified
 104 .Ar device
 105 using the indicated
 106 .Ar mode .
 107 .Ar Device
 108 is a full pathname and
 109 .Ar mode
 110 is an
 111 .Tn ASCII
 112 representation of a decimal
 113 number suitable for passing to
 114 .Xr open 2 .
 115 If a device had already been opened, it is
 116 closed before a new open is performed.
 117 .Sm off
 118 .It Xo Sy C Ar device No \en
 119 .Xc
 120 .Sm on
 121 Close the currently open device.  The
 122 .Ar device
 123 specified is ignored.
 124 .Sm off
 125 .It Xo Sy L
 126 .Ar whence No \en
 127 .Ar offset No \en
 128 .Xc
 129 .Sm on
 130 Perform an
 131 .Xr lseek 2
 132 operation using the specified parameters.
 133 The response value is that returned from the
 134 .Xr lseek
 135 call.
 136 .Sm off
 137 .It Sy W Ar count No \en
 138 .Sm on
 139 Write data onto the open device.
 140 The
 141 .Nm
 142 utility reads
 143 .Ar count
 144 bytes from the connection, aborting if
 145 a premature end-of-file is encountered.
 146 The response value is that returned from
 147 the
 148 .Xr write 2
 149 call.
 150 .Sm off
 151 .It Sy R Ar count No \en
 152 .Sm on
 153 Read
 154 .Ar count
 155 bytes of data from the open device.
 156 If
 157 .Ar count
 158 exceeds the size of the data buffer (10 kilobytes), it is
 159 truncated to the data buffer size.
 160 The
 161 .Nm
 162 utility then performs the requested
 163 .Xr read 2
 164 and responds with
 165 .Sm off
 166 .Sy A Ar count-read No \en
 167 .Sm on
 168 if the read was
 169 successful; otherwise an error in the
 170 standard format is returned.  If the read
 171 was successful, the data read is then sent.
 172 .Sm off
 173 .It Xo Sy I Ar operation
 174 .No \en Ar count No \en
 175 .Xc
 176 .Sm on
 177 Perform a
 178 .Dv MTIOCOP
 179 .Xr ioctl 2
 180 command using the specified parameters.
 181 The parameters are interpreted as the
 182 .Tn ASCII
 183 representations of the decimal values
 184 to place in the
 185 .Ar mt_op
 186 and
 187 .Ar mt_count
 188 fields of the structure used in the
 189 .Xr ioctl 2
 190 call.  The return value is the
 191 .Ar count
 192 parameter when the operation is successful.
 193 .It Sy S
 194 Return the status of the open device, as
 195 obtained with a
 196 .Dv MTIOCGET
 197 .Xr ioctl 2
 198 call.  If the operation was successful,
 199 an ``ack'' is sent with the size of the
 200 status buffer, then the status buffer is
 201 sent (in binary).
 202 .El
 203 .Pp
 204 Any other command causes
 205 .Nm
 206 to exit.
 207 .Sh DIAGNOSTICS
 208 All responses are of the form described above.
 209 .Sh SEE ALSO
 210 .Xr rcmd 3 ,
 211 .Xr rexec 3 ,
 212 .Xr mtio 4 ,
 213 .Xr rdump 8 ,
 214 .Xr rrestore 8
 215 .Sh BUGS
 216 People should be discouraged from using this for a remote
 217 file access protocol.
 218 .Sh HISTORY
 219 The
 220 .Nm
 221 utility appeared in
 222 .Bx 4.2 .