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