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.8 2002/04/15 11:57:29 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
  45 .Nm dump,
  46 .Nm restore
  47 or
  48 .Nm tar
  49 programs in manipulating a magnetic tape drive through an interprocess
  50 communication connection.
  51 .Nm rmt
  52 is normally started up with an
  53 .Xr rexec 3
  54 or
  55 .Xr rcmd 3
  56 call.
  57 .Pp
  58 The
  59 .Nm
  60 program accepts requests specific to the manipulation of magnetic tapes,
  61 performs the commands, then responds with a status indication.
  62 All responses are in
  63 .Tn ASCII
  64 and in one of the following two forms.
  65 .Pp
  66 Successful commands have responses of:
  67 .Bd -filled -offset indent
  68 .Sm off
  69 .Sy A Ar number No \en
  70 .Sm on
  71 .Ed
  72 .Pp
  73 where
  74 .Ar number
  75 is an
  76 .Tn ASCII
  77 representation of a decimal number.
  78 .Pp
  79 Unsuccessful commands are responded to with:
  80 .Bd -filled -offset indent
  81 .Sm off
  82 .Xo Sy E Ar error-number
  83 .No \en Ar error-message
  84 .No \en
  85 .Xc
  86 .Sm on
  87 .Ed
  88 .Pp
  89 where
  90 .Ar error-number
  91 is one of the possible error numbers described in
  92 .Xr intro 2
  93 and
  94 .Ar error-message
  95 is the corresponding error string as printed from a call to
  96 .Xr perror 3 .
  97 .Pp
  98 The protocol is comprised of the
  99 following commands, which are sent as indicated - no spaces are supplied
 100 between the command and its arguments, or between its arguments, and
 101 .Ql \en
 102 indicates that a newline should be supplied:
 103 .Bl -tag -width Ds
 104 .Sm off
 105 .It Xo Sy \&O Ar device
 106 .No \en Ar mode No \en
 107 .Xc
 108 .Sm on
 109 Open the specified
 110 .Ar device
 111 using the indicated
 112 .Ar mode .
 113 .Ar Device
 114 is a full pathname and
 115 .Ar mode
 116 is an
 117 .Tn ASCII
 118 representation of a decimal number suitable for passing to
 119 .Xr open 2 .
 120 If a device had already been opened, it is closed before a
 121 new open is performed.
 122 .Sm off
 123 .It Xo Sy C Ar device No \en
 124 .Xc
 125 .Sm on
 126 Close the currently open device.  The
 127 .Ar device
 128 specified is ignored.
 129 .Sm off
 130 .It Xo Sy L
 131 .Ar whence No \en
 132 .Ar offset No \en
 133 .Xc
 134 .Sm on
 135 Perform an
 136 .Xr lseek 2
 137 operation using the specified parameters.
 138 The response value is that returned from the
 139 .Xr lseek
 140 call.
 141 .Sm off
 142 .It Sy W Ar count No \en
 143 .Sm on
 144 Write data onto the open device.
 145 .Nm rmt
 146 reads
 147 .Ar count
 148 bytes from the connection, aborting if a premature end-of-file is encountered.
 149 The response value is that returned from the
 150 .Xr write 2
 151 call.
 152 .Sm off
 153 .It Sy R Ar count No \en
 154 .Sm on
 155 Read
 156 .Ar count
 157 bytes of data from the open device.
 158 If
 159 .Ar count
 160 exceeds the size of the data buffer (10 kilobytes), it is
 161 truncated to the data buffer size.
 162 .Nm rmt
 163 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 successful; otherwise an error in the standard format
 170 is returned.  If the read 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.  The parameters are interpreted as the
 180 .Tn ASCII
 181 representations of the decimal values to place in the
 182 .Ar mt_op
 183 and
 184 .Ar mt_count
 185 fields of the structure used in the
 186 .Xr ioctl
 187 call.  The return value is the
 188 .Ar count
 189 parameter when the operation is successful.
 190 .Pp
 191 By issuing the
 192 .Ql I-1\en0\en
 193 command, a client will specify that he is using the VERSION 1 protocol.
 194 .Pp
 195 For a VERSION 0 client, the
 196 .Ar operation
 197 parameter is the platform
 198 .Ar mt_op
 199 value (could be different if the client and the
 200 .Nm
 201 server are on two different platforms). For a VERSION 1 client,
 202 the
 203 .Ar operation
 204 parameter is standardized as below:
 205 .Bl -tag -width Fl
 206 .It Ic 0
 207 Issue a MTWEOF command (write
 208 .Ar count
 209 end-of-file records).
 210 .It Ic 1
 211 Issue a MTFSF command (forward space over
 212 .Ar count
 213 file marks).
 214 .It Ic 2
 215 Issue a MTBSF command (backward space over
 216 .Ar count
 217 file marks).
 218 .It Ic 3
 219 Issue a MTFSR command (forward space
 220 .Ar count
 221 inter-record gaps).
 222 .It Ic 4
 223 Issue a MTBSR command (backward space
 224 .Ar count
 225 inter-record gaps).
 226 .It Ic 5
 227 Issue a MTREW command (rewind).
 228 .It Ic 6
 229 Issue a MTOFFL command (rewind and put the drive offline).
 230 .It Ic 7
 231 Issue a MTNOP command (no operation, set status only).
 232 .El
 233 .Sm off
 234 .It Xo Sy i Ar operation
 235 .No \en Ar count No \en
 236 .Xc
 237 .Sm on
 238 Perform an extended
 239 .Dv MTIOCOP
 240 .Xr ioctl 2
 241 command using the specified parameters.
 242 The parameters are interpreted as the
 243 .Tn ASCII
 244 representations of the decimal values to place in the
 245 .Ar mt_op
 246 and
 247 .Ar mt_count
 248 fields of the structure used in the
 249 .Xr ioctl
 250 call.  The return value is the
 251 .Ar count
 252 parameter when the operation is successful.
 253 The possible operations are:
 254 .Bl -tag -width Fl
 255 .It Ic 0
 256 Issue a MTCACHE command (switch cache on).
 257 .It Ic 1
 258 Issue a MTNOCACHE command (switch cache off).
 259 .It Ic 2
 260 Issue a MTRETEN command (retension the tape).
 261 .It Ic 3
 262 Issue a MTERASE command (erase the entire tape).
 263 .It Ic 4
 264 Issue a MTEOM command (position to end of media).
 265 .It Ic 5
 266 Issue a MTNBSF command (backward space count files to BOF).
 267 .El
 268 .ne 1i
 269 .Sm off
 270 .It Sy S
 271 .Sm on
 272 Return the status of the open device, as
 273 obtained with a
 274 .Dv MTIOCGET
 275 .Xr ioctl
 276 call.  If the operation was successful,
 277 an ``ack'' is sent with the size of the
 278 status buffer, then the status buffer is
 279 sent (in binary, which is non-portable between different platforms).
 280 .Sm off
 281 .It Xo Sy s Ar sub-command
 282 .Xc
 283 .Sm on
 284 This is a replacement for the previous S command, portable across different
 285 platforms. If the open device is a magnetic tape, return members of the
 286 magnetic tape status structure, as obtained with a
 287 .Dv MTIOCGET
 288 ioctl call. If the open device is not a magnetic tape, an error is returned.
 289 If the
 290 .Dv MTIOCGET
 291 operation was successful, the numerical value of the structure member is
 292 returned in decimal. The following sub commands are supported:
 293 .Bl -tag -width Fl
 294 .It Ic T
 295 return the content of the structure member
 296 .Ar mt_type
 297 which contains the type of the magnetic tape device.
 298 .It Ic D
 299 return the content of the structure member
 300 .Ar mt_dsreg
 301 which contains the "drive status register".
 302 .It Ic E
 303 return the content of the structure member
 304 .Ar mt_erreg
 305 which contains the "error register". This structure member must be retrieved
 306 first because it is cleared after each
 307 .Dv MTIOCGET
 308 ioctl call.
 309 .It Ic R
 310 return the content of the structure member
 311 .Ar mt_resid
 312 which contains the residual count of the last I/O.
 313 .It Ic F
 314 return the content of the structure member
 315 .Ar mt_fileno
 316 which contains the file number of the current tape position.
 317 .It Ic B
 318 return the content of the structure member
 319 .Ar mt_blkno
 320 which contains the block number of the current tape position.
 321 .It Ic f
 322 return the content of the structure member
 323 .Ar mt_flags
 324 which contains MTF_ flags from the driver.
 325 .It Ic b
 326 return the content of the structure member
 327 .Ar mt_bf
 328 which contains the optimum blocking factor.
 329 .El
 330 .El
 331 .Sm on
 332 .Pp
 333 Any other command causes
 334 .Nm
 335 to exit.
 336 .Sh DIAGNOSTICS
 337 All responses are of the form described above.
 338 .Sh SEE ALSO
 339 .Xr rcmd 3 ,
 340 .Xr rexec 3 ,
 341 .Xr /usr/include/sys/mtio.h ,
 342 .Xr rdump 8 ,
 343 .Xr rrestore 8
 344 .Sh BUGS
 345 People should be discouraged from using this for a remote
 346 file access protocol.
 347 .Sh AUTHOR
 348 The
 349 .Nm dump/restore
 350 backup suit was ported to Linux's Second Extended File System
 351 by Remy Card <card@Linux.EU.Org>. He maintained the initial versions
 352 of dump (up and including 0.4b4, released in january 1997).
 353 .Pp
 354 Starting with 0.4b5, the new maintainer is Stelian Pop
 355 .br
 356 <stelian@popies.net>.
 357 .Sh AVAILABILITY
 358 The
 359 .Nm dump/restore
 360 backup suit is available from
 361 .br
 362 http://dump.sourceforge.net
 363 .Sh HISTORY
 364 The
 365 .Nm
 366 command appeared in
 367 .Bx 4.2 .