ZOO(1) UNIX Programmer's Manual ZOO(1) NAME zoo - manipulate archives of files in compressed form SYNOPSIS zoo {acDehlLPTuUvx}[cdEfInMNoOpPquv1:./@] archive [file] ... zoo -command archive [file] ... zoo h DESCRIPTION ^[[4mZoo^[[m is used to create and maintain collections of files in compressed form. It uses a Lempel-Ziv compression algorithm that gives space savings in the range of 20% to 80% depend- ing on the type of file data. The command ^[[4mzoo^[[m h gives summary of commands. ^[[4mZoo^[[m will not add an archive to itself, nor add the archive's backup (with .bak extension to the filename) to the archive. ^[[4mZoo^[[m has two types of commands: Expert commands, which con- sist of one command letter followed by zero or more modifier characters, and Novice commands, which consist of a hyphen (`-') followed by a command word that may be abbreviated. Expert commands are case-sensitive but Novice commands are not. When ^[[4mzoo^[[m adds a file to an existing archive, it marks as deleted any already-archived file with the same name. (Directory prefixes are significant in this comparison if and only if directory names are being stored.) Deleted files may be later undeleted. Archives may be packed to recover space occupied by deleted files. All commands assume that the archive name ends with the characters .zoo unless a different extension is supplied. Novice commands Novice commands may be abbreviated to a hyphen followed by at least one command character. Each Novice command works in two stages. First, the command does its intended work. Then, if the result was that one or more files were deleted in the specified archive, the archive is packed. If packing occurs, the original unpacked archive is always left behind with an extension of .bak. No Novice command ever stores the directory prefix of a file. When a Novice command is used to add a file to an archive, any already-archived file with the same name, regardless of the directory prefix, is marked deleted. Printed 9/14/87 Aug 28, 1987 1 ZOO(1) UNIX Programmer's Manual ZOO(1) The Novice commands are as follows. -add Adds the specified files to the archive. -freshen Adds a specified file to the archive if and only if an older file by the same name already exists in the archive. -delete Deletes the specified files from the archive. -update Adds a specified file to the archive either: if an older file by the same name already exists in the archive or: if a file by the same name does not already exist in the archive. -extract Extracts the specified files from the archive. If no file is specified all files are extracted. -move Equivalent to -add except that source files are deleted after addition. -print Equivalent to -extract except that extracted data are sent to standard output. -list Gives information about the specified archived files including any attached comments. If no files are specified all files are listed. Deleted files are not listed. -test Equivalent to -extract except that the extracted data are not saved but any errors encountered are reported. -comment Allows the user to add or update comments attached to archived files. When prompted, the user may: type a carriage return to skip the file, leaving any current comment unchanged; or type a (possibly null) comment of up to 65,535 characters terminated by /end (case- insensitive) on a separate line; or type the end-of- file character (normally control D) to skip all remain- ing files. -delete Deletes the specified files. Printed 9/14/87 Aug 28, 1987 2 ZOO(1) UNIX Programmer's Manual ZOO(1) The correspondence between Novice and Expert commands is as follows. Novice Equivalent Command Description Expert Command _______________________________________________________________________ -add add files to archive aP: -extract extract files from archive x -move move files to archive aMP: -test test archive integrity xNd -print extract files and send to standard output xp -delete delete files from archive DP -list list information about archived files v -update update archive by adding new or newer files aunP: -freshen freshen archive by adding newer files auP: -comment allows user to attach comments to files c Expert commands The general format of expert commands is: ^[[4mzoo^[[m {acDehlPTuUvx}[cdEfInMNoOpPquv1:./@] archive [file] ... The characters enclosed within {} are commands. Choose any one of these. The characters enclosed within [] just to the right of the {} are modifiers and zero or more of these may immediately follow the command character. All combinations of command and modifier characters may not be valid. Files are added to an archive with the command: ^[[4mzoo^[[m {au}[cfIMnPqu:] archive [file] ... Command characters are: a Add each specified file to archive. Any already- archived file with the same name is marked as deleted. u Do an update of the archive. A specified file is added to the archive only if a copy of it is already in the archive and the copy being added is newer than the copy already in the archive. The following modifiers are specific to these commands. M Move files to archive. This makes ^[[4mzoo^[[m delete (unlink) the original files after they have been added to the archive. Files are deleted after addition of all files to the archive is complete and after any requested packing of the archive has been done, and only if ^[[4mzoo^[[m detected no errors. Printed 9/14/87 Aug 28, 1987 3 ZOO(1) UNIX Programmer's Manual ZOO(1) n Add new files only. A specified file is added only if it isn't already in the archive. P Pack archive after files have been added. u Applied to the a command, this modifier makes it behave identically to the u command. The combination of the n modifier with the u modifier or u command causes addition of a file to the archive either if the file is not already in the archive, ^[[4mor^[[m if the file is already in the archive but the archived copy is older than the copy being added. : Do not store directory names. In the absence of this modifier ^[[4mzoo^[[m stores the full pathname of each archived file. I Read filenames to be archived from standard input. ^[[4mZoo^[[m will read its standard input and assume that each line of text contains a filename. Under AmigaDOS and the **IX family, the entire line is used. Under MS-DOS and VAX/VMS, ^[[4mzoo^[[m assumes that the filename is terminated by a blank, tab, or newline; thus it is permissible for the line of text to contain more than one field separated by white space, and only the first field will be used. Under the **IX family of operating systems, ^[[4mzoo^[[m can be used as follows in a pipeline: find . -print | zoo aI sources If the I modifier is specified, no filenames may be supplied on the command line itself. Files are extracted from an archive with the command: ^[[4mzoo^[[m {ex}[dNoOpq./@] archive [file] ... The e and x commands are synonymous. If no file was speci- fied, all files are extracted from the archive. The following modifiers are specific to the e and x com- mands: N Do not save extracted data but report any errors encountered. Printed 9/14/87 Aug 28, 1987 4 ZOO(1) UNIX Programmer's Manual ZOO(1) O Overwrite files. Normally, if a file being extracted would overwrite an already-existing file of the same name, ^[[4mzoo^[[m asks you if you really want to overwrite it. You may answer the question with `y', which means yes, overwrite; or `n', which means no, don't overwrite; or `a', which means assume the answer is `y' for this and all subsequent files. The O modifier makes ^[[4mzoo^[[m assume that files may always be overwritten. The O, N, and p modifiers are mutually exclusive. o This is equivalent to the O modifier if and only if it is given at least twice. It is otherwise ignored. p Pipe extracted data to standard output. Error messages are piped to standard output as well. However, if a bad CRC is detected, an error message is sent both to standard error and to standard output. / Extract to original pathname. Any needed directories must already exist. In the absence of this modifier all files are extracted into the current directory. If this modifier is doubled as //, needed directories need not exist and are created if necessary. Archived files are listed with the command: ^[[4mzoo^[[m {lLv}[adfqv@/1] archive[.zoo] [file] ... l Information presented includes the date and time of each file, its original and current (compressed) sizes, and the percentage size decrease due to compression (labelled CF or compression factor). If a file was added to the archive in a different timezone, the difference between timezones is shown in hours as a signed number. As an example, if the difference is listed as +3, this means that the file was added to the archive in a timezone that is 3 hours west of the current timezone. The file time listed is, however, always the original timestamp of the archived file, as observed by the user who archived the file, expressed as that user's local time. If no filename is supplied all files are listed except deleted files. L This is identical to the l command except that all sup- plied arguments must be archives and the contents of each are listed. v This causes a verbose listing, which additionally shows any comment attached to each file. Using the v Printed 9/14/87 Aug 28, 1987 5 ZOO(1) UNIX Programmer's Manual ZOO(1) modifier with the l command has the same effect. In addition to the general modifiers described later, the following modifiers can be applied to the archive list com- mands. a This gives a single-line format containing both each filename and the name of the archive, sorted by archive name. It is especially useful with the L command, since the result can be further sorted on any field to give a master listing of the entire contents of a set of archives. 1 This forces one filename to be listed per line. It is most useful in combination with the f modifier. / This forces any directory name to be always listed, even in fast columnized listings that do not normally include any directory names. Files may be deleted and undeleted from an archive with the following commands: ^[[4mzoo^[[m {DU}[Pq1] archive file ... The D command deletes the specified files and the U command undeletes the specified files. The 1 modifier (the digit one, not the letter ell) forces deletion or undeletion of at most one file. If multiple instances of the same file exist in an archive, use of the 1 modifier may allow selective extraction of one of these. Comments may be added to an archive with the command: ^[[4mzoo^[[m c archive This behaves identically to the -comment command. The timestamp of an archive may be adjusted with the com- mand: ^[[4mzoo^[[m T[q] archive ^[[4mZoo^[[m normally attempts to maintain the timestamp of an archive to reflect the age of the newest file stored in it. Should the timestamp ever be incorrect it can be fixed with the T command. An archive may be packed with the command: ^[[4mzoo^[[m P[EPq] archive Printed 9/14/87 Aug 28, 1987 6 ZOO(1) UNIX Programmer's Manual ZOO(1) If the backup copy of the archive already exists, ^[[4mzoo^[[m will refuse to pack the archive unless the P modifier is also given. The E modifier causes ^[[4mzoo^[[m not to save a backup copy of the original archive after packing. A unique temporary file in the current directory is used to initially hold the packed archive. This file will be left behind if packing is interrupted or if for some reason this file cannot be renamed to the name of the original archive when packing is complete. Packing removes any garbage data appended to an archive because of Xmodem file transfer and also recovers space used by comments that were replaced. 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 a file already in the archive, any comment attached to the replaced 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 -com- ment command. Applied to the archive list command l, the c modifier causes the listing 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 ^[[4mzoo^[[m lists the name of each file and what action it is performing. The q modifier Printed 9/14/87 Aug 28, 1987 7 ZOO(1) UNIX Programmer's Manual ZOO(1) 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. Error messages are never suppressed. @ Extract or list beginning at position n, where n is a decimal number following the @ sign without any inter- vening spaces. This may be used to recover data from a damaged archive by skipping the damaged part. The number specified must be the position within the archive of an undamaged directory entry. This position is usually obtained from ^[[4mfiz^[[m(^[[4m1^[[m). 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 ^[[4mzoo^[[m as described below. Under MS-DOS and AmigaDOS, quoting of wildcards is not needed. All wildcard expansion of filenames is done by ^[[4mzoo^[[m, and wildcards inside directory names are expanded only when listing or extracting files but not when adding them. The wildcard syntax interpreted by ^[[4mzoo^[[m 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 Printed 9/14/87 Aug 28, 1987 8 ZOO(1) UNIX Programmer's Manual ZOO(1) only by itself or preceded by a directory name. It is not specially interpreted if it is part of a filename. MS-DOS users should note that ^[[4mzoo^[[m 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. FILES xXXXXXX - temporary file used during packing archive_name.bak - backup of archive SEE ALSO compress(1), fiz(1) BUGS 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 ^[[4mzoo^[[m 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 ^[[4mzoo^[[m 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 ^[[4mzoo^[[m on a VAX/VMS system includes any uppercase characters, it must be enclosed in double quotes. Under VAX/VMS, ^[[4mzoo^[[m does not currently restore file timestamps; this will be fixed as soon as I figure out RMS extended 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 ^[[4mbilf^[[m.^[[4mc^[[m that is supplied with ^[[4mzoo^[[m. It is not currently possible to create a ^[[4mzoo^[[m archive con- taining all ^[[4mzoo^[[m archives that do not contain themselves. Printed 9/14/87 Aug 28, 1987 9 ZOO(1) UNIX Programmer's Manual ZOO(1) 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. FUTURE DIRECTIONS A revised version of ^[[4mzoo^[[m is in the works which will allow numbering of multiple versions of a file and automatically perform end-of-line conversion for text files moved between dissimilar systems. It will be upward and downward compati- ble with existing versions of ^[[4mzoo^[[m. THANKS Thanks are due to: Paul Homchick, who provided numerous detailed reports about some nasty bugs. Bill Davidsen, who fixed ^[[4mzoo^[[m'^[[4ms^[[m handling of daylight savings time and also provided changes to make this manual format correctly with ^[[4mtroff^[[m. AUTHOR Rahul Dhesi Printed 9/14/87 Aug 28, 1987 10 echo shar: "92 control characters may be missing from 'zoo.man'"