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