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

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