'tar' - is an acronym for 'tape archiver' It is a tool to save files to archive media and restore them back again. Despite of its name, the program handles many media types, be it a floppy disk or regular file. The program was initially written for UNIX operating system, but since many other OS support its format, tar became a useful tool for information exchange between different platforms. This document describes yet another implementation of the program, which could be noted for portability between MS-DOS and UNIX clones, portability both in data format and source text level. System requirements Program will execute - on any IBM PC compatible computer running MS-DOS 3.0 or compatible OS; - any generic UNIX clone. Before running the program you will probably have to compile it, especially if you are a UNIX user. To do that you should have: - any C compiler compatible with K&R or ANSI standard - for UNIX version; - Turbo C v2.0 under MS-DOS 3.30 - for DOS version. Declaring such a wide portability shall probably have some restrictions, but, alas, I do not know about them. The size of free memory required for program depends of the action selected. As a rule, about 64K bytes is enough to read/write archives without compression. If you are going to use compression options, the program can take all the megabytes available. Anyway, the program will be able to process archive in a regular file (see below). It also supports floppy diskettes under MS-DOS. Media types available under UNIX is determined by device drivers available in the system. Running the program The program can be run simply from command line. You have to type to the system prompt a line with the following syntax: Tar ... where options define both action to perform and some additional options. You have to specify at least one option to define action, and command line must contain only one action option. Options can be preceded by '-' (minus) sign. Traditional command line syntax requires all the options to be typed in place, as a single command line argument. Some of the options require parameters, such as numerical value or a file name. Such parameters must follow the options, separated by spaces, exactly in the order of respective options. The rest of the command line contains a list of files to extract from archive or to store. This file list can be omitted for extraction options, such as 't' or 'x', in this case the program will process all the files in archive; other options makes the list obligatory. You may use wildcards '?' and '*' in file names both under DOS and UNIX. Note, however, that UNIX version can not process wildcards for files which are not in archive, this is done by command processor - e.g. shell - instead. Consult your manual for the details of wildcard processing. Here follows the list of options along with their descriptions (unlike most other implementations this program is case insensitive, i.e., makes no difference between upper and lowercase letters): a - add (store) files to archive, the option is fully analogous to traditional 'r' option, and was added to user convenience. You have to specify the list of files to be stored. Note, that normally files are appended to the end of archive, so the archive can contain several files with the same name; by default, the program will extract the latest version. Such a behavior may be changed by 'c', 'd' and 'w' options. x - extract files from archive; program extracts specified files, if no file name is given, the whole archive will be extracted. If the directory name appears in command line, the program extracts all of the files and subdirectories in a given directory. t - type archive directory. The files to be processed are defined as for the 'x' command. The program outputs list of file names, unless 'v' modifier is given. With 'v' option each file name is preceded by its UNIX access rights mask, numeric user and group identifiers and file length in bytes. Usage with 'e' or 'z' option forces printing both compressed and original file lengths. d - the specified files will be deleted from archive; this option is for file archives only. r - read files from disk to archive; the option is an alias for 'a', it is preserved for the compatibility reasons. c - the 'a' option implies that archive media contains an existing tar archive, or archive file already exists. The 'c' option creates a new archive or overwrites old one (if any). This option also implies 'a' so you do not need to specify it. y - delete files and directories after storing them into archive. This option implies 'a'. u - update archive. Normally program stores all of the files specified. Given option causes tar to store files only if they are not present in archive or if the files were modified. This option implies 'a'. i - ignore read errors. This option may help (but may not) to restore damaged archive. v - verbose. Normally program works silently; this option forces printing of a log with most operations or produces a lot of additional information with 't' option. w - the program will ask for your confirmation before processing each file. e - apply a compression to archive files. The compression algorithm has rather good compression ratio, but is processor intensive. Besides, you won't be able to restore the compressed file by standard 'tar' program - use this option carefully. z - compress files in archive with traditional UNIX algorithm. It is much faster than previous option, and it is compatible with most Unix systems, so you can extract files with 'uncompress' or even 'tar' program alone, but this algorithm has comparatively low compression ratio. You may specify 'bits' factor typing it immediately after z letter (e.g. z12); note, that this rule does not follow regular command line syntax. See 'compress' program manual to understand 'bits' factor meaning. , - (comma) this option is similar to 'z', but the whole archive will be (de)compressed rather than individual files. . - (point) this option is similar to ',' (comma) and allows to read deflated archive in regular zip or GNU zip format. s - program will not process '?' and '*' wildcards in archive file names. m - sets modification time of files to current time. By default the program sets date and time of modification for extracted files exactly as they have before they have been placed into archive. o - option meaning depends on the host operating system, namely under UNIX it means - omit files owner. By default program tries to restore original files owner and group. The option forces tar to set the user who invokes tar as files owner, which is especially useful when files are marked with zero owner, i.e. root'. under DOS respectively - prevent files overwriting. Since UNIX file names are longer than DOS, there is a chance that two or more UNIX files will have same DOS names, so they couldn't co-exist onto DOS disk. If the 'o' option given, the program will rename extracted file if there is a file on the disk with the same name. This option can also affect multivolume processing. Namely, if two different UNIX files have same DOS names and second file is fragmented between volumes then extents of the second file will be appended to first one. Alas, I see no solution for this problem. l - option meaning depends on the host operating system, namely under UNIX it means - print list of files being archived, which have other links besides those placed in archive. under DOS respectively - make copies of linked files to simulate UNIX links (otherwise the program will extract first copy only and print warning messages on the others). p - save in archives directories info (e.g. owner and permissions) as well as files. n - no directory nesting. The program will not recurs into subdirectories. / for UNIX or \ for DOS - omit left slash in file names. : - omit MS-DOS drive name from file name. j - you will be prompted to add file comment while storing; this comment will be shown by 't' option. Note, that used implementation of this option is incompatible with P1003 standard, so I had to choose between either standard or backward compatibility. In any case you'd better avoid this option. f - this option requires an argument - a name of archive file or special file. By default, program tries to get a file name from 'TAPE' environment variable. If no archive name is given, tar tries to handle floppy disk under MS-DOS or to use /dev/mt0 under UNIX. File names are also used to support hardware devices, i.e. floppy disks and streamers. See section 'Special files' below. You also can store default file name (without 'f' option itself) into 'TAPE' environment variable - this is especially useful with streamer devices. The name consisting of single minus sign stands for standard input/output. This is UNIX convention and it is better to avoid this possibility under MS-DOS. k - this option requires an argument, diskette capacity in Kbytes. Although the program tries to adjust appropriate diskette type for a given hardware, you often will not be able to read or write floppies without defining its type. This option is not applicable in UNIX version. b - this option requires an argument, so called 'blocking factor'. This program allows blocking factor in the range of 1 to 32. The sense of the option is rather tricky. Big blocking factor allows to save much space on some tape devices, but if you are going to transfer data between different computers I strongly recommend not to use blocking factor more than 16. Note, that original tar does not allow values more than 20. In general this option does not influence the resulting archive with floppy devices or regular files, but appropriate value can drastically increase tar speed. As a rule, this program adjust the most appropriate blocking factor, so you do not need to use this option, but it is also possible that you will not be able to restore files without setting properly the value for a given archive. [0-9] single digit stands for the number of storage device; e.g. 1 means MS-DOS drive B: @ - this option requires an argument - a name of file, containing the continuation of a command line. This option allows tar to read a list of file specification from a separate file. As above, a file name consisting of single minus means standard input. The size of input defined by this option must not exceed 32760 bytes. Special files Special files (also called 'device drivers') are widely used in UNIX to interact with hardware devices. There are no useful special files under MS-DOS (oh, of course you can create an archive at 'nul', it will go to the neverland), but DOS version supports its own internal special file names, which are divided into two groups. The following file names designate floppy devices: fd048ss8, fd048ds8, fd135ds9, fd048ss9, fd048ds9, fd135ds18, fd096ds9, fd096ds15, rainbow Such a "file name" consists of the following components: - device type, e.g 'fd'; - floppy radial density, e.g. 048, 096 or 135 tracks per inch; first two relate to 5.25" floppies, the last is for 3.5" disks; - number of working surfaces: ss means 'single side' while ds - 'double side'; - the last value is a number of sectors per track. Note, that usually you do not need to use this mechanism, it could be better to set 'k' option instead. The last name, "rainbow", is for disks in DEC Rainbow format; it has no equivalent options. For better hardware compatibility it is recommended to format such disks on the PC they will be read or written. There exists a couple of PC programs, which allow such formatting. The second group of special file names refers to QIC-02 streamer tape devices. Be aware that you have QIC-02 device, since the program does not support for example SCSI or QIC-40/80 devices. Since streamers have no standard software interface like BIOS it's necessary to mention device hardware configuration in a command line (or 'TAPE' environment variable - see above). So, streamer 'file name' have a complex syntax, it includes - device name itself, followed by - separator - colon or semicolon - and - parameter list. The parameter list consists of parameter groups separated by commas, semicolons or dots (there is no difference). Each parameter group (save 'norewind parameter - see below) in turn consists of keyword followed by assignment (:=) and some value. The program recognizes three device names: Archive, Everex and Wangtek Each name means device clone name and corresponds to plenty of device brands. Most of existing QIC-02 streamers belongs to one of the above three types. The names of the clones are borrowed from the trademarks of their respective manufacturers but keep in mind that there is no strict rule (e.g. Archive corporation produced streamers that fits to Everex clone). Usually you have test you streamer with different device names to select appropriate one. Parameter list may include the following options (most of them concerns to hardware, so consult you streamer documentation): base:= - IO base address, this is the only obligatory parameter; dma:= - DMA channel number; there is a rumor about devices without DMA, but I have not seen one, so usually you have to use this option; irq:= - interrupt request number; as a rule you do not need to use this option, but it may or may not solve hardware problems, such as - another device uses same interrupt request number, - your system BIOS has no default handler for hardware interrupts; qic:= - defines tape format/capacity, valid QIC numbers are 11, 24, 120, 150, 300, 600, 2100 and 2200; first four formats may also be specified by corresponding number of tracks as tracks:= Note, that most streamer devices can not support all this formats; since the program can not detect formats supported you should yourself care of proper tape format. Fortunately most streamers detect format of existing data or set its default format for writing, so as a rule you do not need in this option at all. norewind - this is the only keyword which does not require corresponding value. The option is supplied to maintain several archives on a single tape. (Note that QIC-02 standard does not allow to add files into existing tar archives. This program includes an option to do that, but it is possible that hardware disables it. You do allowed to handle several archives on a tape, but keep in mind that it is not allowed by some UNIX systems). Unlike device name, parameters may be shortened, it is possible to mention as many (few) letters from keyword as you like or omit any part - ':' or '=' - of the assignment sign or both of them (see example below). The only blocking factor allowed by all QIC-02 devices is 1 - and it is default value for streamer tape in this program. Unlike many other implementations which fragments large logical block into small physical pieces, you are allowed to change the physical block size, but I have no idea about results. GENERIC WARNING: I made all possible efforts to provide robust hardware interface, but I have no means to make it 100% reliable. So BEFORE storying any useful information, please check that data written by this program can be read afterwards. Examples List file names in archive anyfile.tar: Tar tf anyfile.tar Print verbosely directory of 1.2M floppy in drive B: Tar tv1k 1200 Store all files from given list to tape, as dense as possible: Tar cvebf@ 32 /dev/tape listfile.s Extract all files from streamer cartridge (in DOS), hardware chosen as IO base address 300h, DMA channel 1 and QIC-24 tape format: Tar xvf archive:b300,dma:=1,t:9 Compiling the program Before doing this, you need to have a properly installed C compiler. Place program sources into separate directory, then - type !compile at the DOS prompt to build DOS version. - issue make command to build UNIX version. Note: if you work under ISC UNIX or another System V, you should try 'make -f makefile.ix' command to decrease size of the executable file. Diagnostics Can only handle XX bits. Continue? Not enough RAM to perform un/compression with desired bits factor (either default or specified). You will be prompted to continue with maximum possible bits factor. Diskette capacity XXXK assigned Since you have not specified diskette capacity, the program informs you about its choice. Extract anyway? Archive file can not be uncompressed due to some reason and you are prompted to extract its compressed image. File compressed with XX bits, can only handle XX bits. Archive file can not be uncompressed for the current bits factor is less than the factor during compression. File is not in compressed format Although archive has '.Z' suffix, its structure does not match compressed one. Thus, the file can not be uncompressed and you will be prompted to extract it as is. No memory for encoding. Continue? Files can not be packed due to lack of free memory. You are prompted to store them unpacked. Tar: XXX blocks skipped to find header Archive corrupted, skipped blocks possibly contains lost information. Tar: '...' checksum error Checksum algorithm fails while unpacking the file. Tar: '...' decode error Internal compressor error. Tar: '...' decreased size File decreased size while the program stored it. Tar: '...' exceeds limit in size Input for '@' option exceeds 32760 bytes in size. Tar: '...' name too long The name of file in archive must not exceed 100 characters. Tar: '...' not a file Current version allows to store in archive regular files only. Tar: '...' seek error Error processing file. Tar: 'm' and 'u' options ambiguous Do you really want both this options? Tar: archive unchanged There was no job for 'u' or 'd' options. Tar: bad blocksize (max is 32) The program allows block factor in the range of 1 to 32. Tar: bad directory structure Archive is corrupted (file header error). Tar: bad option '.' Invalid character in option string. Tar: base address must be specified Error in streamer parameters (DOS only). Tar: blocksize = XX Since you have not specified block factor, the program informs you about its choice. Tar: blocksize multiply defined You have specified block factor more than once. Tar: can't access '...' Error processing file. Tar: can't create '...' Error processing file, probably the file system at your computer is full. Tar: can't create directory '...' Error processing file, probably the file system at your computer is full. Tar: can't create scratch file Error processing file, probably the file system at your computer is full. Tar: can't delete '...' Error processing file. Tar: can't delete scratch file Error processing file, this usually does not mean tar lost some data, but it indicates some filesystem problem. Tar: can't find '...' No file matches given wildcard specification (DOS only). Tar: can't handle '...' Error processing file. Tar: can't link '...' - data stay in '...' The program can not restore links properly (UNIX only). Tar: can't link '...' The program can not restore links properly (UNIX only). Tar: can't open '...' Probably the file given does not exist or access denied. Tar: can't open directory '...' Error processing directory, probably access denied. Tar: can't open file '...' Probably the file given does not exist or access denied. Tar: can't process '...' Error processing file. Tar: can't read '...' Error processing file. Tar: can't remove '...' The directory mentioned can not be deleted. Tar: can't rename '...' to '...' Error performing 'd' option, archive stayed unchanged. Tar: can't update stdout You may not apply given option to standard output. Tar: delete option is for file archives only Tar: device parameter error Error in streamer parameters (DOS only). Tar: directory checksum error Archive is corrupted (file header error). Tar: diskette error: ... Probably the diskette is corrupted. Tar: drive not present You have specified diskette drive which does not exist (DOS only). Tar: error extracting '...' Error processing file. Possible reason: there is no space left on the hard disk. Tar: error processing '...' Error processing file. Tar: error reading '...' Error processing file. Tar: error shrinking memory block Internal runtime error. Tar: fault run mkdir! The 'mkdir' command was not found in /bin, /usr/bin and /etc directories (UNIX only). Tar: fault run rmdir! The 'rmdir' command was not found in /bin, /usr/bin and /etc directories (UNIX only). Tar: incompatible options Tar: input must be free It is not allowed to use standard input with 'f' option and any of 'w' or 'j' options. Tar: insert NEXT diskette and press ENTER when ready... You are prompted to continue multivolume archive processing. Tar: invalid base address Error in streamer parameters (DOS only). Tar: invalid bits factor The bits factor must be in range of 12 to 16. Tar: invalid character after 'X' Error in streamer parameters (DOS only). Tar: invalid diskette size Allowed arguments for 'k' option are: 160, 180, 320, 360, 720, 1200, 1440 (DOS only). Tar: invalid DMA channel number Tar: invalid IRQ number Tar: invalid number of tracks Tar: invalid QIC number Error in streamer parameters (DOS only). Tar: missed XX link(s) to '...' The file has multiple links and given number of them were not stored in the archive; you will not see this message unless 'l' option is given (UNIX only). Tar: no files specified Tar: no memory to unpack. You will be prompted to extract packed image. Tar: not enough memory to uncompress You will be prompted to extract compressed file. Tar: not enough memory Tar: nothing to do You have to specify either 'a', 'x', 't' or 'd' option. Tar: out of memory; link(s) lost Not enough memory to keep list of links, links will be stored in archive as a separate files (UNIX only). Tar: tape blocksize error Error processing archive. Tar: tape close error Error processing archive. Tar: tape device multiply defined You have specified ambiguous options. Tar: tape read error Error processing archive. Tar: tape seek fault Error processing archive. Tar: tape write error Error processing archive. Possible reason: there is no space for archive file on hard disk. Tar: unknown parameter '...' Error in streamer parameters (DOS only). Tar: unsupported hardware configuration That is (DOS only). Tar: warning: bad sector XXX, skipped The sector has physical defects, tar has skipped it. Note: you will not be able to read such a diskette on another computer (DOS only). Tar: warning: can't open terminal device, may be problems Standard input is used for 'f' or '@' option and the program can not open terminal device (/dev/tty - UNIX only). Tar: warning: renamed to '...' UNIX file name was changed according to DOS rules.