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