rmt/rmt.8

   1 .\"     $NetBSD: rmt.8,v 1.6 1997/10/17 13:03:15 lukem Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)rmt.8       8.3 (Berkeley) 6/1/94
  35 .\"
  36 .Dd June 1, 1994
  37 .Dt RMT 8
  38 .Os BSD 4.2
  39 .Sh NAME
  40 .Nm rmt
  41 .Nd remote magtape protocol module
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Sh DESCRIPTION
  45 .Nm
  46 is a program used by the remote dump and restore programs
  47 in manipulating a magnetic tape drive through an interprocess
  48 communication connection.
  49 .Nm
  50 is normally started up with an
  51 .Xr rexec 3
  52 or
  53 .Xr rcmd 3
  54 call.
  55 .Pp
  56 The
  57 .Nm
  58 program accepts requests specific to the manipulation of
  59 magnetic tapes, performs the commands, then responds with
  60 a status indication.  All responses are in
  61 .Tn ASCII
  62 and in
  63 one of two forms.
  64 Successful commands have responses of:
  65 .Bd -filled -offset indent
  66 .Sm off
  67 .Sy A Ar number No \en
  68 .Sm on
  69 .Ed
  70 .Pp
  71 .Ar Number
  72 is an
  73 .Tn ASCII
  74 representation of a decimal number.
  75 Unsuccessful commands are responded to with:
  76 .Bd -filled -offset indent
  77 .Sm off
  78 .Xo Sy E Ar error-number
  79 .No \en Ar error-message
  80 .No \en
  81 .Xc
  82 .Sm on
  83 .Ed
  84 .Pp
  85 .Ar Error-number
  86 is one of the possible error
  87 numbers described in
  88 .Xr intro 2
  89 and
  90 .Ar error-message
  91 is the corresponding error string as printed
  92 from a call to
  93 .Xr perror 3 .
  94 The protocol is comprised of the
  95 following commands, which are sent as indicated - no spaces are supplied
  96 between the command and its arguments, or between its arguments, and
  97 .Ql \en
  98 indicates that a newline should be supplied:
  99 .Bl -tag -width Ds
 100 .Sm off
 101 .It Xo Sy \&O Ar device
 102 .No \en Ar mode No \en
 103 .Xc
 104 Open the specified
 105 .Ar device
 106 using the indicated
 107 .Ar mode .
 108 .Ar Device
 109 is a full pathname and
 110 .Ar mode
 111 is an
 112 .Tn ASCII
 113 representation of a decimal
 114 number suitable for passing to
 115 .Xr open 2 .
 116 If a device had already been opened, it is
 117 closed before a new open is performed.
 118 .It Xo Sy C Ar device No \en
 119 .Xc
 120 Close the currently open device.  The
 121 .Ar device
 122 specified is ignored.
 123 .It Xo Sy L
 124 .Ar offset No \en
 125 .Ar whence No \en
 126 .Xc
 127 .Sm on
 128 Perform an
 129 .Xr lseek 2
 130 operation using the specified parameters.
 131 The response value is that returned from the
 132 .Xr lseek
 133 call.
 134 .Sm off
 135 .It Sy W Ar count No \en
 136 .Sm on
 137 Write data onto the open device.
 138 .Nm
 139 reads
 140 .Ar count
 141 bytes from the connection, aborting if
 142 a premature end-of-file is encountered.
 143 The response value is that returned from
 144 the
 145 .Xr write 2
 146 call.
 147 .Sm off
 148 .It Sy R Ar count No \en
 149 .Sm on
 150 Read
 151 .Ar count
 152 bytes of data from the open device.
 153 If
 154 .Ar count
 155 exceeds the size of the data buffer (10 kilobytes), it is
 156 truncated to the data buffer size.
 157 .Nm
 158 then performs the requested
 159 .Xr read 2
 160 and responds with
 161 .Sm off
 162 .Sy A Ar count-read No \en
 163 .Sm on
 164 if the read was
 165 successful; otherwise an error in the
 166 standard format is returned.  If the read
 167 was successful, the data read is then sent.
 168 .Sm off
 169 .It Xo Sy I Ar operation
 170 .No \en Ar count No \en
 171 .Xc
 172 .Sm on
 173 Perform a
 174 .Dv MTIOCOP
 175 .Xr ioctl 2
 176 command using the specified parameters.
 177 The parameters are interpreted as the
 178 .Tn ASCII
 179 representations of the decimal values
 180 to place in the
 181 .Ar mt_op
 182 and
 183 .Ar mt_count
 184 fields of the structure used in the
 185 .Xr ioctl
 186 call.  The return value is the
 187 .Ar count
 188 parameter when the operation is successful.
 189 .ne 1i
 190 .It Sy S
 191 Return the status of the open device, as
 192 obtained with a
 193 .Dv MTIOCGET
 194 .Xr ioctl
 195 call.  If the operation was successful,
 196 an ``ack'' is sent with the size of the
 197 status buffer, then the status buffer is
 198 sent (in binary).
 199 .El
 200 .Sm on
 201 .Pp
 202 Any other command causes
 203 .Nm
 204 to exit.
 205 .Sh DIAGNOSTICS
 206 All responses are of the form described above.
 207 .Sh SEE ALSO
 208 .Xr rcmd 3 ,
 209 .Xr rexec 3 ,
 210 .Xr mtio 4 ,
 211 .Xr rdump 8 ,
 212 .Xr rrestore 8
 213 .Sh BUGS
 214 People should be discouraged from using this for a remote
 215 file access protocol.
 216 .Sh HISTORY
 217 The
 218 .Nm
 219 command appeared in
 220 .Bx 4.2 .