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