Notes on the Amiga version of Zoo. (2.00) Please see the file changes which should have been included with this distribution for a list of the changes from the previous version of AmigaZoo. AmigaZoo supports full-length AmigaDOS filenames and can archive and restore a directory structure. Note, for adding comments to an archive, the Amiga's eof character is a control \. Thanks to some suggestions from a single drive user, this release of AmigaZoo has two commands to try and make their life a little bit easier when using AmigaZoo. The first is a command line option to AmigaZoo that causes it to wait for the user to press return before doing any disk I/O. If a "w" is the first character in the command AmigaZoo will wait for return. (zoo wx zfile) The other is a program, included in this distribution, that sets the behavior of the system back to how it was before a cd command is issued. This should make single drive users a little less loath to use the cd command. The program is called 'uncd'. AmigaZoo can be used advantageously with a pipe device. Though I have yet to see a shell that allows them to be used effortlessly, I have heard that they exist and would appreciate pointers to a good one. One use of a pipe that comes to mind, is the use of a find program, to archive a directory tree. A find program by Rodney Lewis was posted to usenet that serves nicely for this. One way of using this with the current CLI is to have two CLI's and type into one of them "find >p:list -type f -name *.c -print" then type into the other window "zoo file General modifiers The following modifiers are applicable to several commands: c Applied to the a and u commands, this causes the user to be prompted for a comment for each file added to the archive. If the file being added has replaced, or is a newer generation of, a file already in the archive, any comment attached to that file is shown to the user and becomes attached to the newly-added file unless the user changes it. Possible user responses are as described for the -comment command. Applied to the archive list command l, the c modifier causes the list- ing of any comments attached to archived files. . In conjunction with / or // this modifier causes any extracted pathname beginning with `/' to be interpreted relative to the current directory, resulting in the possible creation of a subtree rooted at the current directory. In conjunction with the command P the . modifier causes the packed archive to be created in the current directory. This is intended to allow users with limited disk space but multiple disk drives to pack large archives. d Most commands that act on an archive act only on files that are not deleted. The d modifier makes commands act on both normal and deleted files. If doubled as dd, this modifier forces selection only of deleted files. f Applied to the a and u commands, the f modifier causes fast archiving by adding files without compression. Applied to l it causes a fast listing of files in a multicolumn format. q Be quiet. Normally zoo lists the name of each file and what action it is performing. The q modifier suppresses this. When files are being extracted to standard output, the q modifier suppresses the header preceding each file. When archive contents are being listed, this modifier suppresses any header and trailer. When a fast columnized listing is being obtained, this modifier causes all output to be com- bined into a single set of filenames for all archives being listed. Printed 2/4/88 Feb 3, 1988 11 ZOO(1) UNIX Programmer's Manual ZOO(1) When doubled as qq, this modifier suppresses WARNING messages, and when tripled as qqq, ERROR messages are suppressed too. FATAL error messages are never suppressed. Recovering data from damaged archives The @ modifier allows the user to specify the exact position in an archive where zoo should extract a file from, allowing damaged portions of an archive to be skipped. This modifier must be immediately followed by a decimal integer without intervening spaces, and possibly by a comma and another decimal integer, giving a command of the form l@m or l@m,n (to list archive contents) or x@m or x@m,n (to extract files from an archive). Listing or extraction begin at position m in the archive. The value of m must be the position within the archive of an undamaged directory entry. This position is usually obtained from fiz(1) version 2.0 or later. If damage to the archive has shortened or lengthened it, all positions within the archive may be changed by some constant amount. To compensate for this, the value of n may be specified. This value is also usually obtained from fiz(1). It should be the position in the archive of the file data corresponding to the directory entry that has been specified with m. Thus if the command x@456,575 is given, it will cause the first 456 bytes of the archive to be skipped and extraction to begin at offset 456; in addition, zoo will attempt to extract the file data from position 575 in the archive instead of the value that is found in the directory entry read from the archive. For example, here is some of the output of fiz when it acts on a damaged zoo archive: **************** 2526: DIR [changes] ==> 95 2587: DATA **************** 3909: DIR [copyrite] ==> 1478 3970: DATA 4769: DATA **************** In such output, DIR indicates where fiz found a directory entry in the archive, and DATA indicates where fiz found file data in the archive. Filenames located by fiz are enclosed in square brackets, and the notation "==> 95" indicates that the directory entry found by fiz at position 2526 has a file data pointer to position 95. (This is clearly wrong, since file data always occur in an archive after their directory entry.) In actuality, fiz found file data at positions 2587, 3970, and 4769. Since fiz found only two directory entries, and each directory entry Printed 2/4/88 Feb 3, 1988 12 ZOO(1) UNIX Programmer's Manual ZOO(1) corresponds to one file, one of the file data positions is an artifact. In this case, commands to try giving to zoo might be x@2526,2587 (extract beginning at position 2526, and get file data from position 2587), x@3090,3970 (extract at 3090, get data from 3970) and x@3909,4769 (extract at 3909, get data from 4769). Once a correctly-matched directory entry/file data pair is found, zoo will in most cases syn- chronize with and correctly extract all files subsequently found in the archive. Trial and error should allow all undamaged files to be extracted. Also note that self- extracting archives created using sez (the Self-Extracting Zoo utility for MS-DOS), which are normally executed on an MS-DOS system for extraction, can be extracted on non-MSDOS systems using zoo's damaged-archive recovery method using the @ modifier. Wildcard handling Under the **IX family of operating systems, the shell nor- mally expands wildcards to a list of matching files. Wild- cards that are meant to match files within an archive must therefore be escaped or quoted. When selecting files to be added to an archive, wildcard conventions are as defined for the shell. When selecting files from within an archive, wildcard handling is done by zoo as described below. Under MS-DOS and AmigaDOS, quoting of wildcards is not needed. All wildcard expansion of filenames is done by zoo, and wildcards inside directory names are expanded only when listing or extracting files but not when adding them. The wildcard syntax interpreted by zoo is limited to the following characters. * Matches any sequence of zero or more characters. ? Matches any single character. Arbitrary combinations of * and ? are allowed. / If a supplied pattern contains a slash anywhere in it, then the slash separating any directory prefix from the filename must be matched explicitly. If a supplied pattern contains no slashes, the match is selective only on the filename. c-c Two characters separated by a hyphen specify a charac- ter range. All filenames beginning with those charac- ters will match. The character range is meaningful only by itself or preceded by a directory name. It is Printed 2/4/88 Feb 3, 1988 13 ZOO(1) UNIX Programmer's Manual ZOO(1) not specially interpreted if it is part of a filename. : and ; These characters are used to separate a filename from a generation number and are used when selecting specific generations of archived files. If no generation char- acter is used, the filename specified matches only the latest generation of the file. If the generation char- acter is specified, the filename and the generation are matched independently by zoo's wildcard mechanism. If no generation is specified following the : or ; charac- ter, all generations of that file will match. As a special case, a generation number of 0 matches only the latest generation of a file, while ^0 matches all gen- erations of a file except the latest one. If no filename is specified preceding the generation charac- ter, all filenames will match. As a corollary, the generation character by itself matches all generations of all files. MS-DOS users should note that zoo does not treat the dot as a special character, and it does not ignore characters fol- lowing an asterisk. Thus * matches all filenames; *.* matches filenames containing a dot; *_* matches filenames containing an underscore; and *z matches all filenames that end with the character z, whether or not they contain a dot. Usage hints The Novice command set in zoo is meant to provide an inter- face with functionality and format that will be familiar to users of other similar archive utilities. In keeping with this objective, the Novice commands do not maintain or use any subdirectory information or allow the use of zoo's abil- ity to maintain multiple generations of files. For this reason, users should switch to exclusively using the Expert commands as soon as possible. Although the Expert command set is quite large, it should be noted that in almost every case, all legal modifiers for a command are fully orthogonal. This means that the user can select any combination of modifiers, and when they act together, they will have the intuitively obvious effect. Thus the user need only memorize what each modifier does, and then can combine them as needed without much further thought. For example, consider the a command which is used to add files to an archive. By itself, it simply adds the speci- fied files. To cause only already-archived files to be updated if their disk copies have been modified, it is only necessary to add the u modifier, making the command au. To Printed 2/4/88 Feb 3, 1988 14 ZOO(1) UNIX Programmer's Manual ZOO(1) cause only new files (i.e., files not already in the archive) to be added, the n modifier is used to create the command an. To cause both already-archived files to be updated and new files to be added, the u and n modifiers can be used together, giving the command aun. Since the order of modifiers is not significant, the command could also be anu. Further, the c modifier can be used to cause zoo to prompt the user for a comment to attach to each file added. And the f modifier can cause fast addition (addition without compression). It should be obvious then that the command auncf will cause zoo to update already-archived files, add new files, prompt the user for comments, and do the addition of files without any compression. Furthermore, if the user wishes to move files to the archive, i.e., delete the disk copy of each file after it is added to the archive, it is only necessary to add the M modifier to the command, so it becomes auncfM. And if the user also wishes to cause the archive to be packed as part of the command, thus recovering space from any files that are replaced, the command can be modified to auncfMP by adding the P modifier that causes packing. Similarly, the archive listing commands can be built up by combining modifiers. The basic command to list the contents of an archive is l. If the user wants a fast columnized listing, the f modifier can be added to give the lf command. Since this listing will have a header giving the archive name and a trailer summarizing interesting information about the archive, such as the number of deleted files, the user may wish to "quieten" the listing by suppressing these; the relevant modifier is q, which when added to the command gives lfq. If the user wishes to see the **IX mode (file protection) bits, and also information about multiple gen- erations, the modifiers m (show mode bits) and g (show gen- eration information) can be added, giving the command lfqmg. If the user also wishes to see an attached archive comment, the modifier A (for archive) will serve. Thus the command lfqmgA will give a fast columnized listing of the archive, suppressing any header and trailer, showing mode bits and generation information, and showing any comment attached to the archive as a whole. If in addition individual comments attached to files are also needed, simply append the c modifier to the command, making it lfqmgAc. The above com- mand will not show any deleted files, however; to see them, use the d modifier, making the command lfqmgAcd (or double it as in lfqmgAcdd if only the deleted files are to be listed). And if the user also wishes to see the CRC value for each file being listed, the modifier C will do this, as in the command lfqmgAcdC, which gives a fast columnized listing of all files, including deleted files, showing any Printed 2/4/88 Feb 3, 1988 15 ZOO(1) UNIX Programmer's Manual ZOO(1) archive comment and file comments, and file protection codes and generation information, as well as the CRC value of each file. Note that the above command lfqmgAcdC could also be abbrevi- ated to VfqmgdC because the command V is shorthand for lcA (archive listing with all comments shown). Similarly the command v is shorthand for lA (archive listing with archive comment shown). Both V and v can be used as modifiers to any of the other archive listing commands. Generations By default, zoo assumes that only the latest generation of a specified file is needed. If generations other than the latest one need to be selected, this may be done by specify- ing them in the filename. For example, the name stdio.h would normally refer to the latest generation of the file stdio.h stored in a zoo archive. To get an archive listing showing all generations of stdio.h in the archive, the specification stdio.h:* could be used (enclosed in single quotes if necessary to protect the wildcard character * from the shell). Also, stdio.h:0 selects only the latest genera- tion of stdio.h, while stdio.h:^0 selects all generations except the latest one. The : character here separates the filename from the generation number, and the character * is a wildcard that matches all possible generations. For con- venience, the generation itself may be left out, so that the name stdio.h: (with the : but without a generation number or a wildcard) matches all generations exactly as stdio.h:* does. If a generation is specified but no filename is present, as in :5, :*, or just :, all filenames of the specified genera- tion will be selected. Thus :5 selects generation 5 of each file, and :* and : select all generations of all files. It is important to note that zoo's idea of the latest gen- eration of a file is not based upon searching the entire archive. Instead, whenever zoo adds a file to an archive, it is marked as being the latest generation. Thus, if the latest generation of a file is deleted, then no generation of that file is considered the latest any more. This can be surprising to the user. For example, if an archive already contains the file stdio.h:5 and a new copy is added, appear- ing in the archive listing as stdio.h:6, and then stdio.h:6 is deleted, the remaining copy stdio.h:5 will no longer be considered to be the latest generation, and the file stdio.h:5, even if undeleted, will no longer appear in an archive listing unless generation 5 (or every generation) is specifically requested. This behavior will likely be improved in future releases of zoo. Printed 2/4/88 Feb 3, 1988 16 ZOO(1) UNIX Programmer's Manual ZOO(1) FILES xXXXXXX - temporary file used during packing archive_name.bak - backup of archive SEE ALSO compress(1), fiz(1) BUGS Files with generation counts that wrap around from 65535 to 1 are not currently handled correctly. If a file's genera- tion count reaches a value close to 65535, it should be manually set back down to a low number. This may be easily done with a command such as gc-65000, which subtracts 65000 from the generation count of each specified file. This problem will be fixed in a future release. Although zoo on **IX systems preserves the lowest nine mode bits of regular files, it does not currently do the same for directories. Currently zoo's handling of the characters : and ; in filenames is not robust, because it interprets these to separate a filename from a generation number. A quoting mechanism will eventually be implemented. Standard input cannot be archived nor can a created archive be sent to standard output. Spurious error messages may appear if the filename of an archive is too long. Since zoo never archives any file with the same name as the archive or its backup (regardless of any path prefixes), care should be taken to make sure that a file to be archived does not coincidentally have the same name as the archive it is being added to. It usually suffices to make sure that no file being archived is itself a zoo archive. (Previous ver- sions of zoo sometimes tried to add an archive to itself. This bug now seems to be fixed.) Only regular files are archived; directories and devices are not. Early versions of MS-DOS have a bug that prevents "." from referring to the root directory; this leads to anomalous results if the extraction of paths beginning with a dot is attempted. VAX/VMS destroys case information unless arguments are enclosed in double quotes. For this reason if a command given to zoo on a VAX/VMS system includes any uppercase characters, it must be enclosed in double quotes. Under VAX/VMS, zoo does not currently restore file timestamps; this will be fixed as soon as I figure out RMS extended Printed 2/4/88 Feb 3, 1988 17 ZOO(1) UNIX Programmer's Manual ZOO(1) attribute blocks, or DEC supplies a utime() function, which- ever occurs first. Other VMS bugs, related to file struc- tures, can often be overcome by using the program bilf.c that is supplied with zoo. It is not currently possible to create a zoo archive con- taining all zoo archives that do not contain themselves. DIAGNOSTICS Error messages are intended to be self-explanatory and are divided into three categories. WARNINGS are intended to inform the user of an unusual situation, such as a CRC error during extraction, or -freshening of an archive containing a file newer than one specified on the command line. ERRORS are fatal to one file, but execution continues with the next file if any. FATAL errors cause execution to be aborted. The occurrence of any of these causes an exit status of 1. Normal termination without any errors gives an exit status of 0. (Under VAX/VMS, however, to avoid an annoying mes- sage, zoo always exits with an error code of 1.) COMPATIBILITY All versions of zoo on all systems are required to create archives that can be extracted and listed with all versions of zoo on all systems, regardless of filename and directory syntax or archive structure; furthermore, any version of zoo must be able to fully manipulate all archives created by all lower-numbered versions of zoo on all systems. So far as I can tell, this upward compatiblity (all manipulations) and downward compatiblity (ability to extract and list) is maintained by zoo version 2.0. You are forbidden, with the force of copyright law, to create from the zoo source code any derivative work that violates this compatibility goal, whether knowingly or through negligence. If any violation of this compatibility goal is observed-i.e., if you are able to use an implementation of zoo to create an archive that some implementation of zoo on any system cannot extract-this should be considered a serious problem and reported to me. CHANGES Zoo version 1.5 was posted to Usenet in mid-1987. Later, I distributed version 1.71 via anonymous UUCP and disks, but I did not widely distribute it by other means such as online information services or bulletin boards, because changes from 1.5 to 1.71 were minor. Although 1.5 was distributed for MSDOS in binary form, 1.71 was not. The Amiga version of 1.71 has just been released as this documentation is written. The current version 2.0 is a significant enhancement from 1.5, with many new features and improvements. Here is a list. In parentheses is given the version in which each Printed 2/4/88 Feb 3, 1988 18 ZOO(1) UNIX Programmer's Manual ZOO(1) feature was introduced. - (1.71) New modifiers to the list commands permit optional suppression of header and trailer information, inclusion of directory names in columnized listings, and fast one-column listings. - (1.71) Timezones are handled. - (1.71) A bug was fixed that had made it impossible to individually update comments for a file whose name did not correspond to MS-DOS format. - (1.71) A change was made that now permits use of the shared library on the **IX PC. - (1.71) VAX/VMS is now supported reasonably well. - (2.0) A comment may now be attached to the archive itself. - (2.0) The OO option allows forced overwriting of read- only files. - (2.0) Zoo will no longer extract a file if a newer copy already exists on disk; the S option will override this. - (2.0) File attributes are preserved for **IX systems. - (2.0) Multiple generations of the same file are sup- ported. - (2.0) Zoo will now act as a compression or decompres- sion filter on a stream of data and will use a CRC value to check the integrity of a data stream that is uncompressed. - (2.0) A bug was fixed that caused removal of a direc- tory link if files were moved to an archive by the superuser on a **IX system. - (2.0) The data recovery modifier @ was greatly enhanced. Self-extracting archives created for MS-DOS systems can now be extracted by zoo on any system with help from fiz(1). FUTURE DIRECTIONS A revised version of zoo is in the works that will be able to write newly-created archives to standard output, and will also automatically perform end-of-line conversion for text files moved between dissimilar systems. It will be upward Printed 2/4/88 Feb 3, 1988 19 ZOO(1) UNIX Programmer's Manual ZOO(1) and downward compatible with existing versions of zoo. ACKNOWLEDGEMENTS The zoo archiver was initially developed using Microsoft C 3.0 on a PC clone manufactured by Toshiba of Japan and almost sold by Xerox. Availability of the following systems was helpful in achieving portability: Paul Homchick's Compaq running Microport System V/AT; The Eskimo BBS somewhere in Oregon running Xenix/68000; Greg Laskin's system 'gryphon' which is an Intel 310 running Xenix/286; Ball State University's AT&T 3B2/300, UNIX PC, and VAX-11/785 (4.3BSD) systems. In addition J. Brian Waters provided feedback to help me make the code compilable on his Amiga using Manx/Aztec C. More recently, actual development, as opposed to portability testing, has been done exclusively on my own AT from PC's Limited running Microport System V/AT. The executable version 2.0 for MS-DOS is currently compiled with Borland's Turbo C 1.0. Special thanks are due to: J. Brian Waters , who has worked diligently to port zoo to AmigaDOS, created Amiga-specific code, and continues keeping it updated. Paul Homchick , who provided numerous detailed reports about some nasty bugs. Bill Davidsen , who fixed zoo's handling of daylight savings time, provided changes to make this manual format correctly with troff, and provided many useful bug reports and suggestions. Mark Alexander , who provided me with some bug fixes, and also some portability modifications and speed optimizations that are due to be incorporated into the next release. AUTHOR Rahul Dhesi Printed 2/4/88 Feb 3, 1988 20