home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 9 Archive / 09-Archive.zip / untgz095.zip / UNTGZ.DOC < prev    next >
Text File  |  1997-02-17  |  16KB  |  371 lines
  1.  
  2.  
  3.                    U N T G Z
  4.  
  5.             D e c o m p r e s s i o n   U t i l i t y
  6.  
  7.                           Version 0.95 - Feb 17, 1997
  8.  
  9.  
  10.         
  11.                 "useful and easy tool"
  12.          "It is making a big difference to my quality of life."
  13.    "It's great for those Unix type zip files 'tar' on a lot of these ftp sites"
  14.  
  15.                  (statements from UNTGZ users)
  16.  
  17. Overview of this documentation:
  18.  
  19.         1. INTRODUCTION - What is UNTGZ ?
  20.         2. HOW TO USE UNTGZ
  21.         3. UNTGZ OUTPUT
  22.         4. OVERWRITE QUERY
  23.         5. HOW DO I CREATE .TGZ ARCHIVES ?
  24.         6. PROBLEMS ?
  25.     7. ERROR / WARNING MESSAGES
  26.     8. HOW GOOD IS THE .TGZ ARCHIVE FORMAT ?
  27.         0. TO DO: What further UNTGZ versions will feature
  28.        10. THANKS AND CREDITS TO:
  29.        11. WHERE TO GET THE LATEST VERSION
  30.        12. LICENSE / CONTACTING THE AUTHOR
  31.  
  32. 1. INTRODUCTION - What is UNTGZ ?
  33.  
  34.  UNTGZ is a utility that lets you decompress archives created with the UNIX
  35. TAR/GZIP programs under MS-DOS. These archives usually have the extension .TGZ
  36. and are a very common standard for ftp-servers or UNIX-oriented CD-ROMs.
  37. Note that there are also DOS versions of TAR and GZIP, however, if you want to
  38. decompress TGZ archives with these programs, large temporary files will be cre-
  39. ated. The result is that TGZ decompression under MS-DOS used to be very slow.
  40. With UNTGZ, you can decompress these archives in a single step without creating
  41. temporary files, which means it is much faster.
  42. In addition to this, UNTGZ provides a conveniant way to extract uncompressed
  43. TAR files. UNTGZ can also uncompress gzip'ed files that do not contain a TAR
  44. archive. Plus, there is support for PKZIP compressed TAR archives.
  45.  
  46. Another feature of UNTGZ is the filename conversion. If an archive contains
  47. long (UNIX-style) pathnames, these will automatically be converted into the
  48. MS-DOS '8.3' format (not in the Windows NT version, of course).
  49. If the archive contains subdirectories, these will be created automatically.
  50.  
  51. If you are familiar with UNIX: UNTGZ does the same as the 'tar xfz' command.
  52.  
  53. There are several versions of UNTGZ: UNTGZ.EXE, UNTGZ386.EXE and UNTGZ32.EXE.
  54. An OS/2 Version is now also available (UNTGZOS2.EXE) thanks to Nitin Chandra.
  55. UNTGZ is the standard version which runs on any PC-compatible computer, in-
  56. cluding XTs. UNTGZ/386 is smaller and faster, but requires at least a 386SX
  57. to run. If you have a 386/486/pentium computer, I would suggest renaming 
  58. UNTGZ386.EXE to UNTGZ.EXE.
  59. UNTGZ32 is the Windows NT/Windows 95 version. It is a true 32-bit WIN32
  60. application (character mode) and can be run within a Windows NT/95 DOS box.
  61. If you have Windows NT or Windows 95, then I would strongly recommand using
  62. UNTGZ/32bit, as it is _by far_ faster than the DOS version and supports long
  63. filenames.
  64. If you are interested in how UNTGZ works, the source code is also available.
  65.  
  66. 2. HOW TO USE UNTGZ
  67.  
  68. USAGE:  UNTGZ <filename> <filespec> to extract from TGZ/TAR archive
  69.         UNTGZ -l <filename> <filespec> to list/test TGZ/TAR archive
  70.         UNTGZ -t <filename> to test CRC of GZ/TGZ archive
  71.         UNTGZ -d <infile> <outfile> to decompress GZ archive
  72.  
  73.         GZIP compressed , PKZIP compressed and uncompressed TAR archives
  74.         are supported. You can also use UNTGZ to extract the first file of
  75.         a "normal" PKZIP archive, using the -d option.
  76.  
  77.  To decompress an archive, just type 'UNTGZ archive.tgz'. If you wish to 
  78. extract only specific files, you may specify a filename to extract, or a
  79. combination of wildcards. Example: 'UNTGZ archive.tgz *.c'.
  80. (UNTGZ supports UNIX-style wildcards: * ? [a-b] [!a-b] [^a-b])
  81. Wildcards are not case-sensitive.
  82. UNTGZ will also perform a CRC-check while extracting and inform you if the
  83. archive is damaged.
  84.  
  85. To list the contents of an archive without extracting anything, type the 
  86. following: 'UNTGZ -l archive.tgz'. You can also specify wildcards to list
  87. only selected files. Example: 'UNTGZ -l archive.tgz *.exe'.
  88. Either '-' or '/' may be used as switch char. Commandline arguments are
  89. case insensitive. E.g. 'UNTGZ -l test.tgz' is equivalent to 'UNTGZ /L test.tgz'.
  90. Note that listing an archive will also automatically perform a CRC check.
  91.  
  92. 3. UNTGZ OUTPUT
  93.  
  94.  When you decompress an archive, UNTGZ will tell you the date and time of its
  95. creation as well as the platform on which the archive was created. At this time
  96. the following platforms are recognized:
  97. MS-DOS, OS/2, UNIX, Windows NT / Win32, VAX/VMS, Amiga, Atari, Macintosh,
  98. PRIMOS, TOPS20.
  99. If the platform is not recognized, UNTGZ will report 'unknown platform' as well
  100. as the ID number of the platform.
  101. UNTGZ will then show which files are currently decompressed. If filename con-
  102. version is performed, the MS-DOS name will also be displayed. Example:
  103. ' Extracting verylong-name.c to verylong.c'.
  104. You can abort decompression by pressing Ctrl-Break. Note that this may cause
  105. the file which is currently decompressed to be corrupt.
  106.  
  107. 4. OVERWRITE QUERY
  108.  
  109.  If UNTGZ tries to create a file which is already present on the hard disk, it
  110. will show a prompt in the form 'overwrite (Y/N/A/S/R/Q)'. Valid answers are:
  111. Y  (Yes)    : the file will be overwritten.
  112. N  (No)        : the file will not be overwritten.
  113. A  (Always)    : all files will be overwritten - no more queries
  114. S  (Skip)    : no files will be overwritten - no more queries
  115. Q  (Quit)    : abort decompression
  116. R  (Rename)    : prompt for new filename.
  117.           When entering the new filename, type the whole path.
  118.           Remember to use UNIX-style path separators ('/')
  119. Note that you may sometimes get this overwrite-query even when decompressing an
  120. archive to an empty directory. This is due to the conversion of long filenames
  121. to the MS-DOS format. For instance, the file 'verylong-1.name' and the file
  122. 'verylong-2.name' will both be called 'verylong.nam' after converting their
  123. names to the '8.3'-format. You will then get the overwrite-query. So, be care-
  124. full when you get the (Y/N/A/S/R/Q)-query while decompressing long-filename
  125. archives.
  126.  
  127. 5. HOW DO I CREATE .TGZ ARCHIVES ?
  128.  
  129.  To create .TGZ archives, you need two programs: TAR and GZIP. Type:
  130.  
  131. tar cvf archive.tar *.*
  132. gzip archive.tar
  133. ren archive.taz archive.tgz
  134.  
  135. This will compress all files in the current directory and its subdirs into the
  136. archive 'archive.tgz'
  137. Of course, this is complicated and slow. If you want real fast compression,
  138. use the UNIX tar program.
  139. There is also a program called X1 that can create .TGZ archives. X1 is
  140. very fast and supports many other archive formats, too - including ZIP, ARJ
  141. LZH, etc. If you're looking for a versatile compression program that can
  142. also create TGZ archives, then get X1.
  143. X1 is job(free)ware and you can get the most recent version from
  144. ftp://ftp.elf.stuba.sk:/pub/pc/pack/x1dos???.zip.
  145. Make sure you get the latest X1 version. Older versions use '\' as path
  146. seperator (dos style) and not '/', as other tar implementations do.
  147. This means that X1-created TGZ archives containing subdirectories are
  148. incompatible with the UNIX tar.
  149. UNTGZ can't decompress these archives, either.
  150. This problem is present in X1 0.94e and older versions.
  151.  
  152. 6. PROBLEMS ?
  153.  
  154. At the moment, UNTGZ can only decompress files compressed with the 'deflation'
  155. algorithm (GZIP method 8). This is the same algorithm used by PKZIP.
  156. UNTGZ cannot decompress archives created by the COMPRESS command. This is due
  157. to licensing restrictions; the LZW algorithm used by COMPRESS is patented by
  158. Unisys.
  159. Archives created using SCO 'PACK' aren't supported, either. Maybe I'll imple-
  160. ment this some day ...
  161.  
  162. When decompressing a broken archive, and you answer 'No' at the query
  163. "untgz: warning - possibly invalid tar archive, skip to next block",
  164. weird things may occur. This may even lead to a crash. Answer N only if you
  165. are 100% sure about what you are doing.
  166. The 'No' is only to allow decompression of archives having a broken checksum
  167. field.
  168.  
  169. The OS/2 version may not work correctly if you extract an archive with long
  170. filenames on a FAT drive. If you extract such an archive on a FAT partition,
  171. use UNTGZ for DOS. No Problems on HPFS Partitions.
  172. Sorry, but as I don't have access to an OS/2 machine, I cannot implement
  173. OS/2 specific checking routines.
  174.  
  175. 7. ERROR / WARNING MESSAGES
  176.  
  177. untgz: error - can't open archive.tgz
  178.     - the archive name you have specified is invalid (file not found).
  179.     - the archive cannot be opened for another reason (SHARE problem).
  180.  
  181. untgz: error - missing filename
  182.     - you have used the -l option without specifying an archive name.
  183.  
  184. untgz: error - '.' is not a valid filespec.
  185.     - '.' is not usable as a specification of files to extract
  186.  
  187. untgz: decompression engine error - bad compressed data.
  188.         - the archive is severely damaged and cannot be decompressed.
  189.  
  190. untgz: error - unknown archive type.
  191.         - the archive is not a gzip archive or uncompressed TAR archive.
  192.           PKZIP archives are not supported at the moment.
  193.  
  194. untgz: error - unknown compression (0)
  195.         - the gzip archive uses a compression type unknown to UNTGZ.
  196.           Only deflation (method 8) is supported, as gzip 1.2.4 does
  197.           not support other compression methods.
  198.  
  199. untgz: error - multi-volume archives not supported
  200.         - UNTGZ cannot decompress the archive, because it is a multi-
  201.           volume archive.
  202.  
  203. untgz: error - don't know how to handle extended gzip header.
  204.         - extended gzip headers are not supported. I have never seen a
  205.           gzip file with extended header, as they are totally uncommon.
  206.           If anyone needs extended header support anyway, please send mail.
  207.           I will then implement it.
  208.  
  209. untgz: error - unexpected EOF
  210.         - the tar archive is truncated and cannot be correctly decompressed.
  211.  
  212. untgz: error - unexpected end of file
  213.         - the gzip archive is truncated and cannot be correctly decompressed.
  214.  
  215. untgz: error - file is encrypted.
  216.         - decryption is not supported and probably never will be.
  217.           (Export restrictions?)
  218.  
  219. untgz: internal error - nothing to do.
  220.         - congratulations, you have found a bug in UNTGZ! (I hope you'll
  221.           never see this message). Please report what circumstances have
  222.           caused this message.
  223.  
  224. untgz: error - aborted, file may be corrupt.
  225.         - you have pressed ctrl-break (DOS versions only)
  226.  
  227. untgz: error - unable to create directory
  228.         - the directory cannot be created. The most common reason for
  229.           this problem is that a _file_ already exists having the same
  230.           name as the directory to be created.
  231.  
  232. untgz: error - can't create file, skipping file.txt
  233.         - disk write-protected?
  234.         - disk full?
  235.         - file read-only?
  236.         - SHARE problem?
  237.  
  238. untgz: error - can't write file, disk full?
  239.         - This message is self-explanatory.
  240.  
  241. untgz: warning - possibly invalid tar archive, skip to next block (Y/N/A/Q)
  242.         - The archive is a 'normal' gzip file and does not contain a TAR
  243.           archive, (this is most likely. Use -d switch!) 
  244.         - The TAR archive contains redundand date (between headers).
  245.         - The TAR archive is broken.
  246.         - RECOMMENDED OPERATION: JUST PRESS ENTER.
  247.           If you are sure this is _not_ a TAR archive, then press Q.
  248.           Answering 'Yes' will cause UNTGZ to check if the next block is
  249.           a valid TAR header. Answering 'Always' or pressing Enter will
  250.           cause UNTGZ to search for a valid TAR header.
  251.           Answering 'No' will ignore that the header information is not
  252.           valid and will attempt decompression anyway. (Warning! This may
  253.           even cause a crash!) Answer 'No' only if you know what you are
  254.           doing (e.g. when trying to fix a broken TAR archive).
  255.  
  256. untgz: warning - duplicate directory name
  257.         - the directory UNTGZ tried to create already exists.
  258.  
  259. untgz: warning - broken file(s), crc32 error!
  260.         - CRC error. The decompressed data is invalid.
  261.         - Due to the GZIP/TAR archive format, it is not possible to say
  262.           in which file the error occured.
  263.  
  264. 8. HOW GOOD IS THE .TGZ ARCHIVE FORMAT?
  265.  
  266. Here's a short comparison between .TGZ and other common archive formats:
  267. I've compressed the Borland CLIB source (C+ASM source) into a single archive.
  268. (C:\BORLANDC\CTRL\CLIB\*.*). If you don't believe the test results, then
  269. TRY THIS AT HOME!
  270.  
  271. Original size: 1.294.460 bytes
  272.  
  273. Packer:            Command:                                Archive size:
  274. ARJ 2.41a       ARJ -jm clib.arj *.*                398.834 bytes
  275. LHA 2.13       LHA a clib.lzh *.*                395.336 bytes
  276. PKZIP 2.04g       PKZIP -ex clib.zip *.*            412.316 bytes
  277. Ultra Compress II  UC2 a clib.uc2                257.932 bytes
  278. TGZ           TAR cvf clib.tar *.*; gzip -9 clib.tar    240.866 bytes
  279. TGZ (X1)       X1 a CLIB.TGZ                234.080 bytes
  280. RAR 2.00 (solid)   RAR a -m5 -s clib.rar            231.564 bytes
  281.  
  282. All archivers, including UC2, were configured to provide maximum compression.
  283. This comparison is not meant to show that other archivers are bad. It should
  284. just show that the .TGZ archive format is quite competitive in terms of
  285. compression performance.
  286.  
  287. 9. TO DO: What further UNTGZ versions will feature
  288.  
  289. - whatever YOU suggest
  290.  
  291. 10. THANKS AND CREDITS TO:
  292.  
  293. - Mark Adler:        for putting his INFLATE.C in the public domain.
  294.             INFLATE.C provides the decompression routines
  295.             for UNTGZ.
  296.  
  297. - Nitin Chandra:        OS/2 Version. Compilation of Win32 version (0.93).
  298.   nitin@indiagate.com   Useful hints and source modifications.
  299.  
  300. - Joan Poveda           Compilation of OS/2 and Win32 versions (0.94 and
  301.   sheltie@ctv.es        0.95)
  302.  
  303. - The authors of UNZIP:    for their wildcard matching routines (MATCH.C)
  304.  
  305. - Mateusz Majer:    for providing moral support and for trying to
  306.             develop a freeware TGZ packer.
  307.  
  308. - Chin-yuan Kuo:        for his very detailed and useful bug report
  309.  
  310. - my girlfried:         for not complaining that I spend so much time
  311.                         programming ;-)
  312.             Yes, it's still the same girlfriend as in 
  313.             Version 0.93.
  314.  
  315. - all those who sent e-mail to encourage further development!
  316.   Thanks! Without you, UNTGZ wouldn't be what it is today - so
  317.   continue writing and support freeware.
  318.                         
  319. 11. WHERE TO GET THE LATEST VERSION
  320.  
  321. On the world wide web, go to the page
  322.  
  323. http://people.darmstadt.netsurf.de/tst/untgz.htm
  324.  
  325. If this doesn't work, then download it from:
  326. ftp://ftp.elf.stuba.sk/pub/pc/pack/untgz???.zip
  327. There are some mirror sites, too.
  328.  
  329. UNTGZ is also available from the SimTel.net software archive.
  330. Simply search for "untgz". There are over 60 mirror sites all
  331. over the world.
  332.  
  333. UNTGZ is available from The Solutions! BBS. +91-11-6855362, 6965881, 6867674
  334. 24 Hrs, FREE, Over 2 GB Online, IndiaNet, OS/2 newsgroups.
  335.  
  336. For a more or less complete list of other programs that can handle TAR/TGZ/GZIP
  337. files, visit:
  338.  
  339.         http://people.darmstadt.netsurf.de/tst/tar.htm
  340.  
  341. The location for my homepage may change in the future.
  342. An AltaVista search for "Tillmann Steinbrecher" should find the
  343. new location.
  344.  
  345. 12. LICENSE / CONTACTING THE AUTHOR
  346.  
  347.         This freeware program may be distributed according to 
  348.         the terms of the GNU general public license version 2.
  349.     
  350.     See file 'copying' for details.
  351.  
  352.         You can contact me via e-mail: tst@bigfoot.com
  353.  
  354.         If you have any suggestions to make, don't hesi-
  355.         tate to send e-mail.
  356.  
  357.         If you can find a bug in UNTGZ, I URGE YOU to report
  358.         it accompanied my the information I need in order to
  359.         fix it. Thanks a lot.
  360.  
  361. Here's my snail-mail address:
  362.  
  363.     Tillmann Steinbrecher
  364.     Im Wiesengrund 10
  365.     D-64372 Ober-Ramstadt
  366.     GERMANY
  367.  
  368. Amazing that somebody actually _read_ this doc.
  369.  
  370. All trade marks are property of their respective owners.
  371.