Browse files

2.5

  • Loading branch information...
1 parent 9793184 commit 5379044bb138abbe867efe3e4730e366f1bf5642 @kholtman committed Feb 5, 2012
View
58 ANNOUNCE-2.5
@@ -0,0 +1,58 @@
+Subject: Afio archiver version 2.5
+Keywords: backup archiver compressed fault tolerant afio cpio
+
+After being more than 1 year in beta, this new afio version includes
+support for >2GB files.
+
+* WHAT IS AFIO?
+
+Afio is an archiver/backup program that produces cpio-format archives.
+
+Like tar, afio can make compressed archives. However, the compressed
+archives produced by afio are much safer than tar -z archives. If a
+tar -z archive has a read error, tar is unable to extract the files
+beyond this error. The compressed archive format used by afio allows
+it to recover from read errors and go on unpacking the next file.
+
+* WHAT IS NEW IN VERSION 2.5?
+
+- Added support for archiving files larger than 2 GB.
+ The resulting archives are not fully compatible with cpio, but
+ preserve cpio compatibility as much as possible.
+
+- Various small bug fixes.
+
+- Added support for creating archives larger than 2GB on a filesystem.
+
+- New -6 option to suppress the compression of files based on shell
+ pattern matching.
+
+- New -vv option for ls -l style file list output when creating an
+ archive.
+
+- Restores modification time of directories correctly.
+
+- Improved/debugged support for handling many hard linked files.
+
+- Support for UID/GID values larger than 64K.
+
+- Some additional small new features.
+
+- Improved documentation.
+
+- Added automatic regression that can be used to test the binary after
+ compilation.
+
+
+* WHERE DO I GET IT?
+
+Version 2.5 is at:
+
+ http://members.brabant.chello.nl/~k.holtman/afio-2.5.tgz
+
+And soon at
+
+ ibiblio.org : /pub/Linux/system/backup/afio-2.5.tgz
+
+ http://freshmeat.net/projects/afio/
+
View
822 HISTORY
@@ -0,0 +1,822 @@
+
+This file contains some historical information on afio. It also
+contains notes about changes in new versions.
+
+============Very old README file contents==============================
+
+Afio is a better way of dealing with cpio-format archives. It is
+generally faster than cpio, provides more diverse magnetic tape
+options and deals somewhat gracefully with input data corruption.
+
+Afio is quite portable. It is now running under 4.2BSD, System V
+and even one or two UNIX-like operating systems. Please see the
+beginning of afio.c for a brief description of the compile-time
+configuration options.
+
+[...]
+
+ Mark Brukhartz
+ Lachman Associates, Inc.
+ ..!{ihnp4, sun}!laidbak!mdb
+
+[...]
+
+=================Notes on changes in new versions==================
+
+
+Dave Gymer (dpg@cs.nott.ac.uk) (up to version 2.3-dpg-3):
+
+This is my port to Linux of afio. See afio.1 and README for a
+description of what this does. It's based on work I did to port this
+to MiNT by Eric Smith on the Atari ST, and consists mainly of bugfixes
+and one important new feature; the use of st_rdev to indicate whether
+a regular file was compressed by afio or not if it's name in the
+archive ends in .z. I did this because I didn't want backups of files
+which were already compressed (like .tar.Z archives and some of the
+stuff in the Xfree386-1.1 distribution) to be uncompressed if I
+restored my filesystem.
+
+This also means that the -Z option is meaningful when listing the
+contents of an archive; if given, any .z files are listed without the
+.z if afio compressed them, or with the .z if they were like that when
+afio found them.
+
+I also ran the code through GNU Indent 1.4.
+
+This is the third release of my version; this one knows about gzipped
+files (.z), uses gzip instead of compress, and handles other files
+which rarely compress well, like JPEGs.
+
+You may want to undefine LONGZFILE if you still use the Minix fs; I
+use xiafs so it doesn't matter. Even if you do use the Minix fs,
+you'll only get bitten if you try to restore a compressed archive
+without uncompressing files.
+
+Andrew Stevens (as@prg.oxford.ac.uk) (version 2.3-dpg-4 onwards)
+
+I've tidied the code a little to make the double-buffering work (and
+prompt sensibly) and avoid leakage of file-handles in the compression
+code.
+
+This code really really needs splitting up into multiple source files!
+
+I have tested backing up and restoring off floppies fairly thoroughly
+(various options), but I have no the faintest idea how reliable any of
+the other stuff is.
+
+I have included my favourite backup script as an example of the usage
+of afio. [This script is in the script1 subdirectory.]
+This uses the directory /usr/adm/dump to record dumping
+dates and a file /usr/adm/dump/DONTDUMP (example included) to
+filter out non-dumpable areas.
+
+The afio source as given will not attempt to compress files ending in
+ .Z .z .gz
+ .arc .gif .zip .zoo .lha .jpeg .jpg
+ .tpz .taz .tgz .tzg
+See also the -E option in the manual page.
+
+
+Koen Holtman (koen@hep.caltech.edu) (version 2.3.5 (for Linux) onwards)
+
+Introduced new options -E, -G, -M, -w and -W.
+
+On compressing files, afio now temporarily stores the result in memory
+in stead of creating (potentially huge) /tmp files. This way, there
+is no danger of the /tmp filesystem getting full during a backup, so
+that a backup script calling afio can safely use /tmp. Afio won't use
+more than 2 meg memory for temporary storage (also see the -M option).
+If it runs out of memory, it calls gzip twice, the first time to
+determine the length of the result, the second time to get the data
+itself.
+
+The -y and -Y options now are able to handle real shell patterns, and
+generally work more sensible.
+Verifying floppy disks now works on Linux.
+
+
+Version 2.3.6 (for Linux):
+
+Added -T option. The options -G and -T can be used to optimize the
+backup speed/compression ratio if you have a slow machine or a fast
+backup medium. Added -S option. Fixed some bugs in 2.3.5.
+
+
+Version 2.3.6-dpg-1 (for Linux):
+
+Bug fix in -F option by Dave Gymer (dpg@Cs.Nott.AC.UK).
+
+
+Version 2.3.7:
+
+Deleted shared memory code to reduce code clutter.
+
+Removed `buggy gzip workaround' in compfile.c, this caused afio to
+hang occasionally if the -f option was used. This means that afio will
+only run with newer gzip versions. (I don't know exactly which version
+is new enough, though gzip 1.2.3 and above certainly are. Just try
+it.)
+
+Edited -F code to fix `double prompting' bug.
+
+Added more warnings to the manual.
+
+Added some ifdefs and a few notes to make porting to other unix
+versions easier.
+
+
+Version 2.4:
+
+Added -r option and small bugfix in tty handling, both by Anders
+Baekgaard (ab@osiris.cpk.auc.dk).
+
+Added -B option that prints the byte position of each file in the
+archive in the -v output.
+
+Made -F option do writing in O_SYNC mode under Linux. Thus afio will
+notice some floppy disk write errors using Linux kernel 1.1.54 or
+higher.
+
+Updated manual page. Updated usage message.
+
+Made version number shorter, though number of changes does not warrant
+a new major version.
+
+
+Version 2.4.1:
+
+Fixed bug that sometimes caused unzipping to fail due to a seek on a
+pipe (bug found and fixed by Keith Owens).
+
+Deleted malloc() result check in meminit() to help porting, malloc(0)
+returns NULL on some machines.
+
+Fixed bug caused by incorrect assumptions about write(), triggered
+under Linux if afio -iZ ... is stopped and restarted.
+
+Now exits if a broken pipe occurs on the stderr of afio -i or the
+stdout of afio -t and afio -rv. Thus afio -t can be used with head to
+get a table of contents of the beginning of an archive.
+
+Fixed bug in setting suid/sgid bits when restoring a file that does
+not have user=root, group=root. Afio did not take into account that
+the Linux chown() clears these bits in some cases.
+
+Expanded semantics of -s, changed the behavior when afio gets an input
+eof without there being an -s option given; the old behavior can be
+gotten back by using -s 0. This change prevents bogus insert next
+disk messages when the archive ends prematurely.
+
+Made control file feature (added -D option).
+
+Fixed bug in afio 2.4 that caused symbolic link info to be omitted
+when creating an archive.
+
+Fixed bugs in -r option.
+
+Removed empty lines from logfile created with -L option, also fixed
+bug in logfile creation.
+
+Reorganized documentation files, updated manual page.
+
+
+Version 2.4.2:
+
+Added code to let subprocesses close archive file descriptor, needed
+for some tape drivers when changing tapes.
+
+Fixed bug in multivolume tape read code.
+
+Added some portabilty stuff:
+- Rewrote archive header scanf to be more portable.
+- Changed CPPFLAGS into CFLAGS in Makefile.
+- Changed ssize_t and size_t in writeall() to int.
+- Added code to clear asb.sb_rdev in the file stat block if not a
+ device: some OSes put (garbage?) info in this field in stead of
+ clearing it and afio wants it cleared.
+
+Added -a option to preserve atime on files read when doing -o or -r.
+Using it will set the ctime for these files to the current time, so
+this option _cannot_ be used together with most incremental backup
+schemes, which rely on the ctime being preserved.
+
+Fixed bug in -f option when used with -s.
+
+Updated manual, added new warning to BUGS section.
+
+Fixed tocentry() to print -B byte offset to stdout instead of stderr.
+
+Added support for creation of UNIX sockets in restore.
+
+Added single qoutes around rsh switches.
+
+Added `-s 0' functionality to the -I command.
+
+Added -z calculation to -I and -O commands.
+
+Changed restore not to do utime() to restore time on symlinks: the
+timestamp change gets done on the file linked to and that is not very
+productive.
+
+Took -N flag out of LDOPTS in Makefile. No idea what it should have
+done.
+
+Added `f to format' option in floppy handling code (patch by Ulrich
+Lauther). Note that afio still does not have adequate multivolume
+floppy support: use the tbackup program as a wrapper around afio for
+that.
+
+Changed default format command in Makefile from /bin/fdformat to
+fdformat.
+
+Changed nice(-40) to nice(-10) for subprocess in -f option.
+
+Added options -U, -P, -Q to force compression, specify compression
+program and pass options to the compression program, based on patch
+file by karsten.ballueder@stud.uni-karlsruhe.de. Added script3/
+directory to distribution.
+
+Version 2.4.3:
+
+Fixed bug in restore code which sometimes prevents an old file from
+being overwritten with a hard link. Based on report by Nokubi
+Takatsugu.
+
+Version 2.4.4:
+
+Fixeded more bugs in hard link handling, based on same report by
+Nokubi Takatsugu. The inode field in the archive header only stores
+the meast significant 16 bits, which is too little for todays
+filesystems, yet the unpacking code assumes that these 16 bit fields
+have unique values for each filesystem entry when handling hard links.
+This can cause problems when unpacking files with hardlinks. Added
+code to 1) make unpacking od old archives safer by adding more sanitiy
+checks and 2) ensure that hardlink processing related inode fields in
+newly produced archives are unique by inventing unique inode numbers
+if necessary. Added -4 flag to write `extended ascii' format archives
+with 4-byte inode fields, based on code by Nokubi Takatsugu. See
+manpage for caveats about -4.
+
+Incorporated some patches by Rob W. W. Hooft to speed up buffer memory
+allocation for -Z option. Rob reported impressive speedup (due to
+less mallocs all the time) for large files in some cases but I have
+been unable to duplicate any dramatic speedup myself.
+
+Fixed bug reported by Sebastian Wilhelmi: afio -o now correctly exits
+with a fatal error and 1 exit status if there is a write error to the
+backup medium. Added -J flag to revert to something like old
+behavior: with -J, media write errors give a warning and writing goes
+on, and afio finally exits with status 1. (Actual old behavior was
+printing warning going on and exiting with status 0. Bad.)
+
+Improved -Z reporting using patch by Ed Casas. Made some additional
+improvements too.
+
+Afio will now exit with status 1 if there any warnings were printed
+during the operation (but some may be missed if -f is used).
+
+Added a sleep(2) to lower chance of race condition in rsh processing
+when reading remote archives with afio ... host:/file. Problems
+reported/investigated by Rob Browning and Dirk Eddelbuettel. [Note
+that, in spite of me correcting problems in it, remote file handling
+is still not officially supported by this maintainer -- KH]
+
+Incorporated some patches by Juergen Lock to make porting to (Free)BSD
+systems easier. This should also solve an IRIX porting problem
+reported by Mike McDonnell.
+
+Incorporated patch by Timo Korvola to allow specification of an
+alternative remote shell program (like ssh) for remote archives.
+
+Added patch by Werner Koch to speficy user for remote file processing.
+Full syntax now is `filename_without_:' for local files or
+[user@]host[%rsh][=afio]:file for remote files. (A patch for the same
+feature was sent by David Atkinson too.)
+
+Added some DEC Alpha porting patches by George Brizicky. Incorporated
+a Solaris porting patch by Erich Focht.
+
+Added -H (promptscript) option using patch by Alexander Zangerl.
+
+Fixed buggy handling of 0-length files which already have a .z
+extension. Bug reported by Bob Mitchell.
+
+Incorporated patch by Dave Gymer which adds -0 option like GNU cpio,
+to allow input filenames to be terminated with a '\0' instead of a
+'\n'. When used with find ... -print0, can be used to ensure that any
+filename can be handled, even if it contains a newline. (A patch for
+the same feature was sent by Rob Browning too.)
+
+Lots of manpage updates, also updated BUGS section of manpage.
+
+
+Version 2.4.5:
+
+Fixed progress reporting and media change code to handle archives and
+archive volumes above 2GB and 4GB correctly, based on patch by Mike
+Black. Problems also reported by Maik Musall.
+
+Added 'g' (gigabytes) as a possible size denotation in options taking
+numbers, using patch by Mike Black.
+
+Added @ option based on patch by Mike Black.
+
+Removed bug in 2.4.4 which would report media change messages as
+warnings about errors in the final -z count.
+
+Added three extensions (.deb, .rpm, .bz2) to the list of those to be
+excluded from compression by default. Patch by Dirk Eddelbuettel.
+
+Fixed bug in code for restoring archived made with -4 option (oops!).
+Bug found by Chris Thompson.
+
+Incorporated patch by Bryan Henderson which fixes bug in floppy
+prompting if -f option used (every prompt was issued twice).
+
+Improved -H (promptscript) option using patch by Raphael Manfredi.
+Promptscript now has tty on its stdin, and gets one more argument.
+Included sample promptscript by Raphael Manfredi.
+
+When writing archive without specifying -s or -s 0, added code to
+switch to next volume if current one is full (if write() returns 0
+bytes witten or ENOSPC error). Part of code based on patch by Raphael
+Manfredi.
+
+Some updates to documentation.
+
+
+Version 2.4.6:
+
+Fixed file closing bug in -r option which prevented tape switches when
+verifying with some tapes. Bug reported by Tetsuya Makimura and also
+by Alan J. Wylie.
+
+Switched to -Wall in Makefile, modified code to suppress -Wall
+warnings (at least with my gcc), based on patch by Holger Schurig.
+
+Added some extensions to the list of those to be excluded from
+compression by default. From patch by Holger Schurig.
+
+In tests and source code checks, no year 2000 (Y2K) problems have been
+found with afio. All afio versions back to at least 2.3.6 should have
+no year 2000 problems, nor should existing archives produced with such
+versions have year 2000 problems within. Current afio versions do
+have the usual unix second counter underflow problem, which will
+manifest itself in 2038. The date-printing afio options (-tv and -L)
+print 4 digit years. The archive formats output by afio (both ASCII
+and extended ASCII) use the usual unix seconds-since-1970 counts to
+represent dates, these counts are encoded as octal numbers in a
+wide-enough field.
+
+Some non-Linux platforms, Sun in particular have a dev_t larger than
+16 bits. This caused problems archiving devices on these platforms.
+We now take this into account: if it is larger than a 16 bit number,
+the dev_t value is re-encoded in the dev and ino parts of the header.
+The makedev include is also updated to special-case for Sun. Based on
+a bug report by by Guenter Steger.
+
+Fixed bug in interference between -Z and -l options on writing an
+archive. Fixed bug in -U, which would not force compression of hard
+linked files. Documented internal afio limitations connected to -Z on
+hard links and -U and hard links.
+
+Added -1 option and revised its default for better backwards
+compatibilty with existing backup scripts. Compatibility problem (tob
+never going on to verify phase if afio exited 1) reported by Denis
+Sbragion. (I recall that the problem was also reported by someone
+else but can't find the report anymore.) Same problem, or maybe not,
+also reported by Florin B Manolache.
+
+Added -3 option for better compatibility with pgp. Based on bug
+reports by Jens Getreu. And many thanks to Jens Getreu for testing
+the -3 option! This fixes a security hole:
+
+ --snip--
+ [SECURITY] afio: security hole in 'afio -P pgp' encrypted archives
+
+ I. Description
+
+ Since version 2.4.2, the afio archiver has had an interface, the '-P
+ pgp' command line option, which can be used to pgp-encrypt the file
+ data witten to an afio archive. Following up on some bug reports, I
+ have recently discovered a security problem with this afio-pgp
+ interface: pgp encryption is not always applied in the right way.
+ This makes it possible to crack the encyption on the file data in an
+ 'encrypted' archive produced using afio with the '-P pgp' option.
+
+ The security of files which were already encrypted _before_ being
+ written to the archive is not affected.
+
+ II. Impact
+
+ It is possible to cheaply crack the encryption of at least some of
+ the file data in the 'encrypted' archives produced using 'afio -P
+ pgp'. This includes archives produced using the pgp_write example
+ script included in the [pre-2.4.6] afio distribution.
+
+ III. Solution
+
+ _Existing archives_ [made with pre-2.4.6 afio versions] produced
+ with 'afio -P pgp' should really be treated with the same care
+ (against theft etc.) as unencrypted archives. If such existing
+ archives cannot be deleted or safely locked away, then encrypting
+ the _entire_ existing archive file with pgp will protect it.
+
+ --snip--
+
+Updated scripts in script3/ to use new -3 option.
+
+Updated manpage, added some afio command line examples. cdrecord
+example contributed by Joachim Bergmeyer.
+
+Added code to make -y -Y -w -W also work when creating archives.
+Based on patch by Brian Powell.
+
+Fixed bug in -a option, which would not restore the access time on
+files stored with compression when creating an archive. Based on
+patch by David Rourke.
+
+Made some changes to ease portability to the IRIX native C compiler.
+See also the PORTING file. Based on patch file by Brian Gunney.
+
+Afio currently invokes gzip for compression in the -Z option.
+Performance experiments by Ted Phelps showed that linking the zlib
+compression library and invoking it internally will not lead to big
+performance benefits. Though zlib is faster for very small files, it
+turns out that invoking gzip is faster for larger files. Switching to
+zlib would imply a major disturbance in the source. The small to
+negative performance benefits expected do not seem to justify this, so
+switching to zlib is not currently considered.
+
+Made some changes to ease portability to HPUX with gcc. See also the
+PORTING file. Based on patch file by Daniel Andersson.
+
+Enhanced -s option based on patch by Sebastian Weber, it now can
+accept a comma-separated list of sizes.
+
+Updated manpage BUGS section to say that afio does not restore
+owner/group information on symlinks. Restoring this info would be
+possible using the relatively new `lchown' system call, but that call
+is not supported on older linux systems and some other unix systems.
+Problem reported by Marko Jahnke. Further reporting by
+Giuliano P Procida.
+
+Added gnupg_* scripts to script3/ dir. Scripts by Jens Getreu.
+
+Added script5/ dir and scripts, contributed by Jens Getreu.
+
+Updated existing scripts part of SCRIPTS file.
+
+Updated /script1 and script2/ to improve/remove /tmp file handling.
+Based on patches by Marius Tomaschewski. These changes make the
+scripts more resistant to funny security exploit business with
+pre-existing /tmp files.
+
+Added code to round down volume size to a multiple of the block size
+in the -s option. Added -9 option to suppress this: pre-2.4.6
+versions of afio defaulted to no rounding down. Rounding down is
+needed for compatibility with some devices, notably ftape. Based on
+bug report by L. C. Robinson.
+
+Changed -H promptscript option to take running as an at or cron job
+into account. If /dev/tty is not a connected device, afio will now
+connect /dev/null to the stdin of the promptscript. Based on bug
+report by Andreas Wehler.
+
+
+Version 2.4.7:
+
+
+Fixed bug that sometimes caused `-- compressed' to be printed twice in
+verify operation. Has to do with not flushing stdout, stderr before
+forking. Bug reported by JP Vossen.
+
+Added more material on how pattern matching works in the -y option
+section of the manpage, and added examples of selective restores to
+manpage. Based on questions by Kjell Palmius and Stojan Rancic.
+
+Added text to BUGS section about afio not being able to write into
+directories for which it has no write permissions, except when running
+as root. Problem reported by Kagan Kayal.
+
+Fixed bug that caused afio -s option values above 4gb to be sometimes
+treated as a much lower value when reading an archive. This was a
+truncation-in-casting bug triggered by some combinations of -b and -s
+values. Bug reported by Michael Zieger.
+
+Looked into the case of reading/writing archives to/from regular
+filesystem files which are bigger than 2 GB. Seem to work on newer
+linux systems supporting such large files. On the recent linux system
+I tried (Red Hat 6.2, kernel 2.4.2, GCC 2.95.3, libc.so.6 ->
+libc-2.1.3.so) a freshly compiled afio can read and write >2GB archive
+files to the filesystem. HOWEVER I also got reports from others with
+_the same_ or _newer_ versions of stuff that their compiled afio is
+not able to do this. I have not found a pattern to this: your best
+bet is to recompile the afio executable on your platform and try.
+Based on reports by Grzegorz Wieczorek and Norbert Veber.
+
+Looked into the case of >=2GB files being included *in* an archive.
+With pre-2.4.7 afio versions under Linux, two cases of breakage
+apply. 1) if afio was compiled without large filesystem support then
+such files generated "Value too large for defined data type" error,
+however WITHOUT causing nonzero exit (unless -1 option made `missing
+files' a cause for nonzero exit). 2) if afio was compiled with large
+filesysten support such files would be archived. However, such files
+could then not be verified, listed or unpacked correctly because the
+afio archive header does not have enough room to correctly represent a
+>=2GB file size. [Note: If you really really need to restore such a
+file: by doing some hacks and hand-holding the restore it should be
+possible to achieve this -- all the data is in the archive, afio just
+does not know after how many extra increments of 2GB (or 4GB?) blocks
+it ends]. Added following bugfixes to address all this. No matter
+how it is compiled under Linux, afio will now issue a warning when
+encountering a >=2GB file in the set to archive, and not archive that
+file. The warning will cause nonzero exit (unless -1 option changes
+this). Also documented 2GB limitations in manpage. Based on bug
+reports by Mike Black.
+
+
+Fixed bug that mis-calculated compression ratio number (XX%) printed
+by afio -o -v when compressing very large files. Bug found by Koen
+Holtman.
+
+Did more work on hard links to soft links (some installs actually make
+these things! Sheesh!) Afio -t output is improved for these, and afio
+-r does not give incorrect verify errors anymore on veryfiying the
+second, third, etc. link. Afio -i now correctly restores hardlinked
+soft links (at least on the linux kernel I tested it on). Updated
+manpage to change earlier statement that "Some Linux kernels allow one
+to create a hard link to a symbolic link. afio cannot handle such
+hard links correctly.". Based on bug report by Thomas Dorner. Should
+also be cleaner fix to problem reported earlier by Giuliano P Procida.
+
+If a fatal error occurs and data was transferred, afio makes sure to
+print an error message which includes the offset of the fatal error.
+Based on bug report by Francesco Potorti.
+
+Fixed typesetting bug in afio manpage that caused -R option
+description to exclude the `Disk format command string' argument.
+Based on a 1998 bug report by Lee Bradshaw, and thanks to Dirk
+Eddelbuettel for prompting me to look over the Debian bug report
+database for for afio again -- looks like I lost track of it when I
+got the report the first time.
+
+Added -2 option -- this also means changing the default behavior for
+compressing very large files.
+
+Updated maintainer e-mail addresses.
+
+Added some more documentation on sparse file handling to the manpage.
+
+Documented some -r option limitations in BUGS section of manpage.
+
+Added maximum name length check on reading file names from stdin with
+afio -i.
+
+
+Version 2.4.7.9beta:
+
+[This is a BETA release, meaning that I (the maintainer) am applying
+less strict quality control than I would do for a normal release.
+The main reason for the BETA is to get >2GB functionality out to
+people who need it now and are willing to take some extra risk.]
+
+Changes incorporated via Debian 2.4.7-7 (Debian packaging releases
+maintained by Dirk Eddelbuettel).
+
+Corrected typo in manpage, cdrecord was spelled crdrecord. Based on
+report by Christoph Claus.
+
+Switched to large file compile environment (-D_FILE_OFFSET_BITS=64
+-D_LARGEFILE_SOURCE) in order write archives larger than 2GB. Based
+on suggestions by Norbert Veber.
+
+Applied patch by Dieter Schuster to correct an endian issue on 32-bit
+powerpc systems, trigged by having 64 bit off_t. The bug was in the
+sprintf formatting in outhead(), asb->sb_size should be (unsigned long
+int) asb->sb_size.
+
+Applied patches by Stephen van Egmond to correct endian issues on 32-bit
+powerpc systems and fix all -Wall issues.
+
+Lots of little changes and fixes of fixes based on the above. Based
+on discussions and tests with/from Stephen van Egmond, Dirk
+Eddelbuettel, Dieter Schuster, Complete history of fixing not
+documented here. Historians, see Debian bug DB numbers #144986 and
+#153948, and maybe more bug numbers too.
+
+Put very elaborate warning flags in compiler options -- need
+to take out later.
+
+[End of list of changes incorporated via Debian 2.4.7-7.]
+
+Improved type used for the variable pad in outeof()
+
+Removed linkp and some use of it in incheckentry(). This was a bug
+(dormant?) introduced by maintenance in 2.4.7. Based on reports by
+several people, including at least Matthias Stolte, Stephen van
+Egmond, Devin Reade, and Mike Black.
+
+Added large ASCII header support for 2G files and 32bit inodes, uid,
+gid, dev, rdev, and nlink values, as well as 64 bit mtime values (be
+prepared for if time_t goes higher than 2038). Based on patch from
+Clark Rawlins.
+
+Changed inode type in large ascii header to 64 bits.
+
+Added extra space (2 bytes) for flags to second extended ascii header,
+and variable-length extra header (with 2-byte length indicator). All
+set to 0 in this release.
+
+Updated and improved discussion of archive portability in manpage.
+
+Changed installation locations for `make install' to be compatible
+(I think) with the Linux Filesystem Hierarchy Standard.
+
+
+Version 2.4.7.9beta4:
+
+Fixed bug in defines: ushort was defined twice
+
+Updated regression test scripts some more. Changed >2gb regression
+test to use 4.1 gb file: that way we actually use more than 32 bits in
+the file size.
+
+Updated README.FIRST file based on various regression test results.
+
+Made ascii art in .h file to decode large ASCII header. Put a few
+ascii chars in the large ascii header to make it easier to read.
+
+Added a lot of casting refinements based on study of elaborate
+compiler warnings.
+
+
+Version 2.4.7.9beta5:
+
+Improved makesparse code in regression test.
+
+Version 2.4.8beta1:
+
+Added -6 option based on suggestions from, discussions with, and patch
+from Matthias Stolte.
+
+Extended -E option syntax. Created new mechanism to create -E default
+extensions list from the manpage, because I keep updating it. Added
+more extensions based on suggestions by Kevin Cosgrove and Matthias
+Stolte. Made default -E extension matching case-insensitive, and
+added case sensitiveness configurability to the -E option, based on
+suggestion by Kevin Cosgrove.
+
+Added discussion of using bzip2 to the manpage, prompted by question
+from Nick Papadonis.
+
+Improved the documentation of the -Z option in the manpage.
+
+Fixed (largely theoretical) bug in nameaddfile().
+
+Improved description of -A option (and defaults if no -A used) on the
+manpage. Based on a problem report by Matthew Vernon.
+
+Fixed bug in verify command: if the file in the archive is not
+compressed, and the file on the filesystem has grown larger than the
+file on the archive, this was not detected before. Based on bug
+reporting and analysis by Ryan W. Maple and Rainer Koenig, and patch
+by Ryan W. Maple.
+
+Added pointer to the HISTORY file in the authors section of the
+manpage.
+
+Added section on web site and internet resources to manpage.
+
+Made some internal buffers used during compression and verify larger.
+
+Fixed bug in verify code: verifying a compressed or uncompresses file
+has a logic bug in that it assumed that the read(f,b,s) system calls
+would always return with s bytes if not end of file/stream yet. This
+assumption is incorrect, especially when reading data from a
+pipe. (Strange that this bug never seemed to cause real problems until
+I did some testing with a large sparse file and `cat' as the
+compression program)
+
+Removed limitation (introduced in one of the 2.4.7.beta versions) in
+the -2 option that for files bigger than 2GB, compression is never
+attempted, unless the -U flag says so. This limitation was introduced
+at the time because of concerns that gzip would not work on >2GB
+files. Some testing showed that gzip works fine (and bzip2 also).
+
+Added code to use lchown call, so that owner information on symlinks
+is restored (if the OS does nor have a lchown call, the HAVE_LCHOWN
+symbol can be commented out in the Makefile). Based on patch file
+from Matthias Goebl.
+
+Added -vv option, and documented stderr/stdout behavior of -v option
+better. Based on patch file from Matthias Goebl.
+
+Added code to set the correct modification times on directories that
+are restored, even if these directories have additional files restored
+into them. (In older versions, the mtime was set when creating the
+directory, but then usually the filesystem updates that mtime to the
+current time when the directory is filled. Now, the original mtimes
+of restored directories are remembered, and they are set again just
+before afio exits.) Based on patch file from Matthias Goebl.
+
+Added a sanity check on the stdin at the start of executing -o mode.
+Output file is only opened (and, if existing, truncated to 0 length)
+when the stdin data starts looking like a file list. This should
+prevent deletion of the archive file contents in most cases when
+people who want to do afio -i myarchive accidentally type afio -o
+myarchive. The idea is that people who type afio -o accidentally will
+see the error messages and press ctrl-C in time.
+
+Documented archive format in the manpage, and improved documentation
+of the -k option. Also included a hint about the -k option in the
+unrecognisable archive error messages. Based on problem reports by
+Evren Yurtesen and Carter Alvord.
+
+Added example of splitting archive into 1GB parts to overcome 2GB
+filesystem limitations. Based on question by Bob Stewart.
+
+Updated maintainer e-mail addresses again. Updated README,
+INSTALLATION files.
+
+Documented archive portability problem in handling major/minor numbers
+across different OS versions in BUGS section.
+
+Fixed bugs in hard link handling when creating an archive (when
+running without -4 option). (I did some tests on this code with 130K
+files with hard links, and it turns out that the old code was not
+correct, though it usually does do the right think when archiving
+moderate numbers of hard linked files.) The code in linkto()
+for creating unique 16-bit inode numbers for files with hard links in
+the archive was buggy. The code would definately fail to produce a
+correct archive when packing more than 4096 sets of hard linked files
+in the archive, and could also fail in some cases when 4096 had not
+been reached. The impact of this bug is somewhat low, I never got any
+bug reports about it, so I guess that most people who have lots of
+hard links and care about restoring them correctly were using -4
+already. (The -4 option did not suffer from these bugs, and did
+correctly handle many hard links as advertised.)
+
+Added code so that, if number of archived hard links goes over 64K,
+then large archive headers will be used to store any additional hard
+linked files. This maximises cpio (and afio backwards) compatibility,
+while removing the 64K hard link restriction for the normal invocation
+of afio. Updated manpage accordingly.
+
+Fixed bug in *un*packing of archives created with -4 option: hard
+linked files these archives would not always be unpacked correctly
+(with afio not printing any error messages about things being
+incorrect) if the -4 flag was ommitted on the command line when using
+afio -i.
+
+Added printing of warning message for the case `archive will not be
+fully compatible with cpio or afio versions 2.4.7 and lower', and c
+and C letters for -1 option. Based in part on discussions with Mike
+Black.
+
+Added code for handling uid/gid values >64K, by using large ASCII
+header. Based on problem report by Jeffrey Eugene Crawford.
+
+Added code for handling time_t values >2^31. Not that Linux supports
+these yet...
+
+Added n letter to -1 flag, based on patch by Keith G. Murphy.
+
+Documented use of additional arguments to generic prompt script in -H
+flag, based on suggestion by Lance Albin.
+
+Updated usage message that is printed when afio is run without
+command line arguments or with invalid arguments.
+
+Added M letter to -1 option. Based on suggestion by Devin Reade.
+
+Version 2.5:
+
+In afio.h ulo and ull macros, added L and LL letters in constants.
+This is more correct and portable and fixes compiler warnings on newer
+gcc versions.
+
+Documented `long long' issues in PORTING file. Removed ifdeffed
+typedef ulonglong porting hacks from the afio.h file.
+
+Changed mknod() call to mkfifo() call when creating named pipe from
+archive. Freebsd cannot make named pipes with mknod.
+
+Added some extra defines to suppress some warnings on sun platform.
+Also added some stuff around awk invocations in makefile and regtest
+to make things easier on sun -- the sun platform I tried it on had a
+default awk that was too ancient to understand things like gsub.
+
+Added some discussion of sun and freebsd to PORTING file.
+
+Fix to regression test: no longer complains if two compared directory
+inodes have a size difference. Bases on bug report by vasudeva.
+
+Changed sanity check on the stdin at the start of executing -o mode:
+now the check only happens if stdin is a tty. This allows scripts to
+make empty archives, and is needed for compatibility with tob. Based
+on problem report by Dirk Eddelbuettel.
+
+Changed read() to readall() in outdata().
+
+Updated SCRIPTS file.
View
140 INSTALLATION
@@ -0,0 +1,140 @@
+
+To install afio, follow these steps:
+
+STEP 1. Compile.
+----------------
+
+Unpack the afio sources, go to the top level source directory, compile
+the binary by typing:
+
+make
+
+
+Side note on compiler warnings:
+-------------------------------
+
+You may get some compiler warnings -- these do not always indicate a
+real problem. (The GCC maintainers add new types of warning messages
+regularly, and afio is usually behind in updating the sources to
+eliminate new warnings.)
+
+Known warnings that you will get with some gcc versions:
+
+afio.o(.text+0xef41): In function `syserr':
+: warning: `sys_errlist' is deprecated; use `strerror' or `strerror_r' instead
+afio.o(.text+0xef30): In function `syserr':
+: warning: `sys_nerr' is deprecated; use `strerror' or `strerror_r' instead
+
+These warnings do not indicate a real problem.
+
+See the file PORTING for more information on compiling afio on
+non-Linux machines.
+
+STEP 2 (OPTIONAL). Regression tests.
+------------------------------------
+
+Optionally, you can run some automatic regression tests to check if
+the new afio binary works OK. If you have an older version of afio
+installed, the tests will also check (just to be extra paranoid) if
+the archive format used by the old binary is still interoperable with
+the new binary. The formats should be compatible unless there is a
+serious bug.
+
+See below for details on running the two automatic regression tests.
+
+STEP 3. Install the binary and manual page.
+-------------------------------------------
+
+Do this manually, or type
+
+make install
+
+which installs the afio binary in /usr/local/bin, and the manual page
+in /usr/share/man/man1 -- these are the correct locations for most
+Linux systems.
+
+** Warning: older versions the afio `make install' (before
+ 2.4.7.9beta) used /usr/bin as the executable install directory. If
+ /usr/bin is before /usr/local/bin in your PATH, you might have to
+ delete or rename any older version of afio in /usr/bin.
+
+
+Notes on using afio
+-------------------
+
+Afio has far too many options to be used directly from the command
+line, it is best used as an `archive engine' in a backup script.
+
+See the file SCRIPTS for more information on backup scripts that use
+afio.
+
+See the file PORTING for information on compiling afio on non-Linux
+machines.
+
+
+Details on the two automatic regression tests (step 2).
+-------------------------------------------------------
+
+Test 1: regtest: file handling and archive portability regression test
+----------------------------------------------------------------------
+
+**Note: the test scripts may fail to work on non-GNU platforms that
+ have very old versions of tools like awk, find, and diff. See the
+ PORTING file for more information.
+
+If you are going to use afio for system backups, this test is best run
+from the root account. In that case the test will also try whether
+afio correctly invokes filesystem operations (like making devices and
+changing file ownership settings) that normal user accounts are not
+allowed to do.
+
+You can compile and run this test with
+
+make regtest
+
+This test prints a line with 'OK!' at the end it succeeds.
+
+ --> this regression test is known to report small permission
+ related problems on several Non-Linux platforms. These mostly
+ have to do (I think) with different approaches the kernels take
+ to handling permissions, so these small problems do not
+ necessarily indicate that the compiled afio is buggy.
+
+
+If you are unsure about interpreting the result of a regression test,
+please check if any recent information (e.g. in the comments) on the
+site http://freshmeat.net/projects/afio/ answers your question. If
+not, or if you think you have found a new bug on your platform,
+whether Linux or not, feel free to mail the afio maintainer (see the
+README file).
+
+
+Test 2: regtest2gb: large file handling test
+--------------------------------------------
+
+This test tries out the large file handling capabilities of afio, and
+is only applicable to systems with large (>2GB) file support. If you
+don't know if your system supports large files, you can find that out
+by running the test.
+
+This test requires a) sparse file support in the filesystem (which is
+present in most Unixes, including Linux, or b) 2.2 GB free space on
+the filesystem. You can compile and run this test with
+
+make regtest2gb
+
+This test prints a line with 'OK!' at the end it succeeds.
+
+ --> this regression test will of course fail on platforms
+ that do not support >2GB files.
+ Note that, if the test fails, this is often not due to a bug
+ in afio, but more likely to a missing feature or configuration
+ problem in the kernel, the filesystem, the compiler, or the
+ libraries.
+ As of Dec 2003, the test is known to report success on
+ - Red Hat Linux 7.3
+ - Debian Linux 3.0/testing (not 3.0/stable) on most platforms,
+ including i386
+ - At least some versions of Solaris
+ - FreeBSD 3.5-STABLE
+
View
114 Makefile
@@ -0,0 +1,114 @@
+SHELL=/bin/sh
+##
+## See the INSTALLATION file for quick installation instructions.
+##
+## I wrote this Makefile, based on comments in the source. -rich $alz.
+## Define INDEX to use index() in place of strchr() (v7, BSD).
+#1 = -UINDEX
+## Define MEMCPY when an efficient memcpy() exists (SysV).
+2 = -DMEMCPY
+## Define MKDIR when a mkdir() system call is present (4.2BSD, SysVr3).
+3 = -DMKDIR
+## Define NOVOID if your compiler doesn't like void casts.
+#4 = -UNOVOID
+## Define SYSTIME to use <sys/time.h> rather than <time.h> (4.2BSD).
+#5 = -USYSTIME
+## Define VOIDFIX to allow pointers to functions returning void (non-PCC).
+6 = -DVOIDFIX
+## Define CTC3B2 to support AT&T 3B2 streaming cartridge tape.
+#7 = -UCTC3B2
+## Define HAVEFCNTL if you have <fcntl.h>
+8 = -DHAVEFCNTL
+## Define MYTEMPNAM if you don't have tempnam()
+#a = -UMYTEMPNAM
+## Define UNIXPC if you are on a 3b1, 7300, etc.
+## (problem is you can't write to a floppy from shared memory)
+#b = -UUNIXPC
+## Define HAVEMEMCMP if you have memcmp otherwise assumes bcmp
+c = -DHAVEMEMCMP
+## Define DEFFMTCMD to being how to format the media you use the most
+## This is the DEFault FoRMat CoManD.
+d = -DDEFFMTCMD='"fdformat /dev/fd0H1440"'
+## Define LONGZFILE if you want .Z to be tagged on the end of a 14 char
+## file name (or longer for BSD) in the archive when the file is compressed
+#e = -DLONGZFILE
+
+## Define HAVE_LCHOWN is the system has an lchown call (like chown but does
+## not follow symlinks)
+e2 = -DHAVE_LCHOWN
+
+## Define PRG_COMPRESS to get something other than `gzip'.
+# you need to edit compfile.c (-G option) if you change this line.
+f = -DPRG_COMPRESS='"gzip"'
+
+## Define HAVEFNMATCH if you want to use the gnu fnmatch() routine for
+# -y -Y -w -W matching.
+# If it is not defined, a primitive replacement match routine is used that
+# only supports patterns of the form "cccc" and "cccc*". Make sure that
+# you change the manual page in this case.
+
+g = -DHAVEFNMATCH
+
+# fnmatch() is in the gnu C library, so it is directly available on
+# Linux. If your system (e.g. SCO) does not have the gnu C library,
+# unpack the archive gnu.fnmatch.tar.gz and uncomment the following
+# two lines:
+
+#M = fnmatch.o
+#I = -I.
+
+# Please read the COPYING.LIB file in this archive if you plan to
+# redistribute afio executables with this library linked in.
+
+#uncomment one of the two lines below to
+#get the normal or large file compile environment
+# afio will work when compiled in both environments, but on old or non-linux
+# systems the large file compile environment itself might be buggy or beta.
+#LARGEFILEFLAGS=
+LARGEFILEFLAGS=-D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE
+
+# even more warnings flags..
+MW=
+#MW=-Wtraditional -Wcast-qual -Wcast-align -Wconversion -pedantic -Wlong-long -Wimplicit -Wuninitialized -W -Wshadow -Wsign-compare -Wstrict-prototypes -Wmissing-declarations
+
+CFLAGS1 = -Wall -Wstrict-prototypes -s -O2 -fomit-frame-pointer ${LARGEFILEFLAGS} ${MW}
+
+CC=gcc
+
+CFLAGS = ${CFLAGS1} $1 $2 $3 $4 $5 $6 $7 $8 $9 $a $b $c $d $e ${e2} $f $g $I
+LDFLAGS =
+
+afio : afio.o compfile.o exten.o match.o $M
+ ${CC} ${LDFLAGS} afio.o compfile.o exten.o match.o $M -o afio
+
+clean:
+ rm -f *.o afio
+ rm -f regtest/cmpstat regtest/makesparse
+ rm -f regtest/statsize regtest/statsize64
+ cd regtest; /bin/sh regtest.clean
+
+install: afio
+ cp afio /usr/local/bin
+ cp afio.1 /usr/share/man/man1
+
+# generate default list of -E extensions from manpage
+# note: on sun, I had to change awk command below to nawk or gawk
+# to get it to work.
+exten_default.h : afio.1
+ awk -f exten_make.awk afio.1 >exten_default.h
+
+
+afio.o : afio.h patchlevel.h
+compfile.o : afio.h
+exten.o : afio.h exten_default.h
+match.o : afio.h
+
+regtest: regtestx
+
+regtestx: afio
+ cd regtest; make; rm cmpstat
+
+regtest2gb: regtest2gbx
+
+regtest2gbx: afio
+ cd regtest; make 2gb
View
170 PORTING
@@ -0,0 +1,170 @@
+
+This afio version is based on a Linux port of afio 2.3. Since the
+original port, significant functionality has been added and some bugs
+were removed. While primarily intended for use under Linux, this code
+should be portable to other UNIX versions. As far as I know, there
+has been no afio development beyond 2.3 outside the Linux community,
+except for non-Linux patches that people mail back to me.
+
+--------------------------------------------------------------------------
+
+The code in this archive compiles under Linux.
+
+You may have to tweak the makefile to compile it on other platforms.
+
+If you make a `clean' port of this code, meaning that you add ifdefs
+to the source files and `uncomment this for %s' lines to the makefile,
+you may want to send diffs to me (see README file for maintainer
+e-mail address) so that I can merge them with the next afio version.
+If you encounter any POSIX compatibility problems, please report them.
+
+--------------------------------------------------------------------------
+
+UNSIGNED LONG LONG USE
+
+New potential porting problems introduced since version 2.4.7.9beta1.
+
+Since 2.4.7.9beta1, afio supports >2GB files, and this support depends
+on the compiler having `unsigned long long' support, and also on
+having `unsigned long long' format support in the printf and scanf
+functions. Any non-ancient version of gcc and glibc will have this
+support.
+
+In theory, it is not a huge job to add some ifdefs for platforms
+without compiler support for long long, ifdefs which drop the 2GB
+support but otherwise leave a functional afio that can be compiled
+with old compilers. However I (=the current maintainer) am not doing
+this yet until I get real problem reports or patches -- I suspect that
+in practice nobody is using such old compilers anymore.
+
+See comments in the afio 2.4.7 afio.h file for the story behind the
+typedef unsigned long long ulonglong;
+
+--------------------------------------------------------------------------
+
+SOME POTENTIAL PORTING PROBLEMS
+
+1) Availability of fnmatch(), see the makefile.
+
+2) Changing the makefile to work with your make and C compiler.
+
+3) Making floppy verify work on your unix flavor.
+
+The code in afio.c should be highly portable. However I can not
+guarantee it to keep working if changes are made to the defines in the
+makefile. The code in the other .c files was written on a Linux
+machine for gcc, and assumes a posixy environment. I have not tried
+it on other machines but on most modern unixes it should compile. I
+would like to hear about (un)successful ports to other machines.
+
+Some of the afio code is a horrible mess, making incremental changes
+very difficult. A complete rewrite of the floppy disk interfacing
+code is probably needed if extensions are to be added. At the moment
+afio is (afaik) the only fault tolerant compressing archiver program
+available, but it probably has some bugs lurking in it. Because of
+this afio is not an optimal solution. I hope that afio will be
+replaced by a compressing version of gnu cpio or by cpio combined with
+with a fault tolerant compression backend (probably based on a gzip
+library) in the future.
+
+------------------------------------------------------------------
+
+REGTESSION TEST SCRIPT PORTING
+
+The regtession test scripts mentioned in the INSTALL file may fail to
+work on non-GNU platforms that have very old versions of tools like
+bash, awk, find, and diff.
+
+-----------------
+
+Some notes about regression testing on (some versions of) FreeBSD
+
+- FreeBSD has a `bash' exectutable that does not implement full GNU
+ bash. The test scripts have been written to avoid any
+ incompatibilities.
+
+-----------------
+
+Some notes about regression testing on (some versions of) sun
+
+- if the default awk command is very old, it cannot parse the awk
+ scripts. Change it to `nawk' or `gawk' -- see the comments in
+ the regtest/regtest script.
+
+- if the default find command does not support the -print0 option,
+ one test will fail. You can try to subsiture GNU find if it
+ is installed
+
+- if some tests fail, then `diff -u' is used to print the differences.
+ The default diff on some sun platforms does not recognise the -u
+ option, You can try to subsiture GNU diff if it is installed.
+
+- On at least some version of sun, the default tar command incorrectly
+ restores directory permissions. This will show up as failure of one
+ regression test, but here actually tar is at fault. Example output
+ where this happens:
+
+ * compare unpacked tar archive with newly unpacked test archive
+ drwxr-xr-x 7 kholtman zh 2048 Dec 1 2002 t2/afiot
+ drwxrwxrwx 7 kholtman zh 2048 Dec 1 2002 t4/afiot
+ cmpstat t4/afiot t2/afiot: mode difference
+ drwxr-xr-x 2 kholtman zh 2048 Dec 2 2002 t2/afiot/ztest
+ drwxrwxrwx 2 kholtman zh 2048 Dec 2 2002 t4/afiot/ztest
+ cmpstat t4/afiot/ztest t2/afiot/ztest: mode difference
+ drwxr-xr-x 3 kholtman zh 2048 Dec 1 2002 t2/afiot/special
+ drwxrwxrwx 3 kholtman zh 2048 Dec 1 2002 t4/afiot/special
+
+- The sun kernel (on at least some versions of sun) handles
+ permission bits on symlinks different from the Linux way. This
+ results in a failure of at least one regression test. Example
+ output where this happens:
+
+ * compare table-of-contents file made by new afio with archived toc
+ t2.arch t2.new differ: char 2048, line 44
+ --- t2.arch 2003-12-19 22:02:53.000001000 +0100
+ +++ t2.new 2003-12-19 22:02:53.000001000 +0100
+ @@ -44,9 +44,6 @@
+ -lrwxrwxrwx 1 x x DATE afiot/link with spaces S-> name with spaces
+ -lrwxrwxrwx 1 x x DATE afiot/link1 S-> y2k
+ -lrwxrwxrwx 1 x x DATE afiot/linkx S-> /etc/sysconfig/ipchains
+ +lrwxr-xr-x 1 x x DATE afiot/link with spaces S-> name with spaces
+ +lrwxr-xr-x 1 x x DATE afiot/link1 S-> y2k
+ +lrwxr-xr-x 1 x x DATE afiot/linkx S-> /etc/sysconfig/ipchains
+ FAILURE in: compare table-of-contents file made by new afio
+ with archived toc
+
+------------------------------------------------------------------
+
+HISTORICAL PORTING NOTES
+
+Historical note: The porting hints below were all written before 1996
+as far as I can tell -- they are probably not relevant to recent
+systems.
+
+Note for SCO porters from Karel Kubat, karel@icce.rug.nl:
+
+ Please read the makefile about the changes needed for fnmatch().
+
+ You may want to change the -DDEFFMTCMD value in the makefile.
+
+ If you encounter any other options which may need changing, please mail me
+ at karel@icce.rug.nl. I'm not the maintainer of afio for SCO platforms, but
+ I'd like to know if you come across anything spectacular.
+
+
+Note for IRIX porters using the SGI native C compiler (cc):
+
+ Modify the Makefile to use CC=cc, comment out the CFLAGS1 line,
+ and add
+ -Dirix_cc_compatibility
+ to the CFLAGS line.
+
+Note for HPUX porters using gcc (maybe some (older?) gcc versions
+only):
+
+ These steps seem to be needed to get afio to compile, but I
+ cannot guarantee that they are sufficient to make it work on HPUX:
+ - Comment out '8 = -DHAVEFCNTL' in the Makefile
+ - Remove the '-g' from the CFLAGS1 line in the Makefile.
+
+
View
76 README
@@ -0,0 +1,76 @@
+
+This is afio 2.5.
+
+To find out if this is the latest version, you can look at
+http://freshmeat.net/projects/afio/
+
+The current maintainer is Koen Holtman (koen@hep.caltech.edu).
+
+When mailing the maintainer, please use the word `afio' somewhere in
+the subject line, this lowers the chance that your mail will get
+accidentally deleted.
+
+Alternative e-mail address for the maintainer: k.holtman@chello.nl
+
+>> See the first lines of afio.c for licensing/redistribution information <<
+
+--------------------------------------------------------------------------
+
+Afio makes cpio-format archives. It deals somewhat gracefully with
+input data corruption. Supports multi-volume archives during
+interactive operation. Afio can make compressed archives that are
+much safer than compressed tar or cpio archives. Afio is best used as
+an `archive engine' in a backup script.
+
+Since version 2.4.8beta1, afio supports files greater than 2 GB.
+
+--------------------------------------------------------------------------
+
+See the file INSTALLATION for installation instructions.
+
+See the file SCRIPTS for more information on backup scripts that use
+afio.
+
+See the file PORTING for information on compiling afio on non-Linux
+machines.
+
+---------------------------------------------------------------------------
+
+This afio version is based on a Linux port of afio 2.3. Since the
+original port, significant functionality has been added and some bugs
+were removed. While primarily intended for use under Linux, this code
+should be portable to other UNIX versions. As far as I know, there
+has been no afio development beyond 2.3 outside the Linux community.
+Thus, it should be safe to advertise ports of this code to other UNIX
+versions as ports of afio version 2.4.1.
+
+---------------------------------------------------------------------------
+
+Afio has far too many options and features (some of which are not even
+in the manual page). Anything in afio that doesn't relate to reading
+or writing an archive from/to a simple file or pipe or backing up and
+restoring from floppies remains untested.
+
+In particular, nobody has verified if the options -p -d -e -g -h -j -l
+-m -u and -R and the special case archive name `!command' really do
+what they claim to do.
+
+Typical `tested' afio uses are
+ ... | afio -o -v -s 1440k -F -Z /dev/fd0H1440
+ afio -oZvx /tmp/pipe1 </tmp/pipe2
+ afio -i -Z -k -v -x -n /tmp/pipe1
+ ... | afio -s 512m -c 1024 -Z -T 20k -G 1 -E /backup/compressed -v -o \
+ -L /backup/LOG -z /dev/tape 2>/dev/tty8 >/var/adm/backup
+
+WARNING1: the code for -F (and -f and -K) is a complete mess. It will
+probably work in the normal case, but don't expect it to handle a
+write/verify error correctly. If you get such an error, best thing is
+to restart afio completely.
+
+WARNING2:The remote archive facilites (host:/file archive names) have
+not been exhaustively tested. These facilities have seen a lot of
+real-life use though. However, there may be bugs in the code for
+error handling and error reporting with remote archives.
+
+---------------------------------------------------------------------------
+
View
54 SCRIPTS
@@ -0,0 +1,54 @@
+
+Afio has far too many options to be used directly from the command
+line, it is best used as an `archive engine' in a backup
+script.
+
+
+1) Using an existing script.
+
+There are a number of backup scripts using afio that I know of.
+Apart from incorporating the functions of afio, such scripts offer
+some general `administrative structure' like backup volumes, file
+exclusion, log files and incremental backup facilities.
+
+The available scripts have some large differences in the type of
+backup device they were primarily designed for (from floppy to network
+attached tape), the amount of maintenance done on them, and presumably
+the amount of remaining bugs.
+
+A list of scripts that use afio:
+
+This list was last updated Dec 2003 -- I have only listed scripts
+for which I found some evidence that they are (still) maintained.
+
+---------------------------------------------------------------------------
+Title: tob: Tape Oriented Backup
+http://tinyplanet.ca/projects/tob/
+---------------------------------------------------------------------------
+Title: flexbackup: A flexible backup tool.
+http://www.flexbackup.org/
+---------------------------------------------------------------------------
+Title: KBackup - Karsten's Backup System
+http://kbackup.sourceforge.net/
+---------------------------------------------------------------------------
+
+
+2) Writing your own backup script. (Or adapting an existing one.)
+
+Aside from the manual page, the files README.afio, README.linux,
+and script*/* provide information for script writers.
+
+Three sample backup scripts are included with this afio release. The
+material in script1/ is written by Andrew Stevens, that in script2/ by
+Dave Gymer, that in script5/ by Gens Getreu. All scripts will
+probably need some editing to run on your configuration.
+
+Sample scripts for backups with pgp encryption are included in
+script3/. There were contributed by Karsten Ballueder.
+
+Sample scripts for backups with GnuPG (gpg) encryption are also
+included in script3/. There were contributed by Jens Getreu.
+
+A sample script for use with the -H option is included in
+script4/. This script was provided by Raphael Manfredi.
+
View
1,607 afio.1
@@ -0,0 +1,1607 @@
+'br $Header: /u/buhrt/src/afio/RCS/afio.1,v 2.3 1991/09/25 20:08:33 buhrt Exp $
+.TH AFIO 1
+.SH NAME
+afio \- manipulate archives and files
+.SH SYNOPSIS
+.B ...
+|
+.B afio -o
+[
+.I options
+] archive : write (create) archive
+.br
+.B afio -i
+[
+.I options
+] archive : install (unpack) archive
+.br
+.B afio -t
+[
+.I options
+] archive : list table-of-contents of archive
+.br
+.B afio -r
+[
+.I options
+] archive : verify archive against filesystem
+.br
+.B afio -p
+[
+.I options
+] directory [ ... ] : copy files
+.PP
+.SH DESCRIPTION
+.I Afio
+manipulates groups of files, copying them within the (collective)
+filesystem or between the filesystem and an
+.I afio
+archive.
+.PP
+With
+.BR \-o ,
+reads pathnames from the standard input
+and writes an
+.IR archive .
+.PP
+With
+.BR \-t ,
+reads an
+.I archive
+and writes a table-of-contents to the standard output.
+.PP
+With
+.BR \-i ,
+installs the contents of an
+.I archive
+relative to the working directory.
+.PP
+With
+.BR \-p ,
+reads pathnames from the standard input
+and copies the files to each
+.IR directory .
+Cannot be combined with the
+.B \-Z
+option.
+.PP
+With
+.BR \-r ,
+reads
+.IR archive
+and verifies it against the filesystem. This is useful for verifying
+tape archives.
+.PP
+Creates missing directories as necessary, with permissions
+to match their parents.
+.PP
+Removes leading slashes from pathnames,
+making all paths relative to the current directory.
+This is a safety feature to prevent inadvertent overwriting
+of system files when doing restores. To suppress this safety
+feature, the
+.BR -A
+option must be used while writing an archive, but also when
+reading (installing), verifying, and cataloging an existing archive.
+.PP
+Supports compression while archiving, with the
+.BR -Z
+option. Will compress individual files in the archive, not the
+entire archive datastream, which makes
+.I afio
+compressed archives much more robust than
+.I `tar\ zc'
+type archives.
+.PP
+Supports multi-volume archives during interactive operation
+(i.e., when
+.I /dev/tty
+is accessible and
+.I SIGINT
+is not being ignored).
+.PP
+.SH ARCHIVE PORTABILITY
+.I afio
+archives are portable between different types of UNIX systems,
+as they contain only ASCII-formatted
+header information.
+.PP
+Except in special cases discussed below,
+.I afio
+will create archives with the same format as ASCII
+.IR cpio (1)
+archives.
+Therefore
+.IR cpio (1)
+can usually be used to restore an
+.I afio
+archive in the case that
+.I afio
+is not available on a system. (With most
+.I cpio
+versions, to unpack an ASCII format archive, use
+.IR "cpio \-c" ,
+and for GNU
+.IR cpio (1)
+use
+.IR "cpio -H odc" .)
+When unpacking with
+.IR cpio ,
+any compressed files inside an
+.I "afio -Z"
+archive are not uncompressed by
+.IR cpio ,
+but will be created on the file system as compressed files with a .z
+extension.
+.PP
+Unfortunately, the ASCII cpio archive format cannot represent some
+files and file properties that can be present in a modern UNIX filesystem.
+If afio creates an
+archive with such things, then it uses an afio-specific 'large ASCII' header
+for the files concerned.
+Archives with large ASCII headers cannot be unpacked completely by
+.I cpio
+or
+.I afio
+versions before 2.4.8.
+.PP
+When creating an archive, the `large ASCII' header is used by
+.I afio
+to cover the following situations:
+.RS 3
+.TP 3
+.B o
+A file has a size larger than 2 GB
+.TP
+.B o
+The archive contains more than 64K files which have hard links
+.TP
+.B o
+A file, directory, or special file has a UID or GID value
+larger than 65535.
+.RE
+.PP
+The
+.BR \-5
+option can be used to always preserve
+.I cpio
+compatibility, it will cause
+.I afio
+to fail rather than produce an incompatible archive in the cases above.
+.PP
+Archives made using the (deprecated)
+.BR \-4
+option are also
+.BR not
+compatible with
+.IR cpio ,
+but they are compatible with
+.I afio
+versions 2.4.4 and later.
+.PP
+.SH ARCHIVE FILE FORMAT
+An
+.I afio
+archive file has a simple format. The archive starts with
+a file header for the first file,
+followed by the contents of the first file (which will either
+be the exact contents byte-for-byte,
+or the exact contents in some compressed format).
+The data of the first file is immediately followed by
+the file header of the second file,
+and so on. At the end, there is a special `end of archive' header, usually
+followed by some padding bytes.
+.PP
+A multi-volume
+.I afio
+archive is simply a normal archive split up into multiple parts. There
+are no special volume-level data headers. This means that that
+volumes can be split and merged by external programs, as long as the
+data stays in the correct order. It also implies that the contents of
+a single file can cross volume boundaries.
+Selective restores of files at known volume locations can be done
+by feeding only the needed volumes to
+.IR afio ,
+provided that the
+.B -k
+option is used.
+.PP
+The contents of hard linked files are (unless the
+.B -l
+option is used) only stored once in the archive.
+The file headers for the second, third, and later occurence of a hard
+linked file have no data after them. This makes selective
+restores of hard-liked files difficult:
+if later occurences are to be restored correctly,
+the first occurence always needs to be selected too.
+.PP
+.SH OPTIONS
+.TP 13
+.BI "-@ " address
+Send email to
+.I address
+when a volume change (tape change, floppy change) is needed, and also when
+the entire operation is complete. Uses
+.IR sendmail (1)
+to send the mail.
+.TP
+.B -a
+Preserve the last access times (atimes) of the files read when
+making or verifying an archive.
+.B Warning:
+if this option is used,
+.I afio
+will change the last inode changed times (ctimes) of these files.
+Thus, this option cannot be used together with an incremental backup
+scheme that relies on the ctimes being preserved.
+.TP
+.BI \-b "\ size"
+Read or write
+.IR size -character
+archive blocks.
+Suffices of
+.BR b ,
+.BR k ,
+.B m
+and
+.B g
+denote multiples of
+.IR 512 ,
+.IR kilobytes ,
+.IR megabytes
+and
+.IR gigabytes ,
+respectively.
+Defaults to
+.I 5120
+for compatibility with
+.IR cpio (1).
+In some cases, notably when using
+.I ftape
+with some tape drives,
+.B \-b 10k
+is needed for compatibility. Note that
+.B \-b 10k
+is the default block size used by
+.IR tar (1),
+so it is usually a good choice if the tape setup is known to work
+with
+.IR tar (1).
+.TP
+.BI \-c "\ count"
+Buffer
+.I count
+archive blocks between I/O operations. A large
+.I count
+is recommended for efficient use with streaming magnetic tape drives, in
+order to reduce the number of tape stops and restarts.
+.TP
+.B \-d
+Don't create missing directories.
+.TP
+.BI \-e "\ bound"
+Pad the archive to a multiple of
+.I bound
+characters.
+Recognizes the same suffices as
+.BR \-s .
+Defaults to
+.I 1x\^
+(the
+.B \-b
+block size)
+for compatibility with
+.IR cpio (1).
+.TP
+.B \-f
+Spawn a child process to actually write to the archive; provides
+a clumsy form of double-buffering.
+Requires
+.B \-s
+for multi-volume archive support.
+.TP
+.B \-g
+Change to input file directories. Avoids quadratic filesystem
+behavior with long similar pathnames. Requires all absolute
+pathnames, including those for the
+.B \-o
+.I archive
+and the
+.B \-p
+.IR directories .
+.TP
+.B \-h
+Follow symbolic links, treating them as ordinary files and directories.
+.TP
+.B \-j
+Don't generate sparse filesystem blocks on restoring files.
+By default,
+.I afio
+creates sparse filesystem blocks (with
+.IR lseek (2))
+when possible when restoring files from an archive,
+but not if these files were stored in a compressed form. Unless stored in
+a compressed form, sparse files are not archived efficiently:
+they will take space equal to the full file length.
+(The sparse file handling in
+.I afio
+does not make much sense except in a historical way.)
+.TP
+.B \-k
+Rather
+than complaining about unrecognizable input,
+skip unreadable data (or partial file contents) at the
+.I beginning
+of the archive file being read, and search for the next valid archive header.
+This option is needed to deal with certain types of backup media damage.
+It is also useful to support quick
+selective restores from multi-volume archives, or
+from searchable block devices, if the volume or location of the file to be
+restored is known in advance (see the
+.B -B
+option).
+If, for example, a selective restore is done with
+the fourth volume of a multi-volume afio archive,
+then the
+.B \-k
+option needs to be used, else
+.I afio
+will complain about the input not being a well-formed archive.
+.TP
+.B \-l
+With
+.BR \-o ,
+write file contents with each hard link.
+.sp
+With
+.BR \-t ,
+report hard links.
+.sp
+With
+.BR \-p ,
+attempt to link files rather than copying them.
+.TP
+.B \-m
+Mark output files with a common current timestamp
+(rather than with input file modification times).
+.TP
+.B \-n
+Protect newer existing files (comparing file modification times).
+.TP
+.BI \-s "\ size"
+Restrict each portion of a multi-volume archive to
+.I size
+characters. This
+option recognizes the same size suffices as
+.BR \-b .
+Also, the suffix
+.B x
+denotes a multiple of the
+.B \-b
+block size (and must follow any
+.B \-b
+specification).
+.I size
+can be a single size or a comma-seperated list of sizes,
+for example '2m,5m,8m', to specify different sizes for the
+subsequent volumes. If there are more volumes than sizes, the last
+specified size is used for all remaining volumes.
+This option is useful
+with finite-length devices which do not return short
+counts at end of media (sigh); output to magnetic tape typically
+falls into this category. When an archive is being read or written, using
+.B \-s
+causes
+.I afio
+to prompt for the next volume if the specified volume length is reached.
+The
+.B \-s
+option will also cause
+.I afio
+to prompt if there is a premature EOF while reading the input.
+The special case
+.B -s 0
+will activate this prompting for the next volume on premature EOF without
+setting a volume length.
+When writing an archive,
+.I afio
+will prompt for the next volume on end-of-media, even without
+.B -s 0
+being supplied, if the device is capable of reporting end-of-media.
+If the volume
+.I size
+specified is not a multiple of the block size set with the
+.B -b
+option, then
+.I afio(1)
+will silently round down the volume size to the nearest multiple of
+the block size. This rounding down can be suppressed using the
+.B -9
+option: if
+.B -9
+is used,
+.I afio(1)
+will write a small block of data, smaller than the
+.B -b
+size, at the end of the volume to completely fill it to the specified
+size. Some devices are not able to handle such small block writes.
+.TP
+.B \-u
+Report files with unseen links.
+.TP
+.B \-v
+Verbose. Report pathnames (to stderr) as they are processed. When used with
+.BR \-t ,
+gives an
+.I "ls \-l"
+style report (including link information) to stdout instead.
+When used twice
+.RB ( -vv )
+with
+.BR \-o ,
+gives an
+.I "ls \-l"
+style report to stdout while writing the archive. (But this use of
+.B -vv
+will not work if the archive is also being written to stdout.)
+.TP
+.BI \-w "\ filename"
+Treats each line in
+.I filename
+as an
+.B \-y
+pattern, see
+.BR \-y .
+.TP
+.B \-x
+Retain file ownership and setuid/setgid permissions.
+This is the default for the super-user; he may use
+.B \-X
+to override it.
+.TP
+.BI \-y "\ pattern"
+Restrict processing of files to names matching shell wildcard pattern
+.IR pattern .
+Use this flag once for each pattern to be recognized.
+With the possible exception of the presence of a leading slash, the
+complete file name as appearing in the archive table-of-contents must
+match the pattern, for example the file name 'etc/passwd' is matched
+by the pattern '*passwd' but NOT by the pattern 'passwd'. See
+.B `man 7 glob'
+for more information on shell wildcard pattern matching.
+The only difference with shell wildcard pattern matching is that in
+.I afio
+the wildcards will also match '/' characters in file
+names. For example the pattern '/usr/src/*' will match the
+file name '/usr/src/linux/Makefile', and any other file name
+starting with '/usr/src'. Unless the
+.B -S
+option is given, any leading slash in the pattern or the filename is
+ignored when matching,
+e.g.
+.I /etc/passwd
+will match
+.IR etc/passwd .
+Use
+.B \-Y
+to supply patterns which are
+.I not
+to be processed.
+.B \-Y
+overrides
+.B \-y
+if a filename matches both.
+See also
+.BR \-w\ and\ \-W .
+.B Note:
+if
+.I afio
+was compiled without using the GNU fnmatch library, then the full
+shell wildcard pattern syntax cannot be used,
+and matching support is limited to patterns which are a full
+literal file name and patterns which end in '*'.
+.TP
+.B \-z
+Print execution statistics. This is meant for human consumption;
+use by other programs is officially discouraged.
+.TP
+.B -A
+Do not turn absolute paths into relative paths. That is don't remove
+the leading slash. Applies to the path names written in an archive,
+but also to the path names read out of an archive during read (install),
+verify, and cataloging operations.
+.TP
+.B -B
+If the
+.B -v
+option is used, prints the byte offset of the start of each file in
+the archive.
+If your tape drive can start reading at any position in an
+archive, the output of
+.B -B
+can be useful for doing quick selective restores.
+.TP
+.BI -D "\ controlscript"
+Set the control script name to
+.IR controlscript ,
+see the section on
+.B control files
+below.
+.TP
+.BI -E "\ [+]filename" " | -E CS | -E CI"
+While creating an archive with compressed files using the
+.B -Z
+option, disable (attempts at) compression for files with
+particular extensions.
+This option can be used to speed up the creation of the archive, by
+making
+.I afio
+avoid trying to use
+.I gzip
+on files that contain compressed data already.
+By default, if no specific
+.B -E
+option is given, all files with the extensions
+'br the two START_ and END_ comments below are used by the makefile to create
+'br the compiled-in defaults for the -E option.
+'br NOTE: the awk script called by in the makefile disregards all
+'br FIRST words on each line below,
+'br i.e. it disregards the .I typesetting commands and the word and.
+'br so BE CAREFUL TO TAKE THIS INTO ACCOUNT if you edit the text below,
+'br else the awk script might miss some extensions, or take some
+'br common words you add as default extensions.
+'br START_EXT_LIST
+.I .Z .z .gz .bz2 .tgz
+.I .arc .zip .rar .lzh .lha
+.I .uc2 .tpz .taz .tgz .rpm .zoo .deb
+.I .gif .jpeg .jpg .tif .tiff .png .pdf
+.I .arj .avi .bgb .cab .cpn .hqx .jar
+.I .mp3 .mpg .mpq .pic .pkz .psn .sit
+and
+.I .smk
+'br END_EXT_LIST
+will not be compressed.
+Also by default, the file extension matching is case-insensitive (to do the
+right thing with respect to MS-DOS based filesystems).
+The
+.BI -E "\ filename"
+form of this option will replace the default list of file extensions
+by reading a new list of file extensions, separated by whitespace, from
+.IR filename .
+.I filename
+may contain comments preceded by a #. The extensions in
+.I filename
+should usually all start with a dot, but they do not need to start with a
+dot, for example the extension 'tz' will match the file name 'hertz'.
+The
+.BI -E "\ +filename"
+form (with a + sign in front of
+.IR filename )
+can be
+used to specify extensions in addition to the built-in
+default list, instead of replacing the whole default list.
+To make extension matching case-sensitive, add the special option form
+.B -E CS
+to the command line. The form
+.B -E CI
+invokes the (default) case-insensitive comparison.
+See also the
+.B -6
+option, which offers an additional way to suppress compression.
+.TP
+.B -F
+This is a floppy disk,
+.B -s
+is required. Causes floppy writing in
+.B O_SYNC
+mode under Linux. With kernel version 1.1.54 and above, this allows
+.I afio
+to detect some floppy errors while writing.
+Uses shared memory if compiled in otherwise mallocs as needed (a 3b1
+will not be able to malloc the needed memory w/o shared memory),
+.I afio
+assumes either way you can malloc/shmalloc a chunck of memory
+the size of one disk. Examples: 795k: 3.5" (720k drive), 316k (360k drive)
+.nf
+At the end of each disk this message occurs:
+ Ready for disk [#] on [output]
+ (remove the disk when the light goes out)
+ Type "go" (or "GO") when ready to proceed
+ (or "quit" to abort):
+.fi
+.TP
+.BI \-G "\ factor"
+Specifies the
+.IR gzip (1)
+compression speed factor, used when compressing files with the
+.B -Z
+option.
+Factor 1 is the fastest with least compression, 9 is slowest with best
+compression.
+The default value is 6. See also the
+.IR gzip (1)
+manual page.
+If you have a slow machine or a fast backup medium, you may want to
+specify a low value for
+.I factor
+to speed up the backup. On large (>200k) files,
+.B -G 1
+typically zips twice as fast as
+.BR "-G 6" ,
+while still achieving a better result than
+.IR compress "(1)."
+The zip speed for small files is mainly determined by the invocation time
+of
+.I gzip
+(1), see the
+.B -T
+option.
+.TP
+.BI "-H " promptscript
+Specify a script to run, in stead of using the normal prompt, before
+advancing to the next achive volume. The script will be run with the
+volume number, archive specification, and the reason for changing to
+the next volume as arguments. The script
+should exit with 0 for OK and 1 for abort, other exit codes will be
+treated as fatal errors.
+.I afio
+executes the script by taking the
+.I promptscript
+string, appending the arguments, and then calling the shell to execute
+the resulting command line. This means that a general-purpose
+prompt script can be supplied with additional arguments, via the
+.I afio
+command line, by using a
+.B -H
+option value like
+-H "generic_promptscript additional_arg_1 additional_arg_2".
+.TP
+.B -J
+Try to continue after a media write error when doing a backup (normal
+behavior is to abort with a fatal error).
+.TP
+.B -K
+Verify the output against what is in the memory copy of the disk (-F required).
+If the writing or verifying fails the following menu pops up
+.nf
+ [Writing/Verify] of disk [disk #] has FAILED!
+ Enter 1 to RETRY this disk
+ Enter 2 to REFORMAT this disk before a RETRY
+
+ Enter quit to ABORT this backup
+.fi
+Currently,
+.I afio
+will not process the answers 1 and 2 in the right way. The menu above
+is only useful in that it signifies that something is wrong.
+.TP
+.BI "-L " Log_file_path
+Specify the name of the file to log errors and the final totals to.
+.TP
+.BI \-M "\ size
+Specifies the maximum amount of memory to use for the temporary storage of
+compression results when using the
+.B -Z
+option. The default is
+.B -M 2m
+(2 megabytes). If the compressed version of a file is larger than
+this (or if
+.I afio
+runs out of virtual memory),
+.IR gzip (1)
+is run twice of the file,
+the first time to determine the length of the result, the second time
+to get the compressed data itself.
+.TP
+.BI \-P "\ progname"
+Use the program
+.I progname
+instead of the standard
+.IR gzip (1)
+for compression and decompression with the
+.B -Z
+option. For example, use the options
+.B -Z -P bzip2
+to write and install archives using
+.IR bzip2 (1)
+compression. If
+.I progname
+does not have command line options (-c, -d, and -<number>) in the style of
+.IR gzip (1)
+then the
+.B -Q
+option can be used to supply the right options.
+See also the
+.BR -Q ,
+.B -U
+and
+.B -3
+options.
+.TP
+.BI \-Q "\ opt"
+Pass the option
+.I "opt"
+to the compression or decompression program used with the
+.B -Z
+option. For passing multiple options, use
+.B -Q
+multiple times. If no
+.B -Q
+flag is present, the standard options are passed. The standard
+options are
+.B -c -6
+when the program is called for compression and
+.B -c -d
+when the program is called for decompression. Use the special case
+.B -Q
+""
+if no options at all are to be passed to the program.
+.TP
+.BI -R "\ Disk format command string"
+This is the command that is run when you enter 2 to reformat the disk after
+a failed verify.
+The default (fdformat /dev/fd0H1440) can be changed
+to a given system's default by editing the Makefile.
+You are also prompted for formatting whenever a disk change
+is requested.
+.TP
+.BI -S
+Do not ignore a leading slash in the pattern or the file name when matching
+.B \-y
+and
+.B -Y
+patterns. See also
+.BR -A .
+.TP
+.BI -T "\ threshold"
+Only compress a file when using the
+.B -Z
+option if its length is at least
+.IR threshold .
+The default is
+.BR "-T 0k" .
+This is useful if you have a slow machine or a fast backup medium.
+Specifying
+.B "-T 3k"
+typically halves the number of invocations of
+.IR gzip (1),
+saving some 30% computation time, while creating an archive
+that is only 5% longer. The combination
+.B -T 8k -G 1
+typically saves 70% computation time and gives a 20% size increase.
+The latter combination may be a good alternative to not using
+.B -Z
+at all. These figures of course depend heavily on the kind of files
+in the archive and the processor - i/o speed ratio on your machine.
+See also the
+.B -2
+option.
+.TP
+.B -U
+If used with the
+.B -Z
+option, forces compressed versions to be stored of all files, even if
+the compressed versions are bigger than the original versions, and
+disregarding any (default) values of the
+.B -T
+and
+.B -2
+options. This is useful when the
+.B -P
+and
+.B -Q
+options are used to replace the compression program
+.I gzip
+with an encryption program in order to make an archive with encrypted files.
+Due to internal limitations of
+.IR afio ,
+use of this flag forces the writing of file content with each hard
+linked file, rather than only once for every set of hard linked files.
+.B WARNING:
+use of the -U option
+will also cause compression (or whatever operation the
+.B -P
+option indicates) on files larger than 2 GB, if these
+are present in the input. Not all compression programs might handle
+such huge files correctly (recent Linux versions of gzip, bzip2, and
+gpg have all been tested and seem to work OK). If your setup is
+obscure, some testing might be warranted.
+.TP
+.BI \-W "\ filename"
+Treats each line in
+.I filename
+as an
+.B \-Y
+pattern, see
+.BR \-Y .
+.TP
+.BI \-Y "\ pattern"
+Do
+.I not
+process files whose names match shell wildcard pattern
+.IR pattern .
+See also
+.BR "\-y " and " -W" .
+.TP
+.B -Z
+Compress the files that go into the archive when creating an archive,
+or uncompress them again when installing an archive.
+.I afio -Z
+will compress each file in the archive individually, while keeping the archive
+headers uncompressed. Compared to
+.I tar zc
+style archives,
+.I afio -Z
+archives are therefore much more fault-tolerant
+against read errors on the backup medium.
+When creating an archive with the
+.I -Z
+option,
+.I afio
+will run
+.I gzip
+on each file encountered, and, if the result is smaller than the original,
+store the compressed version of the file.
+Requires
+.IR gzip (1)
+to be in your path. Mainly to speed up
+.I afio
+operation, compression is not attempted on a file if:
+1) the file is very small (see the
+.B -T
+option),
+2) the file is very large (see the
+.B -2
+option),
+3) the file has a certain extension, so it probably contains
+compressed data already (see the
+.B -E
+option),
+4) the file pathname matches a certain pattern, as set by the
+.B -6
+option,
+5) the file has hard links (this due to an internal limitation of afio,
+but this limitation does not apply if the
+.B -l
+option is also used).
+Regardless of the above, if the
+.B -U
+option is used then the compression program is always run, and the
+compressed result is always stored.
+When installing an archive with compressed files, the
+.B -Z
+option needs to be used in order to make afio automatically uncompress
+the files that it compressed earlier.
+The
+.B -P
+option can be used to do the (un)compression with programs other than
+.IR gzip ,
+see the
+.B -P
+(and
+.B -Q
+and
+.BR -3 )
+options in this manpage for details.
+See also the
+.BR -G
+option which provides yet another way to tune the compression process.
+.TP
+.B -0
+Assume input filenames to be terminated with a '\\0' instead
+of a '\\n'. When used with
+.IR "find ... -print0" ,
+can be used to ensure that any filename can be handled,
+even if it contains a newline.
+.TP
+.BI \-1 "\ warnings-to-ignore"
+Control if
+.IR afio (1)
+should exit with a nonzero code after printing certain warning messages,
+and if certain warning messages should be printed at all.
+This option is sometimes useful when calling
+.IR afio (1)
+from inside a backup script or program.
+.IR afio (1)
+will exit with a nonzero code on encountering
+various 'hard' errors, and also (with the default value of the
+.B -1
+option) when it has printed
+certain warning messages during execution.
+.I warnings-to-ignore
+is a list of letters which determines the behavior related to warning messages.
+The default value for this option is
+.BR "-1 mc" .
+For
+.I afio
+versions 2.4.3 and earlier, the default was
+.BR "-1 a" .
+For
+.I afio
+versions 2.4.4 and 2.4.5, the default was
+.BR "-1 ''" .
+The defined
+.I warnings-to-ignore
+letters are as follows.
+.I a
+is for for ignoring
+.IR a ll
+possible warnings on exit: if this letter is used,
+the printing of a warning message will
+never cause a nonzero exit code.
+.I m
+is for ignoring in the exit code any warning about
+.IR m issing
+files, which will be printed when, on
+creating an archive, a file whose name was read from the standard
+input is not found.
+.I c
+is for ignoring in the exit code the warning that the
+archive being created will not be not fully compatible with
+.IR c pio
+or afio versions 2.4.7 or lower.
+.I C
+is the same as
+.IR c ,
+but in addition the warning message will not even be printed.
+.I M
+will suppress the printing of all warning messages asssociated with
+.IR M ultivolume
+archive handling, messages like "Output limit reached" and
+"Continuing".
+.I n
+is for ignoring in the exit code a particular class of
+.IR n o-such-file
+warnings: it ignores these warnings when they happen after the file has already
+been succesfully opened. This unusual warning situation can occur
+when archiving files on Windows smbfs filesystems -- due to a Windows problem,
+smbfs files with non-ASCII characters in their names
+can sometimes be opened but not read. When the
+.B -Z
+option is used, the
+.I n
+letter function is (currently) only implemented for files with sizes
+smaller than indicated by the
+.B -T
+option, so in that case the
+.B -T
+option is also needed for this letter to have any effect.
+.TP
+.BI "-2 " maximum-file-size-to-compress
+Do not compress any files which
+are larger than this size when making a compressed archive
+with the
+.B -Z
+option. The default value is
+.BR "-2 200m"
+(200 Megabytes). This maximum size cutoff lowers the risk that a major portion
+of a large file
+will be irrecoverable due to small media errors. If a media error occurs
+while reading a file that
+.I afio
+has stored in a compressed form, then
+.I afio
+and
+.I gzip
+will not be able to restore the entire remainder of that file.
+This is usually an acceptable risk for small files. However for very
+large files the risk of loosing a large amount of data because
+of this effect will usually be too big. The special case
+.B "-2 0"
+eliminates any maximum size cutoff.
+.TP
+.BI "-3 " filedescriptor-nr
+Rewind the filedescriptor before invoking the (un)compression program
+if using the
+.B -Z
+option. This
+is useful when the
+.B -P
+and
+.B -Q
+options are used to replace the compression program
+.I gzip
+with some types of encryption programs in order to make or read an archive
+with encrypted files. The rewinding is needed to interface
+correctly with some encryption programs that read their key from an open
+filedescriptor. If the
+.B -P
+program name matches 'pgp' or 'gpg', then the
+.B -3
+option
+.I must
+be used to avoid
+.IR afio (1)
+reporting an error. Use the special case
+.B "-3 0"
+to supress the error message without rewinding any file descriptor.
+The
+.B "-3 0"
+option may also be needed to sucessfully read back encrypted archives
+made with
+.I afio
+version 2.4.5 and older.
+.TP
+.B -4
+(Deprecated, the intended effect of this option is now
+achieved by default as long as the
+.B -5
+option is not used. This option could still be useful for compatibility
+with machines running an older version of
+.IR afio .)
+Write archive with the `extended ASCII' format headers which use 4-byte
+inode numbers. Archives using the extended ASCII format headers
+are
+.B not
+compatible with any other archiver. This option was useful for reliably
+creating and restoring sets of files with many internal
+hard links, for example a news spool.
+.TP
+.B -5
+Refuse to create an archive that is incompatible with
+.IR cpio (1).
+If this option is used,
+.I afio
+will never write any `large ASCII' file headers that are incompatible with
+.IR cpio (1),
+but fail with an error code instead.
+See the ARCHIVE PORTABILITY section above for more information on the
+use of `large ASCII' file headers.
+.TP
+.B -6 "\ filename"
+While creating an archive with compressed files using the
+.B -Z
+option, disable (attempts at) compression for files that match
+particular shell patterns.
+This option can be used to speed up the creation of the archive, by
+making
+.I afio
+avoid trying to use
+.I gzip
+on files that contain compressed data already.
+Reads shell wildcard patterns from
+.IR filename ,
+treating each line in the file as a pattern.
+Files whose names match these patterns are not to be compressed when using the
+.B -Z
+option. Pattern matching is done in exactly the same way as described for
+the
+.B -y
+option. See also the
+.B -E
+option: the (default) settings of the
+.B -E
+option will further restrict compression attempts.
+The
+.B -E
+option controls compression attempts based on file extensions;
+the
+.B -6
+option is mainly intended as a method for excluding all
+files in certain subdirectory trees from compression.
+.TP
+.B -9
+Do not round down any
+.B -s
+volume sizes to the nearest
+.B -b
+block size. See the
+.B -s
+option.
+.PP
+.SH NOTES
+Special-case archive names:
+.RS 3
+.TP 3
+.B o
+Specify
+.I \-
+to read or write the standard input or output, respectively.
+This disables multi-volume archive handling.
+.TP
+.B o
+Prefix a command string to be executed with an exclamation mark
+.RI ( ! ).
+The command is executed once for each archive volume,
+with its standard input or output piped to
+.IR afio .
+It is expected to produce a zero exit code when all is well.
+.TP
+.B o
+Use
+.I system:file
+to access an archive in
+.I file
+on
+.IR system .
+This is really just a special case of pipelining.
+It requires a 4.2BSD-style remote shell
+.RI ( rsh (1C))
+and a remote copy of
+.IR afio .
+.TP
+.B o
+A more elaborate case of the above is
+.I [user@]host[%rsh][=afio]:file
+where the optional
+.I user@
+component specifies the user name on the remote host, the optional
+.I %rsh
+specifies the (local) name of the remote shell command to use,
+and the optional
+.I =afio
+specifies the name of the remote copy of the afio command.
+.TP
+.B o
+Anything else specifies a local file or device.
+An output file will be created if it does not already exist.
+.RE
+.PP
+Recognizes obsolete binary
+.IR cpio (1)
+archives (including those from machines with reversed byte order),
+but cannot write them.
+.PP
+Recovers from archive corruption by searching for a valid magic
+number. This is rather simplistic, but, much like a disassembler,
+almost always works.
+.PP
+Optimizes pathnames with respect to the current and parent
+directories. For example,
+.I ./src/sh/../misc/afio.c
+becomes
+.IR src/misc/afio.c .
+.SH CONTROL FILES
+.I Afio
+archives can contain so-called control files. Unlike normal archive
+entries, a control file in not unpacked to the filesystem. A control
+file has a
+.I label
+and some
+.IR data .
+When
+.I afio
+encounters a control file in the archive it is reading, it will feed the
+.I label
+and
+.I data
+to a so-called control script. The control script is supplied by
+the user. It can perform special actions based on the
+.I label
+and
+.I data
+it receives from
+.IR afio .
+.PP
+.B Control file labels.
+The control file mechanism can be used for many things. Examples are
+putting archive descriptions at the beginning of the archive and
+embedding lists of files to move before unpacking the rest or the
+archive.
+.PP
+To distinguish between different uses, the