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