git.gag.com Git - debian/mtx/blob - scsitape.1

   1 .\" scsitape.1  Document Copyright 2001 Eric Lee Green
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
  21 .\" USA.
  22 .\"
  23 .TH SCSITAPE 1 SCSITAPE1.0
  24 .SH NAME
  25 scsitape \- control SCSI tape devices
  26 .SH SYNOPSIS
  27 scsitape [-f <scsi-generic-device>] commands
  28 .SH DESCRIPTION
  29 The
  30 .B scsitape
  31 command controls SCSI tape drives in a platform-independent
  32 manner. As long as 'mtx' works on the platform, so does 'scsitape'.
  33 .P
  34 Note that 'scsitape' and your OS's native tape driver may stomp on each
  35 other. In particular, if you use 'setblk' and your OS's native tape
  36 driver has a different notion of the block size, you may get evil results.
  37 It is recommended to use 'scsitape' only for software where you've written
  38 your own low-level READ and WRITE routines that use the SCSI command set
  39 to directly talk to tape drives (i.e., you do not use the OS's native tape
  40 driver at all).
  41 .SH OPTIONS
  42 The first argument, given following
  43 .B -f
  44 , is the SCSI generic device corresponding to your tape drive.
  45 Consult your operating system's documentation for more information (for
  46 example, under Linux these are generally /dev/sg0 through /dev/sg15,
  47 under FreeBSD these are /dev/pass0 through /dev/passX. Under Solaris
  48 this is usually the same as your tape drive (Solaris has a SCSI passthrough
  49 ioctl). You can set the STAPE or TAPE environment variable rather
  50 than use -f.
  51 .P
  52 .SH COMMANDS
  53 .TP 10
  54 .B setblk <n>
  55 Set the tape drive's SCSI block size to <n> bytes. (NOTE: if you are
  56 using your OS's native tape driver, THIS IS EVIL!).
  57
  58 .TP 10
  59 .B fsf <n>
  60 Go forward by <n> tapemarks.
  61 .TP 10
  62 .B bsf <n>
  63 Go to immediately previous the <n>th previous tapemark. (WARNING: This
  64 probably doesn't do what you expect -- e.g. if you are immediately
  65 after a tapemark and type 'bfs 1', it moves to immediately *before*
  66 that tape mark, for a sum total of zero effective movement!).
  67 .TP 10
  68 .B eod
  69 Go to end of data.
  70 .TP 10
  71 .B rewind
  72 Rewind the tape drive.
  73 .TP 10
  74 .B eject
  75 Eject the tape currently in the drive.
  76 .TP 10
  77 .B erase
  78 Does a *short* erase (warning: does NOT work on all drives!).
  79 .TP 10
  80 .B mark <n>
  81  write <n> filemarks ( 'mark 0' flushes the drive's buffers ).
  82 .TP 10
  83 .B seek <n>
  84 Seek to a logical position <n> that was reported by a previous 'tapeinfo'
  85 command.
  86 .TP 10
  87 .B write <blocksize>
  88 write blocks from stdin to the tape. Chunk the data into <blocksize>-sized
  89 chunks. *DOES NOT WRITE OUT A TAPEMARK!* (you will need to use a
  90 subsequent
  91 .B mark 1
  92 command to write out a tape mark).
  93 .TP 10
  94 .B read [<blocksize>] [ <#blocks/#bytes> ]
  95 read blocks from the tape, write them to stdout. If we are in variable
  96 block mode, <blocksize> should be zero (note: The maximum block size
  97 we currently support in variable block mode is 128K, MAX_READ_SIZE will
  98 need to be turned into a settable variable to allow bigger reads). If
  99 <blocksize> is ommitted, we assume that we're in variable block mode, and
 100 that we are going to read from tape until we hit a tapemark or end of
 101 partition or end of tape.
 102
 103
 104 .SH AUTHORS
 105 This program was written by Eric Lee Green <eric@badtux.org>.
 106 Major portions of the 'mtxl.c' library used herein were written by
 107 Leonard Zubkoff.
 108 .P
 109
 110 The SCSI read and write routines are based upon those that Richard
 111 Fish wrote for Enhanced Software Technology's BRU 16.1 product,
 112 substantially modified to work in our particular environment (in
 113 particular, all the variable block stuff is new since BRU only does
 114 fixed block reads and writes, and the BRU code uses bitmasks rather
 115 than bitfields for the various flags and such in return values, as
 116 well as the BRU code having a different SCSI API and having variable
 117 names considerably shorter than the rather sesquipedalian 'mtx'
 118 identifiers). As required by 'mtxl.c', these routines are licensed
 119 under the GNU General Public License.
 120
 121 .SH HINTS
 122 Under Linux,
 123 .B cat /proc/scsi/scsi
 124 will tell you what SCSI devices you have.
 125 You can then refer to them as
 126 .B /dev/sga,
 127 .B /dev/sgb,
 128 etc. by the order they
 129 are reported.
 130 .P
 131 Under FreeBSD,
 132 .B camcontrol devlist
 133 will tell you what SCSI devices you
 134 have, along with which
 135 .B pass
 136 device controls them.
 137 .P
 138 Under Solaris 7 and 8,
 139 .B /usr/sbin/devfsadm -C
 140 will clean up your /devices directory. Then
 141 .B find /devices -name 'st@*' -print
 142 will return a list of all tape drives. /dev on Solaris is apparently only
 143 of historical interest.
 144
 145 .SH BUGS AND LIMITATIONS
 146
 147 for
 148 .B scsitape read 0 <n>
 149 where  you are doing variable-block-size reads and wish for <n> bytes,
 150 it instead reads one and exactly one block from tape and prints that
 151 (no matter what its size). Use 'dd' on the output of scsitape if you
 152 want finer control.
 153 .P
 154 .B scsitape read 0
 155 attempts reads of MAX_READ_SIZE, which is currently 128K. If blocks on tape
 156 are larger than 128K, only the first 128K will be read -- the remainder
 157 will be silently dumped in the toilet.
 158 .P
 159 This program does not interact well (or at all :-) with your OS's
 160 native tape driver.  You will likely see weird things happen if you
 161 attempt to intermingle scsitape commands with native tape driver
 162 operations. Note that BRU 16.1 for Solaris (and possibly others, but
 163 Solaris I know about) will have a 'scsi' keyword to bypass the
 164 native tape driver and write via direct uscsi commands, so if you use
 165 'scsitape' to bypass the flaws of the native Solaris driver, you can use
 166 BRU 16.1 to write your actual tape archives. (Assuming that BRU 16.1
 167 has been released at the time that you read this).
 168
 169 .SH AVAILABILITY
 170 This version of
 171 .B scsitape
 172 is currently being maintained by Robert Nelson <robertnelson@users.sourceforge.net>
 173 as part of the 'mtx' suite of programs. The 'mtx' home page is
 174 http://mtx.sourceforge.net and the actual code is currently available there and via
 175 SVN from http://sourceforge.net/projects/mtx.
 176
 177 .SH SEE ALSO
 178 .BR loaderinfo (1), tapeinfo (1), mtx (1)