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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     $Id: rmt.8.in,v 1.10 2003/03/30 15:40:40 stelian Exp $
  29 .\"
  30 .TH RMT 8 "version __VERSION__ of __DATE__" BSD "System management commands"
  31 .SH NAME
  32 rmt \- remote magtape protocol module
  33 .SH SYNOPSIS
  34 .B rmt
  35 .SH DESCRIPTION
  36 .B Rmt
  37 is a program used by the remote
  38 .BR dump (8),
  39 .BR restore (8)
  40 or
  41 .BR tar (1)
  42 programs in manipulating a magnetic tape drive through an interprocess
  43 communication connection.
  44 .B Rmt
  45 is normally started up with an
  46 .BR rexec (3)
  47 or
  48 .BR rcmd (3)
  49 call.
  50 .PP
  51 The
  52 .B rmt
  53 program accepts requests specific to the manipulation of magnetic tapes,
  54 performs the commands, then responds with a status indication.  All responses
  55 are in
  56 .B ASCII
  57 and in one of the following two forms.
  58 .PP
  59 Successful commands have responses of:
  60 .RS
  61 .B A\fInumber\fR\en
  62 .RE
  63 .PP
  64 where
  65 .I number
  66 is an
  67 .B ASCII
  68 representation of a decimal number.
  69 .PP
  70 Unsuccessful commands are responded to with:
  71 .RS
  72 .B E\fIerror-number\fR\en\fIerror-message\fR\en
  73 .RE
  74 .PP
  75 where
  76 .I error-number
  77 is one of the possible error numbers described in
  78 .BR intro (2)
  79 and
  80 .I error-message
  81 is the corresponding error string as printed from a call to
  82 .BR perror (3).
  83 .PP
  84 The protocol is comprised of the following commands, which are sent as
  85 indicated - no spaces are supplied between the command and its arguments, or
  86 between its arguments, and \en indicates that a newline should be supplied:
  87 .TP
  88 .B O\fIdevice\fR\en\fImode\fR\en
  89 Open the specified
  90 .I device
  91 using the indicated
  92 .IR mode .
  93 .I Device
  94 is a full pathname and
  95 .I mode
  96 is an
  97 .B ASCII
  98 representation of a decimal number suitable for passing to
  99 .BR open (2).
 100 If a device had already been opened, it is closed before a new open is
 101 performed.
 102 .TP
 103 .B C\fIdevice\fR\en
 104 Close the currently open device.  The
 105 .I device
 106 specified is ignored.
 107 .TP
 108 .B L\fIwhence\fR\en\fIoffset\fR\en
 109 Perform an
 110 .BR lseek (2)
 111 operation using the specified parameters. The response value is that returned
 112 from the
 113 .B lseek
 114 call.
 115 .TP
 116 .B W\fIcount\fR\en
 117 Write data onto the open device.
 118 .B Rmt
 119 reads
 120 .I count
 121 bytes from the connection, aborting if a premature end-of-file is encountered.
 122 The response value is that returned from the
 123 .BR write (2)
 124 call.
 125 .TP
 126 .B R\fIcount\fR\en
 127 Read
 128 .I count
 129 bytes of data from the open device. If
 130 .I count
 131 exceeds the size of the data buffer (10 kilobytes), it is truncated to the
 132 data buffer size.
 133 .B Rmt
 134 then performs the requested
 135 .BR read (2)
 136 and responds with
 137 .B A\fIcount-read\fR\en
 138 if the read was successful; otherwise an error in the standard format is
 139 returned. If the read was successful, the data read is then sent.
 140 .TP
 141 .B I\fIoperation\fR\en\fIcount\fR\en
 142 Perform a
 143 .B MTIOCOP
 144 .BR ioctl (2)
 145 command using the specified parameters.  The parameters are interpreted as the
 146 .B ASCII
 147 representations of the decimal values to place in the
 148 .B mt_op
 149 and
 150 .B mt_count
 151 fields of the structure used in the
 152 .B ioctl
 153 call.  The return value is the
 154 .I count
 155 parameter when the operation is successful.
 156 .IP
 157 By issuing the
 158 .B I-1\en0\en
 159 command, a client will specify that he is using the VERSION 1 protocol.
 160 .IP
 161 For a VERSION 0 client, the
 162 .I operation
 163 parameter is the platform
 164 .B mt_op
 165 value (could be different if the client and the
 166 .B rmt
 167 server are on two different platforms). For a VERSION 1 client, the
 168 .I operation
 169 parameter is standardized as below:
 170 .RS
 171 .TP
 172 .B 0
 173 Issue a
 174 .B MTWEOF
 175 command (write
 176 .I count
 177 end-of-file records).
 178 .TP
 179 .B 1
 180 Issue a
 181 .B MTFSF
 182 command (forward space over
 183 .I count
 184 file marks).
 185 .TP
 186 .B 2
 187 Issue a
 188 .B MTBSF
 189 command (backward space over
 190 .I count
 191 file marks).
 192 .TP
 193 .B 3
 194 Issue a
 195 .B MTFSR
 196 command (forward space
 197 .I count
 198 inter-record gaps).
 199 .TP
 200 .B 4
 201 Issue a
 202 .B MTBSR
 203 command (backward space
 204 .I count
 205 inter-record gaps).
 206 .TP
 207 .B 5
 208 Issue a
 209 .B MTREW
 210 command (rewind).
 211 .TP
 212 .B 6
 213 Issue a
 214 .B MTOFFL
 215 command (rewind and put the drive offline).
 216 .TP
 217 .B 7
 218 Issue a
 219 .B MTNOP
 220 command (no operation, set status only).
 221 .RE
 222 .TP
 223 .B i\fIoperation\fR\en\fIcount\fR\en
 224 Perform an extended
 225 .B MTIOCOP
 226 .BR ioctl (2)
 227 command using the specified parameters. The parameters are interpreted as the
 228 .B ASCII
 229 representations of the decimal values to place in the
 230 .B mt_op
 231 and
 232 .B mt_count
 233 fields of the structure used in the
 234 .B ioctl
 235 call.  The return value is the
 236 .I count
 237 parameter when the operation is successful. The possible operations are:
 238 .RS
 239 .TP
 240 .B 0
 241 Issue a
 242 .B MTCACHE
 243 command (switch cache on).
 244 .TP
 245 .B 1
 246 Issue a
 247 .B MTNOCACHE
 248 command (switch cache off).
 249 .TP
 250 .B 2
 251 Issue a
 252 .B MTRETEN
 253 command (retension the tape).
 254 .TP
 255 .B 3
 256 Issue a
 257 .B MTERASE
 258 command (erase the entire tape).
 259 .TP
 260 .B 4
 261 Issue a
 262 .B MTEOM
 263 command (position to end of media).
 264 .TP
 265 .B 5
 266 Issue a
 267 .B MTNBSF
 268 command (backward space count files to BOF).
 269 .RE
 270 .TP
 271 .B S
 272 Return the status of the open device, as obtained with a
 273 .B MTIOCGET
 274 .B ioctl
 275 call.  If the operation was successful, an \*(lqack\*(rq is sent with the size
 276 of the status buffer, then the status buffer is sent (in binary, which is
 277 non-portable between different platforms).
 278 .TP
 279 .BI s sub-command
 280 This is a replacement for the previous
 281 .B S
 282 command, portable across different platforms. If the open device is a magnetic
 283 tape, return members of the magnetic tape status structure, as obtained with a
 284 .B MTIOCGET
 285 ioctl call. If the open device is not a magnetic tape, an error is returned. If
 286 the
 287 .B MTIOCGET
 288 operation was successful, the numerical value of the structure member is
 289 returned in decimal. The following sub commands are supported:
 290 .RS
 291 .TP
 292 .B T
 293 return the content of the structure member
 294 .B mt_type
 295 which contains the type of the magnetic tape device.
 296 .TP
 297 .B D
 298 return the content of the structure member
 299 .B mt_dsreg
 300 which contains the "drive status register".
 301 .TP
 302 .B E
 303 return the content of the structure member
 304 .B mt_erreg
 305 which contains the "error register". This structure member must be retrieved
 306 first because it is cleared after each
 307 .B MTIOCGET
 308 ioctl call.
 309 .TP
 310 .B R
 311 return the content of the structure member
 312 .B mt_resid
 313 which contains the residual count of the last I/O.
 314 .TP
 315 .B F
 316 return the content of the structure member
 317 .B mt_fileno
 318 which contains the file number of the current tape position.
 319 .TP
 320 .B B
 321 return the content of the structure member
 322 .B mt_blkno
 323 which contains the block number of the current tape position.
 324 .TP
 325 .B f
 326 return the content of the structure member
 327 .B mt_flags
 328 which contains MTF_ flags from the driver.
 329 .TP
 330 .B b
 331 return the content of the structure member
 332 .B mt_bf
 333 which contains the optimum blocking factor.
 334 .RE
 335 .PP
 336 Any other command causes
 337 .B rmt
 338 to exit.
 339 .SH DIAGNOSTICS
 340 All responses are of the form described above.
 341 .SH SEE ALSO
 342 .BR rcmd (3),
 343 .BR rexec (3),
 344 .I /usr/include/sys/mtio.h,
 345 .BR rdump (8),
 346 .BR rrestore (8)
 347 .SH BUGS
 348 People should be discouraged from using this for a remote file access protocol.
 349 .SH AUTHOR
 350 The
 351 .B dump/restore
 352 backup suit was ported to Linux's Second Extended File System by Remy Card
 353 <card@Linux.EU.Org>. He maintained the initial versions of
 354 .B dump
 355 (up and including 0.4b4, released in january 1997).
 356 .PP
 357 Starting with 0.4b5, the new maintainer is Stelian Pop <stelian@popies.net>.
 358 .SH AVAILABILITY
 359 The
 360 .B dump/restore
 361 backup suit is available from <http://dump.sourceforge.net>
 362 .SH HISTORY
 363 The
 364 .B rmt
 365 command appeared in 4.2BSD.