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 .\" $DragonFly: src/usr.sbin/rmt/rmt.8,v 1.4 2006/04/17 18:01:38 swildner Exp $
  35 .\"
  36 .Dd June 1, 1994
  37 .Dt RMT 8
  38 .Os
  39 .Sh NAME
  40 .Nm rmt
  41 .Nd remote magtape protocol module
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 utility is used by the remote dump and restore programs
  48 in manipulating a magnetic tape drive through an interprocess
  49 communication connection.  It 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 utility 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 2
 136 call.
 137 .Sm off
 138 .It Sy W Ar count No \en
 139 .Sm on
 140 Write data onto the open device.
 141 The
 142 .Nm
 143 utility reads
 144 .Ar count
 145 bytes from the connection, aborting if
 146 a premature end-of-file is encountered.
 147 The response value is that returned from
 148 the
 149 .Xr write 2
 150 call.
 151 .Sm off
 152 .It Sy R Ar count No \en
 153 .Sm on
 154 Read
 155 .Ar count
 156 bytes of data from the open device.
 157 If
 158 .Ar count
 159 exceeds the size of the data buffer (10 kilobytes), it is
 160 truncated to the data buffer size.
 161 The
 162 .Nm
 163 utility 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
 170 successful; otherwise an error in the
 171 standard format is returned.  If the read
 172 was successful, the data read is then sent.
 173 .Sm off
 174 .It Xo Sy I Ar operation
 175 .No \en Ar count No \en
 176 .Xc
 177 .Sm on
 178 Perform a
 179 .Dv MTIOCOP
 180 .Xr ioctl 2
 181 command using the specified parameters.
 182 The parameters are interpreted as the
 183 .Tn ASCII
 184 representations of the decimal values
 185 to place in the
 186 .Ar mt_op
 187 and
 188 .Ar mt_count
 189 fields of the structure used in the
 190 .Xr ioctl 2
 191 call.  The return value is the
 192 .Ar count
 193 parameter when the operation is successful.
 194 .It Sy S
 195 Return the status of the open device, as
 196 obtained with a
 197 .Dv MTIOCGET
 198 .Xr ioctl 2
 199 call.  If the operation was successful,
 200 an ``ack'' is sent with the size of the
 201 status buffer, then the status buffer is
 202 sent (in binary).
 203 .El
 204 .Pp
 205 Any other command causes
 206 .Nm
 207 to exit.
 208 .Sh DIAGNOSTICS
 209 All responses are of the form described above.
 210 .Sh SEE ALSO
 211 .Xr rcmd 3 ,
 212 .Xr rexec 3 ,
 213 .Xr mtio 4 ,
 214 .Xr rdump 8 ,
 215 .Xr rrestore 8
 216 .Sh HISTORY
 217 The
 218 .Nm
 219 utility appeared in
 220 .Bx 4.2 .
 221 .Sh BUGS
 222 People should be discouraged from using this for a remote
 223 file access protocol.