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