www.delorie.com/djgpp/doc/utils/utils_3.html   search  
DJGPP Utilities Reference

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. djtar

Usage: djtar [-n `changeFile'] [-e `dir'] [-o `dir'] [-t|-x] [-i] [-v] [-p] [-.|-!.] [-d|-u|-b] `tarfile'

djtar is a program that is designed to ease the problems related to extracting Unix tar files on a DOS machine. The long file names and illegal characters make regular tar programs useless. What djtar does is make some obvious name conversions automatically and give you an opportunity to provide alternate names for more difficult cases, where several filenames map to the same name in the restricted 8+3 DOS filename space.

djtar can read compressed tar files and decompress them on the fly. (This can be also achieved by piping the output of gzip to djtar, but for very large archives you can run out of free disk space, because DOS implements pipes as temporary disk files.) djtar knows about all the compression methods supported by gzip, namely, deflation (by gzip), LZW compression (by compress), LZH compression (as with compress -H available with some versions of compress), or Huffman compression (by pack).

djtar can decompress `.tar' archive files compressed with bzip2, even if several of such bzip2-compressed `*.tar.bz2' or `*.tbz' archive files have been concatenated into a single file.

djtar can decompress files compressed with zip or pkzip as well, but only if the `.zip' file contains only files compressed with either the deflation or stored (i.e., uncompressed, like with `pkzip -e0') methods.

djtar can also read tar archives (compressed or otherwise) written on a Unix machine to a diskette as a raw device (i.e., without DOS filesystem). To use djtar with such archives, specify a name of the drive (like A:) as a tarfile argument.

When extracting files from compressed archives, djtar will validate them with whatever reduntant checks are available with the compression format, and print diagnostic messages whenever these checks fail. The checks and the diagnostics are generally identical to those performed by gzip. Some of the diagnostics are only printed under the verbose operation switched on by the `-v' switch. Unless you use the `-i' switch, djtar will refuse to create files and directories beyond the first tar directory entry which fails the checksum test; this usually means the file is either corrupted or not in a valid tar format.

An additional bonus of using djtar is that it can convert Unix-style text files to DOS-style text files, and vice versa. By default, it will write all files exactly as found in the archive, but the `-u' and `-d' options can change that. djtar will always convert DOS batch files to DOS-style text files, if they have been stored as UNIX-style text files. This is because `command.com' refuses to run batch files that contain UNIX-style EOLs.

djtar performs a number of file name conversions in an attempt to make the files fit into MS-DOS's restricted file names. Any file ending in `.info-n', where n is a number, becomes `.in'. Any file ending in `.tar.gz' becomes `.tgz'. Any file ending in `.tar.bzip2', `.tar.bz2' or `.tar.bz' becomes `.tbz' and any file ending in `.bzip2' becomes `.bz2'. Any `++' string within a file name becomes `xx'. Any leading dots are changed to underscores (but current and parent directories, `./' and `../' are left alone). Any remaining multiple dots are changed to dashes, unless the part before the dot is shorter than 3 characters and there are more than 1 dot in the filename, in which case the dot also becomes an underscore. As a result, e.g., `.foo.a.b' becomes `_foo.a-b', and `sh.lex.c' becomes `sh_lex.c'.

While djtar is running, if it cannot successfully perform an exclusive open of the given file (it will refuse to overwrite an existing file), it will prompt you for a new name. You may type in either a complete path, a replacement file name (no directory part), or just hit return (the file is skipped).

If djtar is called as djtart, it behaves as if it were called with the `-t' switch; when called as djtarx, it behaves like djtar -x. Thus you can create 2 links to `djtar.exe' which will save you some typing.

By default, djtar just lists the contents of the archive(s) given as its arguments. If you want to extract files, you must use the `-x' option.

Options:

-x

By default, djtar just lists the contents of the archive(s) given as its arguments. If you want to extract files, you must use this option, or call djtar via a link named djtarx.

-t

This option causes djtar to only print the contents of the tar file, without actually creating any files. All the decompression, CRC checks etc. are still performed; thus, this option can also be used to test archive integrity. This is the default behavior of djtar, unless you call it via a link named djtarx.

-v

This option modifies the output format slightly to aid in debugging tar file problems. It also causes djtar to emit more verbose warning messages and print the compression method for compressed archives.

-.

Enable the automatic conversion of dots to underscores and dashes. This is the default.

-!.

Disable the conversion of dots. You get the control of file renaming when names of several files clash.

-n `changeFile'

This option allows you to specify a list of filename conversions ahead of time. Thus, you can use djtart or djtar -t to list the files, figure out the new names with your favorite editor, and supply that file to djtar. This way, you have the fullest possible control on how the extracted files will be named on your system.

The format of the `changeFile' file is like this:

 
dir/dir/dir/old.name.here  dir/dir/dir/newname.hre
dir/dir/dir/old2.name.here  dir/dir/dir/newname2.hre
dir/dir/dir.to.skip.here

The directories must be complete, not relative. The "old" directories must match the complete path in the tar file, and the "new" directories indicate where the file goes on the DOS disk. If there is no "new" directory specified, the "old" one and all its siblings will be not extracted.

-d

Convert all text files to DOS text format on output. This won't usually affect binary files, but as djtar detects the file type by looking at its first 512 bytes, a small possibility of a binary file rendered useless by this conversion still exists, so you're advised to only use this option with archives of text files.

By default, djtar writes all files exactly as it finds them.

-u

Convert all text files to UNIX text format on output. This won't usually affect binary files, but as djtar detects the file type by looking at its first 512 bytes, a small possibility of a binary file rendered useless by this conversion still exists, so you're advised to only use this option with archives of text files.

By default, djtar writes all files exactly as it finds them.

-b

Write all files exactly as found in the archive, with no conversions of text files. This is the default. Files written to the console (when `-p' is in effect) are always written in text mode, so this option doesn't have any effect when used with `-p', unless the output of djtar is redirected to a file or a pipe.

-e string

Only extract files whose full path names do not begin with string. This option can be used to skip portions of archive. If both this and `-o' options are specified, then this option has precendence. In other ways `-e' is similar to `-o' option.

-o string

Only extract files whose full path names begin with string. This option can be used to extract portions of archive. Files which aren't extracted will still be shown, but with a string `[ skipped ]' appended to their names. When given the `-o' option, djtar actually checks if string is the initial substring of each filename, so you can specify incomplete file names, thus using `-o' as a poor man's wildcard facility. You may specify multiple `-o' options to extract several different directories and files.

-i

Attempt to unpack damaged archives. By default, djtar will refuse to create files whose directory entries in the tar archive fail the checksum test, and any files beyond that point. This option tells djtar to ignore the checksum test and proceed anyway. Checksum failure usually means that the tar file is either corrupted or not in valid tar format, so this option is meant to be used either with the `-t' option, or in the rare cases when you know for sure the tar file is valid (like if you had to edit it to change the filenames).

-p

When given this switch, djtar will write the files to its standard output, which can be piped into another program (like a pager) or redirected to a file. This option is designed to allow you to view or extract individual files (e.g., the `README' files) without having to open the entire archive, and should be used with an appropriate `-o filename' option.

When this option is used, diagnostic messages will be directed to the standard error stream (as opposed to standard output in normal operation), so that they won't get mixed with the files' data.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster   donations   bookstore     delorie software   privacy  
  Copyright 2004   by DJ Delorie     Updated Nov 2004