git.gag.com Git - debian/tar/blob - doc/rmt.8

   1 .\" This file is part of GNU tar. -*- nroff -*-
   2 .\" Copyright 2013 Free Software Foundation, Inc.
   3 .\"
   4 .\" GNU tar is free software; you can redistribute it and/or modify
   5 .\" it under the terms of the GNU General Public License as published by
   6 .\" the Free Software Foundation; either version 3 of the License, or
   7 .\" (at your option) any later version.
   8 .\"
   9 .\" GNU tar is distributed in the hope that it will be useful,
  10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 .\" GNU General Public License for more details.
  13 .\"
  14 .\" You should have received a copy of the GNU General Public License
  15 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16 .TH RMT 1 "January 27, 2014" "RMT" "GNU TAR Manual"
  17 .SH NAME
  18 rmt \- remote magnetic tape server
  19 .SH SYNOPSIS
  20 .B rmt
  21 .SH DESCRIPTION
  22 .B Rmt
  23 provides remote access to files and devices for
  24 .BR tar (1),
  25 .BR cpio (1),
  26 and similar backup utilities.  It is normally called by running
  27 .BR rsh (1)
  28 or
  29 .BR ssh (1)
  30 to the remote machine, optionally using a different
  31 login name if one is supplied.
  32 .PP
  33 The calling program communicates with
  34 .B rmt
  35 by sending requests on its standard input and reading replies from the
  36 standard output.  A request consists of a request letter followed by
  37 an argument (if required) and a newline character.  Additional data,
  38 if any, are sent after the newline.  On success,
  39 .B rmt
  40 returns
  41 .PP
  42 .in +4
  43 .BI A number \en
  44 .PP
  45 where \fInumber\fR is an ASCII representation of a decimal return
  46 code.  Additional data are returned after this line.  On error, the
  47 following response is returned:
  48 .PP
  49 .in +4
  50 .BI E errno \en error-message \en
  51 .PP
  52 where \fIerrno\fR is one of the system error codes, as described in
  53 .BR errno (3),
  54 and \fIerror-message\fR is a one-line human-readable description of
  55 the error, as printed by
  56 .BR perror (3).
  57 .PP
  58 Available commands and possible responses are discussed in detail in
  59 the subsequent section.
  60 .SH COMMANDS
  61 .TP
  62 .BI O device \en flags \en
  63 Opens the \fIdevice\fR with given \fIflags\fR. If a
  64 device had already been opened, it is closed before opening the new one.
  65 .sp
  66 .B Arguments
  67 .RS
  68 .TP
  69 .I device
  70 The name of the device to open.
  71 .TP
  72 .I flags
  73 Flags for
  74 .BR open (2):
  75 a decimal number, or any valid \fBO_*\fR constant from
  76 .B fcntl.h
  77 (the initial \fBO_\fR may be omitted), or a bitwise or (using \fB|\fR)
  78 of any number of these, e.g.:
  79 .in +4
  80 .EX
  81 576
  82 64|512
  83 CREAT|TRUNC
  84 .EE
  85 .RS
  86 In addition, a combined form is also allowed, i.e. a decimal mode followed
  87 by its symbolic representation.  In this case the symbolic representation
  88 is given preference.
  89 .RE
  90 .sp
  91 .B Reply
  92 .RS
  93 .B A0\en
  94 on success.
  95 .RE
  96 .sp
  97 .B Extensions
  98 .RS
  99 BSD version allows only decimal number as \fIflags\fR.
 100 .RE 1
 101 .TP
 102 \fBC\fR[\fIdevice\fR]\fB\en\fR
 103 Close the currently open device.
 104 .RS
 105 .TP
 106 .B Arguments
 107 .br
 108 Any arguments are silently ignored.
 109 .TP
 110 .B Reply
 111 .br
 112 .B A0\en
 113 on success.
 114 .RE
 115 .TP
 116 .BI L whence \en offset \en
 117 .RS
 118 Performs an
 119 .BR lseek (2)
 120 on the currently open device with the specified
 121 parameters.
 122 .TP
 123 .B Arguments
 124 .RS
 125 .TP
 126 .I whence
 127 Where to measure offset from. Valid values are:
 128 .sp
 129 .nf
 130 .ta 1n 20n
 131         0, SET, SEEK_SET        seek from the file beginning
 132         1, CUR, SEEK_CUR        seek from the current location
 133         2, END, SEEK_END        seek from the file end
 134 .fi
 135 .RE
 136 .TP
 137 .B Reply
 138 .br
 139 .BI A offset \en
 140 on success. The \fIoffset\fR is the new offset in file.
 141 .TP
 142 .B Extensions
 143 BSD version allows only 0,1,2 as \fIwhence\fR.
 144 .RE
 145 .TP
 146 .BI R count \en
 147 .br
 148 Read \fIcount\fR bytes of data from the current device.
 149 .RS
 150 .TP
 151 .B Arguments
 152 .RS
 153 .TP
 154 .I count
 155 number of bytes to read.
 156 .RE
 157 .TP
 158 .B Reply
 159 .br
 160 On success:
 161 .sp
 162 .in +4
 163 .BI A rdcount \en
 164 .in
 165 .sp
 166 followed by \fIrdcount\fR bytes of data read from the device.
 167 .RE
 168 .TP
 169 .BI W count \en
 170 Writes data onto the current device.  The command is followed by
 171 \fIcount\fR bytes of input data.
 172 .RS
 173 .TP
 174 .B Arguments
 175 .RS
 176 .TP
 177 .I count
 178 Number of bytes to write.
 179 .RE
 180 .TP
 181 .B Reply
 182 .br
 183 On success: \fBA\fIwrcount\fB\en\fR, where \fIwrcount\fR is the number of
 184 bytes actually written.
 185 .RE
 186 .TP
 187 .BI I opcode \en count \en
 188 Perform a
 189 .B MTIOCOP
 190 .BR ioctl (2)
 191 command with the specified paramedters.
 192 .RS
 193 .TP
 194 .B Arguments
 195 .RS
 196 .TP
 197 .I opcode
 198 .B MTIOCOP
 199 operation code.
 200 .TP
 201 .I count
 202 mt_count.
 203 .RE
 204 .TP
 205 .B Reply
 206 .br
 207 On success: \fBA0\en\fR.
 208 .RE
 209 .TP
 210 .B S\en
 211 Returns the status of the currently open device, as obtained from a
 212 .B MTIOCGET
 213 .BR ioctl (2)
 214 call.
 215 .RS
 216 .TP
 217 .B Arguments
 218 .br
 219 None
 220 .TP
 221 .B Reply
 222 .br
 223 On success: \fBA\fIcount\fB\en\fR followed by \fIcount\fR bytes of
 224 data.
 225 .RE
 226 .SH "SEE ALSO"
 227 .BR tar (1).
 228 .SH BUGS
 229 Using this utility as a general-purpose remote file access tool is
 230 discouraged.
 231 .SH "BUG REPORTS"
 232 Report bugs to <bug\-tar@gnu.org>.
 233 .SH HISTORY
 234 The
 235 .B rmt
 236 command appeared in 4.2BSD.  The GNU
 237 .BR rmt
 238 is written from scratch, using the BSD specification.
 239 .SH COPYRIGHT
 240 Copyright \(co 2013 Free Software Foundation, Inc.
 241 .br
 242 .na
 243 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
 244 .br
 245 .ad
 246 This is free software: you are free to change and redistribute it.
 247 There is NO WARRANTY, to the extent permitted by law.
 248 .\" Local variables:
 249 .\" eval: (add-hook 'write-file-hooks 'time-stamp)
 250 .\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
 251 .\" time-stamp-format: "%:B %:d, %:y"
 252 .\" time-stamp-end: "\""
 253 .\" time-stamp-line-limit: 20
 254 .\" end: