Print this page
10529 Convert mtio(7I) to mandoc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/mtio.7i
+++ new/usr/src/man/man7i/mtio.7i
1 -'\" te
2 1 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 -.TH MTIO 7I "April 9, 2016"
7 -.SH NAME
8 -mtio \- general magnetic tape interface
9 -.SH SYNOPSIS
10 -.LP
11 -.nf
12 -#include <sys/types.h>
13 -#include <sys/ioctl.h>
14 -#include <sys/mtio.h>
15 -.fi
16 -
17 -.SH DESCRIPTION
18 -.LP
2 +.\" Copyright 2018, Joyent, Inc.
3 +.\" The contents of this file are subject to the terms of the
4 +.\" Common Development and Distribution License (the "License").
5 +.\" You may not use this file except in compliance with the License.
6 +.\"
7 +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8 +.\" or http://www.opensolaris.org/os/licensing.
9 +.\" See the License for the specific language governing permissions
10 +.\" and limitations under the License.
11 +.\"
12 +.\" When distributing Covered Code, include this CDDL HEADER in each
13 +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
14 +.\" If applicable, add the following below this CDDL HEADER, with the
15 +.\" fields enclosed by brackets "[]" replaced with your own identifying
16 +.\" information: Portions Copyright [yyyy] [name of copyright owner]
17 +.Dd August 31, 2018
18 +.Dt MTIO 7I
19 +.Os
20 +.Sh NAME
21 +.Nm mtio
22 +.Nd general magnetic tape interface
23 +.Sh SYNOPSIS
24 +.In sys/types.h
25 +.In sys/ioctl.h
26 +.In sys/mtio.h
27 +.Sh DESCRIPTION
19 28 1/2", 1/4", 4mm, and 8mm magnetic tape drives all share the same general
20 29 character device interface.
21 -.sp
22 -.LP
30 +.Pp
23 31 There are two types of tape records: data records and end-of-file (EOF)
24 -records. S\fBEOF\fR records are also known as tape marks and file marks. A
25 -record is separated by interrecord (or tape) gaps on a tape.
26 -.sp
27 -.LP
28 -End-of-recorded-media (EOM) is indicated by two \fBEOF\fR marks on 1/2" tape;
29 -by one \fBEOF\fR mark on 1/4", 4mm, and 8mm cartridge tapes.
30 -.SS "1/2" Reel Tape"
31 -.LP
32 -Data bytes are recorded in parallel onto the 9-track tape. Since it is a
33 -variable-length tape device, the number of bytes in a physical record may
34 -vary.
35 -.sp
36 -.LP
37 -The recording formats available (check specific tape drive) are 800 \fBBPI,\fR
38 -1600 \fBBPI,\fR 6250 \fBBPI,\fR and data compression. Actual storage capacity
39 -is a function of the recording format and the length of the tape reel. For
40 -example, using a 2400 foot tape, 20 Mbyte can be stored using 800 \fBBPI,\fR 40
41 -Mbyte using 1600 \fBBPI,\fR 140 Mbyte using 6250 \fBBPI,\fR or up to 700 Mbyte
42 -using data compression.
43 -.SS "1/4" Cartridge Tape"
44 -.LP
45 -Data is recorded serially onto 1/4" cartridge tape. The number of bytes per
46 -record is determined by the physical record size of the device. The I/O request
47 -size must be a multiple of the physical record size of the device. For
48 -\fBQIC-11,\fR \fBQIC-24,\fR and \fBQIC-150\fR tape drives, the block size is
49 -512 bytes.
50 -.sp
51 -.LP
52 -The records are recorded on tracks in a serpentine motion. As one track is
32 +records.
33 +.Sy EOF
34 +records are also known as tape marks and file marks.
35 +A record is separated by interrecord (or tape) gaps on a tape.
36 +.Pp
37 +End-of-recorded-media (EOM) is indicated by two
38 +.Sy EOF
39 +marks on 1/2\(dq tape; by one
40 +.Sy EOF
41 +mark on 1/4\(dq, 4mm, and 8mm cartridge tapes.
42 +.Ss "1/2\(dq Reel Tape"
43 +Data bytes are recorded in parallel onto the 9-track tape.
44 +Since it is a
45 +variable-length tape device, the number of bytes in a physical record may vary.
46 +.Pp
47 +The recording formats available (check specific tape drive) are 800
48 +.Sy BPI ,
49 +1600
50 +.Sy BPI ,
51 +6250
52 +.Sy BPI ,
53 +and data compression.
54 +Actual storage capacity is a function of the recording format and the length of the tape reel.
55 +For example, using a 2400 foot tape, 20 Mbyte can be stored using 800
56 +.Sy BPI ,
57 +40 Mbyte using 1600
58 +.Sy BPI ,
59 +140 Mbyte using 6250
60 +.Sy BPI ,
61 +or up to 700 Mbyte using data compression.
62 +.Ss "1/4\(dq Cartridge Tape"
63 +Data is recorded serially onto 1/4\(dq cartridge tape.
64 +The number of bytes per
65 +record is determined by the physical record size of the device.
66 +The I/O request
67 +size must be a multiple of the physical record size of the device.
68 +For
69 +.Sy QIC-11 ,
70 +.Sy QIC-24 ,
71 +and
72 +.Sy QIC-150
73 +tape drives, the block size is 512 bytes.
74 +.Pp
75 +The records are recorded on tracks in a serpentine motion.
76 +As one track is
53 77 completed, the drive switches to the next and begins writing in the opposite
54 -direction, eliminating the wasted motion of rewinding. Each file, including the
55 -last, ends with one file mark.
56 -.sp
57 -.LP
78 +direction, eliminating the wasted motion of rewinding.
79 +Each file, including the last, ends with one file mark.
80 +.Pp
58 81 Storage capacity is based on the number of tracks the drive is capable of
59 -recording. For example, 4-track drives can only record 20 Mbyte of data on a
82 +recording.
83 +For example, 4-track drives can only record 20 Mbyte of data on a
60 84 450 foot tape; 9-track drives can record up to 45 Mbyte of data on a tape of
61 -the same length. \fBQIC-11\fR is the only tape format available for 4-track
62 -tape drives. In contrast, 9-track tape drives can use either \fBQIC-24\fR or
63 -\fBQIC-11.\fR Storage capacity is not appreciably affected by using either
64 -format. \fBQIC-24\fR is preferable to \fBQIC-11\fR because it records a
85 +the same length.
86 +.Sy QIC-11
87 +is the only tape format available for 4-track
88 +tape drives.
89 +In contrast, 9-track tape drives can use either
90 +.Sy QIC-24
91 +or
92 +.Sy QIC-11 .
93 +Storage capacity is not appreciably affected by using either format.
94 +.Sy QIC-24
95 +is preferable to
96 +.Sy QIC-11
97 +because it records a
65 98 reference signal to mark the position of the first track on the tape, and each
66 99 block has a unique block number.
67 -.sp
68 -.LP
69 -The \fBQIC-150\fR tape drives require \fBDC-6150\fR (or equivalent) tape
70 -cartridges for writing. However, they can read other tape cartridges in
71 -\fBQIC-11,\fR \fBQIC-24,\fR or \fBQIC-120\fR tape formats.
72 -.SS "8mm Cartridge Tape"
73 -.LP
74 -Data is recorded serially onto 8mm helical scan cartridge tape. Since it is a
75 -variable-length tape device, the number of bytes in a physical record may
76 -vary. The recording formats available (check specific tape drive) are standard
100 +.Pp
101 +The
102 +.Sy QIC-150
103 +tape drives require
104 +.Sy DC-6150
105 +(or equivalent) tape cartridges for writing.
106 +However, they can read other tape cartridges in
107 +.Sy QIC-11 ,
108 +.Sy QIC-24 ,
109 +or
110 +.Sy QIC-120
111 +tape formats.
112 +.Ss "8mm Cartridge Tape"
113 +Data is recorded serially onto 8mm helical scan cartridge tape.
114 +Since it is a
115 +variable-length tape device, the number of bytes in a physical record may
116 +vary.
117 +The recording formats available (check specific tape drive) are standard
77 118 2Gbyte, 5Gbyte, and compressed format.
78 -.SS "4mm DAT Tape"
79 -.LP
119 +.Ss "4mm DAT Tape"
80 120 Data is recorded either in Digital Data Storage (DDS) tape format or in Digital
81 -Data Storage, Data Compressed (DDS-DC) tape format. Since it is a
82 -variable-length tape device, the number of bytes in a physical record may
83 -vary. The recording formats available are standard 2Gbyte and compressed
84 -format.
85 -.SS "Persistent Error Handling"
86 -.LP
121 +Data Storage, Data Compressed (DDS-DC) tape format.
122 +Since it is a
123 +variable-length tape device, the number of bytes in a physical record may vary.
124 +The recording formats available are standard 2Gbyte and compressed format.
125 +.Ss "Persistent Error Handling"
87 126 Persistent error handling is a modification of the current error handling
88 -behaviors, BSD and SVR4. With persistent error handling enabled, all tape
127 +behaviors, BSD and SVR4.
128 +With persistent error handling enabled, all tape
89 129 operations after an error or exception will return immediately with an error.
90 130 Persistent error handling can be most useful with asynchronous tape operations
91 -that use the \fBaioread\fR(3C) and \fBaiowrite\fR(3C) functions.
92 -.sp
93 -.LP
94 -To enable persistent error handling, the ioctl \fBMTIOCPERSISTENT\fR must be
95 -issued. If this ioctl succeeds, then persistent error handling is enabled and
96 -changes the current error behavior. This ioctl will fail if the device driver
131 +that use the
132 +.Xr aioread 3C
133 +and
134 +.Xr aiowrite 3C
135 +functions.
136 +.Pp
137 +To enable persistent error handling, the ioctl
138 +.Dv MTIOCPERSISTENT
139 +must be issued.
140 +If this ioctl succeeds, then persistent error handling is enabled and
141 +changes the current error behavior.
142 +This ioctl will fail if the device driver
97 143 does not support persistent error handling.
98 -.sp
99 -.LP
144 +.Pp
100 145 With persistent error handling enabled, all tape operations after an exception
101 146 or error will return with the same error as the first command that failed; the
102 -operations will not be executed. An exception is some event that might stop
103 -normal tape operations, such as an End Of File (EOF) mark or an End Of Tape
104 -(EOT) mark. An example of an error is a media error. The \fBMTIOCLRERR\fR ioctl
105 -must be issued to allow normal tape operations to continue and to clear the
106 -error.
107 -.sp
108 -.LP
147 +operations will not be executed.
148 +An exception is some event that might stop
149 +normal tape operations, such as an End Of File (EOF) mark or an End Of Tape
150 +(EOT) mark.
151 +An example of an error is a media error.
152 +The
153 +.Dv MTIOCLRERR
154 +ioctl must be issued to allow normal tape operations to continue and to clear
155 +the error.
156 +.Pp
109 157 Disabling persistent error handling returns the error behavior to normal SVR4
110 158 error handling, and will not occur until all outstanding operations are
111 -completed. Applications should wait for all outstanding operations to complete
112 -before disabling persistent error handling. Closing the device will also
159 +completed.
160 +Applications should wait for all outstanding operations to complete
161 +before disabling persistent error handling.
162 +Closing the device will also
113 163 disable persistent error handling and clear any errors or exceptions.
114 -.sp
115 -.LP
116 -The \fBRead Operation\fR and \fBWrite Operation\fR subsections contain more
117 -pertinent information reguarding persistent error handling.
118 -.SS "Read Operation"
119 -.LP
120 -The \fBread\fR(2) function reads the next record on the tape. The record size
121 -is passed back as the number of bytes read, provided it is not greater than the
122 -number requested. When a tape mark or end of data is read, a zero byte count is
164 +.Pp
165 +The
166 +.Sx Read Operation
167 +and
168 +.Sx Write Operation
169 +subsections contain more pertinent information reguarding persistent error handling.
170 +.Ss "Read Operation"
171 +The
172 +.Xr read 2
173 +function reads the next record on the tape.
174 +The record size is passed back as the number of bytes read, provided it is not
175 +greater than the number requested.
176 +When a tape mark or end of data is read, a zero byte count is
123 177 returned; all successive reads after the zero read will return an error and
124 -\fBerrno\fR will be set to \fBEIO\fR. To move to the next file, an \fBMTFSF\fR
125 -ioctl can be issued before or after the read causing the error. This error
126 -handling behavior is different from the older \fBBSD\fR behavior, where another
127 -read will fetch the first record of the next tape file. If the \fBBSD\fR
128 -behavior is required, device names containing the letter \fBb\fR (for \fBBSD\fR
129 -behavior) in the final component should be used. If persistent error handling
178 +.Va errno
179 +will be set to
180 +.Er EIO .
181 +To move to the next file, an
182 +.Dv MTFSF
183 +ioctl can be issued before or after the read causing the error.
184 +This error
185 +handling behavior is different from the older
186 +.Sy BSD
187 +behavior, where another read will fetch the first record of the next tape file.
188 +If the
189 +.Sy BSD
190 +behavior is required, device names containing the letter
191 +.Ql b
192 +(for
193 +.Sy BSD
194 +behavior) in the final component should be used.
195 +If persistent error handling
130 196 was enabled with either the BSD or SVR4 tape device behavior, all operations
131 -after this read error will return \fBEIO\fR errors until the \fBMTIOCLRERR\fR
132 -ioctl is issued. An \fBMTFSF\fR ioctl can then he issued.
133 -.sp
134 -.LP
197 +after this read error will return
198 +.Er EIO
199 +errors until the
200 +.Dv MTIOCLRERR
201 +ioctl is issued.
202 +An
203 +.Dv MTFSF
204 +ioctl can then he issued.
205 +.Pp
135 206 Two successful successive reads that both return zero byte counts indicate
136 -\fBEOM\fR on the tape. No further reading should be performed past the
137 -\fBEOM.\fR
138 -.sp
139 -.LP
207 +.Sy EOM
208 +on the tape.
209 +No further reading should be performed past the
210 +.Sy EOM .
211 +.Pp
140 212 Fixed-length I/O tape devices require the number of bytes read to be a multiple
141 -of the physical record size. For example, 1/4" cartridge tape devices only read
142 -multiples of 512 bytes. If the blocking factor is greater than 64,512 bytes
213 +of the physical record size.
214 +For example, 1/4\(dq cartridge tape devices only read
215 +multiples of 512 bytes.
216 +If the blocking factor is greater than 64,512 bytes
143 217 (minphys limit), fixed-length I/O tape devices read multiple records.
144 -.sp
145 -.LP
218 +.Pp
146 219 Most tape devices which support variable-length I/O operations may read a range
147 -of 1 to 65,535 bytes. If the record size exceeds 65,535 bytes, the driver reads
148 -multiple records to satisfy the request. These multiple records are limited to
149 -65,534 bytes. Newer variable-length tape drivers may relax the above limitation
150 -and allow applications to read record sizes larger than 65,534. Refer to the
220 +of 1 to 65,535 bytes.
221 +If the record size exceeds 65,535 bytes, the driver reads
222 +multiple records to satisfy the request.
223 +These multiple records are limited to
224 +65,534 bytes.
225 +Newer variable-length tape drivers may relax the above limitation
226 +and allow applications to read record sizes larger than 65,534.
227 +Refer to the
151 228 specific tape driver man page for details.
152 -.sp
153 -.LP
154 -Reading past logical \fBEOT\fR is transparent to the user. A read operation
229 +.Pp
230 +Reading past logical
231 +.Sy EOT
232 +is transparent to the user.
233 +A read operation
155 234 should never hit physical EOT.
156 -.sp
157 -.LP
235 +.Pp
158 236 Read requests that are lesser than a physical tape record are not allowed.
159 237 Appropriate error is returned.
160 -.SS "Write Operation"
161 -.LP
162 -The \fBwrite\fR(2) function writes the next record on the tape. The record has
238 +.Ss "Write Operation"
239 +The
240 +.Xr write 2
241 +function writes the next record on the tape.
242 +The record has
163 243 the same length as the given buffer.
164 -.sp
165 -.LP
244 +.Pp
166 245 Writing is allowed on 1/4" tape at either the beginning of tape or after the
167 -last written file on the tape. With the Exabyte 8200, data may be appended only
246 +last written file on the tape.
247 +With the Exabyte 8200, data may be appended only
168 248 at the beginning of tape, before a filemark, or after the last written file on
169 249 the tape.
170 -.sp
171 -.LP
172 -Writing is not so restricted on 1/2", 4mm, and the other 8mm cartridge tape
173 -drives. Care should be used when appending files onto 1/2" reel tape devices,
174 -since an extra file mark is appended after the last file to mark the \fBEOM.\fR
175 -This extra file mark must be overwritten to prevent the creation of a null
176 -file. To facilitate write append operations, a space to the \fBEOM\fR ioctl is
177 -provided. Care should be taken when overwriting records; the erase head is just
250 +.Pp
251 +Writing is not so restricted on 1/2\(dq, 4mm, and the other 8mm cartridge tape
252 +drives.
253 +Care should be used when appending files onto 1/2\(dq reel tape devices,
254 +since an extra file mark is appended after the last file to mark the
255 +.Sy EOM .
256 +This extra file mark must be overwritten to prevent the creation of a null file.
257 +To facilitate write append operations, a space to the
258 +.Sy EOM
259 +ioctl is provided.
260 +Care should be taken when overwriting records; the erase head is just
178 261 forward of the write head and any following records will also be erased.
179 -.sp
180 -.LP
262 +.Pp
181 263 Fixed-length I/O tape devices require the number of bytes written to be a
182 -multiple of the physical record size. For example, 1/4" cartridge tape devices
264 +multiple of the physical record size.
265 +For example, 1/4\(dq cartridge tape devices
183 266 only write multiples of 512 bytes.
184 -.sp
185 -.LP
267 +.Pp
186 268 Fixed-length I/O tape devices write multiple records if the blocking factor is
187 -greater than 64,512 bytes (minphys limit). These multiple writes are limited to
188 -64,512 bytes. For example, if a write request is issued for 65,536 bytes using
189 -a 1/4" cartridge tape, two writes are issued; the first for 64,512 bytes and
269 +greater than 64,512 bytes (minphys limit).
270 +These multiple writes are limited to
271 +64,512 bytes.
272 +For example, if a write request is issued for 65,536 bytes using
273 +a 1/4\(dq cartridge tape, two writes are issued; the first for 64,512 bytes and
190 274 the second for 1024 bytes.
191 -.sp
192 -.LP
275 +.Pp
193 276 Most tape devices which support variable-length I/O operations may write a
194 -range of 1 to 65,535 bytes. If the record size exceeds 65,535 bytes, the driver
195 -writes multiple records to satisfy the request. These multiple records are
196 -limited to 65,534 bytes. As an example, if a write request for 65,540 bytes is
277 +range of 1 to 65,535 bytes.
278 +If the record size exceeds 65,535 bytes, the driver
279 +writes multiple records to satisfy the request.
280 +These multiple records are
281 +limited to 65,534 bytes.
282 +As an example, if a write request for 65,540 bytes is
197 283 issued, two records are written; one for 65,534 bytes followed by another
198 -record for 6 bytes. Newer variable-length tape drivers may relax the above
199 -limitation and allow applications to write record sizes larger than 65,534.
200 -Refer to the specific tape driver man page for details.
201 -.sp
202 -.LP
203 -When logical \fBEOT\fR is encountered during a write, that write operation
284 +record for 6 bytes.
285 +Newer variable-length tape drivers may relax the above
286 +limitation and allow applications to write record sizes larger than 65,534.
287 +effer to the specific tape driver man page for details.
288 +.Pp
289 +When logical
290 +.Sy EOT
291 +is encountered during a write, that write operation
204 292 completes and the number of bytes successfully transferred is returned (note
205 293 that a 'short write' may have occurred and not all the requested bytes would
206 -have been transferred. The actual amount of data written will depend on the
207 -type of device being used). The next write will return a zero byte count. A
208 -third write will successfully transfer some bytes (as indicated by the returned
209 -byte count, which again could be a short write); the fourth will transfer zero
210 -bytes, and so on, until the physical \fBEOT\fR is reached and all writes will
211 -fail with \fBEIO\fR.
212 -.sp
213 -.LP
214 -When logical \fBEOT\fR is encountered with persistent error handling enabled,
215 -the current write may complete or be a short write. The next write will return
216 -a zero byte count. At this point an application should act appropriately for
294 +have been transferred.
295 +The actual amount of data written will depend on the
296 +type of device being used).
297 +The next write will return a zero byte count.
298 +A third write will successfully transfer some bytes (as indicated by the
299 +returned byte count, which again could be a short write); the fourth will
300 +transfer zero bytes, and so on, until the physical
301 +.Sy EOT
302 +is reached and all writes will
303 +fail with
304 +.Er EIO .
305 +.Pp
306 +When logical
307 +.Sy EOT
308 +is encountered with persistent error handling enabled,
309 +the current write may complete or be a short write.
310 +The next write will return a zero byte count.
311 +At this point an application should act appropriately for
217 312 end of tape cleanup or issue yet another write, which will return the error
218 -\fBENOSPC\fR. After clearing the exception with \fBMTIOCLRERR\fR, the next
219 -write will succeed (possibly short), followed by another zero byte write count,
220 -and then another \fBENOSPC\fR error.
221 -.sp
222 -.LP
223 -Allowing writes after \fBLEOT\fR has been encountered enables the flushing of
224 -buffers. However, it is strongly recommended to terminate the writing and close
313 +.Er ENOSPC .
314 +After clearing the exception with
315 +.Dv MTIOCLRERR ,
316 +the next write will succeed (possibly short), followed by another zero byte
317 +write count, and then another
318 +.Er ENOSPC
319 +error.
320 +.Pp
321 +Allowing writes after
322 +.Sy EOT
323 +has been encountered enables the flushing of buffers.
324 +However, it is strongly recommended to terminate the writing and close
225 325 the file as soon as possible.
226 -.sp
227 -.LP
326 +.Pp
228 327 Seeks are ignored in tape I/O.
229 -.SS "Close Operation"
230 -.LP
328 +.Ss "Close Operation"
231 329 Magnetic tapes are rewound when closed, except when the "no-rewind" devices
232 -have been specified. The names of no-rewind device files use the letter \fBn\fR
233 -as the end of the final component. The no-rewind version of \fB/dev/rmt/0l\fR
234 -is \fB/dev/rmt/0ln\fR. In case of error for a no-rewind device, the next open
235 -rewinds the device.
236 -.sp
237 -.LP
330 +have been specified.
331 +The names of no-rewind device files use the letter
332 +.Ql n
333 +as the end of the final component.
334 +The no-rewind version of
335 +.Pa /dev/rmt/0l
336 +is
337 +.Pa /dev/rmt/0ln .
338 +In case of error for a no-rewind device, the next open rewinds the device.
339 +.Pp
238 340 If the driver was opened for reading and a no-rewind device has been specified,
239 341 the close advances the tape past the next filemark (unless the current file
240 -position is at \fBEOM),\fR leaving the tape correctly positioned to read the
241 -first record of the next file. However, if the tape is at the first record of a
242 -file it doesn't advance again to the first record of the next file. These
243 -semantics are different from the older \fBBSD\fR behavior. If \fBBSD\fR
342 +position is at
343 +.Sy EOM ) ,
344 +leaving the tape correctly positioned to read the first record of the next file.
345 +However, if the tape is at the first record of a
346 +file it doesn't advance again to the first record of the next file.
347 +These semantics are different from the older
348 +.Sy BSD
349 +behavior.
350 +If
351 +.Sy BSD
244 352 behavior is required where no implicit space operation is executed on close,
245 -the non-rewind device name containing the letter \fBb\fR (for \fBBSD\fR
353 +the non-rewind device name containing the letter
354 +.Ql b
355 +(for
356 +.Sy BSD
246 357 behavior) in the final component should be specified.
247 -.sp
248 -.LP
358 +.Pp
249 359 If data was written, a file mark is automatically written by the driver upon
250 -close. If the rewinding device was specified, the tape will be rewound after
251 -the file mark is written. If the user wrote a file mark prior to closing, then
252 -no file mark is written upon close. If a file positioning ioctl, like rewind,
360 +close.
361 +If the rewinding device was specified, the tape will be rewound after
362 +the file mark is written.
363 +If the user wrote a file mark prior to closing, then
364 +no file mark is written upon close.
365 +If a file positioning ioctl, like rewind,
253 366 is issued after writing, a file mark is written before repositioning the tape.
254 -.sp
255 -.LP
256 -All buffers are flushed on closing a tape device. Hence, it is strongly
257 -recommended that the application wait for all buffers to be flushed before
258 -closing the device. This can be done by writing a filemark via \fBMTWEOF,\fR
367 +.Pp
368 +All buffers are flushed on closing a tape device.
369 +Hence, it is strongly recommended that the application wait for all buffers to
370 +be flushed before closing the device.
371 +This can be done by writing a filemark via
372 +.Dv MTWEOF ,
259 373 even with a zero count.
260 -.sp
261 -.LP
262 -Note that for 1/2" reel tape devices, two file marks are written to mark the
263 -\fBEOM\fR before rewinding or performing a file positioning ioctl. If the user
264 -wrote a file mark before closing a 1/2" reel tape device, the driver will
374 +.Pp
375 +Note that for 1/2\(dq reel tape devices, two file marks are written to mark the
376 +.Sy EOM
377 +before rewinding or performing a file positioning ioctl.
378 +If the user
379 +wrote a file mark before closing a 1/2\(dq reel tape device, the driver will
265 380 always write a file mark before closing to insure that the end of recorded
266 -media is marked properly. If the non-rewinding device was specified, two file
381 +media is marked properly.
382 +If the non-rewinding device was specified, two file
267 383 marks are written and the tape is left positioned between the two so that the
268 -second one is overwritten on a subsequent \fBopen\fR(2) and \fBwrite\fR(2).
269 -.sp
270 -.LP
271 -If no data was written and the driver was opened for \fBWRITE-ONLY\fR access,
272 -one or two file marks are written, thus creating a null file.
273 -.sp
274 -.LP
384 +second one is overwritten on a subsequent
385 +.Xr open 2
386 +and
387 +.Xr write 2 .
388 +.Pp
389 +If no data was written and the driver was opened for
390 +.Sy WRITE-ONLY
391 +access, one or two file marks are written, thus creating a null file.
392 +.Pp
275 393 After closing the device, persistent error handling will be disabled and any
276 394 error or exception will be cleared.
277 -.SH IOCTLS
278 -.LP
279 -Not all devices support all \fBioctls\fR. The driver returns an \fBENOTTY\fR
395 +.Sh IOCTLS
396 +Not all devices support all
397 +.Sy ioctls .
398 +The driver returns an
399 +.Er ENOTTY
280 400 error on unsupported ioctls.
281 -.sp
282 -.LP
283 -The following structure definitions for magnetic tape \fBioctl \fRcommands are
284 -from \fB<sys/mtio.h>\fR\&.
285 -.sp
286 -.LP
287 -The minor device byte structure is::
288 -.sp
289 -.in +2
290 -.nf
401 +.Pp
402 +The following structure definitions for magnetic tape
403 +.Xr ioctl 2
404 +commands are from
405 +.In sys/mtio.h .
406 +.Pp
407 +The minor device byte structure is:
408 +.Bd -literal
291 409 15 7 6 5 4 3 2 1 0
292 410 ________________________________________________________________________
293 411 Unit # BSD Reserved Density Density No rewind Unit #
294 412 Bits 7-15 behavior Select Select on Close Bits 0-1
295 -.fi
296 -.in -2
297 -
298 -.sp
299 -.in +2
300 -.nf
413 +.Ed
414 +.Bd -literal
301 415 /*
302 416 * Layout of minor device byte:
303 417 */
304 -#define MTUNIT(dev) (((minor(dev) & 0xff80) >> 5) +
305 -(minor(dev) & 0x3))
418 +#define MTUNIT(dev) (((minor(dev) & 0xff80) >> 5) + (minor(dev) & 0x3))
306 419 #define MT_NOREWIND (1 <<2)
307 420 #define MT_DENSITY_MASK (3 <<3)
308 421 #define MT_DENSITY1 (0 <<3) /* Lowest density/format */
309 422 #define MT_DENSITY2 (1 <<3)
310 423 #define MT_DENSITY3 (2 <<3)
311 424 #define MT_DENSITY4 (3 <<3) /* Highest density/format */
312 425 #define MTMINOR(unit) (((unit & 0x7fc) << 5) + (unit & 0x3))
313 -#define MT_BSD (1 <<6) /* BSD behavior on close */
426 +#define MT_BSD (1 <<6) /* BSD behavior on close */
314 427
428 +/* Structure for MTIOCTOP - magnetic tape operation command */
315 429
316 -/* Structure for MTIOCTOP \(mi magnetic tape operation command */
317 -
318 -struct mtop {
430 +struct mtop {
319 431 short mt_op; /* operation */
320 432 daddr_t mt_count; /* number of operations */
321 433 };
322 -.fi
323 -.in -2
324 434
325 -.sp
326 -.in +2
327 -.nf
328 435 /* Structure for MTIOCLTOP - magnetic tape operation command */
329 436 Works exactly like MTIOCTOP except passes 64 bit mt_count values.
330 -struct mtlop {
437 +struct mtlop {
331 438 short mt_op;
332 439 short pad[3];
333 440 int64_t mt_count;
334 441 };
335 -.fi
336 -.in -2
442 +.Ed
443 +.Pp
444 +The following operations of
445 +.Dv MTIOCTOP
446 +and
447 +.Dv MTIOCLTOP
448 +ioctls are supported:
449 +.Pp
450 +.Bl -tag -width MTIOCGETERROR -compact -offset 2n
451 +.It Dv MTWEOF
452 +Write an end-of-file record
453 +.It Dv MTFSF
454 +Forward space over file mark
455 +.It Dv MTBSF
456 +Backward space over file mark (1/2", 8mm only)
457 +.It Dv MTFSR
458 +Forward space to inter-record gap
459 +.It Dv MTBSR
460 +Backward space to inter-record gap
461 +.It Dv MTREW
462 +Rewind
463 +.It Dv MTOFFL
464 +Rewind and take the drive off-line
465 +.It Dv MTNOP
466 +No operation, sets status only
467 +.It Dv MTRETEN
468 +Retension the tape (cartridge tape only)
469 +.It Dv MTERASE
470 +Erase the entire tape and rewind
471 +.It Dv MTEOM
472 +Position to EOM
473 +.It Dv MTNBSF
474 +Backward space file to beginning of file
475 +.It Dv MTSRSZ
476 +Set record size
477 +.It Dv MTGRSZ
478 +Get record size
479 +.It Dv MTTELL
480 +Get current position
481 +.It Dv MTSEEK
482 +Go to requested position
483 +.It Dv MTFSSF
484 +Forward to requested number of sequential file marks
485 +.It Dv MTBSSF
486 +Backward to requested number of sequential file marks
487 +.It Dv MTLOCK
488 +Prevent media removal
489 +.It Dv MTUNLOCK
490 +Allow media removal
491 +.It Dv MTLOAD
492 +Load the next tape cartridge into the tape drive
493 +.It Dv MTIOCGETERROR
494 +Retrieve error records from the st driver
495 +.El
496 +.Bd -literal -offset 2n
497 +/* structure for MTIOCGET - magnetic tape get status command */
337 498
338 -.sp
339 -.LP
340 -The following operations of \fBMTIOCTOP\fR and \fBMTIOCLTOP\fR ioctls are
341 -supported:
342 -.sp
343 -.ne 2
344 -.na
345 -\fBMTWEOF\fR
346 -.ad
347 -.RS 17n
348 -write an end-of-file record
349 -.RE
350 -
351 -.sp
352 -.ne 2
353 -.na
354 -\fBMTFSF\fR
355 -.ad
356 -.RS 17n
357 -forward space over file mark
358 -.RE
359 -
360 -.sp
361 -.ne 2
362 -.na
363 -\fBMTBSF\fR
364 -.ad
365 -.RS 17n
366 -backward space over file mark (1/2", 8mm only)
367 -.RE
368 -
369 -.sp
370 -.ne 2
371 -.na
372 -\fBMTFSR\fR
373 -.ad
374 -.RS 17n
375 -forward space to inter-record gap
376 -.RE
377 -
378 -.sp
379 -.ne 2
380 -.na
381 -\fBMTBSR\fR
382 -.ad
383 -.RS 17n
384 -backward space to inter-record gap
385 -.RE
386 -
387 -.sp
388 -.ne 2
389 -.na
390 -\fBMTREW\fR
391 -.ad
392 -.RS 17n
393 -rewind
394 -.RE
395 -
396 -.sp
397 -.ne 2
398 -.na
399 -\fBMTOFFL\fR
400 -.ad
401 -.RS 17n
402 -rewind and take the drive off-line
403 -.RE
404 -
405 -.sp
406 -.ne 2
407 -.na
408 -\fBMTNOP\fR
409 -.ad
410 -.RS 17n
411 -no operation, sets status only
412 -.RE
413 -
414 -.sp
415 -.ne 2
416 -.na
417 -\fBMTRETEN\fR
418 -.ad
419 -.RS 17n
420 -retension the tape (cartridge tape only)
421 -.RE
422 -
423 -.sp
424 -.ne 2
425 -.na
426 -\fBMTERASE\fR
427 -.ad
428 -.RS 17n
429 -erase the entire tape and rewind
430 -.RE
431 -
432 -.sp
433 -.ne 2
434 -.na
435 -\fBMTEOM\fR
436 -.ad
437 -.RS 17n
438 -position to EOM
439 -.RE
440 -
441 -.sp
442 -.ne 2
443 -.na
444 -\fBMTNBSF\fR
445 -.ad
446 -.RS 17n
447 -backward space file to beginning of file
448 -.RE
449 -
450 -.sp
451 -.ne 2
452 -.na
453 -\fBMTSRSZ\fR
454 -.ad
455 -.RS 17n
456 -set record size
457 -.RE
458 -
459 -.sp
460 -.ne 2
461 -.na
462 -\fBMTGRSZ\fR
463 -.ad
464 -.RS 17n
465 -get record size
466 -.RE
467 -
468 -.sp
469 -.ne 2
470 -.na
471 -\fBMTTELL\fR
472 -.ad
473 -.RS 17n
474 -get current position
475 -.RE
476 -
477 -.sp
478 -.ne 2
479 -.na
480 -\fBMTSEEK\fR
481 -.ad
482 -.RS 17n
483 -go to requested position
484 -.RE
485 -
486 -.sp
487 -.ne 2
488 -.na
489 -\fBMTFSSF\fR
490 -.ad
491 -.RS 17n
492 -forward to requested number of sequential file marks
493 -.RE
494 -
495 -.sp
496 -.ne 2
497 -.na
498 -\fBMTBSSF\fR
499 -.ad
500 -.RS 17n
501 -backward to requested number of sequential file marks
502 -.RE
503 -
504 -.sp
505 -.ne 2
506 -.na
507 -\fBMTLOCK\fR
508 -.ad
509 -.RS 17n
510 -prevent media removal
511 -.RE
512 -
513 -.sp
514 -.ne 2
515 -.na
516 -\fBMTUNLOCK\fR
517 -.ad
518 -.RS 17n
519 -allow media removal
520 -.RE
521 -
522 -.sp
523 -.ne 2
524 -.na
525 -\fBMTLOAD\fR
526 -.ad
527 -.RS 17n
528 -load the next tape cartridge into the tape drive
529 -.RE
530 -
531 -.sp
532 -.ne 2
533 -.na
534 -\fBMTIOCGETERROR\fR
535 -.ad
536 -.RS 17n
537 -retrieve error records from the st driver
538 -.RE
539 -
540 -.sp
541 -.in +2
542 -.nf
543 -/* structure for MTIOCGET \(mi magnetic tape get status command */
544 -
545 499 struct mtget {
546 500 short mt_type; /* type of magtape device */
547 -/* the following two registers are device dependent */
501 +
502 + /* the following two registers are device dependent */
548 503 short mt_dsreg; /* "drive status" register */
549 504 short mt_erreg; /* "error" register */
550 -/* optional error info. */
505 +
506 + /* optional error info. */
551 507 daddr_t mt_resid; /* residual count */
552 508 daddr_t mt_fileno; /* file number of current position */
553 509 daddr_t mt_blkno; /* block number of current position */
554 510 ushort_t mt_flags;
555 511 short mt_bf; /* optimum blocking factor */
556 512 };
557 -/* structure for MTIOCGETDRIVETYPE \(mi get tape config data command */
513 +
514 +/* structure for MTIOCGETDRIVETYPE - get tape config data command */
558 515 struct mtdrivetype_request {
559 516 int size;
560 517 struct mtdrivetype *mtdtp;
561 518 };
562 519 struct mtdrivetype {
563 520 char name[64]; /* Name, for debug */
564 521 char vid[25]; /* Vendor id and product id */
565 522 char type; /* Drive type for driver */
566 523 int bsize; /* Block size */
567 524 int options; /* Drive options */
568 525 int max_rretries; /* Max read retries */
569 526 int max_wretries; /* Max write retries */
570 527 uchar_t densities[MT_NDENSITIES]; /* density codes,low->hi */
|
↓ open down ↓ |
3 lines elided |
↑ open up ↑ |
571 528 uchar_t default_density; /* Default density chosen */
572 529 uchar_t speeds[MT_NSPEEDS]; /* speed codes, low->hi */
573 530 ushort_t non_motion_timeout; /* Seconds for non-motion */
574 531 ushort_t io_timeout; /* Seconds for data to from tape */
575 532 ushort_t rewind_timeout; /* Seconds to rewind */
576 533 ushort_t space_timeout; /* Seconds to space anywhere */
577 534 ushort_t load_timeout; /* Seconds to load tape and ready */
578 535 ushort_t unload_timeout; /* Seconds to unload */
579 536 ushort_t erase_timeout; /* Seconds to do long erase */
580 537 };
581 -.fi
582 -.in -2
583 -
584 -.sp
585 -.in +2
586 -.nf
538 +.Ed
539 +.Bd -literal -offset 2n
587 540 /* structure for MTIOCGETPOS and MTIOCRESTPOS - get/set tape position */
588 - /*
589 - * eof/eot/eom codes.
590 - */
541 +/*
542 + * eof/eot/eom codes.
543 + */
591 544 typedef enum {
592 545 ST_NO_EOF,
593 546 ST_EOF_PENDING, /* filemrk pending */
594 547 ST_EOF, /* at filemark */
595 - ST_EOT_PENDING, /* logical eot pend. */
548 + ST_EOT_PENDING, /* logical eot pend. */
596 549 ST_EOT, /* at logical eot */
597 550 ST_EOM, /* at physical eot */
598 551 ST_WRITE_AFTER_EOM /* flag allowing writes after EOM */
599 - }pstatus;
552 +} pstatus;
600 553
601 - typedef enum { invalid, legacy, logical } posmode;
554 +typedef enum { invalid, legacy, logical } posmode;
602 555
603 - typedef struct tapepos {
604 - uint64_t lgclblkno; /* Blks from start of partition */
605 - int32_t fileno; /* Num. of current file */
606 - int32_t blkno; /* Blk number in current file */
607 - int32_t partition; /* Current partition */
608 - pstatus eof; /* eof states */
609 - posmode pmode; /* which pos. data is valid */
610 - char pad[4];
611 - }tapepos_t;
612 -
613 - If the pmode is legacy,fileno and blkno fields are valid.
614 - If the pmode is logical, lgclblkno field is valid.
615 -.fi
616 -.in -2
617 -
618 -.sp
619 -.LP
620 -The \fBMTWEOF\fR ioctl is used for writing file marks to tape. Not only does
556 +typedef struct tapepos {
557 + uint64_t lgclblkno; /* Blks from start of partition */
558 + int32_t fileno; /* Num. of current file */
559 + int32_t blkno; /* Blk number in current file */
560 + int32_t partition; /* Current partition */
561 + pstatus eof; /* eof states */
562 + posmode pmode; /* which pos. data is valid */
563 + char pad[4];
564 +} tapepos_t;
565 +.Ed
566 +.Pp
567 +.Bd -ragged -compact
568 +If the
569 +.Fa pmode
570 +is legacy,
571 +.Fa fileno
572 +and
573 +.Fa blkno
574 +fields are valid.
575 +.Pp
576 +If the
577 +.Fa pmode
578 +is logical,
579 +.Fa lgclblkno
580 +field is valid.
581 +.Ed
582 +.Pp
583 +The
584 +.Dv MTWEOF
585 +ioctl is used for writing file marks to tape.
586 +Not only does
621 587 this signify the end of a file, but also usually has the side effect of
622 -flushing all buffers in the tape drive to the tape medium. A zero count
623 -\fBMTWEOF\fR will just flush all the buffers and will not write any file marks.
588 +flushing all buffers in the tape drive to the tape medium.
589 +A zero count
590 +.Dv MTWEOF
591 +will just flush all the buffers and will not write any file marks.
624 592 Because a successful completion of this tape operation will guarantee that all
625 593 tape data has been written to the tape medium, it is recommended that this tape
626 594 operation be issued before closing a tape device.
627 -.sp
628 -.LP
629 -When spacing forward over a record (either data or \fBEOF),\fR the tape head is
595 +.Pp
596 +When spacing forward over a record (either data or
597 +.Sy EOF ) ,
598 +the tape head is
630 599 positioned in the tape gap between the record just skipped and the next record.
631 600 When spacing forward over file marks (EOF records), the tape head is positioned
632 -in the tape gap between the next \fBEOF\fR record and the record that follows
633 -it.
634 -.sp
635 -.LP
636 -When spacing backward over a record (either data or \fBEOF),\fR the tape head
637 -is positioned in the tape gap immediately preceding the tape record where the
638 -tape head is currently positioned. When spacing backward over file marks (EOF
639 -records), the tape head is positioned in the tape gap preceding the \fBEOF.\fR
640 -Thus the next read would fetch the \fBEOF.\fR
641 -.sp
642 -.LP
601 +in the tape gap between the next
602 +.Sy EOF
603 +record and the record that follows it.
604 +.Pp
605 +When spacing backward over a record (either data or
606 +.Sy EOF ) ,
607 +the tape head is positioned in the tape gap immediately preceding the tape
608 +record where the tape head is currently positioned.
609 +When spacing backward over file marks (EOF records), the tape head is
610 +positioned in the tape gap preceding the
611 +.Sy EOF .
612 +Thus the next read would fetch the
613 +.Sy EOF .
614 +.Pp
643 615 Record skipping does not go past a file mark; file skipping does not go past
644 -the \fBEOM.\fR After an \fBMTFSR\fR <huge number> command, the driver leaves
645 -the tape logically positioned \fIbefore\fR the \fBEOF.\fR A related feature is
646 -that \fBEOFs\fR remain pending until the tape is closed. For example, a program
616 +the
617 +.Sy EOM .
618 +After an
619 +.Dv MTFSR
620 +<huge number> command, the driver leaves
621 +the tape logically positioned
622 +.Em before
623 +the
624 +.Sy EOF .
625 +A related feature is that
626 +.Sy EOF Ns s
627 +remain pending until the tape is closed.
628 +For example, a program
647 629 which first reads all the records of a file up to and including the \fBEOF\fR
648 -and then performs an \fBMTFSF\fR command will leave the tape positioned just
649 -after that same \fBEOF,\fR rather than skipping the next file.
650 -.sp
651 -.LP
652 -The \fBMTNBSF\fR and \fBMTFSF\fR operations are inverses. Thus, an "
653 -\fBMTFSF\fR \(mi1" is equivalent to an " \fBMTNBSF\fR 1". An " \fBMTNBSF\fR 0"
654 -is the same as " \fBMTFSF\fR 0"; both position the tape device at the beginning
655 -of the current file.
656 -.sp
657 -.LP
658 -\fBMTBSF\fR moves the tape backwards by file marks. The tape position will end
659 -on the beginning of the tape side of the desired file mark. An " \fBMTBSF\fR 0"
630 +and then performs an
631 +.Dv MTFSF
632 +command will leave the tape positioned just
633 +after that same
634 +.Sy EOF ,
635 +rather than skipping the next file.
636 +.Pp
637 +The
638 +.Dv MTNBSF
639 +and
640 +.Dv MTFSF
641 +operations are inverses.
642 +Thus, an
643 +.Dq Dv MTFSF \(mi1
644 +is equivalent to an
645 +.Dq Dv MTNBSF 1 .
646 +An
647 +.Dq Dv MTNBSF 0
648 +is the same as
649 +.Dq Dv MTFSF 0 ;
650 +both position the tape device at the beginning of the current file.
651 +.Pp
652 +.Dv MTBSF
653 +moves the tape backwards by file marks.
654 +The tape position will end
655 +on the beginning of the tape side of the desired file mark.
656 +An
657 +.Dq Dv MTBSF 0
660 658 will position the tape at the end of the current file, before the filemark.
661 -.sp
662 -.LP
663 -\fBMTBSR\fR and \fBMTFSR\fR operations perform much like space file operations,
664 -except that they move by records instead of files. Variable-length I/O devices
665 -(1/2" reel, for example) space actual records; fixed-length I/O devices space
666 -physical records (blocks). 1/4" cartridge tape, for example, spaces 512 byte
667 -physical records. The status ioctl residual count contains the number of files
659 +.Pp
660 +.Dv MTBSR
661 +and
662 +.Dv MTFSR
663 +operations perform much like space file operations,
664 +except that they move by records instead of files.
665 +Variable-length I/O devices
666 +(1/2\(dq reel, for example) space actual records; fixed-length I/O devices space
667 +physical records (blocks).
668 +1/4\(dq cartridge tape, for example, spaces 512 byte
669 +physical records.
670 +The status ioctl residual count contains the number of files
668 671 or records not skipped.
669 -.sp
670 -.LP
671 -MTFSSF and MTBSSF space forward or backward, respectively, to the next
672 -occurrence of the requested number of file marks, one following another. If
673 -there are more sequential file marks on tape than were requested, it spaces
674 -over the requested number and positions after the requested file mark. Note
675 -that not all drives support this command and if a request is sent to a drive
676 -that does not, \fBENOTTY\fR is returned.
677 -.sp
678 -.LP
679 -\fBMTOFFL\fR rewinds and, if appropriate, takes the device off-line by
680 -unloading the tape. It is recommended that the device be closed after offlining
672 +.Pp
673 +.Dv MTFSSF
674 +and
675 +.Dv MTBSSF
676 +space forward or backward, respectively, to the next
677 +occurrence of the requested number of file marks, one following another.
678 +If there are more sequential file marks on tape than were requested, it spaces
679 +over the requested number and positions after the requested file mark.
680 +Note that not all drives support this command and if a request is sent to a
681 +drive that does not,
682 +.Er ENOTTY
683 +is returned.
684 +.Pp
685 +.Dv MTOFFL
686 +rewinds and, if appropriate, takes the device off-line by unloading the tape.
687 +It is recommended that the device be closed after offlining
681 688 and then re-opened after a tape has been inserted to facilitate portability to
682 -other platforms and other operating systems. Attempting to re-open the device
683 -with no tape will result in an error unless the \fBO_NDELAY\fR flag is used.
684 -(See \fBopen\fR(2).)
685 -.sp
686 -.LP
687 -The \fBMTRETEN\fR retension ioctl applies only to 1/4" cartridge tape devices.
689 +other platforms and other operating systems.
690 +Attempting to re-open the device
691 +with no tape will result in an error unless the
692 +.Dv O_NDELAY
693 +flag is used.
694 +.Po
695 +See
696 +.Xr open 2 .
697 +.Pc
698 +.Pp
699 +The
700 +.Dv MTRETEN
701 +retension ioctl applies only to 1/4\(dq cartridge tape devices.
688 702 It is used to restore tape tension, improving the tape's soft error rate after
689 703 extensive start-stop operations or long-term storage.
690 -.sp
691 -.LP
692 -\fBMTERASE\fR rewinds the tape, erases it completely, and returns to the
693 -beginning of tape. Erasing may take a long time depending on the device and/or
694 -tapes. For time details, refer to the drive specific manual.
695 -.sp
696 -.LP
697 -\fBMTEOM\fR positions the tape at a location just after the last file written
698 -on the tape. For 1/4" cartridge and 8mm tape, this is after the last file mark
699 -on the tape. For 1/2" reel tape, this is just after the first file mark but
700 -before the second (and last) file mark on the tape. Additional files can then
704 +.Pp
705 +.Dv MTERASE
706 +rewinds the tape, erases it completely, and returns to the
707 +beginning of tape.
708 +Erasing may take a long time depending on the device and/or
709 +tapes.
710 +For time details, refer to the drive specific manual.
711 +.Pp
712 +.Dv MTEOM
713 +positions the tape at a location just after the last file written
714 +on the tape.
715 +For 1/4\(dq cartridge and 8mm tape, this is after the last file mark
716 +on the tape.
717 +For 1/2\(dq reel tape, this is just after the first file mark but
718 +before the second (and last) file mark on the tape.
719 +Additional files can then
701 720 be appended onto the tape from that point.
702 -.sp
703 -.LP
704 -Note the difference between \fBMTBSF\fR (backspace over file mark) and
705 -\fBMTNBSF\fR (backspace file to beginning of file). The former moves the tape
706 -backward until it crosses an \fBEOF\fR mark, leaving the tape positioned
707 -\fIbefore\fR the file mark. The latter leaves the tape positioned \fIafter\fR
708 -the file mark. Hence, "\fBMTNBSF\fR n" is equivalent to "\fBMTBSF\fR (n+1)"
709 -followed by "\fBMTFSF\fR 1". The 1/4" cartridge tape devices do not support
710 -\fBMTBSF.\fR
711 -.sp
712 -.LP
713 -\fBMTSRSZ\fR and \fBMTGRSZ\fR are used to set and get fixed record lengths. The
714 -\fBMTSRSZ\fR ioctl allows variable length and fixed length tape drives that
715 -support multiple record sizes to set the record length. The \fBmt_count\fR
716 -field of the \fBmtop\fR struct is used to pass the record size to/from the
717 -\fBst\fR driver. A value of \fB0\fR indicates variable record size. The
718 -\fBMTSRSZ\fR ioctl makes a variable-length tape device behave like a
719 -fixed-length tape device. Refer to the specific tape driver man page for
721 +.Pp
722 +Note the difference between
723 +.Dv MTBSF
724 +(backspace over file mark) and
725 +.Dv MTNBSF
726 +(backspace file to beginning of file).
727 +The former moves the tape
728 +backward until it crosses an
729 +.Sy EOF
730 +mark, leaving the tape positioned
731 +.Em before
732 +the file mark.
733 +The latter leaves the tape positioned
734 +.Em after
735 +the file mark.
736 +Hence,
737 +.Dq Dv MTNBSF n
738 +is equivalent to
739 +.Dq Dv MTBSF (n+1)
740 +followed by
741 +.Dq Dv MTFSF 1 .
742 +The 1/4\(dq cartridge tape devices do not support
743 +.Dv MTBSF .
744 +.Pp
745 +.Dv MTSRSZ
746 +and
747 +.Dv MTGRSZ
748 +are used to set and get fixed record lengths.
749 +The
750 +.Dv MTSRSZ
751 +ioctl allows variable length and fixed length tape drives that
752 +support multiple record sizes to set the record length.
753 +The
754 +.Fa mt_count
755 +field of the
756 +.Vt mtop
757 +struct is used to pass the record size to/from the
758 +.Xr st 7D
759 +driver.
760 +A value of
761 +.Ql 0
762 +indicates variable record size.
763 +The
764 +.Dv MTSRSZ
765 +ioctl makes a variable-length tape device behave like a
766 +fixed-length tape device.
767 +Refer to the specific tape driver man page for
720 768 details.
721 -.sp
722 -.LP
723 -\fBMTLOAD\fR loads the next tape cartridge into the tape drive. This is
724 -generally only used with stacker and tower type tape drives which handle
725 -multiple tapes per tape drive. A tape device without a tape inserted can be
726 -opened with the \fBO_NDELAY\fR flag, in order to execute this operation.
727 -.sp
728 -.LP
729 -\fBMTIOCGETERROR\fR allows user-level applications to retrieve error records
730 -from the \fBst\fR driver. An error record consists of the SCSI command cdb
731 -which causes the error and a \fBscsi_arq_status\fR(9S) structure if available.
769 +.Pp
770 +.Dv MTLOAD
771 +loads the next tape cartridge into the tape drive.
772 +This is generally only used with stacker and tower type tape drives which handle
773 +multiple tapes per tape drive.
774 +A tape device without a tape inserted can be
775 +opened with the
776 +.Dv O_NDELAY
777 +flag, in order to execute this operation.
778 +.Pp
779 +.Dv MTIOCGETERROR
780 +allows user-level applications to retrieve error records
781 +from the
782 +.Xr st 7D
783 +driver.
784 +An error record consists of the SCSI command cdb
785 +which causes the error and a
786 +.Xr scsi_arq_status 9S
787 +structure if available.
732 788 The user-level application is responsible for allocating and releasing the
733 -memory for mtee_cdb_buf and scsi_arq_status of each mterror_entry. Before
734 -issuing the ioctl, the mtee_arq_status_len value should be at least equal to
735 -"sizeof(struct scsi_arq_status)." If more sense data than the size of
736 -\fBscsi_arq_status\fR(9S) is desired, the mtee_arq_status_len may be larger
737 -than "sizeof(struct scsi_arq_status)" by the amount of additional extended
738 -sense data desired. The es_add_len field of \fBscsi_extended_sense\fR(9S) can
739 -be used to determine the amount of valid sense data returned by the device.
740 -.sp
741 -.LP
742 -The \fBMTIOCGET\fR get status \fBioctl\fR call returns the drive ID
743 -(\fImt_type\fR), sense key error (\fImt_erreg\fR), file number
744 -(\fImt_fileno\fR), optimum blocking factor (\fImt_bf\fR) and record number
745 -(\fImt_blkno\fR) of the last error. The residual count (\fImt_resid\fR) is set
746 -to the number of bytes not transferred or files/records not spaced. The flags
747 -word (\fImt_flags\fR) contains information indicating if the device is SCSI, if
748 -the device is a reel device and whether the device supports absolute file
749 -positioning. The \fImt_flags\fR also indicates if the device is requesting
750 -cleaning media be used, whether the device is capable of reporting the
751 -requirement of cleaning media and if the currently loaded media is WORM (Write
752 -Once Read Many) media.
753 -.LP
754 -Note -
755 -.sp
756 -.RS 2
757 -When tape alert cleaning is managed by the st driver, the tape target driver
758 -may continue to return a "drive needs cleaning" status unless an MTIOCGET
759 -ioctl() call is made while the cleaning media is in the drive.
760 -.RE
761 -.sp
762 -.LP
763 -The \fBMTIOCGETDRIVETYPE\fR get drivetype ioctl call returns the name of the
764 -tape drive as defined in \fBst.conf\fR (\fIname\fR), Vendor \fBID\fR and model
765 -(\fIproduct\fR), \fBID\fR (\fIvid\fR), type of tape device (\fBtype\fR), block
766 -size (\fIbsize\fR), drive options (\fIoptions\fR), maximum read retry count
767 -(\fImax_rretries\fR), maximum write retry count (\fImax_wretries\fR), densities
768 -supported by the drive (\fIdensities\fR), and default density of the tape drive
769 -(\fIdefault_density\fR).
770 -.sp
771 -.LP
772 -The MTIOCGETPOS ioctl returns the current tape position of the drive. It is
773 -returned in struct tapepos as defined in
774 -\fB/usr/include/sys/scsi/targets/stdef.h\fR.
775 -.sp
776 -.LP
777 -The MTIOCRESTPOS ioctl restores a saved position from the MTIOCGETPOS.
778 -.SS "Persistent Error Handling IOCTLs and Asynchronous Tape Operations"
779 -.ne 2
780 -.na
781 -\fBMTIOCPERSISTENT\fR
782 -.ad
783 -.RS 25n
789 +memory for
790 +.Fa mtee_cdb_buf
791 +and
792 +.Fa scsi_arq_status of each
793 +.Vt mterror_entry .
794 +Before issuing the ioctl, the
795 +.Fa mtee_arq_status_len
796 +value should be at least equal to
797 +.Ql sizeof (struct scsi_arq_status) .
798 +If more sense data than the size of
799 +.Xr scsi_arq_status 9S
800 +is desired, the
801 +.Fa mtee_arq_status_len
802 +may be larger than
803 +.Ql sizeof (struct scsi_arq_status)
804 +by the amount of additional extended sense data desired.
805 +The
806 +.Fa es_add_len
807 +field of
808 +.Xr scsi_extended_sense 9S
809 +can be used to determine the amount of valid sense data returned by the device.
810 +.Pp
811 +The
812 +.Dv MTIOCGET
813 +get status
814 +.Xr ioctl 2
815 +call returns the drive ID
816 +.Pq Fa mt_type ,
817 +sense key error
818 +.Pq Fa mt_erreg ,
819 +file number
820 +.Pq Fa mt_fileno ,
821 +optimum blocking factor
822 +.Pq Fa mt_bf
823 +and record number
824 +.Pq Fa mt_blkno
825 +of the last error.
826 +The residual count
827 +.Pq Fa mt_resid
828 +is set to the number of bytes not transferred or files/records not spaced.
829 +The flags word
830 +.Pq Fa mt_flags
831 +contains information indicating if the device is SCSI, if the device is a reel
832 +device and whether the device supports absolute file positioning.
833 +The
834 +.Fa mt_flags
835 +also indicates if the device is requesting cleaning media be used, whether the
836 +device is capable of reporting the requirement of cleaning media and if the
837 +currently loaded media is WORM (Write Once Read Many) media.
838 +.Pp
839 +Note \(em When tape alert cleaning is managed by the st driver, the tape
840 +target driver may continue to return a
841 +.Dq drive needs cleaning
842 +status unless an
843 +.Dv MTIOCGE
844 +.Xr ioct 2
845 +call is made while the cleaning media is in the drive.
846 +.Pp
847 +The
848 +.Dv MTIOCGETDRIVETYPE
849 +get drivetype ioctl call returns the name of the
850 +tape drive as defined in
851 +.Pa st.conf
852 +.Pq Fa name ,
853 +Vendor
854 +.Sy ID
855 +and model
856 +.Pq Fa product ,
857 +.Sy ID
858 +.Pq Fa vid ,
859 +type of tape device
860 +.Pq Fa type ,
861 +block size
862 +.Pq Fa size ,
863 +drive options
864 +.Pq Fa options ,
865 +maximum read retry count
866 +.Pq Fa max_rretries ,
867 +maximum write retry count
868 +.Pq Fa max_wretries ,
869 +densities supported by the drive
870 +.Pq Fa densities ,
871 +and default density of the tape drive
872 +.Pq Fa default_density .
873 +.Pp
874 +The
875 +.Dv MTIOCGETPOS
876 +ioctl returns the current tape position of the drive.
877 +It is returned in struct tapepos as defined in
878 +.Pa /usr/include/sys/scsi/targets/stdef.h .
879 +.Pp
880 +The
881 +.Dv MTIOCRESTPOS
882 +ioctl restores a saved position from the
883 +.Dv MTIOCGETPOS .
884 +.Ss "Persistent Error Handling IOCTLs and Asynchronous Tape Operations"
885 +.Bl -tag -width MTIOCPERSISTENTSTATUS -compact
886 +.It Dv MTIOCPERSISTENT
784 887 enables/disables persistent error handling
785 -.RE
786 -
787 -.sp
788 -.ne 2
789 -.na
790 -\fBMTIOCPERSISTENTSTATUS\fR
791 -.ad
792 -.RS 25n
888 +.It Dv MTIOCPERSISTENTSTATUS
793 889 queries for persistent error handling
794 -.RE
795 -
796 -.sp
797 -.ne 2
798 -.na
799 -\fBMTIOCLRERR\fR
800 -.ad
801 -.RS 25n
890 +.It Dv MTIOCLRERR
802 891 clears persistent error handling
803 -.RE
804 -
805 -.sp
806 -.ne 2
807 -.na
808 -\fBMTIOCGUARANTEEDORDER\fR
809 -.ad
810 -.RS 25n
892 +.It Dv MTIOCGUARANTEEDORDER
811 893 checks whether driver guarantees order of I/O's
812 -.RE
813 -
814 -.sp
815 -.LP
816 -The \fBMTIOCPERSISTENT\fR ioctl enables or disables persistent error handling.
894 +.El
895 +.Pp
896 +The
897 +.Dv MTIOCPERSISTENT
898 +ioctl enables or disables persistent error handling.
817 899 It takes as an argument a pointer to an integer that turns it either on or off.
818 -If the ioctl succeeds, the desired operation was successful. It will wait for
900 +If the ioctl succeeds, the desired operation was successful.
901 +It will wait for
819 902 all outstanding I/O's to complete before changing the persistent error handling
820 -status. For example,
821 -.sp
822 -.in +2
823 -.nf
903 +status.
904 +For example,
905 +.Bd -literal -offset 2n
824 906 int on = 1;
825 907 ioctl(fd, MTIOCPERSISTENT, &on);
826 908 int off = 0;
827 909 ioctl(fd, MTIOCPERSISTENT, &off);
828 -.fi
829 -.in -2
830 -
831 -.sp
832 -.LP
833 -The \fBMTIOCPERSISTENTSTATUS\fR ioctl enables or disables persistent error
834 -handling. It takes as an argument a pointer to an integer inserted by the
835 -driver. The integer can be either 1 if persistent error handling is 'on', or 0
836 -if persistent error handling is 'off'. It will not wait for outstanding I/O's.
910 +.Ed
911 +.Pp
912 +The
913 +.Dv MTIOCPERSISTENTSTATUS
914 +ioctl enables or disables persistent error
915 +handling.
916 +It takes as an argument a pointer to an integer inserted by the
917 +driver.
918 +The integer can be either 1 if persistent error handling is
919 +.Sq on ,
920 +or 0 if persistent error handling is
921 +.Sq off .
922 +It will not wait for outstanding I/O's.
837 923 For example,
838 -.sp
839 -.in +2
840 -.nf
924 +.Bd -literal -offset 2n
841 925 int query;
842 926 ioctl(fd, MTIOCPERSISTENTSTATUS, &query);
843 -.fi
844 -.in -2
845 -
846 -.sp
847 -.LP
848 -The \fBMTIOCLRERR\fR ioctl clears persistent error handling and allows tape
849 -operations to continual normally. This ioctl requires no argument and will
850 -always succeed, even if persistent error handling has not been enabled. It will
851 -wait for any outstanding I/O's before it clears the error.
852 -.sp
853 -.LP
854 -The \fBMTIOCGUARANTEEDORDER\fR ioctl is used to determine whether the driver
855 -guarantees the order of I/O's. It takes no argument. If the ioctl succeeds, the
856 -driver will support guaranteed order. If the driver does not support guaranteed
857 -order, then it should not be used for asynchronous I/O with \fBlibaio\fR. It
858 -will wait for any outstanding I/O's before it returns. For example,
859 -.sp
860 -.in +2
861 -.nf
927 +.Ed
928 +.Pp
929 +The
930 +.Dv MTIOCLRERR
931 +ioctl clears persistent error handling and allows tape
932 +operations to continual normally.
933 +This ioctl requires no argument and will
934 +always succeed, even if persistent error handling has not been enabled.
935 +It will wait for any outstanding I/O's before it clears the error.
936 +.Pp
937 +The
938 +.Dv MTIOCGUARANTEEDORDER
939 +ioctl is used to determine whether the driver
940 +guarantees the order of I/O's.
941 +It takes no argument.
942 +If the ioctl succeeds, the driver will support guaranteed order.
943 +If the driver does not support guaranteed order, then it should not be used
944 +for asynchronous I/O with
945 +.Xr libaio 3lib .
946 +It will wait for any outstanding I/O's before it returns.
947 +For example,
948 +.Bd -literal -offset 2n
862 949 ioctl(fd, MTIOCGUARANTEEDORDER)
863 -.fi
864 -.in -2
865 -
866 -.sp
867 -.LP
868 -See the \fBPersistent Error Handling\fR subsection above for more information
869 -on persistent error handling.
870 -.SS "Asynchronous and State Change IOCTLS"
871 -.ne 2
872 -.na
873 -\fB\fBMTIOCSTATE\fR\fR
874 -.ad
875 -.RS 14n
950 +.Ed
951 +.Pp
952 +See the
953 +.Sx Persistent Error Handling
954 +subsection above for more information on persistent error handling.
955 +.Ss "Asynchronous and State Change IOCTLS"
956 +.Bl -tag -width 1n
957 +.It Dv MTIOCSTATE
876 958 This ioctl blocks until the state of the drive, inserted or ejected, is
877 -changed. The argument is a pointer to a \fBmtio_state\fR, \fBenum\fR, whose
878 -possible enumerations are listed below. The initial value should be either the
879 -last reported state of the drive, or \fBMTIO_NONE\fR. Upon return, the
880 -\fBenum\fR pointed to by the argument is updated with the current state of the
881 -drive.
882 -.RE
883 -
884 -.sp
885 -.in +2
886 -.nf
959 +changed.
960 +The argument is a pointer to a
961 +.Vt enum mtio_state ,
962 +whose possible enumerations are listed below.
963 +The initial value should be either the last reported state of the drive, or
964 +.Dv MTIO_NONE .
965 +Upon return, the
966 +enum pointed to by the argument is updated with the current state of the drive.
967 +.Bd -literal -offset 2n
887 968 enum mtio_state {
888 -MTIO_NONE /* Return tape's current state */
889 -MTIO_EJECTED /* Tape state is "ejected" */
890 -MTIO_INSERTED /* Tape state is "inserted" */
891 -;
892 -.fi
893 -.in -2
894 -
895 -.sp
896 -.LP
969 + MTIO_NONE /* Return tape's current state */
970 + MTIO_EJECTED /* Tape state is "ejected" */
971 + MTIO_INSERTED /* Tape state is "inserted" */
972 +};
973 +.Ed
974 +.El
975 +.Pp
897 976 When using asynchronous operations, most ioctls will wait for all outstanding
898 977 commands to complete before they are executed.
899 -.SS "IOCTLS for Multi-initiator Configurations"
900 -.ne 2
901 -.na
902 -\fBMTIOCRESERVE\fR
903 -.ad
904 -.RS 21n
978 +.Ss "IOCTLS for Multi-initiator Configurations"
979 +.Bl -tag -width MTIOCFORCERESERVE -compact
980 +.It Dv MTIOCRESERVE
905 981 reserve the tape drive
906 -.RE
907 -
908 -.sp
909 -.ne 2
910 -.na
911 -\fBMTIOCRELEASE\fR
912 -.ad
913 -.RS 21n
982 +.It Dv MTIOCRELEASE
914 983 revert back to the default behavior of reserve on open/release on close
915 -.RE
916 -
917 -.sp
918 -.ne 2
919 -.na
920 -\fBMTIOCFORCERESERVE\fR
921 -.ad
922 -.RS 21n
984 +.It Dv MTIOCFORCERESERVE
923 985 reserve the tape unit by breaking reservation held by another host
924 -.RE
925 -
926 -.sp
927 -.LP
928 -The \fBMTIOCRESERVE\fR ioctl reserves the tape drive such that it does not
929 -release the tape drive at close. This changes the default behavior of releasing
930 -the device upon close. Reserving the tape drive that is already reserved has no
931 -effect. For example,
932 -.sp
933 -.LP
934 -\fBioctl(fd, MTIOCRESERVE);\fR
935 -.sp
936 -.LP
937 -The \fBMTIOCRELEASE\fR ioctl reverts back to the default behavior of reserve on
986 +.El
987 +.Pp
988 +The
989 +.Dv MTIOCRESERVE
990 +ioctl reserves the tape drive such that it does not
991 +release the tape drive at close.
992 +This changes the default behavior of releasing the device upon close.
993 +Reserving the tape drive that is already reserved has no effect.
994 +For example,
995 +.Bd -literal -offset 2n
996 +ioctl(fd, MTIOCRESERVE);
997 +.Ed
998 +.Pp
999 +The
1000 +.Dv MTIOCRELEASE
1001 +ioctl reverts back to the default behavior of reserve on
938 1002 open/release on close operation, and a release will occur during the next
939 -close. Releasing the tape drive that is already released has no effect. For
940 -example,
941 -.sp
942 -.LP
943 -\fBioctl(fd, MTIOCRELEASE);\fR
944 -.sp
945 -.LP
946 -The \fBMTIOCFORCERESERVE\fR ioctl breaks a reservation held by another host,
947 -interrupting any I/O in progress by that other host, and then reserves the tape
948 -unit. This ioctl can be executed only with super-user privileges. It is
949 -recommended to open the tape device in \fBO_NDELAY\fR mode when this ioctl
950 -needs to be executed, otherwise the open will fail if another host indeed has
951 -it reserved. For example,
952 -.sp
953 -.in +2
954 -.nf
1003 +close.
1004 +Releasing the tape drive that is already released has no effect.
1005 +For example,
1006 +.Bd -literal -offset 2n
1007 +ioctl(fd, MTIOCRELEASE);
1008 +.Ed
1009 +.Pp
1010 +The
1011 +.Dv MTIOCFORCERESERVE
1012 +ioctl breaks a reservation held by another host, interrupting any I/O in
1013 +progress by that other host, and then reserves the tape unit.
1014 +This ioctl can be executed only with super-user privileges.
1015 +It is recommended to open the tape device in
1016 +.Dv O_NDELAY
1017 +mode when this ioctl needs to be executed, otherwise the open will fail if
1018 +another host indeed has it reserved.
1019 +For example,
1020 +.Bd -literal -offset 2n
955 1021 ioctl(fd, MTIOCFORCERESERVE);
956 -.fi
957 -.in -2
958 -
959 -.SS "IOCTLS for Handling Tape Configuration Options"
960 -.ne 2
961 -.na
962 -\fBMTIOCSHORTFMK\fR
963 -.ad
964 -.RS 23n
965 -enables/disables support for writing short filemarks. This is specific to
966 -Exabyte drives.
967 -.RE
968 -
969 -.sp
970 -.ne 2
971 -.na
972 -\fBMTIOCREADIGNOREILI\fR
973 -.ad
974 -.RS 23n
1022 +.Ed
1023 +.Ss "IOCTLS for Handling Tape Configuration Options"
1024 +.Bl -tag -width MTIOCREADIGNOREEOFS
1025 +.It Dv MTIOCSHORTFMK
1026 +enables/disables support for writing short filemarks.
1027 +This is specific to Exabyte drives.
1028 +.It Dv MTIOCREADIGNOREILI
975 1029 enables/disables suppress incorrect length indicator (SILI) support during reads
976 -.RE
977 -
978 -.sp
979 -.ne 2
980 -.na
981 -\fBMTIOCREADIGNOREEOFS\fR
982 -.ad
983 -.RS 23n
1030 +.It Dv MTIOCREADIGNOREEOFS
984 1031 enables/disables support for reading past two EOF marks which otherwise indicate
985 -End-Of-recording-Media (EOM) in the case of 1/2" reel tape drives
986 -.RE
987 -
988 -.sp
989 -.LP
990 -The \fBMTIOCSHORTFMK\fR ioctl enables or disables support for short filemarks.
1032 +End-Of-recording-Media (EOM) in the case of 1/2\(dq reel tape drives
1033 +.El
1034 +.Pp
1035 +The
1036 +.Dv MTIOCSHORTFMK
1037 +ioctl enables or disables support for short filemarks.
991 1038 This ioctl is only applicable to Exabyte drives which support short filemarks.
992 -As an argument, it takes a pointer to an integer. If 0 (zero) is the
993 -specified integer, then long filemarks will be written. If 1 is the specified
994 -integer, then short filemarks will be written. The specified tape behavior will
995 -be in effect until the device is closed.
996 -.sp
997 -.LP
1039 +As an argument, it takes a pointer to an integer.
1040 +If 0 (zero) is the specified integer, then long filemarks will be written.
1041 +If 1 is the specified integer, then short filemarks will be written.
1042 +The specified tape behavior will be in effect until the device is closed.
1043 +.Pp
998 1044 For example:
999 -.sp
1000 -.in +2
1001 -.nf
1045 +.Bd -literal -offset 2n
1002 1046 int on = 1;
1003 1047 int off = 0;
1004 1048 /* enable short filemarks */
1005 1049 ioctl(fd, MTIOSHORTFMK, &on);
1006 1050 /* disable short filemarks */
1007 1051 ioctl(fd, MTIOCSHORTFMK, &off);
1008 -.fi
1009 -.in -2
1010 -
1011 -.sp
1012 -.LP
1013 -Tape drives which do not support short filemarks will return an \fBerrno\fR of
1014 -\fBENOTTY.\fR
1015 -.sp
1016 -.LP
1017 -The \fBMTIOCREADIGNOREILI\fR ioctl enables or disables the suppress incorrect
1018 -length indicator (SILI) support during reads. As an argument, it takes a
1019 -pointer to an integer. If 0 (zero) is the specified integer, SILI will not be
1020 -used during reads and incorrect length indicator will not be suppressed. If 1
1021 -is the specified integer, SILI will be used during reads and incorrect length
1022 -indicator will be suppressed. The specified tape behavior will be in effect
1023 -until the device is closed.
1024 -.sp
1025 -.LP
1052 +.Ed
1053 +.Pp
1054 +Tape drives which do not support short filemarks will return an
1055 +.Va errno
1056 +of
1057 +.Er ENOTTY .
1058 +.Pp
1059 +The
1060 +.Dv MTIOCREADIGNOREILI
1061 +ioctl enables or disables the suppress incorrect
1062 +length indicator (SILI) support during reads.
1063 +As an argument, it takes a pointer to an integer.
1064 +If 0 (zero) is the specified integer, SILI will not be
1065 +used during reads and incorrect length indicator will not be suppressed.
1066 +If 1 is the specified integer, SILI will be used during reads and incorrect
1067 +length indicator will be suppressed.
1068 +The specified tape behavior will be in effect until the device is closed.
1069 +.Pp
1026 1070 For example:
1027 -.sp
1028 -.in +2
1029 -.nf
1071 +.Bd -literal -offset 2n
1030 1072 int on = 1;
1031 1073 int off = 0;
1032 1074 ioctl(fd, MTIOREADIGNOREILI, &on);
1033 1075 ioctl(fd, MTIOREADIGNOREILI, &off);
1034 -.fi
1035 -.in -2
1036 -
1037 -.sp
1038 -.LP
1039 -The \fBMTIOCREADIGNOREEOFS\fR ioctl enables or disables support for reading
1076 +.Ed
1077 +.Pp
1078 +The
1079 +.Dv MTIOCREADIGNOREEOFS
1080 +ioctl enables or disables support for reading
1040 1081 past double EOF marks which otherwise indicate End-Of-recorded-media (EOM) in
1041 -the case of 1/2" reel tape drives. As an argument, it takes a pointer to an
1042 -integer. If 0 (zero) is the specified integer, then double EOF marks indicate
1043 -End-Of-recodred-media (EOD). If 1 is the specified integer, the double EOF
1044 -marks no longer indicate EOM, thus allowing applications to read past two EOF
1045 -marks. In this case it is the responsibility of the application to detect
1046 -end-of-recorded-media (EOM). The specified tape behavior will be in effect
1047 -until the device is closed.
1048 -.sp
1049 -.LP
1082 +the case of 1/2\(dq reel tape drives.
1083 +As an argument, it takes a pointer to an integer.
1084 +If 0 (zero) is the specified integer, then double EOF marks indicate
1085 +End-Of-recodred-media (EOD).
1086 +If 1 is the specified integer, the double EOF marks no longer indicate EOM,
1087 +thus allowing applications to read past two EOF marks.
1088 +In this case it is the responsibility of the application to detect
1089 +end-of-recorded-media (EOM).
1090 +The specified tape behavior will be in effect until the device is closed.
1091 +.Pp
1050 1092 For example:
1051 -.sp
1052 -.in +2
1053 -.nf
1093 +.Bd -literal -offset 2n
1054 1094 int on = 1;
1055 1095 int off = 0;
1056 1096 ioctl(fd, MTIOREADIGNOREEOFS, &on);
1057 1097 ioctl(fd, MTIOREADIGNOREEOFS, &off);
1058 -.fi
1059 -.in -2
1060 -
1061 -.sp
1062 -.LP
1063 -Tape drives other than 1/2" reel tapes will return an \fBerrno\fR of
1064 -\fBENOTTY.\fR
1065 -.SH EXAMPLES
1066 -.LP
1067 -\fBExample 1 \fRTape Positioning and Tape Drives
1068 -.sp
1069 -.LP
1070 -Suppose you have written three files to the non-rewinding 1/2" tape device,
1071 -\fB/dev/rmt/0ln,\fR and that you want to go back and \fBdd\fR(1M) the second
1072 -file off the tape. The commands to do this are:
1073 -
1074 -.sp
1075 -.in +2
1076 -.nf
1077 -mt \fB-F\fR /dev/rmt/0lbn bsf 3
1078 -mt \fB-F\fR /dev/rmt/0lbn fsf 1
1098 +.Ed
1099 +.Pp
1100 +Tape drives other than 1/2\(dq reel tapes will return an
1101 +.Va errno
1102 +of
1103 +.Er ENOTTY .
1104 +.Sh FILES
1105 +.Pa /dev/rmt/ Ns Ao unit number Ac \
1106 + Ns Ao density Ac \
1107 + Ns Bo Ao BSD behavior Ac Bc \
1108 + Ns Bo Ao no rewind Ac Bc
1109 +.Pp
1110 +Where
1111 +.Aq density
1112 +can be
1113 +.Ql l ,
1114 +.Ql m ,
1115 +.Ql h ,
1116 +.Ql u/c
1117 +(low, medium, high, ultra/compressed, respectively), the
1118 +.Aq BSD behavior
1119 +option is
1120 +.Ql b , and the
1121 +.Aq no rewind
1122 +option is
1123 +.Ql n .
1124 +.Pp
1125 +For example,
1126 +.Pa /dev/rmt/0hbn
1127 +specifies unit 0, high density,
1128 +.Sy BSD
1129 +behavior and no rewind.
1130 +.Sh EXAMPLES
1131 +.Bl -inset
1132 +.It Sy Example 1
1133 +Tape Positioning and Tape Drives
1134 +.Pp
1135 +Suppose you have written three files to the non-rewinding 1/2\(dq tape device,
1136 +.Pa /dev/rmt/0ln ,
1137 +and that you want to go back and
1138 +.Xr dd 1M
1139 +the second file off the tape.
1140 +The commands to do this are:
1141 +.Bd -literal -offset 2n
1142 +mt -F /dev/rmt/0lbn bsf 3
1143 +mt -F /dev/rmt/0lbn fsf 1
1079 1144 dd if=/dev/rmt/0ln
1080 -.fi
1081 -.in -2
1082 -
1083 -.sp
1084 -.LP
1145 +.Ed
1146 +.Pp
1085 1147 To accomplish the same tape positioning in a C program, followed by a get
1086 1148 status ioctl:
1087 -
1088 -.sp
1089 -.in +2
1090 -.nf
1149 +.Bd -literal -offset 2n
1091 1150 struct mtop mt_command;
1092 1151 struct mtget mt_status;
1093 1152 mt_command.mt_op = MTBSF;
1094 1153 mt_command.mt_count = 3;
1095 1154 ioctl(fd, MTIOCTOP, &mt_command);
1096 1155 mt_command.mt_op = MTFSF;
1097 1156 mt_command.mt_count = 1;
1098 1157 ioctl(fd, MTIOCTOP, &mt_command);
1099 1158 ioctl(fd, MTIOCGET, (char *)&mt_status);
1100 -.fi
1101 -.in -2
1102 -
1103 -.sp
1104 -.LP
1159 +.Ed
1160 +.Pp
1105 1161 or
1106 -
1107 -.sp
1108 -.in +2
1109 -.nf
1162 +.Bd -literal -offset 2n
1110 1163 mt_command.mt_op = MTNBSF;
1111 1164 mt_command.mt_count = 2;
1112 1165 ioctl(fd, MTIOCTOP, &mt_command);
1113 1166 ioctl(fd, MTIOCGET, (char *)&mt_status);
1114 -.fi
1115 -.in -2
1116 -
1117 -.sp
1118 -.LP
1167 +.Ed
1168 +.Pp
1119 1169 To get information about the tape drive:
1120 -
1121 -.sp
1122 -.in +2
1123 -.nf
1170 +.Bd -literal -offset 2n
1124 1171 struct mtdrivetype mtdt;
1125 1172 struct mtdrivetype_request mtreq;
1126 1173 mtreq.size = sizeof(struct mtdrivetype);
1127 1174 mtreq.mtdtp = &mtdt;
1128 1175 ioctl(fd, MTIOCGETDRIVETYPE, &mtreq);
1129 -.fi
1130 -.in -2
1131 -
1132 -.SH FILES
1133 -.LP
1134 -\fB/dev/rmt/\fR\fI<unit number><density>\fR[\fI<BSD behavior>\fR][\fI<no
1135 -rewind>\fR]
1136 -.sp
1137 -.LP
1138 -Where \fIdensity\fR can be \fBl,\fR \fBm,\fR \fBh,\fR \fBu/c\fR (low, medium,
1139 -high, ultra/compressed, respectively), the \fIBSD behavior \fR option is
1140 -\fBb\fR, and the \fIno rewind \fR option is \fBn\fR.
1141 -.sp
1142 -.LP
1143 -For example, \fB/dev/rmt/0hbn\fR specifies unit 0, high density, \fBBSD\fR
1144 -behavior and no rewind.
1145 -.SH SEE ALSO
1146 -.LP
1147 -\fBmt\fR(1), \fBtar\fR(1), \fBdd\fR(1M), \fBopen\fR(2), \fBread\fR(2),
1148 -\fBwrite\fR(2), \fBaioread\fR(3C), \fBaiowrite\fR(3C), \fBar.h\fR(3HEAD),
1149 -\fBst\fR(7D)
1150 -.sp
1151 -.LP
1152 -\fI1/4 Inch Tape Drive Tutorial\fR
1176 +.Ed
1177 +.El
1178 +.Sh SEE ALSO
1179 +.Xr mt 1 ,
1180 +.Xr tar 1 ,
1181 +.Xr dd 1M ,
1182 +.Xr open 2 ,
1183 +.Xr read 2 ,
1184 +.Xr write 2 ,
1185 +.Xr aioread 3C ,
1186 +.Xr aiowrite 3C ,
1187 +.Xr ar.h 3HEAD ,
1188 +.Xr st 7D
1189 +.Pp
1190 +.%T 1/4 Inch Tape Drive Tutorial
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX