1 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
   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
  28 1/2", 1/4", 4mm, and 8mm magnetic tape drives all share the same general
  29 character device interface.
  30 .Pp
  31 There are two types of tape records: data records and end-of-file (EOF)
  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

 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
 157 Disabling persistent error handling returns the error behavior to normal SVR4
 158 error handling, and will not occur until all outstanding operations are
 159 completed.
 160 Applications should wait for all outstanding operations to complete
 161 before disabling persistent error handling.
 162 Closing the device will also
 163 disable persistent error handling and clear any errors or exceptions.
 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
 177 returned; all successive reads after the zero read will return an error and
 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
 196 was enabled with either the BSD or SVR4 tape device behavior, all operations
 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
 206 Two successful successive reads that both return zero byte counts indicate
 207 .Sy EOM
 208 on the tape.
 209 No further reading should be performed past the
 210 .Sy EOM .
 211 .Pp
 212 Fixed-length I/O tape devices require the number of bytes read to be a multiple
 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
 217 (minphys limit), fixed-length I/O tape devices read multiple records.
 218 .Pp
 219 Most tape devices which support variable-length I/O operations may read a range
 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.

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
1070 For example:
1071 .Bd -literal -offset 2n
1072 int on = 1;
1073 int off = 0;
1074 ioctl(fd, MTIOREADIGNOREILI, &on);
1075 ioctl(fd, MTIOREADIGNOREILI, &off);
1076 .Ed
1077 .Pp
1078 The
1079 .Dv MTIOCREADIGNOREEOFS
1080 ioctl enables or disables support for reading
1081 past double EOF marks which otherwise indicate End-Of-recorded-media (EOM) in
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
1092 For example:
1093 .Bd -literal -offset 2n
1094 int on = 1;
1095 int off = 0;
1096 ioctl(fd, MTIOREADIGNOREEOFS, &on);
1097 ioctl(fd, MTIOREADIGNOREEOFS, &off);
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 \

   1 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
   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 February 17, 2020
  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
  28 1/2", 1/4", 4mm, and 8mm magnetic tape drives all share the same general
  29 character device interface.
  30 .Pp
  31 There are two types of tape records: data records and end-of-file (EOF)
  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

 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
 157 Disabling persistent error handling returns the error behavior to normal SVR4
 158 error handling, and will not occur until all outstanding operations are
 159 completed.
 160 Applications should wait for all outstanding operations to complete
 161 before disabling persistent error handling.
 162 Closing the device will also
 163 disable persistent error handling and clear any errors or exceptions.
 164 .Pp
 165 The
 166 .Sx Read Operation
 167 and
 168 .Sx Write Operation
 169 subsections contain more pertinent information regarding 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
 177 returned; all successive reads after the zero read will return an error and
 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
 196 was enabled with either the BSD or SVR4 tape device behavior, all operations
 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 be issued.
 205 .Pp
 206 Two successful successive reads that both return zero byte counts indicate
 207 .Sy EOM
 208 on the tape.
 209 No further reading should be performed past the
 210 .Sy EOM .
 211 .Pp
 212 Fixed-length I/O tape devices require the number of bytes read to be a multiple
 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
 217 (minphys limit), fixed-length I/O tape devices read multiple records.
 218 .Pp
 219 Most tape devices which support variable-length I/O operations may read a range
 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.

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
1070 For example:
1071 .Bd -literal -offset 2n
1072 int on = 1;
1073 int off = 0;
1074 ioctl(fd, MTIOREADIGNOREILI, &on);
1075 ioctl(fd, MTIOREADIGNOREILI, &off);
1076 .Ed
1077 .Pp
1078 The
1079 .Dv MTIOCREADIGNOREEOFS
1080 ioctl enables or disables support for reading
1081 past double EOF marks which otherwise indicate End-Of-recorded-media (EOM) in
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-recorded-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
1092 For example:
1093 .Bd -literal -offset 2n
1094 int on = 1;
1095 int off = 0;
1096 ioctl(fd, MTIOREADIGNOREEOFS, &on);
1097 ioctl(fd, MTIOREADIGNOREEOFS, &off);
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 \