MTIO man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

MTIO(7I)							      MTIO(7I)

NAME
       mtio - general magnetic tape interface

SYNOPSIS
       #include <sys/types.h>
       #include <sys/ioctl.h>
       #include <sys/mtio.h>

DESCRIPTION
       1/2",  1/4",  4mm, and 8mm magnetic tape drives all share the same gen‐
       eral character device interface.

       There are two types of tape records: data records and end-of-file (EOF)
       records.	 SEOF  records	are also known as tape marks and file marks. A
       record is separated by interrecord (or tape) gaps on a tape.

       End-of-recorded-media (EOM) is indicated by two EOF marks on 1/2" tape;
       by one EOF mark on 1/4", 4mm, and 8mm cartridge tapes.

   1/2 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.

       The  recording  formats	available  (check specific tape drive) are 800
       BPI, 1600 BPI, 6250 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
       BPI,  40	 Mbyte	using 1600 BPI, 140 Mbyte using 6250 BPI, or up to 700
       Mbyte using data compression.

   1/4 Cartridge Tape"
       Data is recorded serially onto 1/4" 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 QIC-11, QIC-24, and QIC-150 tape drives, the block size is
       512 bytes.

       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.

       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.  QIC-11  is  the  only  tape	format
       available for 4-track tape drives. In contrast, 9-track tape drives can
       use either QIC-24  or  QIC-11.  Storage	capacity  is  not  appreciably
       affected by using either format. QIC-24 is preferable to 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.

       The QIC-150 tape drives require DC-6150 (or equivalent) tape cartridges
       for writing. However, they can read other tape  cartridges  in  QIC-11,
       QIC-24, or QIC-120 tape formats.

   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.

   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.

   Persistent Error Handling
       Persistent error handling is a modification of the current  error  han‐
       dling  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 asyn‐
       chronous tape operations that  use  the	aioread(3C)  and  aiowrite(3C)
       functions.

       To  enable persistent error handling, the ioctl 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.

       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 MTIOCLRERR ioctl must be issued to allow normal tape
       operations to continue and to clear the error.

       Disabling persistent error handling returns the error behavior to  nor‐
       mal SVR4 error handling, and will not occur until all outstanding oper‐
       ations 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.

       The  Read Operation and Write Operation subsections contain more perti‐
       nent information reguarding persistent error handling.

   Read Operation
       The 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 errno will be set to EIO. To move to the  next
       file, an MTFSF ioctl can be issued before or after the read causing the
       error. This error handling behavior is different	 from  the  older  BSD
       behavior,  where	 another  read will fetch the first record of the next
       tape file. If the BSD behavior is required, device names containing the
       letter  b  (for 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 EIO
       errors until the MTIOCLRERR ioctl is issued. An MTFSF ioctl can then he
       issued.

       Two successful successive reads that both return zero byte counts indi‐
       cate EOM on the tape. No further reading should be performed  past  the
       EOM.

       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" 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.

       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 multi‐
       ple 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.

       Reading	past  logical EOT is transparent to the user. A read operation
       should never hit physical EOT.

       Read requests that are lesser than  a  physical	tape  record  are  not
       allowed.	 Appropriate error is returned.

   Write Operation
       The  write(2)  function	writes the next record on the tape. The record
       has the same length as the given buffer.

       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.

       Writing	is not so restricted on 1/2", 4mm, and the other 8mm cartridge
       tape drives. Care should be used when appending files  onto  1/2"  reel
       tape  devices, since an extra file mark is appended after the last file
       to mark the 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 EOM ioctl is provided. Care should be taken when overwrit‐
       ing  records;  the erase head is just forward of the write head and any
       following records will also be erased.

       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" cartridge
       tape devices only write multiples of 512 bytes.

       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" cartridge tape, two writes are
       issued; the first for 64,512 bytes and the second for 1024 bytes.

       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  applica‐
       tions to write record sizes larger  than 65,534.	 Refer to the specific
       tape driver man page for details.

       When logical 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 EOT is reached and all writes will fail with EIO.

       When logical 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 ENOSPC. After clearing the exception  with	 MTIO‐
       CLRERR,	the  next  write  will	succeed	 (possibly short), followed by
       another zero byte write count, and then another ENOSPC error.

       Allowing writes after LEOT 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.

       Seeks are ignored in tape I/O.

   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 n as the end of the final component. The  no-rewind  version
       of  /dev/rmt/0l	is  /dev/rmt/0ln.  In  case  of	 error for a no-rewind
       device, the next open rewinds the device.

       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 EOM), leaving the tape correctly	 posi‐
       tioned  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
       BSD behavior. If BSD behavior is required where no implicit space oper‐
       ation  is  executed on close, the non-rewind device name containing the
       letter b (for BSD behavior) in the final component should be specified.

       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.

       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
       MTWEOF, even with a zero count.

       Note that for 1/2" reel tape devices, two file  marks  are  written  to
       mark  the  EOM before rewinding or performing a file positioning ioctl.
       If the user wrote a file mark before closing a 1/2" 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 open(2) and write(2).

       If no data was written and the driver was opened for WRITE-ONLY access,
       one or two file marks are written, thus creating a null file.

       After closing the device, persistent error handling  will  be  disabled
       and any error or exception will be cleared.

IOCTLS
       Not  all devices support all ioctls. The driver returns an ENOTTY error
       on unsupported ioctls.

       The following structure definitions for magnetic	 tape  ioctl  commands
       are from <sys/mtio.h>.

       The minor device byte structure is::

	 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

	 /*
	  * 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;
	 };

       The  following  operations  of  MTIOCTOP	 and MTIOCLTOP ioctls are sup‐
       ported:

       MTWEOF
			write an end-of-file record

       MTFSF
			forward space over file mark

       MTBSF
			backward space over file mark (1/2", 8mm only)

       MTFSR
			forward space to inter-record gap

       MTBSR
			backward space to inter-record gap

       MTREW
			rewind

       MTOFFL
			rewind and take the drive off-line

       MTNOP
			no operation, sets status only

       MTRETEN
			retension the tape (cartridge tape only)

       MTERASE
			erase the entire tape and rewind

       MTEOM
			position to EOM

       MTNBSF
			backward space file to beginning of file

       MTSRSZ
			set record size

       MTGRSZ
			get record size

       MTTELL
			get current position

       MTSEEK
			go to  requested  position

       MTFSSF
			forward to requested number of sequential file marks

       MTBSSF
			backward to requested number of sequential file marks

       MTLOCK
			prevent media removal

       MTUNLOCK
			allow media removal

       MTLOAD
			load the next tape cartridge into the tape drive

       MTIOCGETERROR
			retrieve error records from the st driver

	 /* 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 */
	 };

	 /* structure for MTIOCGETPOS and MTIOCRESTPOS - get/set tape position */
	      /*
	   * eof/eot/eom codes.
	       */
	  typedef enum {
		ST_NO_EOF,
		ST_EOF_PENDING,		/* filemrk 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;

	      If the pmode is legacy,fileno and blkno fields are valid.
	      If the pmode is logical, lgclblkno field is valid.

       The 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
       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.

       When  spacing forward over a record (either data or 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 EOF record and
       the record that follows it.

       When spacing backward over a record (either data or 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 EOF.  Thus the next read would fetch the EOF.

       Record skipping does not go past a file mark; file skipping does not go
       past the EOM. After an MTFSR <huge number> command, the	driver	leaves
       the tape logically positioned before the EOF. A related feature is that
       EOFs 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 EOF
       and then performs an MTFSF command will leave the tape positioned  just
       after that same EOF, rather than skipping the next file.

       The  MTNBSF  and MTFSF operations are inverses. Thus, an " MTFSF −1" is
       equivalent to an " MTNBSF 1". An " MTNBSF 0" is the same as " MTFSF 0";
       both position the tape device at the beginning of the current file.

       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  "
       MTBSF  0" will position the tape at the end of the current file, before
       the filemark.

       MTBSR and MTFSR operations perform much	like  space  file  operations,
       except  that they move by records instead of files. Variable-length I/O
       devices (1/2" reel, for example) space actual records; fixed-length I/O
       devices space physical records (blocks). 1/4" cartridge tape, for exam‐
       ple, spaces 512 byte physical records. The status ioctl residual	 count
       contains the number of files or records not skipped.

       MTFSSF  and 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, ENOTTY is returned.

       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  facili‐
       tate  portability  to  other  platforms	and  other  operating systems.
       Attempting to re-open the device with no tape will result in  an	 error
       unless the O_NDELAY flag is used.  (See open(2).)

       The  MTRETEN  retension	ioctl  applies	only  to  1/4"	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.

       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 the drive specific man‐
       ual.

       MTEOM positions the tape at a location just after the last file written
       on  the	tape.  For 1/4" cartridge and 8mm tape, this is after the last
       file mark on the tape. For 1/2" reel tape, this is just after the first
       file mark but before the second (and last) file mark on the tape. Addi‐
       tional files can then be appended onto the tape from that point.

       Note the difference between MTBSF (backspace over file mark) and MTNBSF
       (backspace  file to beginning of file). The former moves the tape back‐
       ward until it crosses an EOF mark, leaving the tape  positioned	before
       the  file  mark.	 The  latter leaves the tape positioned after the file
       mark. Hence, "MTNBSF n" is equivalent  to  "MTBSF  (n+1)"  followed  by
       "MTFSF 1". The 1/4" cartridge tape devices do not support MTBSF.

       MTSRSZ  and  MTGRSZ  are	 used to set and get fixed record lengths. The
       MTSRSZ ioctl allows variable length and fixed length tape  drives  that
       support	multiple  record  sizes to set the record length. The mt_count
       field of the  mtop struct is used to pass the record size  to/from  the
       st  driver.  A  value  of  0 indicates variable record size. The 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.

       MTLOAD  loads the next tape cartridge into the tape drive. This is gen‐
       erally 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 O_NDELAY flag, in order to execute  this	opera‐
       tion.

       MTIOCGETERROR  allows user-level applications to retrieve error records
       from the st driver. An error record consists of the  SCSI  command  cdb
       which  causes  the  error and a scsi_arq_status(9S) structure if avail‐
       able.  The user-level application is  responsible  for  allocating  and
       releasing the memory for mtee_cdb_buf and scsi_arq_status of each mter‐
       ror_entry. Before issuing  the  ioctl,  the  mtee_arq_status_len	 value
       should  be  at least equal to "sizeof(struct scsi_arq_status)." If more
       sense data  than	 the  size  of	scsi_arq_status(9S)  is	 desired,  the
       mtee_arq_status_len may be larger than "sizeof(struct scsi_arq_status)"
       by  the	amount	of  additional	extended  sense	 data  desired.	   The
       es_add_len  field  of  scsi_extended_sense(9S) can be used to determine
       the amount of valid sense data returned by the device.

       The MTIOCGET get status ioctl call  returns  the	 drive	ID  (mt_type),
       sense  key error (mt_erreg), file  number (mt_fileno), optimum blocking
       factor (mt_bf) and record number (mt_blkno)  of	the  last  error.  The
       residual count (mt_resid) is set to the number of bytes not transferred
       or files/records not spaced. The flags word (mt_flags) contains	infor‐
       mation indicating if the device is SCSI, if the device is a reel device
       and whether the device supports absolute file positioning. The 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.

       Note -

	 When tape alert cleaning is managed by the st driver, the tape target
	 driver	 may continue to return a "drive needs cleaning" status unless
	 an MTIOCGET ioctl() call is made while the cleaning media is  in  the
	 drive.

       The  MTIOCGETDRIVETYPE get drivetype ioctl call returns the name of the
       tape drive as defined in	 st.conf (name), Vendor ID  and	 model	(prod‐
       uct),  ID (vid), type of tape device (type), block size	(bsize), drive
       options	(options), maximum read retry  count  (max_rretries),  maximum
       write  retry  count  (max_wretries),  densities	supported by the drive
       (densities), and default density of the tape drive (default_density).

       The MTIOCGETPOS ioctl returns the current tape position of  the	drive.
       It     is    returned	in    struct	tapepos	   as	 defined    in
       /usr/include/sys/scsi/targets/stdef.h.

       The  MTIOCRESTPOS ioctl restores a saved position from the MTIOCGETPOS.

   Persistent Error Handling IOCTLs and Asynchronous Tape Operations
       MTIOCPERSISTENT
				enables/disables persistent error handling

       MTIOCPERSISTENTSTATUS
				queries for persistent error handling

       MTIOCLRERR
				clears persistent error handling

       MTIOCGUARANTEEDORDER
				checks	whether	 driver	 guarantees  order  of
				I/O's

       The  MTIOCPERSISTENT  ioctl  enables  or disables persistent error han‐
       dling.  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,

	 int on = 1;
	 ioctl(fd, MTIOCPERSISTENT, &on);
	 int off = 0;
	 ioctl(fd, MTIOCPERSISTENT, &off);

       The  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
       'on', or 0 if persistent error handling is 'off'. It will not wait  for
       outstanding I/O's.  For example,

	 int query;
	 ioctl(fd, MTIOCPERSISTENTSTATUS, &query);

       The  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.

       The  MTIOCGUARANTEEDORDER ioctl is used to determine whether the driver
       guarantees the order of I/O's. It takes no argument. If the ioctl  suc‐
       ceeds, 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  libaio.  It  will  wait  for any outstanding I/O's before it
       returns. For example,

	 ioctl(fd, MTIOCGUARANTEEDORDER)

       See the Persistent Error Handling subsection above for more information
       on persistent error handling.

   Asynchronous and State Change IOCTLS
       MTIOCSTATE
		     This  ioctl blocks until the state of the drive, inserted
		     or ejected, is changed. The argument is a	pointer	 to  a
		     mtio_state,  enum, whose possible enumerations are listed
		     below. The	 initial  value	 should	 be  either  the  last
		     reported  state  of the drive, or MTIO_NONE. Upon return,
		     the enum pointed to by the argument is updated  with  the
		     current state of the drive.

	 enum mtio_state {
	 MTIO_NONE	/* Return tape's current state */
	 MTIO_EJECTED	/* Tape state is "ejected" */
	 MTIO_INSERTED	/* Tape state is "inserted" */
	 ;

       When  using asynchronous operations, most ioctls will wait for all out‐
       standing commands to complete before they are executed.

   IOCTLS for Multi-initiator Configurations
       MTIOCRESERVE
			    reserve the tape drive

       MTIOCRELEASE
			    revert back to the default behavior of reserve  on
			    open/release on close

       MTIOCFORCERESERVE
			    reserve the tape unit by breaking reservation held
			    by another host

       The 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,

       ioctl(fd, MTIOCRESERVE);

       The  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,

       ioctl(fd, MTIOCRELEASE);

       The 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	privi‐
       leges.  It is recommended to open the tape device in O_NDELAY mode when
       this ioctl needs to be  executed,  otherwise  the  open	will  fail  if
       another host indeed has it reserved. For example,

	 ioctl(fd, MTIOCFORCERESERVE);

   IOCTLS for Handling Tape Configuration Options
       MTIOCSHORTFMK
			      enables/disable  support for writing short file‐
			      marks. This is specific to Exabyte drives.

       MTIOCREADIGNOREILI
			      enables/disable supress incorrect length indica‐
			      tor support during reads

       MTIOCREADIGNOREEOFS
			      enables/disable support for reading past two EOF
			      marks which otherwise indicate End-Of-recording-
			      Media (EOM) in the case of 1/2" reel tape drives

       The  MTIOCSHORTFMK  ioctl  enables  or disables support for short file‐
       marks.  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 bahavior will be  in	effect	until  the  device  is
       closed.

       For example:

	 int on = 1;
	 int off = 0;
	 /* enable short filemarks */
	 ioctl(fd, MTIOSHORTFMK, &on);
	 /* disable short filemarks */
	 ioctl(fd, MTIOCSHORTFMK, &off);

       Tape  drives  which do not support short filemarks will return an errno
       of ENOTTY.

       The 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 supressed.  If 1 is  the specified integer, SILI will be used during
       reads  and incorrect length indicator will be supressed.	 The specified
       tape bahavior will be in effect until the device is closed.

       For example:

	 int on = 1;
	 int off = 0;
	 ioctl(fd, MTIOREADIGNOREILI, &on);
	 ioctl(fd, MTIOREADIGNOREILI, &off);

       The 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" 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-recodred-media	(EOD).	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 bahavior will be in effect until the device
       is closed.

       For example:

	 int on = 1;
	 int off = 0;
	 ioctl(fd, MTIOREADIGNOREEOFS, &on);
	 ioctl(fd, MTIOREADIGNOREEOFS, &off);

       Tape drives other than 1/2" reel tapes will return an errno of ENOTTY.

EXAMPLES
       Example 1 Tape Positioning and Tape Drives

       Suppose	you  have  written  three files to the non-rewinding 1/2" tape
       device, /dev/rmt/0ln, and that you want to go back and dd(1M) the  sec‐
       ond file off the tape. The commands to do this are:

	 mt -F /dev/rmt/0lbn bsf 3
	 mt -F /dev/rmt/0lbn fsf 1
	 dd if=/dev/rmt/0ln

       To  accomplish  the same tape positioning in a C program, followed by a
       get status ioctl:

	 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);

       or

	 mt_command.mt_op = MTNBSF;
	 mt_command.mt_count = 2;
	 ioctl(fd, MTIOCTOP, &mt_command);
	 ioctl(fd, MTIOCGET, (char *)&mt_status);

       To get information about the tape drive:

	 struct mtdrivetype mtdt;
	 struct mtdrivetype_request mtreq;
	 mtreq.size = sizeof(struct mtdrivetype);
	 mtreq.mtdtp = &mtdt;
	 ioctl(fd, MTIOCGETDRIVETYPE, &mtreq);

FILES
       /dev/rmt/<unit number><density>[<BSD behavior>][<no rewind>]

       Where density can be l, m, h, u/c (low, medium, high, ultra/compressed,
       respectively), the BSD behavior	option is b, and the no rewind	option
       is n.

       For example, /dev/rmt/0hbn specifies unit 0, high density, BSD behavior
       and no rewind.

SEE ALSO
       mt(1),	tar(1),	  dd(1M),  open(2),  read(2),  write(2),  aioread(3C),
       aiowrite(3C), ar.h(3HEAD), st(7D)

       1/4 Inch Tape Drive Tutorial

				 Sep 15, 2007			      MTIO(7I)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net