]>
Commit | Line | Data |
---|---|---|
1227625a SP |
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. | |
e1abc9ce | 12 | .\" 3. Neither the name of the University nor the names of its contributors |
1227625a SP |
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 | .\" | |
e1abc9ce | 28 | .\" $Id: rmt.8.in,v 1.10 2003/03/30 15:40:40 stelian Exp $ |
1227625a | 29 | .\" |
153f9a83 SP |
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 | |
d24dc8af | 37 | is a program used by the remote |
153f9a83 SP |
38 | .BR dump (8), |
39 | .BR restore (8) | |
d24dc8af | 40 | or |
153f9a83 | 41 | .BR tar (1) |
d24dc8af | 42 | programs in manipulating a magnetic tape drive through an interprocess |
1227625a | 43 | communication connection. |
153f9a83 | 44 | .B Rmt |
1227625a | 45 | is normally started up with an |
153f9a83 | 46 | .BR rexec (3) |
1227625a | 47 | or |
153f9a83 | 48 | .BR rcmd (3) |
1227625a | 49 | call. |
153f9a83 | 50 | .PP |
1227625a | 51 | The |
153f9a83 | 52 | .B rmt |
d24dc8af | 53 | program accepts requests specific to the manipulation of magnetic tapes, |
153f9a83 SP |
54 | performs the commands, then responds with a status indication. All responses |
55 | are in | |
56 | .B ASCII | |
d24dc8af | 57 | and in one of the following two forms. |
153f9a83 | 58 | .PP |
1227625a | 59 | Successful commands have responses of: |
153f9a83 SP |
60 | .RS |
61 | .B A\fInumber\fR\en | |
62 | .RE | |
63 | .PP | |
d24dc8af | 64 | where |
153f9a83 | 65 | .I number |
1227625a | 66 | is an |
153f9a83 | 67 | .B ASCII |
1227625a | 68 | representation of a decimal number. |
153f9a83 | 69 | .PP |
1227625a | 70 | Unsuccessful commands are responded to with: |
153f9a83 SP |
71 | .RS |
72 | .B E\fIerror-number\fR\en\fIerror-message\fR\en | |
73 | .RE | |
74 | .PP | |
75 | where | |
76 | .I error-number | |
d24dc8af | 77 | is one of the possible error numbers described in |
153f9a83 | 78 | .BR intro (2) |
1227625a | 79 | and |
153f9a83 | 80 | .I error-message |
d24dc8af | 81 | is the corresponding error string as printed from a call to |
153f9a83 SP |
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 | |
1227625a | 89 | Open the specified |
153f9a83 | 90 | .I device |
1227625a | 91 | using the indicated |
153f9a83 SP |
92 | .IR mode . |
93 | .I Device | |
1227625a | 94 | is a full pathname and |
153f9a83 | 95 | .I mode |
1227625a | 96 | is an |
153f9a83 | 97 | .B ASCII |
d24dc8af | 98 | representation of a decimal number suitable for passing to |
153f9a83 SP |
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 | |
1227625a | 104 | Close the currently open device. The |
153f9a83 | 105 | .I device |
1227625a | 106 | specified is ignored. |
153f9a83 SP |
107 | .TP |
108 | .B L\fIwhence\fR\en\fIoffset\fR\en | |
1227625a | 109 | Perform an |
153f9a83 SP |
110 | .BR lseek (2) |
111 | operation using the specified parameters. The response value is that returned | |
112 | from the | |
113 | .B lseek | |
1227625a | 114 | call. |
153f9a83 SP |
115 | .TP |
116 | .B W\fIcount\fR\en | |
1227625a | 117 | Write data onto the open device. |
153f9a83 | 118 | .B Rmt |
1227625a | 119 | reads |
153f9a83 | 120 | .I count |
d24dc8af SP |
121 | bytes from the connection, aborting if a premature end-of-file is encountered. |
122 | The response value is that returned from the | |
153f9a83 | 123 | .BR write (2) |
1227625a | 124 | call. |
153f9a83 SP |
125 | .TP |
126 | .B R\fIcount\fR\en | |
1227625a | 127 | Read |
153f9a83 SP |
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 | |
1227625a | 134 | then performs the requested |
153f9a83 | 135 | .BR read (2) |
1227625a | 136 | and responds with |
153f9a83 SP |
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 | |
1227625a | 142 | Perform a |
153f9a83 SP |
143 | .B MTIOCOP |
144 | .BR ioctl (2) | |
d24dc8af | 145 | command using the specified parameters. The parameters are interpreted as the |
153f9a83 | 146 | .B ASCII |
d24dc8af | 147 | representations of the decimal values to place in the |
153f9a83 | 148 | .B mt_op |
d24dc8af | 149 | and |
153f9a83 | 150 | .B mt_count |
d24dc8af | 151 | fields of the structure used in the |
153f9a83 | 152 | .B ioctl |
d24dc8af | 153 | call. The return value is the |
153f9a83 | 154 | .I count |
d24dc8af | 155 | parameter when the operation is successful. |
153f9a83 | 156 | .IP |
d24dc8af | 157 | By issuing the |
153f9a83 | 158 | .B I-1\en0\en |
d24dc8af | 159 | command, a client will specify that he is using the VERSION 1 protocol. |
153f9a83 | 160 | .IP |
d24dc8af | 161 | For a VERSION 0 client, the |
153f9a83 | 162 | .I operation |
d24dc8af | 163 | parameter is the platform |
153f9a83 | 164 | .B mt_op |
d24dc8af | 165 | value (could be different if the client and the |
153f9a83 SP |
166 | .B rmt |
167 | server are on two different platforms). For a VERSION 1 client, the | |
168 | .I operation | |
d24dc8af | 169 | parameter is standardized as below: |
153f9a83 SP |
170 | .RS |
171 | .TP | |
172 | .B 0 | |
173 | Issue a | |
174 | .B MTWEOF | |
175 | command (write | |
176 | .I count | |
d24dc8af | 177 | end-of-file records). |
153f9a83 SP |
178 | .TP |
179 | .B 1 | |
180 | Issue a | |
181 | .B MTFSF | |
182 | command (forward space over | |
183 | .I count | |
d24dc8af | 184 | file marks). |
153f9a83 SP |
185 | .TP |
186 | .B 2 | |
187 | Issue a | |
188 | .B MTBSF | |
189 | command (backward space over | |
190 | .I count | |
d24dc8af | 191 | file marks). |
153f9a83 SP |
192 | .TP |
193 | .B 3 | |
194 | Issue a | |
195 | .B MTFSR | |
196 | command (forward space | |
197 | .I count | |
d24dc8af | 198 | inter-record gaps). |
153f9a83 SP |
199 | .TP |
200 | .B 4 | |
201 | Issue a | |
202 | .B MTBSR | |
203 | command (backward space | |
204 | .I count | |
d24dc8af | 205 | inter-record gaps). |
153f9a83 SP |
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 | |
d24dc8af | 224 | Perform an extended |
153f9a83 SP |
225 | .B MTIOCOP |
226 | .BR ioctl (2) | |
227 | command using the specified parameters. The parameters are interpreted as the | |
228 | .B ASCII | |
d24dc8af | 229 | representations of the decimal values to place in the |
153f9a83 | 230 | .B mt_op |
1227625a | 231 | and |
153f9a83 | 232 | .B mt_count |
1227625a | 233 | fields of the structure used in the |
153f9a83 | 234 | .B ioctl |
1227625a | 235 | call. The return value is the |
153f9a83 SP |
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 | |
d24dc8af SP |
288 | operation was successful, the numerical value of the structure member is |
289 | returned in decimal. The following sub commands are supported: | |
153f9a83 SP |
290 | .RS |
291 | .TP | |
292 | .B T | |
d24dc8af | 293 | return the content of the structure member |
153f9a83 | 294 | .B mt_type |
d24dc8af | 295 | which contains the type of the magnetic tape device. |
153f9a83 SP |
296 | .TP |
297 | .B D | |
d24dc8af | 298 | return the content of the structure member |
153f9a83 | 299 | .B mt_dsreg |
d24dc8af | 300 | which contains the "drive status register". |
153f9a83 SP |
301 | .TP |
302 | .B E | |
d24dc8af | 303 | return the content of the structure member |
153f9a83 | 304 | .B mt_erreg |
d24dc8af SP |
305 | which contains the "error register". This structure member must be retrieved |
306 | first because it is cleared after each | |
153f9a83 | 307 | .B MTIOCGET |
d24dc8af | 308 | ioctl call. |
153f9a83 SP |
309 | .TP |
310 | .B R | |
d24dc8af | 311 | return the content of the structure member |
153f9a83 | 312 | .B mt_resid |
d24dc8af | 313 | which contains the residual count of the last I/O. |
153f9a83 SP |
314 | .TP |
315 | .B F | |
d24dc8af | 316 | return the content of the structure member |
153f9a83 | 317 | .B mt_fileno |
d24dc8af | 318 | which contains the file number of the current tape position. |
153f9a83 SP |
319 | .TP |
320 | .B B | |
d24dc8af | 321 | return the content of the structure member |
153f9a83 | 322 | .B mt_blkno |
d24dc8af | 323 | which contains the block number of the current tape position. |
153f9a83 SP |
324 | .TP |
325 | .B f | |
d24dc8af | 326 | return the content of the structure member |
153f9a83 | 327 | .B mt_flags |
d24dc8af | 328 | which contains MTF_ flags from the driver. |
153f9a83 SP |
329 | .TP |
330 | .B b | |
d24dc8af | 331 | return the content of the structure member |
153f9a83 | 332 | .B mt_bf |
d24dc8af | 333 | which contains the optimum blocking factor. |
153f9a83 SP |
334 | .RE |
335 | .PP | |
1227625a | 336 | Any other command causes |
153f9a83 | 337 | .B rmt |
1227625a | 338 | to exit. |
153f9a83 | 339 | .SH DIAGNOSTICS |
1227625a | 340 | All responses are of the form described above. |
153f9a83 SP |
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 | |
8d4197bb | 350 | The |
153f9a83 SP |
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 | |
8d4197bb | 359 | The |
153f9a83 SP |
360 | .B dump/restore |
361 | backup suit is available from <http://dump.sourceforge.net> | |
362 | .SH HISTORY | |
1227625a | 363 | The |
153f9a83 SP |
364 | .B rmt |
365 | command appeared in 4.2BSD. |