diff options
Diffstat (limited to 'usr/src/man/man7i/mtio.7i')
| -rw-r--r-- | usr/src/man/man7i/mtio.7i | 1190 |
1 files changed, 0 insertions, 1190 deletions
diff --git a/usr/src/man/man7i/mtio.7i b/usr/src/man/man7i/mtio.7i deleted file mode 100644 index bea7b77ce6..0000000000 --- a/usr/src/man/man7i/mtio.7i +++ /dev/null @@ -1,1190 +0,0 @@ -.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved -.\" Copyright 2018, Joyent, Inc. -.\" 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. -.\" -.\" 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. -.\" -.\" 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] -.Dd August 28, 2021 -.Dt MTIO 7I -.Os -.Sh NAME -.Nm mtio -.Nd general magnetic tape interface -.Sh SYNOPSIS -.In sys/types.h -.In sys/ioctl.h -.In sys/mtio.h -.Sh DESCRIPTION -1/2", 1/4", 4mm, and 8mm magnetic tape drives all share the same general -character device interface. -.Pp -There are two types of tape records: data records and end-of-file (EOF) -records. -.Sy EOF -records are also known as tape marks and file marks. -A record is separated by interrecord (or tape) gaps on a tape. -.Pp -End-of-recorded-media (EOM) is indicated by two -.Sy EOF -marks on 1/2\(dq tape; by one -.Sy EOF -mark on 1/4\(dq, 4mm, and 8mm cartridge tapes. -.Ss "1/2\(dq Reel Tape" -Data bytes are recorded in parallel onto the 9-track tape. -Since it is a -variable-length tape device, the number of bytes in a physical record may vary. -.Pp -The recording formats available (check specific tape drive) are 800 -.Sy BPI , -1600 -.Sy BPI , -6250 -.Sy BPI , -and data compression. -Actual storage capacity is a function of the recording format and the length of the tape reel. -For example, using a 2400 foot tape, 20 Mbyte can be stored using 800 -.Sy BPI , -40 Mbyte using 1600 -.Sy BPI , -140 Mbyte using 6250 -.Sy BPI , -or up to 700 Mbyte using data compression. -.Ss "1/4\(dq Cartridge Tape" -Data is recorded serially onto 1/4\(dq cartridge tape. -The number of bytes per -record is determined by the physical record size of the device. -The I/O request -size must be a multiple of the physical record size of the device. -For -.Sy QIC-11 , -.Sy QIC-24 , -and -.Sy QIC-150 -tape drives, the block size is 512 bytes. -.Pp -The records are recorded on tracks in a serpentine motion. -As one track is -completed, the drive switches to the next and begins writing in the opposite -direction, eliminating the wasted motion of rewinding. -Each file, including the last, ends with one file mark. -.Pp -Storage capacity is based on the number of tracks the drive is capable of -recording. -For example, 4-track drives can only record 20 Mbyte of data on a -450 foot tape; 9-track drives can record up to 45 Mbyte of data on a tape of -the same length. -.Sy QIC-11 -is the only tape format available for 4-track -tape drives. -In contrast, 9-track tape drives can use either -.Sy QIC-24 -or -.Sy QIC-11 . -Storage capacity is not appreciably affected by using either format. -.Sy QIC-24 -is preferable to -.Sy QIC-11 -because it records a -reference signal to mark the position of the first track on the tape, and each -block has a unique block number. -.Pp -The -.Sy QIC-150 -tape drives require -.Sy DC-6150 -(or equivalent) tape cartridges for writing. -However, they can read other tape cartridges in -.Sy QIC-11 , -.Sy QIC-24 , -or -.Sy QIC-120 -tape formats. -.Ss "8mm Cartridge Tape" -Data is recorded serially onto 8mm helical scan cartridge tape. -Since it is a -variable-length tape device, the number of bytes in a physical record may -vary. -The recording formats available (check specific tape drive) are standard -2Gbyte, 5Gbyte, and compressed format. -.Ss "4mm DAT Tape" -Data is recorded either in Digital Data Storage (DDS) tape format or in Digital -Data Storage, Data Compressed (DDS-DC) tape format. -Since it is a -variable-length tape device, the number of bytes in a physical record may vary. -The recording formats available are standard 2Gbyte and compressed format. -.Ss "Persistent Error Handling" -Persistent error handling is a modification of the current error handling -behaviors, BSD and SVR4. -With persistent error handling enabled, all tape -operations after an error or exception will return immediately with an error. -Persistent error handling can be most useful with asynchronous tape operations -that use the -.Xr aioread 3C -and -.Xr aiowrite 3C -functions. -.Pp -To enable persistent error handling, the ioctl -.Dv MTIOCPERSISTENT -must be issued. -If this ioctl succeeds, then persistent error handling is enabled and -changes the current error behavior. -This ioctl will fail if the device driver -does not support persistent error handling. -.Pp -With persistent error handling enabled, all tape operations after an exception -or error will return with the same error as the first command that failed; the -operations will not be executed. -An exception is some event that might stop -normal tape operations, such as an End Of File (EOF) mark or an End Of Tape -(EOT) mark. -An example of an error is a media error. -The -.Dv MTIOCLRERR -ioctl must be issued to allow normal tape operations to continue and to clear -the error. -.Pp -Disabling persistent error handling returns the error behavior to normal SVR4 -error handling, and will not occur until all outstanding operations are -completed. -Applications should wait for all outstanding operations to complete -before disabling persistent error handling. -Closing the device will also -disable persistent error handling and clear any errors or exceptions. -.Pp -The -.Sx Read Operation -and -.Sx Write Operation -subsections contain more pertinent information regarding persistent error handling. -.Ss "Read Operation" -The -.Xr read 2 -function reads the next record on the tape. -The record size is passed back as the number of bytes read, provided it is not -greater than the number requested. -When a tape mark or end of data is read, a zero byte count is -returned; all successive reads after the zero read will return an error and -.Va errno -will be set to -.Er EIO . -To move to the next file, an -.Dv MTFSF -ioctl can be issued before or after the read causing the error. -This error -handling behavior is different from the older -.Sy BSD -behavior, where another read will fetch the first record of the next tape file. -If the -.Sy BSD -behavior is required, device names containing the letter -.Ql b -(for -.Sy BSD -behavior) in the final component should be used. -If persistent error handling -was enabled with either the BSD or SVR4 tape device behavior, all operations -after this read error will return -.Er EIO -errors until the -.Dv MTIOCLRERR -ioctl is issued. -An -.Dv MTFSF -ioctl can then he issued. -.Pp -Two successful successive reads that both return zero byte counts indicate -.Sy EOM -on the tape. -No further reading should be performed past the -.Sy EOM . -.Pp -Fixed-length I/O tape devices require the number of bytes read to be a multiple -of the physical record size. -For example, 1/4\(dq cartridge tape devices only read -multiples of 512 bytes. -If the blocking factor is greater than 64,512 bytes -(minphys limit), fixed-length I/O tape devices read multiple records. -.Pp -Most tape devices which support variable-length I/O operations may read a range -of 1 to 65,535 bytes. -If the record size exceeds 65,535 bytes, the driver reads -multiple records to satisfy the request. -These multiple records are limited to -65,534 bytes. -Newer variable-length tape drivers may relax the above limitation -and allow applications to read record sizes larger than 65,534. -Refer to the -specific tape driver man page for details. -.Pp -Reading past logical -.Sy EOT -is transparent to the user. -A read operation -should never hit physical EOT. -.Pp -Read requests that are lesser than a physical tape record are not allowed. -Appropriate error is returned. -.Ss "Write Operation" -The -.Xr write 2 -function writes the next record on the tape. -The record has -the same length as the given buffer. -.Pp -Writing is allowed on 1/4" tape at either the beginning of tape or after the -last written file on the tape. -With the Exabyte 8200, data may be appended only -at the beginning of tape, before a filemark, or after the last written file on -the tape. -.Pp -Writing is not so restricted on 1/2\(dq, 4mm, and the other 8mm cartridge tape -drives. -Care should be used when appending files onto 1/2\(dq reel tape devices, -since an extra file mark is appended after the last file to mark the -.Sy EOM . -This extra file mark must be overwritten to prevent the creation of a null file. -To facilitate write append operations, a space to the -.Sy EOM -ioctl is provided. -Care should be taken when overwriting records; the erase head is just -forward of the write head and any following records will also be erased. -.Pp -Fixed-length I/O tape devices require the number of bytes written to be a -multiple of the physical record size. -For example, 1/4\(dq cartridge tape devices -only write multiples of 512 bytes. -.Pp -Fixed-length I/O tape devices write multiple records if the blocking factor is -greater than 64,512 bytes (minphys limit). -These multiple writes are limited to -64,512 bytes. -For example, if a write request is issued for 65,536 bytes using -a 1/4\(dq cartridge tape, two writes are issued; the first for 64,512 bytes and -the second for 1024 bytes. -.Pp -Most tape devices which support variable-length I/O operations may write a -range of 1 to 65,535 bytes. -If the record size exceeds 65,535 bytes, the driver -writes multiple records to satisfy the request. -These multiple records are -limited to 65,534 bytes. -As an example, if a write request for 65,540 bytes is -issued, two records are written; one for 65,534 bytes followed by another -record for 6 bytes. -Newer variable-length tape drivers may relax the above -limitation and allow applications to write record sizes larger than 65,534. -effer to the specific tape driver man page for details. -.Pp -When logical -.Sy EOT -is encountered during a write, that write operation -completes and the number of bytes successfully transferred is returned (note -that a 'short write' may have occurred and not all the requested bytes would -have been transferred. -The actual amount of data written will depend on the -type of device being used). -The next write will return a zero byte count. -A third write will successfully transfer some bytes (as indicated by the -returned byte count, which again could be a short write); the fourth will -transfer zero bytes, and so on, until the physical -.Sy EOT -is reached and all writes will -fail with -.Er EIO . -.Pp -When logical -.Sy EOT -is encountered with persistent error handling enabled, -the current write may complete or be a short write. -The next write will return a zero byte count. -At this point an application should act appropriately for -end of tape cleanup or issue yet another write, which will return the error -.Er ENOSPC . -After clearing the exception with -.Dv MTIOCLRERR , -the next write will succeed (possibly short), followed by another zero byte -write count, and then another -.Er ENOSPC -error. -.Pp -Allowing writes after -.Sy EOT -has been encountered enables the flushing of buffers. -However, it is strongly recommended to terminate the writing and close -the file as soon as possible. -.Pp -Seeks are ignored in tape I/O. -.Ss "Close Operation" -Magnetic tapes are rewound when closed, except when the "no-rewind" devices -have been specified. -The names of no-rewind device files use the letter -.Ql n -as the end of the final component. -The no-rewind version of -.Pa /dev/rmt/0l -is -.Pa /dev/rmt/0ln . -In case of error for a no-rewind device, the next open rewinds the device. -.Pp -If the driver was opened for reading and a no-rewind device has been specified, -the close advances the tape past the next filemark (unless the current file -position is at -.Sy EOM ) , -leaving the tape correctly positioned to read the first record of the next file. -However, if the tape is at the first record of a -file it doesn't advance again to the first record of the next file. -These semantics are different from the older -.Sy BSD -behavior. -If -.Sy BSD -behavior is required where no implicit space operation is executed on close, -the non-rewind device name containing the letter -.Ql b -(for -.Sy BSD -behavior) in the final component should be specified. -.Pp -If data was written, a file mark is automatically written by the driver upon -close. -If the rewinding device was specified, the tape will be rewound after -the file mark is written. -If the user wrote a file mark prior to closing, then -no file mark is written upon close. -If a file positioning ioctl, like rewind, -is issued after writing, a file mark is written before repositioning the tape. -.Pp -All buffers are flushed on closing a tape device. -Hence, it is strongly recommended that the application wait for all buffers to -be flushed before closing the device. -This can be done by writing a filemark via -.Dv MTWEOF , -even with a zero count. -.Pp -Note that for 1/2\(dq reel tape devices, two file marks are written to mark the -.Sy EOM -before rewinding or performing a file positioning ioctl. -If the user -wrote a file mark before closing a 1/2\(dq reel tape device, the driver will -always write a file mark before closing to insure that the end of recorded -media is marked properly. -If the non-rewinding device was specified, two file -marks are written and the tape is left positioned between the two so that the -second one is overwritten on a subsequent -.Xr open 2 -and -.Xr write 2 . -.Pp -If no data was written and the driver was opened for -.Sy WRITE-ONLY -access, one or two file marks are written, thus creating a null file. -.Pp -After closing the device, persistent error handling will be disabled and any -error or exception will be cleared. -.Sh IOCTLS -Not all devices support all -.Sy ioctls . -The driver returns an -.Er ENOTTY -error on unsupported ioctls. -.Pp -The following structure definitions for magnetic tape -.Xr ioctl 2 -commands are from -.In sys/mtio.h . -.Pp -The minor device byte structure is: -.Bd -literal -15 7 6 5 4 3 2 1 0 -________________________________________________________________________ -Unit # BSD Reserved Density Density No rewind Unit # -Bits 7-15 behavior Select Select on Close Bits 0-1 -.Ed -.Bd -literal -/* - * Layout of minor device byte: - */ -#define MTUNIT(dev) (((minor(dev) & 0xff80) >> 5) + (minor(dev) & 0x3)) -#define MT_NOREWIND (1 <<2) -#define MT_DENSITY_MASK (3 <<3) -#define MT_DENSITY1 (0 <<3) /* Lowest density/format */ -#define MT_DENSITY2 (1 <<3) -#define MT_DENSITY3 (2 <<3) -#define MT_DENSITY4 (3 <<3) /* Highest density/format */ -#define MTMINOR(unit) (((unit & 0x7fc) << 5) + (unit & 0x3)) -#define MT_BSD (1 <<6) /* BSD behavior on close */ - -/* Structure for MTIOCTOP - magnetic tape operation command */ - -struct mtop { - short mt_op; /* operation */ - daddr_t mt_count; /* number of operations */ -}; - -/* Structure for MTIOCLTOP - magnetic tape operation command */ -Works exactly like MTIOCTOP except passes 64 bit mt_count values. -struct mtlop { - short mt_op; - short pad[3]; - int64_t mt_count; -}; -.Ed -.Pp -The following operations of -.Dv MTIOCTOP -and -.Dv MTIOCLTOP -ioctls are supported: -.Pp -.Bl -tag -width MTIOCGETERROR -compact -offset 2n -.It Dv MTWEOF -Write an end-of-file record -.It Dv MTFSF -Forward space over file mark -.It Dv MTBSF -Backward space over file mark (1/2", 8mm only) -.It Dv MTFSR -Forward space to inter-record gap -.It Dv MTBSR -Backward space to inter-record gap -.It Dv MTREW -Rewind -.It Dv MTOFFL -Rewind and take the drive off-line -.It Dv MTNOP -No operation, sets status only -.It Dv MTRETEN -Retension the tape (cartridge tape only) -.It Dv MTERASE -Erase the entire tape and rewind -.It Dv MTEOM -Position to EOM -.It Dv MTNBSF -Backward space file to beginning of file -.It Dv MTSRSZ -Set record size -.It Dv MTGRSZ -Get record size -.It Dv MTTELL -Get current position -.It Dv MTSEEK -Go to requested position -.It Dv MTFSSF -Forward to requested number of sequential file marks -.It Dv MTBSSF -Backward to requested number of sequential file marks -.It Dv MTLOCK -Prevent media removal -.It Dv MTUNLOCK -Allow media removal -.It Dv MTLOAD -Load the next tape cartridge into the tape drive -.It Dv MTIOCGETERROR -Retrieve error records from the st driver -.El -.Bd -literal -offset 2n -/* structure for MTIOCGET - magnetic tape get status command */ - -struct mtget { - short mt_type; /* type of magtape device */ - - /* the following two registers are device dependent */ - short mt_dsreg; /* "drive status" register */ - short mt_erreg; /* "error" register */ - - /* optional error info. */ - daddr_t mt_resid; /* residual count */ - daddr_t mt_fileno; /* file number of current position */ - daddr_t mt_blkno; /* block number of current position */ - ushort_t mt_flags; - short mt_bf; /* optimum blocking factor */ -}; - -/* structure for MTIOCGETDRIVETYPE - get tape config data command */ -struct mtdrivetype_request { - int size; - struct mtdrivetype *mtdtp; -}; -struct mtdrivetype { - char name[64]; /* Name, for debug */ - char vid[25]; /* Vendor id and product id */ - char type; /* Drive type for driver */ - int bsize; /* Block size */ - int options; /* Drive options */ - int max_rretries; /* Max read retries */ - int max_wretries; /* Max write retries */ - uchar_t densities[MT_NDENSITIES]; /* density codes,low->hi */ - uchar_t default_density; /* Default density chosen */ - uchar_t speeds[MT_NSPEEDS]; /* speed codes, low->hi */ - ushort_t non_motion_timeout; /* Seconds for non-motion */ - ushort_t io_timeout; /* Seconds for data to from tape */ - ushort_t rewind_timeout; /* Seconds to rewind */ - ushort_t space_timeout; /* Seconds to space anywhere */ - ushort_t load_timeout; /* Seconds to load tape and ready */ - ushort_t unload_timeout; /* Seconds to unload */ - ushort_t erase_timeout; /* Seconds to do long erase */ -}; -.Ed -.Bd -literal -offset 2n -/* structure for MTIOCGETPOS and MTIOCRESTPOS - get/set tape position */ -/* - * eof/eot/eom codes. - */ - typedef enum { - ST_NO_EOF, - ST_EOF_PENDING, /* filemark pending */ - ST_EOF, /* at filemark */ - ST_EOT_PENDING, /* logical eot pend. */ - ST_EOT, /* at logical eot */ - ST_EOM, /* at physical eot */ - ST_WRITE_AFTER_EOM /* flag allowing writes after EOM */ -} pstatus; - -typedef enum { invalid, legacy, logical } posmode; - -typedef struct tapepos { - uint64_t lgclblkno; /* Blks from start of partition */ - int32_t fileno; /* Num. of current file */ - int32_t blkno; /* Blk number in current file */ - int32_t partition; /* Current partition */ - pstatus eof; /* eof states */ - posmode pmode; /* which pos. data is valid */ - char pad[4]; -} tapepos_t; -.Ed -.Pp -.Bd -ragged -compact -If the -.Fa pmode -is legacy, -.Fa fileno -and -.Fa blkno -fields are valid. -.Pp -If the -.Fa pmode -is logical, -.Fa lgclblkno -field is valid. -.Ed -.Pp -The -.Dv MTWEOF -ioctl is used for writing file marks to tape. -Not only does -this signify the end of a file, but also usually has the side effect of -flushing all buffers in the tape drive to the tape medium. -A zero count -.Dv MTWEOF -will just flush all the buffers and will not write any file marks. -Because a successful completion of this tape operation will guarantee that all -tape data has been written to the tape medium, it is recommended that this tape -operation be issued before closing a tape device. -.Pp -When spacing forward over a record (either data or -.Sy EOF ) , -the tape head is -positioned in the tape gap between the record just skipped and the next record. -When spacing forward over file marks (EOF records), the tape head is positioned -in the tape gap between the next -.Sy EOF -record and the record that follows it. -.Pp -When spacing backward over a record (either data or -.Sy EOF ) , -the tape head is positioned in the tape gap immediately preceding the tape -record where the tape head is currently positioned. -When spacing backward over file marks (EOF records), the tape head is -positioned in the tape gap preceding the -.Sy EOF . -Thus the next read would fetch the -.Sy EOF . -.Pp -Record skipping does not go past a file mark; file skipping does not go past -the -.Sy EOM . -After an -.Dv MTFSR -<huge number> command, the driver leaves -the tape logically positioned -.Em before -the -.Sy EOF . -A related feature is that -.Sy EOF Ns s -remain pending until the tape is closed. -For example, a program -which first reads all the records of a file up to and including the \fBEOF\fR -and then performs an -.Dv MTFSF -command will leave the tape positioned just -after that same -.Sy EOF , -rather than skipping the next file. -.Pp -The -.Dv MTNBSF -and -.Dv MTFSF -operations are inverses. -Thus, an -.Dq Dv MTFSF \(mi1 -is equivalent to an -.Dq Dv MTNBSF 1 . -An -.Dq Dv MTNBSF 0 -is the same as -.Dq Dv MTFSF 0 ; -both position the tape device at the beginning of the current file. -.Pp -.Dv MTBSF -moves the tape backwards by file marks. -The tape position will end -on the beginning of the tape side of the desired file mark. -An -.Dq Dv MTBSF 0 -will position the tape at the end of the current file, before the filemark. -.Pp -.Dv MTBSR -and -.Dv MTFSR -operations perform much like space file operations, -except that they move by records instead of files. -Variable-length I/O devices -(1/2\(dq reel, for example) space actual records; fixed-length I/O devices space -physical records (blocks). -1/4\(dq cartridge tape, for example, spaces 512 byte -physical records. -The status ioctl residual count contains the number of files -or records not skipped. -.Pp -.Dv MTFSSF -and -.Dv MTBSSF -space forward or backward, respectively, to the next -occurrence of the requested number of file marks, one following another. -If there are more sequential file marks on tape than were requested, it spaces -over the requested number and positions after the requested file mark. -Note that not all drives support this command and if a request is sent to a -drive that does not, -.Er ENOTTY -is returned. -.Pp -.Dv MTOFFL -rewinds and, if appropriate, takes the device off-line by unloading the tape. -It is recommended that the device be closed after offlining -and then re-opened after a tape has been inserted to facilitate portability to -other platforms and other operating systems. -Attempting to re-open the device -with no tape will result in an error unless the -.Dv O_NDELAY -flag is used. -.Po -See -.Xr open 2 . -.Pc -.Pp -The -.Dv MTRETEN -retension ioctl applies only to 1/4\(dq cartridge tape devices. -It is used to restore tape tension, improving the tape's soft error rate after -extensive start-stop operations or long-term storage. -.Pp -.Dv MTERASE -rewinds the tape, erases it completely, and returns to the -beginning of tape. -Erasing may take a long time depending on the device and/or -tapes. -For time details, refer to the drive specific manual. -.Pp -.Dv MTEOM -positions the tape at a location just after the last file written -on the tape. -For 1/4\(dq cartridge and 8mm tape, this is after the last file mark -on the tape. -For 1/2\(dq reel tape, this is just after the first file mark but -before the second (and last) file mark on the tape. -Additional files can then -be appended onto the tape from that point. -.Pp -Note the difference between -.Dv MTBSF -(backspace over file mark) and -.Dv MTNBSF -(backspace file to beginning of file). -The former moves the tape -backward until it crosses an -.Sy EOF -mark, leaving the tape positioned -.Em before -the file mark. -The latter leaves the tape positioned -.Em after -the file mark. -Hence, -.Dq Dv MTNBSF n -is equivalent to -.Dq Dv MTBSF (n+1) -followed by -.Dq Dv MTFSF 1 . -The 1/4\(dq cartridge tape devices do not support -.Dv MTBSF . -.Pp -.Dv MTSRSZ -and -.Dv MTGRSZ -are used to set and get fixed record lengths. -The -.Dv MTSRSZ -ioctl allows variable length and fixed length tape drives that -support multiple record sizes to set the record length. -The -.Fa mt_count -field of the -.Vt mtop -struct is used to pass the record size to/from the -.Xr st 7D -driver. -A value of -.Ql 0 -indicates variable record size. -The -.Dv MTSRSZ -ioctl makes a variable-length tape device behave like a -fixed-length tape device. -Refer to the specific tape driver man page for -details. -.Pp -.Dv MTLOAD -loads the next tape cartridge into the tape drive. -This is generally only used with stacker and tower type tape drives which handle -multiple tapes per tape drive. -A tape device without a tape inserted can be -opened with the -.Dv O_NDELAY -flag, in order to execute this operation. -.Pp -.Dv MTIOCGETERROR -allows user-level applications to retrieve error records -from the -.Xr st 7D -driver. -An error record consists of the SCSI command cdb -which causes the error and a -.Xr scsi_arq_status 9S -structure if available. -The user-level application is responsible for allocating and releasing the -memory for -.Fa mtee_cdb_buf -and -.Fa scsi_arq_status of each -.Vt mterror_entry . -Before issuing the ioctl, the -.Fa mtee_arq_status_len -value should be at least equal to -.Ql sizeof (struct scsi_arq_status) . -If more sense data than the size of -.Xr scsi_arq_status 9S -is desired, the -.Fa mtee_arq_status_len -may be larger than -.Ql sizeof (struct scsi_arq_status) -by the amount of additional extended sense data desired. -The -.Fa es_add_len -field of -.Xr scsi_extended_sense 9S -can be used to determine the amount of valid sense data returned by the device. -.Pp -The -.Dv MTIOCGET -get status -.Xr ioctl 2 -call returns the drive ID -.Pq Fa mt_type , -sense key error -.Pq Fa mt_erreg , -file number -.Pq Fa mt_fileno , -optimum blocking factor -.Pq Fa mt_bf -and record number -.Pq Fa mt_blkno -of the last error. -The residual count -.Pq Fa mt_resid -is set to the number of bytes not transferred or files/records not spaced. -The flags word -.Pq Fa mt_flags -contains information indicating if the device is SCSI, if the device is a reel -device and whether the device supports absolute file positioning. -The -.Fa mt_flags -also indicates if the device is requesting cleaning media be used, whether the -device is capable of reporting the requirement of cleaning media and if the -currently loaded media is WORM (Write Once Read Many) media. -.Pp -Note \(em When tape alert cleaning is managed by the st driver, the tape -target driver may continue to return a -.Dq drive needs cleaning -status unless an -.Dv MTIOCGE -.Xr ioctl 2 -call is made while the cleaning media is in the drive. -.Pp -The -.Dv MTIOCGETDRIVETYPE -get drivetype ioctl call returns the name of the -tape drive as defined in -.Pa st.conf -.Pq Fa name , -Vendor -.Sy ID -and model -.Pq Fa product , -.Sy ID -.Pq Fa vid , -type of tape device -.Pq Fa type , -block size -.Pq Fa size , -drive options -.Pq Fa options , -maximum read retry count -.Pq Fa max_rretries , -maximum write retry count -.Pq Fa max_wretries , -densities supported by the drive -.Pq Fa densities , -and default density of the tape drive -.Pq Fa default_density . -.Pp -The -.Dv MTIOCGETPOS -ioctl returns the current tape position of the drive. -It is returned in struct tapepos as defined in -.Pa /usr/include/sys/scsi/targets/stdef.h . -.Pp -The -.Dv MTIOCRESTPOS -ioctl restores a saved position from the -.Dv MTIOCGETPOS . -.Ss "Persistent Error Handling IOCTLs and Asynchronous Tape Operations" -.Bl -tag -width MTIOCPERSISTENTSTATUS -compact -.It Dv MTIOCPERSISTENT -enables/disables persistent error handling -.It Dv MTIOCPERSISTENTSTATUS -queries for persistent error handling -.It Dv MTIOCLRERR -clears persistent error handling -.It Dv MTIOCGUARANTEEDORDER -checks whether driver guarantees order of I/O's -.El -.Pp -The -.Dv MTIOCPERSISTENT -ioctl enables or disables persistent error handling. -It takes as an argument a pointer to an integer that turns it either on or off. -If the ioctl succeeds, the desired operation was successful. -It will wait for -all outstanding I/O's to complete before changing the persistent error handling -status. -For example, -.Bd -literal -offset 2n -int on = 1; -ioctl(fd, MTIOCPERSISTENT, &on); -int off = 0; -ioctl(fd, MTIOCPERSISTENT, &off); -.Ed -.Pp -The -.Dv MTIOCPERSISTENTSTATUS -ioctl enables or disables persistent error -handling. -It takes as an argument a pointer to an integer inserted by the -driver. -The integer can be either 1 if persistent error handling is -.Sq on , -or 0 if persistent error handling is -.Sq off . -It will not wait for outstanding I/O's. -For example, -.Bd -literal -offset 2n -int query; -ioctl(fd, MTIOCPERSISTENTSTATUS, &query); -.Ed -.Pp -The -.Dv MTIOCLRERR -ioctl clears persistent error handling and allows tape -operations to continual normally. -This ioctl requires no argument and will -always succeed, even if persistent error handling has not been enabled. -It will wait for any outstanding I/O's before it clears the error. -.Pp -The -.Dv MTIOCGUARANTEEDORDER -ioctl is used to determine whether the driver -guarantees the order of I/O's. -It takes no argument. -If the ioctl succeeds, the driver will support guaranteed order. -If the driver does not support guaranteed order, then it should not be used -for asynchronous I/O with -.Xr libaio 3lib . -It will wait for any outstanding I/O's before it returns. -For example, -.Bd -literal -offset 2n -ioctl(fd, MTIOCGUARANTEEDORDER) -.Ed -.Pp -See the -.Sx Persistent Error Handling -subsection above for more information on persistent error handling. -.Ss "Asynchronous and State Change IOCTLS" -.Bl -tag -width 1n -.It Dv MTIOCSTATE -This ioctl blocks until the state of the drive, inserted or ejected, is -changed. -The argument is a pointer to a -.Vt enum mtio_state , -whose possible enumerations are listed below. -The initial value should be either the last reported state of the drive, or -.Dv MTIO_NONE . -Upon return, the -enum pointed to by the argument is updated with the current state of the drive. -.Bd -literal -offset 2n -enum mtio_state { - MTIO_NONE /* Return tape's current state */ - MTIO_EJECTED /* Tape state is "ejected" */ - MTIO_INSERTED /* Tape state is "inserted" */ -}; -.Ed -.El -.Pp -When using asynchronous operations, most ioctls will wait for all outstanding -commands to complete before they are executed. -.Ss "IOCTLS for Multi-initiator Configurations" -.Bl -tag -width MTIOCFORCERESERVE -compact -.It Dv MTIOCRESERVE -reserve the tape drive -.It Dv MTIOCRELEASE -revert back to the default behavior of reserve on open/release on close -.It Dv MTIOCFORCERESERVE -reserve the tape unit by breaking reservation held by another host -.El -.Pp -The -.Dv MTIOCRESERVE -ioctl reserves the tape drive such that it does not -release the tape drive at close. -This changes the default behavior of releasing the device upon close. -Reserving the tape drive that is already reserved has no effect. -For example, -.Bd -literal -offset 2n -ioctl(fd, MTIOCRESERVE); -.Ed -.Pp -The -.Dv MTIOCRELEASE -ioctl reverts back to the default behavior of reserve on -open/release on close operation, and a release will occur during the next -close. -Releasing the tape drive that is already released has no effect. -For example, -.Bd -literal -offset 2n -ioctl(fd, MTIOCRELEASE); -.Ed -.Pp -The -.Dv MTIOCFORCERESERVE -ioctl breaks a reservation held by another host, interrupting any I/O in -progress by that other host, and then reserves the tape unit. -This ioctl can be executed only with super-user privileges. -It is recommended to open the tape device in -.Dv O_NDELAY -mode when this ioctl needs to be executed, otherwise the open will fail if -another host indeed has it reserved. -For example, -.Bd -literal -offset 2n -ioctl(fd, MTIOCFORCERESERVE); -.Ed -.Ss "IOCTLS for Handling Tape Configuration Options" -.Bl -tag -width MTIOCREADIGNOREEOFS -.It Dv MTIOCSHORTFMK -enables/disables support for writing short filemarks. -This is specific to Exabyte drives. -.It Dv MTIOCREADIGNOREILI -enables/disables suppress incorrect length indicator (SILI) support during reads -.It Dv MTIOCREADIGNOREEOFS -enables/disables support for reading past two EOF marks which otherwise indicate -End-Of-recording-Media (EOM) in the case of 1/2\(dq reel tape drives -.El -.Pp -The -.Dv MTIOCSHORTFMK -ioctl enables or disables support for short filemarks. -This ioctl is only applicable to Exabyte drives which support short filemarks. -As an argument, it takes a pointer to an integer. -If 0 (zero) is the specified integer, then long filemarks will be written. -If 1 is the specified integer, then short filemarks will be written. -The specified tape behavior will be in effect until the device is closed. -.Pp -For example: -.Bd -literal -offset 2n -int on = 1; -int off = 0; -/* enable short filemarks */ -ioctl(fd, MTIOSHORTFMK, &on); -/* disable short filemarks */ -ioctl(fd, MTIOCSHORTFMK, &off); -.Ed -.Pp -Tape drives which do not support short filemarks will return an -.Va errno -of -.Er ENOTTY . -.Pp -The -.Dv MTIOCREADIGNOREILI -ioctl enables or disables the suppress incorrect -length indicator (SILI) support during reads. -As an argument, it takes a pointer to an integer. -If 0 (zero) is the specified integer, SILI will not be -used during reads and incorrect length indicator will not be suppressed. -If 1 is the specified integer, SILI will be used during reads and incorrect -length indicator will be suppressed. -The specified tape behavior will be in effect until the device is closed. -.Pp -For example: -.Bd -literal -offset 2n -int on = 1; -int off = 0; -ioctl(fd, MTIOREADIGNOREILI, &on); -ioctl(fd, MTIOREADIGNOREILI, &off); -.Ed -.Pp -The -.Dv MTIOCREADIGNOREEOFS -ioctl enables or disables support for reading -past double EOF marks which otherwise indicate End-Of-recorded-media (EOM) in -the case of 1/2\(dq reel tape drives. -As an argument, it takes a pointer to an integer. -If 0 (zero) is the specified integer, then double EOF marks indicate -End-Of-recorded-media (EOM). -If 1 is the specified integer, the double EOF marks no longer indicate EOM, -thus allowing applications to read past two EOF marks. -In this case it is the responsibility of the application to detect -End-Of-recorded-media (EOM). -The specified tape behavior will be in effect until the device is closed. -.Pp -For example: -.Bd -literal -offset 2n -int on = 1; -int off = 0; -ioctl(fd, MTIOREADIGNOREEOFS, &on); -ioctl(fd, MTIOREADIGNOREEOFS, &off); -.Ed -.Pp -Tape drives other than 1/2\(dq reel tapes will return an -.Va errno -of -.Er ENOTTY . -.Sh FILES -.Pa /dev/rmt/ Ns Ao unit number Ac \ - Ns Ao density Ac \ - Ns Bo Ao BSD behavior Ac Bc \ - Ns Bo Ao no rewind Ac Bc -.Pp -Where -.Aq density -can be -.Ql l , -.Ql m , -.Ql h , -.Ql u/c -(low, medium, high, ultra/compressed, respectively), the -.Aq BSD behavior -option is -.Ql b , and the -.Aq no rewind -option is -.Ql n . -.Pp -For example, -.Pa /dev/rmt/0hbn -specifies unit 0, high density, -.Sy BSD -behavior and no rewind. -.Sh EXAMPLES -.Bl -inset -.It Sy Example 1 -Tape Positioning and Tape Drives -.Pp -Suppose you have written three files to the non-rewinding 1/2\(dq tape device, -.Pa /dev/rmt/0ln , -and that you want to go back and -.Xr dd 1M -the second file off the tape. -The commands to do this are: -.Bd -literal -offset 2n -mt -F /dev/rmt/0lbn bsf 3 -mt -F /dev/rmt/0lbn fsf 1 -dd if=/dev/rmt/0ln -.Ed -.Pp -To accomplish the same tape positioning in a C program, followed by a get -status ioctl: -.Bd -literal -offset 2n -struct mtop mt_command; -struct mtget mt_status; -mt_command.mt_op = MTBSF; -mt_command.mt_count = 3; -ioctl(fd, MTIOCTOP, &mt_command); -mt_command.mt_op = MTFSF; -mt_command.mt_count = 1; -ioctl(fd, MTIOCTOP, &mt_command); -ioctl(fd, MTIOCGET, (char *)&mt_status); -.Ed -.Pp -or -.Bd -literal -offset 2n -mt_command.mt_op = MTNBSF; -mt_command.mt_count = 2; -ioctl(fd, MTIOCTOP, &mt_command); -ioctl(fd, MTIOCGET, (char *)&mt_status); -.Ed -.Pp -To get information about the tape drive: -.Bd -literal -offset 2n -struct mtdrivetype mtdt; -struct mtdrivetype_request mtreq; -mtreq.size = sizeof(struct mtdrivetype); -mtreq.mtdtp = &mtdt; -ioctl(fd, MTIOCGETDRIVETYPE, &mtreq); -.Ed -.El -.Sh SEE ALSO -.Xr mt 1 , -.Xr tar 1 , -.Xr dd 1M , -.Xr open 2 , -.Xr read 2 , -.Xr write 2 , -.Xr aioread 3C , -.Xr aiowrite 3C , -.Xr ar.h 3HEAD , -.Xr st 7D -.Pp -.%T 1/4 Inch Tape Drive Tutorial |