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$
  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 .Nm Rmt
  45 is a program used by the remote dump and restore programs
  46 in manipulating a magnetic tape drive through an interprocess
  47 communication connection.
  48 .Nm Rmt
  49 is normally started up with an
  50 .Xr rexec 3
  51 or
  52 .Xr rcmd 3
  53 call.
  54 .Pp
  55 The
  56 .Nm
  57 program accepts requests specific to the manipulation of
  58 magnetic tapes, performs the commands, then responds with
  59 a status indication.  All responses are in
  60 .Tn ASCII
  61 and in
  62 one of two forms.
  63 Successful commands have responses of:
  64 .Bd -ragged -offset indent
  65 .Sm off
  66 .Sy A Ar number No \en
  67 .Sm on
  68 .Ed
  69 .Pp
  70 .Ar Number
  71 is an
  72 .Tn ASCII
  73 representation of a decimal number.
  74 Unsuccessful commands are responded to with:
  75 .Bd -ragged -offset indent
  76 .Sm off
  77 .Xo Sy E Ar error-number
  78 .No \en Ar error-message
  79 .No \en
  80 .Xc
  81 .Sm on
  82 .Ed
  83 .Pp
  84 .Ar Error-number
  85 is one of the possible error
  86 numbers described in
  87 .Xr intro 2
  88 and
  89 .Ar error-message
  90 is the corresponding error string as printed
  91 from a call to
  92 .Xr perror 3 .
  93 The protocol is comprised of the
  94 following commands, which are sent as indicated - no spaces are supplied
  95 between the command and its arguments, or between its arguments, and
  96 .Ql \en
  97 indicates that a newline should be supplied:
  98 .Bl -tag -width Ds
  99 .Sm off
 100 .It Xo Sy \&O Ar device
 101 .No \en Ar mode No \en
 102 .Xc
 103 .Sm on
 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 .Sm off
 119 .It Xo Sy C Ar device No \en
 120 .Xc
 121 .Sm on
 122 Close the currently open device.  The
 123 .Ar device
 124 specified is ignored.
 125 .Sm off
 126 .It Xo Sy L
 127 .Ar whence No \en
 128 .Ar offset No \en
 129 .Xc
 130 .Sm on
 131 Perform an
 132 .Xr lseek 2
 133 operation using the specified parameters.
 134 The response value is that returned from the
 135 .Xr lseek
 136 call.
 137 .Sm off
 138 .It Sy W Ar count No \en
 139 .Sm on
 140 Write data onto the open device.
 141 .Nm Rmt
 142 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 .Nm Rmt
 161 then performs the requested
 162 .Xr read 2
 163 and responds with
 164 .Sm off
 165 .Sy A Ar count-read No \en
 166 .Sm on
 167 if the read was
 168 successful; otherwise an error in the
 169 standard format is returned.  If the read
 170 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.
 180 The parameters are interpreted as the
 181 .Tn ASCII
 182 representations of the decimal values
 183 to place in the
 184 .Ar mt_op
 185 and
 186 .Ar mt_count
 187 fields of the structure used in the
 188 .Xr ioctl 2
 189 call.  The return value is the
 190 .Ar count
 191 parameter when the operation is successful.
 192 .It Sy S
 193 Return the status of the open device, as
 194 obtained with a
 195 .Dv MTIOCGET
 196 .Xr ioctl 2
 197 call.  If the operation was successful,
 198 an ``ack'' is sent with the size of the
 199 status buffer, then the status buffer is
 200 sent (in binary).
 201 .El
 202 .Pp
 203 Any other command causes
 204 .Nm
 205 to exit.
 206 .Sh DIAGNOSTICS
 207 All responses are of the form described above.
 208 .Sh SEE ALSO
 209 .Xr rcmd 3 ,
 210 .Xr rexec 3 ,
 211 .Xr mtio 4 ,
 212 .Xr rdump 8 ,
 213 .Xr rrestore 8
 214 .Sh BUGS
 215 People should be discouraged from using this for a remote
 216 file access protocol.
 217 .Sh HISTORY
 218 The
 219 .Nm
 220 command appeared in
 221 .Bx 4.2 .