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.5 2007/11/23 23:03:57 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 rcmd 3
  51 call.
  52 .Pp
  53 The
  54 .Nm
  55 utility accepts requests specific to the manipulation of
  56 magnetic tapes, performs the commands, then responds with
  57 a status indication.  All responses are in
  58 .Tn ASCII
  59 and in
  60 one of two forms.
  61 Successful commands have responses of:
  62 .Bd -ragged -offset indent
  63 .Sm off
  64 .Sy A Ar number No \en
  65 .Sm on
  66 .Ed
  67 .Pp
  68 .Ar Number
  69 is an
  70 .Tn ASCII
  71 representation of a decimal number.
  72 Unsuccessful commands are responded to with:
  73 .Bd -ragged -offset indent
  74 .Sm off
  75 .Xo Sy E Ar error-number
  76 .No \en Ar error-message
  77 .No \en
  78 .Xc
  79 .Sm on
  80 .Ed
  81 .Pp
  82 .Ar Error-number
  83 is one of the possible error
  84 numbers described in
  85 .Xr intro 2
  86 and
  87 .Ar error-message
  88 is the corresponding error string as printed
  89 from a call to
  90 .Xr perror 3 .
  91 The protocol is comprised of the
  92 following commands, which are sent as indicated - no spaces are supplied
  93 between the command and its arguments, or between its arguments, and
  94 .Ql \en
  95 indicates that a newline should be supplied:
  96 .Bl -tag -width Ds
  97 .Sm off
  98 .It Xo Sy \&O Ar device
  99 .No \en Ar mode No \en
 100 .Xc
 101 .Sm on
 102 Open the specified
 103 .Ar device
 104 using the indicated
 105 .Ar mode .
 106 .Ar Device
 107 is a full pathname and
 108 .Ar mode
 109 is an
 110 .Tn ASCII
 111 representation of a decimal
 112 number suitable for passing to
 113 .Xr open 2 .
 114 If a device had already been opened, it is
 115 closed before a new open is performed.
 116 .Sm off
 117 .It Xo Sy C Ar device No \en
 118 .Xc
 119 .Sm on
 120 Close the currently open device.  The
 121 .Ar device
 122 specified is ignored.
 123 .Sm off
 124 .It Xo Sy L
 125 .Ar whence No \en
 126 .Ar offset No \en
 127 .Xc
 128 .Sm on
 129 Perform an
 130 .Xr lseek 2
 131 operation using the specified parameters.
 132 The response value is that returned from the
 133 .Xr lseek 2
 134 call.
 135 .Sm off
 136 .It Sy W Ar count No \en
 137 .Sm on
 138 Write data onto the open device.
 139 The
 140 .Nm
 141 utility reads
 142 .Ar count
 143 bytes from the connection, aborting if
 144 a premature end-of-file is encountered.
 145 The response value is that returned from
 146 the
 147 .Xr write 2
 148 call.
 149 .Sm off
 150 .It Sy R Ar count No \en
 151 .Sm on
 152 Read
 153 .Ar count
 154 bytes of data from the open device.
 155 If
 156 .Ar count
 157 exceeds the size of the data buffer (10 kilobytes), it is
 158 truncated to the data buffer size.
 159 The
 160 .Nm
 161 utility 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 MTIOCTOP
 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 mtio 4 ,
 211 .Xr rdump 8 ,
 212 .Xr rrestore 8
 213 .Sh HISTORY
 214 The
 215 .Nm
 216 utility appeared in
 217 .Bx 4.2 .
 218 .Sh BUGS
 219 People should be discouraged from using this for a remote
 220 file access protocol.