mtio man page on OSF1

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

mtio(7)								       mtio(7)

NAME
       mtio - magnetic tape interface

DESCRIPTION
       This description applies to all mass storage tape drives. The /dev/tape
       directory special files, such as tape0, tape20_d0, tape3_d7,  refer  to
       the mass storage tape drives. Tape drives can exist on different buses,
       and have different bus/formatter/controller dependencies.

   Special Files
       This release supports  revised  device  special	file  names  for  tape
       devices.	 Device file names have the base name tapeN, where N is a dec‐
       imal number denoting the instance of the device, and a suffix comprised
       of  the characters _d followed by a single digit. For example tape0_d0.
       This suffix determines the density of the tape device, according to the
       entry for the device in the /etc/ddr.dbase file.

       There  are  also	 two  forms  of device special files that allow you to
       specify the defult density for a device and to enable  compression,  if
       supported on a particular device:

       Device  Special File	 Function /dev/tape/tapeN	  default den‐
       sity for a rewind device /dev/tape/tapeNc	enable compression for
       a  rewind  device  /dev/ntape/tapeN	   default  density for a non-
       rewind device /dev/ntape/tapeNc	     enable  compression  for  a  non-
       rewind device

       Note  that  with	 the new device special file naming, there is a direct
       mapping from the old name suffix to the new name suffix as follows:

       Old Suffix	   New suffix l (low)		       _d0 m  (medium)
       _d2 h (high)		    _d1 a (alternate)		 _d3

       There  are  two	sets of device names for tape that both conform to the
       new naming convention. The /dev/tape directory for rewind  devices  and
       the  /dev/ntape	directory  (for	 no rewind). To determine which device
       special file to use, you can look in the /etc/ddr.dbase file.

       The special files in /dev/tape cause a loaded and on-line tape to auto‐
       matically  rewind  to  the  beginning-of-tape  (BOT) when closed.  Low,
       medium, and high density are relative to the densities supported	 on  a
       particular  tape	 drive.	 See  tz(7)  for more information. The special
       files in /dev/ntape do not cause a rewind when  closed,	regardless  of
       density.	 The  tape  remains in the same position as it was when it was
       last accessed.

       These special files are available to  all  operating  system  utilities
       that can perform I/O to tape.

   Magnetic Tape Operations
       Magnetic	 tape  ioctl system calls perform tape operations.  The opera‐
       tions come under three ioctl request groups. The MTIOCTOP ioctl is used
       to  issue tape operation commands. The MTIOCGET ioctl is used to obtain
       status. The MTIOCRDPOS ioctl is used to obtain tape  position  informa‐
       tion from the tape drive.

   MTIOCTOP ioctl Commands
       The mtop data structure is passed as a parameter to the MTIOCTOP ioctl.
       Please see the /usr/include/sys/mtio.h header file for a definition  of
       the mtop structure.

       The  mt_op  field  specifies the MTIOCTOP tape command to be performed.
       The mt_count field specifies the number of times the command should  be
       performed (where applicable).

       The  following  MTIOCTOP tape commands are supported: Writes an end-of-
       file to the tape.  Physically, an end of file consists of a tape	 mark.
       Repositions  forward  the  number  of  files  specified in the mt_count
       field.  This command repositions the tape forward the specified	number
       of  tape marks.	(Tape marks delimit files.) Upon successful completion
       of this command, the tape is physically positioned at the  end  of  the
       specified  number  of  tape  marks.  Repositions backward the number of
       files specified in the mt_count field.  This  command  repositions  the
       tape  backward the specified number of tape marks.  (Tape marks delimit
       files.) Upon successful completion of the command, the tape  is	physi‐
       cally  positioned  at  the  beginning  of  the specified number of tape
       marks.

					    Note

	      Because MTFSF leaves the tape positioned at the end  of  a  tape
	      mark  and MTBSF leaves it positioned at the beginning, these two
	      commands are not strictly reciprocal operations.	 For  example,
	      if a tape is initially positioned at the beginning of tape (BOT)
	      and the command MTFSF 1 is issued followed by the command	 MTBSF
	      1,  the  tape  does not return to the BOT position. Instead, the
	      tape is positioned on the BOT side of the first tape mark.   Re‐
	      positions	 forward  the  number  of  records  specified  in  the
	      mt_count field.  This command returns a failure if a  tape  mark
	      is  encountered  to indicate that there were not as many records
	      remaining in the file as there were  records  specified  by  the
	      mt_count	field.	 Repositions  backward	the  number of records
	      specified in the mt_count field.	This command returns a failure
	      if a tape mark is encountered to indicate that there were not as
	      many records between the present position and the	 beginning  of
	      the  file as specified in the mt_count field.  Rewinds the tape.
	      This command repositions to the beginning of the tape.   Rewinds
	      and  unloads  the	 tape.	 Does  not perform any tape operation.
	      Always returns success from a tape file.	 Enables  the  use  of
	      hardware-based   write-back   caching  for  better  performance.
	      Caching can speed tape transfer operations, thereby keeping  the
	      unit streaming more effectively. If you use the MTCACHE command,
	      use the MTFLUSH command to flush cached data to media. SCSI tape
	      drives that support caching have their cache turned on automati‐
	      cally by the driver; the MTCACHE command is  unnecessary.	  Dis‐
	      ables  use  of the controller's hardware-based write-back cache.
	      Tape operations using this command are slower than  tape	opera‐
	      tions  using  the MTCACHE command, but do not require use of the
	      MTFLUSH command to guarantee that the data is immediately	 writ‐
	      ten  to  tape.   Clears a serious exception.  Certain operations
	      cause the tape unit to go into a serious exception state.	  This
	      can  happen, for example, when the physical end-of-media foil is
	      encountered.  Typically, when a tape is in a  serious  exception
	      state, all data transfer operations fail.	 Use the MTCSE command
	      to acknowledge the exception condition and allow further	opera‐
	      tions  to proceed.  Clears a hardware or software error.	Clears
	      the subsystem.  Enables end-of-tape detection.  When the end-of-
	      tape markers are reached, the tape is halted on the reel between
	      the two end-of-tape markers.  Only the superuser can issue  this
	      command.	 The MTENAEOT command remains in effect for the device
	      until end-of-tape detection is disabled with the	MTDISEOT  com‐
	      mand.   This  is the default mode after a system boot.  Disables
	      end-of-tape detection.  When the end of  tape  is	 reached,  the
	      tape  will  run off the reel.  Only the superuser can issue this
	      command.	The MTDISEOT command remains in effect for the	device
	      until  end-of-tape  detection  is enabled with the MTENAEOT com‐
	      mand.  Flushes the hardware-based write-back  cache.  For	 tapes
	      that  have  controller-based caching (for example, TMSCP tapes),
	      use this command with the MTCACHE command. For tapes  that  have
	      device-based caching (for example, SCSI tapes), use this command
	      by itself. When caching has been enabled,	 writes	 to  the  tape
	      receive  a  completion status when the data has been transferred
	      to the cache, not when the data is transferred to the media. Use
	      the  MTFLUSH  command  to force a flush of the cache to physical
	      media.  Failure of this command with errno set  to  ENXIO	 means
	      that the drive does not support the flush command. However, SCSI
	      devices do not return ENXIO; therefore you cannot	 rely  on  the
	      MTFLUSH command to determine whether caching is enabled. Failure
	      with errno set to EIO indicates that the cache flush has failed.
	      In  this case, the application should retry writing records that
	      have been written since the  last	 successful  MTFLUSH  command.
	      Retensions the tape by moving the tape one complete pass between
	      EOT and BOT.  Moves the  tape  to	 the  end  of  recorded	 data.
	      Erases  the  tape.  Loads and rewinds the tape.  Loads the tape.
	      Unloads the tape.	 Enables scatter/gather IO for the readv() and
	      writev()	system	calls.	 After	this  command,	any readv() or
	      writev() system calls will cause the tape driver to transfer all
	      iovec  buffers  in  the list in a single transfer to tape.  Dis‐
	      ables scatter/gather IO for  the	readv()	 and  writev()	system
	      calls.  After this command, each buffer provided in a readv() or
	      writev() system call will be transferred	by  itself.   Sends  a
	      SCSI  LOCATE  command  to the tape drive, telling it to position
	      the tape to the SCSI logical  block  address  specified  by  the
	      mt_count	field.	Sends a SCSI LOCATE command to the tape drive,
	      telling it to position the tape to the device  specific  address
	      specified by the mt_count field.

   MTIOCGET ioctl Requests
       The  mtget  data	 structure  is	passed	as a parameter to the MTIOCGET
       ioctl.  Please see the /usr/include/sys/mtio.h header file for a	 defi‐
       nition of the mtget structure.

       The  following  list  describes the fields of the mtget data structure:
       Provides driver-specific drive status information.  This	 is  the  same
       information provided in the stat member of the devget structure used by
       the DEVIOCGET ioctl.

	      For the TMSCP driver, please see	the  /usr/include/sys/devio.h>
	      header file for bit definitions of the stat member.

	      For     the     SCSI     tape    driver,	  please    see	   the
	      /usr/include/io/cam/cam_tape.h header file for  bit  definitions
	      of the ts_flags member of the TAPE_SPECIFIC structure.  Provides
	      driver-specific error information.

	      For  the	TMSCP  driver,	 please	  see	table	B-1   in   the
	      /usr/include/io/dec/sysap/mscp_msg.h  header file for error code
	      definitions.

	      For the SCSI tape driver, the mt_erreg member contains the sense
	      key  byte	 of  the sense data from a SCSI REQUEST SENSE command.
	      Please see the /usr/include/io/cam/scsi_all.h header file or the
	      SCSI-2 standard for definitions of the sense key.	 Also included
	      in this byte are the Filemark, EOM, and ILI bits as  defined  in
	      the  SCSI-2  standard.   Contains command-specific results.  For
	      example, after a read  command  using  a	variable  block-length
	      tape,  mt_resid contains the residual number of bytes not trans‐
	      ferred.  Another example is the space command.   After  a	 space
	      command,	mt_resid  contains  the	 number of blocks or files not
	      spaced over.  Contains the file position of the tape.   Contains
	      the record position within a file.

       Extended	 error	information  can  be found in the /usr/include/io/com‐
       mon/deveei.h header file.

   MTIOCRDPOS ioctl Requests
       The mtrdpos data structure is passed as a parameter to  the  MTIOCRDPOS
       ioctl.	Please see the /usr/include/sys/mtio.h header file for a defi‐
       nition of the mtrdpos, mtrdposs, and mtrdposl structures.

       The following two structure members of the mtrdpos structure are infor‐
       mation  provided	 by  the application to control the format of the data
       returned by the tape drive.  The un member of this  structure  contains
       data passed back to the application from the tape drive.

       This  is a single bit which, if set, tells the SCSI tape driver to send
       the READ POSITION command, requesting that the tape  drive  return  the
       long  data  format.  This is a single bit which, if set, tells the SCSI
       tape driver to send the READ POSITION command, requesting that the tape
       drive  return  the  short  data	format with device specific addresses,
       rather than the SCSI logical block addresses.  If the long_format field
       is  set,	 then this bit is ignored by the tape driver.  This is a union
       of the short (mtrdposs) and the long (mtrdposl) data format structures.
       The  values  in	the members of these data structures are copies of the
       information in the short and long data formats  returned	 by  the  SCSI
       READ  POSITION command as specified in the SCSI standard documentation.
       Please note that the first_blk member of the mtrdposs structure and the
       blk_num member of the mtrdposl structure return information in the form
       which may be used with the MTSEEK and MTSEEKDS commands of the MTIOCTOP
       ioctl.

   System Call Behavior
       Each  read()  or write() system call reads or writes the next record on
       the tape. In the case of a write() system call, the record has the same
       length  as  the	buffer	given. During a read() system call, the record
       size is passed back as the number of bytes  read,  provided  it	is  no
       greater	than  the  buffer  size.  If  the  record is long, an error is
       returned. Seeks are ignored.  Positioning is done  with	a  tape	 ioctl
       call.  A	 zero  byte  count  is	returned when a tape mark is read, but
       another read fetches the first record of the next  tape	file.  When  a
       file  open for writing is closed and the last user command was a write,
       two end-of-file marks (EOF) are written. If a tape reaches the  end-of-
       tape (EOT) marker, the ENOSPC errno value is set.

       Each  read()  or	 write() system call causes the file offset associated
       with the device special file to be incremented.	This  file  offset  is
       reset  to  0  when  the	file is closed. If a program does an unusually
       large number or reads and writes to the tape, it is possible  to	 cause
       the  file  offset to be incremented beyond the maximum allowable value.
       When this happens, any further read() or write() system calls fail with
       an  error  number of EINVAL.  This situation can occur only if the tape
       is read or written to several times over, using repositioning  commands
       such  as	 MTREW to reposition backwards on the tape.  It is recommended
       that any application which expects to make  numerous  passes  over  the
       tape  use the lseek() system call to reset the file offset to zero, for
       example, lseek(fd,0,0).

RESTRICTIONS
       The MTRETEN ioctl is supported only by the SCSI QIC tape drive.

RETURN VALUES
       For the DEVIOCGET and MTIOCGET  ioctls,	the  DEV_TPMARK,  DEV_SHRTREC,
       DEV_EOM,	 DEV_OFFLINE,  DEV_SOFTERR,  and DEV_HARDERR tape driver flags
       are in an indeterminate state unless  the  application  has  gotten  an
       unexpected  return value from a system call (that is, read x bytes from
       tape, and if the return value does not equal x, then the flags are  not
       in an indeterminate state).

       The  MTIOCGET  ioctl call is non-intrusive.  This means that the device
       driver implements support for MTIOCGET solely by interrogating its data
       structures.   The device should not be perturbed.  This also means that
       the MTIOCGET ioctl call always returns ESUCCESS.	 However, because  the
       implementation  of  the	MTIOCGET  ioctl	 is dependent upon each device
       driver, and upon each device driver's ioctl code, an  errno  status  is
       sometimes  returned.   An  errno	 status	 returned from a MTIOCGET call
       indicates an error condition inside the driver itself.  These are  usu‐
       ally pre-processing errors inside the device driver's ioctl code.

ERRORS
       The  MTIOCTOP ioctl commands set errno to [ENXIO] if the command speci‐
       fied in mt_op is not recognized or not supported by the respective tape
       driver.

       The  following  list  describes the possible errno status returned from
       MTIOCGET: The operation was successful.	An error occurred while trying
       to  copy out ioctl data (FOP_IOCTL).  The device database structure was
       not present (no nexus).	The device-specific  data  structure  was  not
       present	(device not opened).  The device driver data structure was not
       present (device not opened).  The request was invalid or the  requested
       function is not supported.  The requested function is not supported.

FILES
       /dev/tape/dev?_d?

       /dev/ntape/tape?_d?

SEE ALSO
       lseek(2), SCSI(7), tz(7), MAKEDEV(8)

								       mtio(7)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OSF1

List of man pages available for OSF1

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