rmt/rmt.8.in

   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 .\"     $Id: rmt.8.in,v 1.5 2000/01/21 10:23:30 stelian Exp $
  33 .\"
  34 .Dd __DATE__
  35 .Dt RMT 8
  36 .Os "rmt __VERSION__"
  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 the remote dump and restore programs
  45 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.
  53 .Pp
  54 The
  55 .Nm
  56 program 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 -filled -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 -filled -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 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 .It Xo Sy C Ar device No \en
 117 .Xc
 118 Close the currently open device.  The
 119 .Ar device
 120 specified is ignored.
 121 .It Xo Sy L
 122 .Ar whence No \en
 123 .Ar offset No \en
 124 .Xc
 125 .Sm on
 126 Perform an
 127 .Xr lseek 2
 128 operation using the specified parameters.
 129 The response value is that returned from the
 130 .Xr lseek
 131 call.
 132 .Sm off
 133 .It Sy W Ar count No \en
 134 .Sm on
 135 Write data onto the open device.
 136 .Nm Rmt
 137 reads
 138 .Ar count
 139 bytes from the connection, aborting if
 140 a premature end-of-file is encountered.
 141 The response value is that returned from
 142 the
 143 .Xr write 2
 144 call.
 145 .Sm off
 146 .It Sy R Ar count No \en
 147 .Sm on
 148 Read
 149 .Ar count
 150 bytes of data from the open device.
 151 If
 152 .Ar count
 153 exceeds the size of the data buffer (10 kilobytes), it is
 154 truncated to the data buffer size.
 155 .Nm Rmt
 156 then performs the requested
 157 .Xr read 2
 158 and responds with
 159 .Sm off
 160 .Sy A Ar count-read No \en
 161 .Sm on
 162 if the read was
 163 successful; otherwise an error in the
 164 standard format is returned.  If the read
 165 was successful, the data read is then sent.
 166 .Sm off
 167 .It Xo Sy I Ar operation
 168 .No \en Ar count No \en
 169 .Xc
 170 .Sm on
 171 Perform a
 172 .Dv MTIOCOP
 173 .Xr ioctl 2
 174 command using the specified parameters.
 175 The parameters are interpreted as the
 176 .Tn ASCII
 177 representations of the decimal values
 178 to place in the
 179 .Ar mt_op
 180 and
 181 .Ar mt_count
 182 fields of the structure used in the
 183 .Xr ioctl
 184 call.  The return value is the
 185 .Ar count
 186 parameter when the operation is successful.
 187 .ne 1i
 188 .It Sy S
 189 Return the status of the open device, as
 190 obtained with a
 191 .Dv MTIOCGET
 192 .Xr ioctl
 193 call.  If the operation was successful,
 194 an ``ack'' is sent with the size of the
 195 status buffer, then the status buffer is
 196 sent (in binary).
 197 .El
 198 .Sm on
 199 .Pp
 200 Any other command causes
 201 .Nm
 202 to exit.
 203 .Sh DIAGNOSTICS
 204 All responses are of the form described above.
 205 .Sh SEE ALSO
 206 .Xr rcmd 3 ,
 207 .Xr rexec 3 ,
 208 .Xr mtio 4 ,
 209 .Xr rdump 8 ,
 210 .Xr rrestore 8
 211 .Sh BUGS
 212 People should be discouraged from using this for a remote
 213 file access protocol.
 214 .Sh AUTHOR
 215 The
 216 .Nm dump/restore
 217 backup suit was ported to Linux's Second Extended File System
 218 by Remy Card <card@Linux.EU.Org>. He maintained the initial versions
 219 of dump (up and including 0.4b4, released in january 1997).
 220 .Pp
 221 Starting with 0.4b5, the new maintainer is Stelian Pop
 222 .br
 223 <pop@cybercable.fr>.
 224 .Sh AVAILABILITY
 225 The
 226 .Nm dump/restore
 227 backup suit is available from
 228 .br
 229 http://dump.sourceforge.net
 230 .Sh HISTORY
 231 The
 232 .Nm
 233 command appeared in
 234 .Bx 4.2 .