home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / wpssafe1.zip / tar.txt < prev    next >
Text File  |  1993-02-24  |  39KB  |  966 lines
  1. ┌─────────────────────────────────────────────────────────────────────────┐
  2. │                                                                         │
  3. │                    SCSI TAPE BACKUP for OS/2 2.0                        │
  4. │                    ─────────────────────────────                        │
  5. │                                                                         │
  6. │                             Version 2.12                                │
  7. │                                                                         │
  8. │       Author: Andreas Kaiser                                            │
  9. │               Danziger Str. 4                                           │
  10. │               D-7000 Stuttgart 70                                       │
  11. │               Germany                                                   │
  12. │                                                                         │
  13. │               Fidonet:  2:241/7220.9                                    │
  14. │               Internet: ak@ananke.stgt.sub.org                          │
  15. │               Voice:    49-711-766116                                   │
  16. │                                                                         │
  17. │        IF YOU CAN USE ELECTRONIC MAIL, PLEASE DO SO. DON'T CALL         │
  18. │        BY VOICE UNLESS ABSOLUTELY UNAVOIDABLE.                          │
  19. │                                                                         │
  20. └─────────────────────────────────────────────────────────────────────────┘
  21.  
  22. $Id: readme.os2,v 1.27 1993/02/22 12:08:32 ak Exp $
  23.  
  24. Legal notices:
  25. --------------
  26.  
  27.      BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
  28. WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. 
  29. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
  30. OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND,
  31. EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  32. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 
  33. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS
  34. WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
  35. ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  36.  
  37.      IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
  38. WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
  39. AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
  40. FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
  41. CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
  42. PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
  43. RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
  44. FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
  45. SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  46. DAMAGES.
  47.  
  48. Der alternative Device-Driver SCSITAPE.SYS unterliegt nicht dem GNU
  49. Copyleft. Der Quellcode dieses Treiber ist nicht erhältlich. Sie können
  50. SCSITAPE.SYS in kommerzieller Umgebung nutzen, Sie dürfen ihn jedoch
  51. nicht verkaufen oder auf andere Art Geld oder andere Gegenleistungen
  52. dafür erhalten. Sie dürfen diesen Treiber nicht als Basis eines
  53. kommerziellen Produktes einsetzen, auch nicht als Beigabe.
  54.  
  55. English translation of the sentences about SCSITAPE.SYS (the german
  56. version has priority):
  57.  
  58. The alternate device driver SCSITAPE.SYS is not governed by the GNU
  59. Copyleft. It's source code is not available. You can use SCSITAPE.SYS
  60. within a commercial environment, but you may not sell it or make profit
  61. in other ways. You may not use it as a base for a commercial product or
  62. as an add-on to a product.
  63.  
  64. ─────────────────────────────────────────────────────────────────────────
  65.  
  66. Thanks to Kai Uwe Rommel for beta test, several fixes and enhancements
  67. and to Eberhard Mattes for his great OS/2 development environment.
  68.  
  69. ─────────────────────────────────────────────────────────────────────────
  70. Contents:
  71. ---------
  72.  
  73.     Binaries:
  74.     .........
  75.  
  76. TAR.EXE        Modified GNU-TAR 1.10 for OS/2 2.0 and tape driver.
  77.         32-bit version using EMX 0.8f. No EMX.DLL required.
  78.  
  79. TAPE.EXE    Tape control utility.
  80.  
  81. COMPRESS.EXE    A file compression program for OS/2, invoked by the
  82.         "-z" tar option. The compression rate is not as good
  83.         as LHARCs and it is not as fast as PKZIP -es, but
  84.         COMPRESS can be used with pipes on both ends. It is
  85.         an OS/2 port of the well known Unix compress program.
  86.         It supports 16-bit compression mode, of course.
  87.  
  88. BUFFER.EXE    Pipe buffer & reblock program for OS/2. Invoked by
  89.         the "-z" option when operating on character devices.
  90.  
  91. SCSITAPE.DMD    Tape device driver for OS/2 2.0, based on an ADD SCSI
  92.         base device driver (such as AHA154X.ADD).
  93.  
  94. SCSITAPE.SYS    Alternate device driver, based on OS2SCSI.DMD.
  95.  
  96. ASPITAPE.SYS    Alternate device driver, based on ASPI (OS2ASPI.DMD).
  97.  
  98. README.ABS    An overview description.
  99. README.OS2    This file.
  100. 1.10/TAR.TEX    TeXinfo documentation of original TAR.
  101.  
  102.     Sources:
  103.     ........
  104.  
  105. 1.10/*        GNU tar 1.10.
  106. TAPE/*:        Tape control program.
  107. UTIL/*:     compress.d, buffer.c
  108. LIBX/*:        Some OS/2 utility functions and library replacements.
  109. OS2-ADD/*:    Tape device driver based on the ADD interface.
  110. OS2-ASPI/*:    Tape device driver based on the ASPI interface.
  111. OS2-DD/*:    OS/2 device driver support library .
  112.  
  113. ─────────────────────────────────────────────────────────────────────────
  114. The drivers:
  115. ------------
  116.  
  117. There are three alternate versions of the device driver. SCSITAPE.DMD
  118. is based on the ADD driver, SCSITAPE.SYS is based on OS2SCSI.DMD and
  119. ASPITAPE.SYS is based on Adaptecs ASPI interface definition which is
  120. implemented by OS2ASPI.DMD.
  121.  
  122. Prerequisites:
  123.  
  124.     SCSITAPE.DMD:
  125.     - SCSI ADD driver like AHA154X.ADD.
  126.  
  127.     SCSITAPE.SYS
  128.     - SCSI ADD driver like AHA154X.ADD.
  129.     - Installed OS2SCSI.DMD.
  130.     - SCB support built into the SCSI adapter (IBM PS/2) or driver.
  131.       OS2SCSI.DMD emulates the required SCB commands starting with
  132.       syslevel 2.00.1, but nevertheless it crashed with an AHA1542.
  133.  
  134.     ASPITAPE.SYS
  135.     - SCSI ADD driver like AHA154X.ADD.
  136.     - Installed OS2ASPI.DMD.
  137.     - Syslevel >= 2.00.1 (service pack).
  138.  
  139. If you run a SCSI adapter not listed below, you may try all versions in
  140. the order SCSITAPE.DMD -> ASPITAPE.SYS -> SCSITAPE.SYS. But be prepared
  141. for immediate or delayed system crashes. Note that a SCSI driver fault
  142. can damage filesystems, so backup your filesystems before.
  143.  
  144. ─────────────────────────────────────────────────────────────────────────
  145. Tested:
  146. -------
  147.  
  148. Host adapters, tested with SCSITAPE.DMD:
  149.  
  150.     Good:
  151.     AHA1542B, AHA1742
  152.     DPT2011            (Mark Leidecker - 2:241/5111.3@fidonet)
  153.     Future Domain TMC-885    OS/2 SYSLEVEL >= 2.00.1 (Service Pack)
  154.                 (Rob Prikanowski - rpr@oce.nl)
  155.     Future Domain TMC-1650    The tape's SCSI ID must be set to 7
  156.                 (toy@alydar.crd.ge.com)
  157.     Future Domain TMC-1670    Service Pack required
  158.                 (manne@minsk.docs.uu.se)
  159.                 
  160.  
  161.     Bad:
  162.     IBM PS/2 SCSI
  163.     AHA1522            (Wolfgang Franke - wfranke@blabel.ppp\
  164.                         .informatik.uni-muenchen.de)
  165.  
  166. Host adapters, tested with ASPITAPE.SYS:
  167.  
  168.     Good:
  169.     AHA1542B        OS/2 SYSLEVEL >= 2.00.1 (Service Pack)
  170.     Future Domain TMC-1670    Service Pack required
  171.                 (manne@minsk.docs.uu.se)
  172.  
  173. Host adapters, tested with SCSITAPE.SYS:
  174.  
  175.     Good:
  176.     IBM PS/2 SCSI 32-bit version
  177.  
  178.     Bad:
  179.     AHA1542B
  180.  
  181. Tape devices:
  182.  
  183.     With QFA (Quick File Access) using SCSI-2 commands:
  184.     Tandberg TDC4200 SCSI-2
  185.     Tandberg TDC4120 SCSI-2
  186.     Tandberg TDC3820 SCSI-2    (Manfred Huber - 100021.3416@compuserve.com)
  187.     HP DAT 35470A/80A    (Martin Vorlaender - 2:241/3420.1@fidonet)
  188.  
  189.     With QFA (Quick File Access) using the Tandberg SCSI-1 commands:
  190.     Tandberg TDC4120 SCSI-1
  191.     Tandberg TDC3820 SCSI-1
  192.     Tandberg TDC3660 SCSI-1
  193.         Wangtek 5150ES, depending on the firmware revision
  194.     Archive Viper 2150S    (Clemens.Beckstein@informatik.uni-erlangen.de)
  195.     Sankyo CP150        (manne@minsk.docs.uu.se)
  196.         Archive Python DAT SCSI-2 - uses SCSI-1 QFA even though it claims
  197.                 to be a SCSI-2 device (mark@mystic.ucdavis.edu)
  198.                     
  199.  
  200.     No QFA:
  201.         Wangtek 5150ES, depending on the firmware revision
  202.  
  203.     No information about QFA:
  204.         Sankyo, equivalent to
  205.     Wangtec 5525ES        (Mark Leidecker - 2:241/5111.3@fidonet)
  206.  
  207. If you are successful and your SCSI adapter or tape device is not
  208. listed above, please send a note to one of my email addresses.
  209.  
  210. ─────────────────────────────────────────────────────────────────────────
  211. Installation:
  212. -------------
  213.  
  214.     SCSITAPE.DMD:
  215.     -------------
  216.  
  217. Copy SCSITAPE.DMD into the root or \OS2 directory (preferably) of your
  218. OS/2 boot partition (the only places where a BASEDEV driver is
  219. recognized). Add the following lines to CONFIG.SYS:
  220.  
  221.     set TAPE=+++TAPE$<id>
  222.     BASEDEV=SCSITAPE.DMD TAPE$<id> A<ano> <id> S<mode>
  223.  
  224.     SCSITAPE.SYS:
  225.     -------------
  226.  
  227. SCSITAPE.SYS can be placed anywhere on your disks, as long as you
  228. specify its full path in CONFIG.SYS.
  229.  
  230.     set TAPE=+++TAPE$<id>
  231.     DEVICE=your_path\SCSITAPE.SYS TAPE$<id> <unit> S<mode>
  232.  
  233. Note that this driver installs successfully, even if there is no tape
  234. present in the system and no tape configured in the system setup
  235. (PS/2). This is a bug.
  236.  
  237.     ASPITAPE.SYS:
  238.     -------------
  239.  
  240. ASPITAPE.SYS can be placed anywhere on your disks, as long as you
  241. specify its full path in CONFIG.SYS.
  242.  
  243.     set TAPE=+++TAPE$<id>
  244.     DEVICE=your_path\ASPITAPE.SYS TAPE$<id> A<ano> <id> S<mode>
  245.  
  246.     all:
  247.     ----
  248.  
  249. <mode>    2  for SCSI-2 devices, like TDC 3820 and TDC 4120
  250.     1  for Tandberg SCSI-1 devices (TDC 3660, TDC 3820, TDC 4120)
  251.     0  for other SCSI-1 devices
  252.  
  253.     Note that there are both SCSI-1 and SCSI-2 versions of Tandberg
  254.     TDC 3820 and TDC 4120 available, with no visible difference.
  255.  
  256.     Run "tape inq" and look for "ANSI 1" or "ANSI 2" to know what
  257.     SCSI level your device supports. Use a <mode> of 0 for this
  258.     purpose.
  259.  
  260. <ano>    Adapter number, starting with 0. Only required if you have
  261.     multiple SCSI adapters with the same (!) ADD driver. If you have
  262.     several tape devices connected to different host adapters, use
  263.     different SCSI ID's to reduce the chance of confusion.
  264.  
  265. <id>    SCSI ID
  266.  
  267. <unit>    1 for the first sequential device, 2 for the second and so on.
  268.  
  269. The driver's <mode> argument determines the way, how both the driver
  270. and the tape interface interpret and print SCSI error codes.
  271.  
  272. If your device supports the QFA commands of Tandberg SCSI-1 (some
  273. Wangtek and Archive 150MB models) and the extended sense data conforms
  274. to SCSI-1 (Tandberg's does not), you should set <mode> to 0.
  275.  
  276. Example:
  277.  
  278.     set TAPE=+++TAPE$4
  279.     BASEDEV=SCSITAPE.DMD TAPE$4 4 S2
  280.  
  281. The leading "+" characters in the file/device name signal TAR to use
  282. the tape device interface instead of the standard file interface.
  283.  
  284. If you like to sort your CONFIG.SYS: The environment variable can be
  285. specified anywhere, only the programs TAPE and TAR use it to
  286. determine the default tape device name.
  287.  
  288. The tape device must be present and powered on when OS/2 boots. This is
  289. enforced by the ADD interface. A device driver on top of an ADD driver
  290. can only access SCSI devices which are known at the time when the ADD
  291. driver is initialized.
  292.  
  293. If you have more than one tape device, install the driver once for each
  294. device, using different SCSI IDs and different device names (TAPE$x).
  295.  
  296. Hint: You may be tempted to use TAPE$0 for the first and TAPE$1 for a
  297. possible second tape device, but this way you are unable to specify the
  298. TAR tape device in short form as -4 or -5, since the options -0 and -1
  299. are reserved for floppy access.
  300.  
  301. Add C<x>, where <x> is the device type code, to the driver command line
  302. if you want to use the driver and the TAPE program to access non-tape
  303. devices. This way you can run any arbitrary SCSI command on the device,
  304. unless it is locked by another driver. If the device is locked by
  305. OS2DASD.DMD (disks are), add /!DM:<id> to the SCSI ADD line - note that
  306. you will have to boot from floppy if this is your boot disk.
  307.  
  308. ASPITAPE.SYS does not care about device types, the option C<id> is
  309. ignored in ASPITAPE.SYS.
  310.  
  311.     SCSITAPE.DMD:
  312.  
  313. If you have a seperate monochrome video card in your machine, you may
  314. want to add the option D3 to the BASEDEV=SCSITAPE.DMD line. The driver
  315. will display all available BASEDEV device driver info on the monochrome
  316. screen at system boot time. Remove this option after getting this info
  317. once because it will seriously slow down operation. As a side effect,
  318. you will definitely know which of your device drivers supports more
  319. than 16MB of memory.
  320.  
  321. Do *not* add /!SM:<id> to the SCSI driver's command line as this option
  322. disables the tape driver too.
  323.  
  324. If the device is locked by OS2SCSI.DMD (e.g. CDROM), comment out
  325. OS2SCSI.DMD.
  326.  
  327.     ASPITAPE.SYS:
  328.  
  329. If the device is locked by OS2SCSI.DMD, add /SM:<id> to the ADD driver
  330. command line.
  331.  
  332. ─────────────────────────────────────────────────────────────────────────
  333. Add SCSI tape support to your OS/2 boot disk:
  334. ---------------------------------------------
  335.  
  336. You may want to create a boot diskette with SCSI tape support, to be
  337. able to restore your files in case of a damaged hard disk. Make a boot
  338. diskette using the REXX program MAKEBOOT or IBMs SE20BOOT (available on
  339. many FTP servers and BBSs).
  340.  
  341. Copy the device driver and its prerequisites (see above) to the
  342. diskette and replace the line BASEDEV=IBMINT13.I13 by
  343. BASEDEV=AHA154X.ADD (or whatever you are using). Add the configration
  344. statements as shown above.
  345.  
  346. Caution: an unmodified MAKEBOOT disk as well as the standard OS/2 boot
  347. disks will probably not allow any SCSI device access except for the
  348. first two BIOS disks, since there is no SCSI driver installed. When
  349. booting non-IBM machines from unmodified diskettes, OS/2 runs the INT13
  350. driver instead of the SCSI driver. The INT13 driver does not allow SCSI
  351. device access except for the two BIOS mapped harddisks.
  352.  
  353. ─────────────────────────────────────────────────────────────────────────
  354. GNU TAR:
  355. --------
  356.  
  357. This is not an introduction into TAR. Look into the TeX file or a good
  358. Unix book to learn more about the usage of TAR.
  359.  
  360. If TAR is invoked without explicit archive specification or with a
  361. archive filename beginning with "+", it always positions to end-of-tape
  362. before data is written to the tape and it automatically appends a
  363. filemark after writing all data. This way TAR never erases existing
  364. tape contents when you accidentally forget the -f switch on the command
  365. line (or if you pressed the wrong key - remember that "c" is close to
  366. "x"). If you want to rewrite the tape from the beginning, either erase
  367. the tape (TAPE ERASE, see below) or write an empty filemark at the
  368. beginning of the tape (TAPE REWIND MARK). If you write an empty
  369. filemark, you have to skip the first tape file (TAPE FILE) when reading
  370. the tape.
  371.  
  372. Multi-volume archives will probably not work when the tape reaches its
  373. limit - it takes too long to test it. If you need multi-volume
  374. archives, use the option -L (--tape-length) to split the data in chunks
  375. of a size somewhat less than the maximum tape capacity.
  376.  
  377. TAR uses whatever block size is preset in the tape device. If the block
  378. size is set to variable, the actual block size is the TAR block size
  379. (usually 10K). Use TAPE BLOCKSIZE to set the tape's blocksize.
  380.  
  381.  
  382. Get help with
  383.     tar --help
  384.  
  385. New/changed options:
  386.  
  387.     -0 -1        Alias for "-f a:" and "-f b:"
  388.  
  389.             Writing diskettes in this way wipes out the DOS
  390.             format. You have to reformat such a diskette
  391.             before reuse with DOS/OS2 files.
  392.  
  393.             Such diskette archives can be used to exchange
  394.             files with most Unix systems.
  395.  
  396.             Not recommended for 360/720KB diskettes in
  397.             1.2MB/1.44MB drives.
  398.  
  399.     -2 .. -7    Alias for "-f +++TAPE$2" .. "-f +++TAPE$7"
  400.  
  401.     -E        Similar to "-v", but prints directory names
  402.             only as they (and the files within them) are
  403.             processed.
  404.  
  405.     -D --tape-dir filename 
  406.             Use and maintain a tape directory. New data is
  407.             appended to the (text) file if it already
  408.             exists.
  409.  
  410.             This option allows fast random access to single
  411.             files (QFA, Quick File Access), provided the
  412.             device supports the random access commands of
  413.             SCSI-2 or Tandberg TDC3600/3800 SCSI-1 series.
  414.             Many 60-150MB streamers do not support these
  415.             commands, so there is no way for a fast random
  416.             access on these models. This is a deficiency of
  417.             the SCSI command set prior to the SCSI-2
  418.             specification.
  419.  
  420.             This option is not usable with compression mode.
  421.  
  422.             NOTE: The format of the tape directory has changed.
  423.             Version 1 tape directories should not be used.
  424.  
  425.     -g --incremental filename
  426.             The backups will be done incremental. Implies
  427.             --all-timestamps and --all-files. If --generation
  428.             is not specified, it defaults to "incremental".
  429.  
  430.             Directories archived with -g contain info about
  431.             all files located in this directory. On restore,
  432.             all files, which exist in the directory on disk
  433.             but not in the directory on the archive, are
  434.             removed from the disk, since they are left over
  435.             from previous incremental restores. Standard
  436.             tar programs will complain about or ignore such
  437.             directories on the archive.
  438.  
  439.             The specified file is the dumpfile.
  440.  
  441.             The dumpfile is not used on restore. Nevertheless
  442.             it has to be specified on the commandline, for
  443.             syntactic reasons.
  444.  
  445.     -G --generation O
  446.             Specifies the state and the strategy of incremental
  447.             backups.
  448.  
  449.         When O is "f[irst]"
  450.  
  451.             The first generation of incremental backups. The
  452.             dumpfile is overwritten, all files are archived.
  453.             Directories are archived in special GNU dump
  454.             format.
  455.  
  456.         When O is "s[econd]"
  457.  
  458.             All files and directories, which were changed
  459.             since the last update of the dumpfile, are
  460.             archived. Directories are archived in special GNU
  461.             dump format.
  462.  
  463.             The dumpfile is *not* updated. If only first and
  464.             second generation incremental backups are used,
  465.             each second generation backup archives all files
  466.             changed since the last first generation backup.
  467.             You no longer need previous second generation
  468.             backup media, once a new one is written.
  469.  
  470.         When O is "i[ncremental]"
  471.  
  472.             All files and directories, which were changed
  473.             since the last update of the dumpfile, are
  474.             archived. Directories are archived in special GNU
  475.             dump format.
  476.  
  477.             The dumpfile is updated to reflect the current
  478.             state of the archived filesystems. All future
  479.             second and incremental generation backups are
  480.             based on latest run.
  481.  
  482.     -L <n>[B|K|M]    You can append B or K or M now, for B=blocksize
  483.             (TAR block size, not tape block size), K=KB, M=MB.
  484.  
  485.         Example:
  486.             -L 145M        Split archive into chunks of 145 MB.
  487.  
  488.             Note that TAR does not account for the current
  489.             tape position. If there is less space on the
  490.             remaining tape than specified in -L, TAR will run
  491.             until it hits the physical end of the tape.
  492.  
  493.     -p --all-files    Include extended attributes, SYSTEM and HIDDEN
  494.             files on backup. Account for extended attributes,
  495.             SYSTEM and HIDDEN file attributes on list and
  496.             restore. The SYSTEM and HIDDEN attributes are
  497.             encoded in the group and world execute bits
  498.             of the Unix style file mode. 
  499.  
  500.             NOTE: The format of archived extended attributes
  501.             has changed. Version 2 does not restore (ignores)
  502.             EAs saved with version 1.
  503.  
  504.     -pp --all-timestamps
  505.             Archive and restores all time stamps, including
  506.             access and creation time stamps of HPFS files.
  507.             This is the default for GNU dumps.
  508.  
  509.     -Y --no-recursion
  510.             Save only the files specified on the command line.
  511.             Do not save contents of directories.
  512.  
  513.     --fat        Convert long (i.e OS/2 HPFS or Unix) filenames
  514.             to FAT 8.3 filenames if required. Use this
  515.             option if you extract archives with filenames
  516.             that exceed the 8.3 FAT restrictions onto HPFS
  517.             file systems but want to convert to 8.3 names
  518.             unconditionally. If you extract onto FAT file
  519.             systems, names which do not fit into 8.3 are
  520.             converted in any case, if --fat is used or
  521.             not.
  522.  
  523.     -Z        Was alias for -z. Now forces buffered pipe
  524.             compression mode. This is automatically done
  525.             when the archive is a character device (tape
  526.             or floppy).
  527.  
  528.     --archive    Archive only those files, where the "archive"
  529.             bit is set. This bit is reset afterwards.
  530.  
  531.             If you create a new file or modifiy a file in
  532.             DOS or OS/2, this bit is automatically set, so
  533.             this is OS/2's "official" way of running
  534.             incremental backups.
  535.  
  536.     --reset-archive    Reset the "archive" bit for every file archived.
  537.             Use this option in a full backup, if you intend
  538.             to later use incemental backups via --archive.
  539.  
  540. This is software designed for (and ported from) Unix systems, so don't
  541. expect all options and features to work. And don't be too much confused
  542. by some warnings, which may occur when TAR tries to set attributes
  543. or filetimes at times when this is not allowed under OS/2.
  544.  
  545. This TAR automatically saves and restores Extended Attributes when -p
  546. is given. Path and filename specifications are sensitive to upper/lower
  547. case and forward/backward slash convention.
  548.  
  549. Since the TAR format is standardized and available on every UNIX
  550. system, you can use TAR to exchange data with UNIX systems. Even
  551. compressed data is compatible with 32-bit Unix systems. If you intend
  552. to exchange tapes or diskettes with standard Unix tar programs, avoid
  553. the GNU TAR specific options -V, -g and the OS/2 specific option -p.
  554.  
  555. Paths and filenames should be specified with forward slashes as path
  556. separators. On extract, paths and filenames must be specified exactly
  557. as shown by "TAR t" except for the trailing "/" of directories, which
  558. should be omitted.
  559.  
  560. Hint: GNU TAR removes leading absolute path indicators such as drive
  561. letters and leading slashes (verbose) on create and extract, unless -P
  562. or --absolute-paths is specified. If put save several partitions into
  563. the same archive, you may not be able to distinguish files with the
  564. same path and filename on restore. Use separate archives (run TAR
  565. seperately) for each logical disk or specify --absolute-paths. You can
  566. still extract files to a relative path even when it was written with an
  567. absolute path.
  568.  
  569. Hint: Although the output of the -v option looks nice, it may be wise
  570. not to use it for large backups. When a large number of small files is
  571. written to tape, the big amount of screen output may slow down the tape
  572. output, forcing the tape into inefficient stop-and-go mode. Use the -E
  573. option instead, if you like to get feedback about the progress of
  574. backups.
  575.  
  576. Examples:
  577.  
  578.     tar cp .        Backup the current directory and
  579.                 all subdirectories including extended
  580.                 attributes, hidden and system files.
  581.  
  582.     tar tpv            List all files on the archive.
  583.  
  584.     tar xpv            Restore whole archive. Restore extended
  585.                 attributes and set attributes of hidden
  586.                 and system files.
  587.  
  588.     tar x path/file        Restore a single file or a directory
  589.                 tree. Filenames are case sensitive.
  590.                 Always use forward slashes.
  591.  
  592.     tar -c -v -D c:/tar_maps/tape.dir c:/
  593.                 Backup logical disk c: and append a
  594.                 tape directory to the specified file.
  595.  
  596.     tar -x -v -D c:/tar_maps/tape.dir this/is/a/single/file
  597.                 Restore "this/is/a/single/file" using
  598.                 the random access commands of SCSI-2
  599.                 or Tandberg SCSI-1 models.
  600.  
  601. OS/2 compressed backup performance: A 486 33MHz equipped with a 5MB/min
  602. streamer provides a compression rate of about 1.5 on a whole disk with
  603. 90MB binaries and an effective disk data throughput of about 85 KB/sec
  604. and a tape data throughput of about 55 KB/sec. When storing the backup
  605. on a diskette (a way to exchange HPFS files), compressed and buffered
  606. (-Z, default if raw diskette) data throughput is faster than the
  607. diskette data throughput. Therefore compressed mode can be considerably
  608. faster than uncompressed mode, depending on the machine's speed and the
  609. data throughput of the backup device.
  610.  
  611. WARNING: If a compressed archive contains a bad block, all data of the
  612. archive starting with the bad block is lost. Uncompressed archives are
  613. recoverable by manually skipping beyond the bad block, compressed
  614. archives are not recoverable. COMPRESS was not written with tape
  615. backups in mind.
  616.  
  617.  
  618.         - - -
  619.  
  620.         Once again, due to some complaints - PLEASE READ:
  621.  
  622. If used with the dedicated tape interface, this version of TAR always
  623. appends to all existing data on the tape, it skips existing tape data
  624. before new data is written to the tape. It does not erase existing tape
  625. contents. If there already was some data on the tape before (even if
  626. cpio, Sytos, ...), this is what you get when reading the tape from the
  627. beginning. If this data does not have the same archive format
  628. (compressed archive or another backup program), you'll get an error
  629. message like "doesn't look like a tar archive".
  630.  
  631. If you want to rewrite the tape from the beginning, either erase the
  632. tape ("tape erase", see below, which is slow but recommended since it
  633. also retensions the tape in the case of a QIC tape device), or write an
  634. empty filemark at the beginning of the tape ("tape rewind mark").
  635.  
  636. If you write an empty filemark to erase the tape, you have to skip the
  637. first tape file ("tape file") when reading the tape, else you get an
  638. error message.
  639.  
  640. You may consider this stuff irritating, but the letters "c" for "create
  641. a tape archive" and "x" for "extract" are too close to each other. If
  642. you accidentally hit "c" instead of "x", you won't kill previous tape
  643. contents since the new data appends to logical EOT instead of killing
  644. your data.
  645.  
  646. If you don't know if you tape drive supports QFA, run
  647.     tape tell
  648.     tape seek 1
  649. If both commands are accepted, you can be pretty sure it supports QFA.
  650. If you get something like "Illegal request", the device doesn't know
  651. about the QFA commands used in the mode you've choosen by the S<x>
  652. option (S0 and S1 use Tandberg's SCSI-1 commands, S2 uses the standard
  653. SCSI-2 commands).
  654.  
  655. ─────────────────────────────────────────────────────────────────────────
  656. Tape utility - TAPE:
  657. --------------------
  658.  
  659. Just run it without any arguments to get usage information. You can
  660. specify multiple verbs in a single call, unless the -Nowait option is
  661. given. Mostly case-insensitive, except for some dangerous commands
  662. which have to be specified in upper case.
  663.  
  664. Examples:
  665.     -0 .. -7    Device TAPE$0 .. TAPE$7
  666.     rew        Rewind tape.
  667.     ret        Retension tape.
  668.     file        Skip until next filemark.
  669.     end        Position to end of written data.
  670.     mark        Write filemark.
  671.     erase        Erase tape.
  672.  
  673.     read <file>    Read tape to file, write to stdout if <file> is "-".
  674.     write <file>    Write file to tape, read from stdin if <file> is "-".
  675.  
  676.     speed <n>    TDC4120: <n>=1: slow (200KB/sec)
  677.                  <n>=2: fast (300KB/sec)
  678.                  (recognized at beginning of tape only)
  679.  
  680. ─────────────────────────────────────────────────────────────────────────
  681. A few words on blocks and sizes:
  682. --------------------------------
  683.  
  684. Most tape devices with a capacity of at least 525MB can be used with
  685. different blocksizes. Both with fixed length blocks of 512 and 1024
  686. bytes as well as with variable length blocks. The default setting
  687. varies. The default setting of TAR is 512 bytes. If the default tape
  688. blocksize differs, you have to set the blocksize before running TAR,
  689. using
  690.     tape blocksize 512
  691. or    tape blocksize 1024
  692. or    tape blocksize 0    -- for variable length blocks
  693.  
  694. You can get the current setting of the tape device with "tape mode 0".
  695. But note that there are devices, which do not show a valid value until
  696. the tape is read. Additionally, this value may depend on the type of
  697. the inserted tape.
  698.  
  699. Tapes for QIC-24 (DC600A 60MB), QIC-120 (DC600XTD 120MB) and QIC-150
  700. (DC6150 150MB, DC6250 250MB) must be used with a blocksize of 512
  701. bytes. If DC6150/6250 tapes work and DC6320 or higher do not work, the
  702. tape device is probably set to a blocksize of 1024 bytes and switches
  703. down to 512 bytes when it recognizes a DC6150/6250 tape (Wangtec
  704. 525MB).
  705.  
  706. TAR works with block sizes of 512 and 1024 bytes (it should work with
  707. any reasonable fixed block size if it is a multiple of 512) as well as
  708. with variable block sizes.
  709.  
  710. Don't confuse the TAR block size ("tar -b<n>") with the tape block size
  711. ("tape blocksize <n>"). Unless variable length tape blocks are used,
  712. the TAR blocksize can be any value which is an exact multiple of the
  713. tape blocksize (default: 10KB). If variable length blocks are used, a
  714. tape block equals a TAR block. Note that TAR also knows about a "record
  715. size" which is the TAR file header and file alignment size and is fixed
  716. to 512 bytes by the TAR archive format.
  717.  
  718. ─────────────────────────────────────────────────────────────────────────
  719. Pipe buffer - BUFFER:
  720. ---------------------
  721.  
  722. Command line options:
  723.  
  724.     -s <number>    Buffer size, 64K..4096K.
  725.     -b <number>    Reblock to a multiple of <number> bytes
  726.             per output block. Pad output with 0 if
  727.             necessary (<number> <= 32768).
  728.     -i <number>    Refill buffer when <number> % empty.
  729.     -o <number>    Flush buffer when <number> % filled.
  730.             Default for -i and -o is 100.
  731.  
  732. When called with "-/" (or any other invalid option) as argument, BUFFER
  733. prints a small usage info. This usage shows the default buffer size as
  734. second number in the line corresponding to "-s".
  735.  
  736. BUFFER is multi-threaded. If the buffer fill ratio permits according to
  737. the input and output tresholds, it will be active on both ends at the
  738. same time.
  739.  
  740. If the buffer size is not specified on the command line, the default
  741. size can be specified with the environment variable BUFFER in KB. If
  742. not specified, the default buffer size depends on the version of the
  743. operating system:
  744.  1.3: The size of the largest contiguous area (DosMemAvail) minus 1MB.
  745.  2.0: 2MB.
  746.  
  747. When copying a large file from one partition to another, BUFFER can
  748. considerably reduce the effects of disk positioning times by using:
  749.     buffer < input-file > output-file
  750.     
  751. ─────────────────────────────────────────────────────────────────────────
  752. Incremental backups:
  753. --------------------
  754.  
  755. There are 3 alternatives:
  756.  
  757. (1) To make incremental backups, where every increment is based on the
  758. previous increment:
  759.  
  760.     full backup:
  761.     tar --create --incremental=dumpfile --generation=first ...
  762.     increment:
  763.     tar --create --incremental=dumpfile --generation=incr ...
  764.  
  765.     To restore such backups, you have to restore the full backup first,
  766.     then all increments in the order they were created. The info saved
  767.     with each directory ensures, that no files will be left over which
  768.     have been erased before the last increment was created.
  769.  
  770. (2) To make incremental backups, where the increments are based on the last
  771. full backup (this is an extension to original GNU tar 1.10, where the
  772. option -G is outdated and next to unusable):
  773.  
  774.     full backup:
  775.     tar --create --incremental=dumpfile --generation=first ...
  776.     increment:
  777.     tar --create --incremental=dumpfile --generation=second ...
  778.  
  779.     To restore such backups, you have to restore the full backup first,
  780.     then the last increment. You do not have to restore other increments.
  781.  
  782. (3) To make incremental backups using the filesystem's "archive" bit:
  783.  
  784.     full backup:
  785.     tar --create --reset-archive ...
  786.     increment:
  787.     tar --create --archive ...
  788.  
  789. You can combine both (1) and (2). In this case, second or incremental
  790. generation backups will archive all files which were changed since the
  791. last first or incremental generation backup. You have to restore the
  792. full backup first, then all incremental generation backups in the order
  793. they were created, then the last second generation backup if it is
  794. newer than the last incremental generation backup.
  795.  
  796. ─────────────────────────────────────────────────────────────────────────
  797. Known bugs:
  798. -----------
  799.  
  800. When there are multiple archives on the same tape and you read them
  801. sequentially using tar, you may get an error message like "I/O error"
  802. on every second run. Ignore this error message and continue.
  803.  
  804. The reason for this message is TAR's own end-of-file mark which causes
  805. TAR to stop reading before having encountered the tape's filemark. The
  806. next run of TAR gets nothing but this filemark which results in the
  807. mentioned error message.
  808.  
  809. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  810.  
  811. --tape-length doesn't know about the current tape head position. If you
  812. append to a tape with existing contents, specifying the full tape
  813. length in --tape-length will not save you from a tape overrun.
  814.  
  815. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  816.  
  817. The device driver r/w interface (file access to TAPE$<id>) will not
  818. always correctly sense the current device block size, so run "tape
  819. blocksize <n>" before, to synchronize driver and device.
  820.  
  821. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  822.  
  823. The driver SCSITAPE.SYS installs successfully, even if there is no tape
  824. drive connected or configured. Reason: I have not found out how to call
  825. OS2SCSI.DMD in init phase, the corresponding DosDevIOCtl calls never
  826. return.
  827.  
  828. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  829.  
  830. There is no support for the "quick erase" option supported by some
  831. drives (HP 35480A) in this release. Although the changes are trivial,
  832. the current state of my source-code management votes against it. Use
  833.     tape CMD cdb=19,0,0,0,0,0
  834. instead (don't mistype or your system may hang!). If your drive accepts
  835. this command, you can erase a tape in a few seconds instead of an hour.
  836.  
  837. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  838.  
  839. When a tape is inserted, the very first TAPE command fails with "Unit
  840. Attention" or alike. This is no a bug but a feature of SCSI tape
  841. drives. TAR itself ignores it using a dummy command but TAPE is
  842. intended as a direct device interface, so it does not make attempts to
  843. hide informations from the user.
  844.  
  845. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  846.  
  847. When writing to a Wangtek or equivalent (Sankyo) drive, you may get
  848. "Seek to end of tape failed", when the tape is empty or the head is
  849. already positioned to end-of-tape at the time TAR is started. This is a
  850. bug/feature of Wangtek tape drives, you can ignore this message.
  851.  
  852. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  853.  
  854. TAR commands, which have to backspace or have to overwrite previous
  855. archive contents, are not supported when operating on tapes. Such as
  856. --append, --update, --delete, --verify.
  857.  
  858. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  859.  
  860. When you backup a FAT partition, TAR loudly complains about not being
  861. able to backup the file "ea data. sf". This is perfectly ok, since
  862. extended attributes are saved with each file individually. It makes no
  863. sense to save it, since the sole reason of this file is to cover the
  864. disk space used by extended attributes so that DOS CHKDSK doesn't
  865. complain about wasted disk space.
  866.  
  867. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  868.  
  869. TAR does not archive files starting with the character '#'. This is a
  870. bug in OS/2, not in TAR.
  871.  
  872. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  873.  
  874. After change of media, TAPE displays a message like "Unit attention".
  875. This is not a bug but a feature of SCSI devices. TAPE could skip this
  876. message just as TAR does, but TAPE is intended as a transparent
  877. low-level utility.
  878.  
  879. ─────────────────────────────────────────────────────────────────────────
  880. Changes since 2.01:
  881. -------------------
  882.  
  883.     2.02:
  884.  
  885. SCSITAPE.DMD: Debug mode was accidentally enabled by default.
  886.  
  887.     2.03:
  888.  
  889. TAR: Fixed a GNU tar bug. If access/creation times were not written to
  890. the archive ("-g" but not "-p"), tar nevertheless extracted dates from
  891. the header fields where the dates were expected. The result were funny
  892. dates such as xx.xx.2098 or xx.xx.1970, depending on your timezone. If
  893. you have such files on your disk, archive them and restore them using
  894. TAR (but avoid --all-timestamps). The access and creation dates will
  895. show the current date afterwards.
  896.  
  897. Archiving access and creation dates when -p was given, wasn't the
  898. brightest idea anyway. If you want to make a system backup with all
  899. dates, use --all-timestamps or twice -p. Gnu dumps enable it by
  900. default.
  901.  
  902. Specify --all-timestamps or twice -p to archive/extract access and
  903. creation timestamps (implicitly enabled for gnu dumps). Except in the
  904. case of a system backup/restore, restoring the creation timestamp isn't
  905. a very good idea as it disturbs future incremental backups.
  906.  
  907. TAR: On extract, tar now correctly creates all required subdirectories
  908. in the path of a file. Previously only the trailing component was
  909. created (the corresponding code in tar relies on getting a specific
  910. error code from mkdir, but every system or library seems to behave
  911. differently in this respect).
  912.  
  913. Removed -G aka --incremental. Renamed --listed-incremental to
  914. --incremental. Added a new -G aka --generation. The functionality of a
  915. plain -g hasn't changed though.
  916.  
  917. OS/2 only: Added --all-files as an additional long option name for -p:
  918.  
  919. -g aka --incremental now implies --all-files and --all-timestamps.
  920.  
  921.     2.10:
  922.  
  923. Added SCSITAPE.SYS, since SCSITAPE.DMD doesn't run on IBM PS/2
  924. machines. Note that this driver has a different license statement as
  925. all other programs and drivers distributed in this package.
  926.  
  927. The Service Pack (2.00.1) contains a valid ASPI driver, so you now have
  928. to choose between 3 different tape device drivers :-).
  929.  
  930. Due to a bug in OS/2 syslevel 2.00.1, earlier version of TAR may fail
  931. to backup extended attributes or may even crash.
  932.  
  933. You can use the filesystem's archive bit for incremental backups now
  934. (thanks to Kai Uwe Rommel). See --archive and --reset-archive.
  935.  
  936. QFA now works with a variable blocksize.
  937.  
  938.     2.11
  939.  
  940. Bugfix release. 2.10 didn't accept EAs when reading an archive. 2.11
  941. now creates correct archives and is able to read archives creates with
  942. 2.10.
  943.  
  944.     2.12
  945.  
  946. TAR: Had to fix the very same bug again since the library function
  947. mkdir() changed in EMX 0.8f. It returns the unix-like error code now,
  948. when the dir already exists, so TAR once again failed to create the
  949. proper directories on extract.
  950.  
  951. ─────────────────────────────────────────────────────────────────────────
  952. Notes:
  953. ------
  954.  
  955. I've got questions of the kind "I'm desperately seeking the command to
  956. format the tape.". Well, neither QIC (DC6xxx) nor DAT not Video8 tapes
  957. have to be formatted before use. Only floppy tapes have to be formatted
  958. because of a limitation of the used floppy controller.
  959.  
  960. Although this version is compiled using EMX 0.8f, it's extended
  961. attribute support is not yet used. The EA representaion in the archive
  962. is still an aligned image of what OS/2 returns in its API. Things might
  963. change in future releases though.
  964.  
  965. ─────────────────────────────────────────────────────────────────────────
  966.