afio - Online in the Cloud

PROGRAM:

NAME

afio - manipulate archives and files

SYNOPSIS

... | afio -o [ options ] archive : write (create) archive
afio -i [ options ] archive : install (unpack) archive
afio -t [ options ] archive : list table-of-contents of archive
afio -r [ options ] archive : verify archive against filesystem
afio -p [ options ] directory [ ... ] : copy files

DESCRIPTION

Afio manipulates groups of files, copying them within the (collective) filesystem or
between the filesystem and an afio archive.

With -o, reads pathnames from the standard input and writes an archive.

With -t, reads an archive and writes a table-of-contents to the standard output.

With -i, installs the contents of an archive relative to the working directory.

With -p, reads pathnames from the standard input and copies the files to each directory.
Cannot be combined with the -Z option.

With -r, reads archive and verifies it against the filesystem. This is useful for
verifying tape archives, to ensure they have no bit errors. The verification compares
file contents, but not permission bits and non-file filesystem entities, so it cannot be
used as a reliable tool to detect every possible change made to a filesystem.

Creates missing directories as necessary, with permissions to match their parents.

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 -A option must be used while
writing an archive, but also when reading (installing), verifying, and cataloging an
existing archive.

Supports compression while archiving, with the -Z option. Will compress individual files
in the archive, not the entire archive datastream, which makes afio compressed archives
much more robust than `tar zc' type archives.

Supports multi-volume archives during interactive operation (i.e., when /dev/tty is
accessible and SIGINT is not being ignored).

OPTIONS

-@ address Send email to address when a volume change (tape change, floppy change) is
needed, and also when the entire operation is complete. Uses sendmail(1) to
send the mail.

-a Preserve the last access times (atimes) of the files read when making or
verifying an archive. Warning: if this option is used, 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.

-b size Read or write size-character archive blocks. Suffices of b, k, m and g
denote multiples of 512, kilobytes, megabytes and gigabytes, respectively.
Defaults to 5120 for compatibility with cpio(1). In some cases, notably when
using ftape with some tape drives, -b 10k is needed for compatibility. Note
that -b 10k is the default block size used by tar(1), so it is usually a good
choice if the tape setup is known to work with tar(1).

-c count Buffer count archive blocks between I/O operations. A large count is
recommended for efficient use with streaming magnetic tape drives, in order
to reduce the number of tape stops and restarts.

-d Don't create missing directories.

-e bound Pad the archive to a multiple of bound characters. Recognizes the same
suffices as -s. Defaults to 1x (the -b block size) for compatibility with
cpio(1).

-f Spawn a child process to actually write to the archive; provides a clumsy
form of double-buffering. Requires -s for multi-volume archive support.

-g Change to input file directories. Avoids quadratic filesystem behavior with
long similar pathnames. Requires all absolute pathnames, including those for
the -o archive and the -p directories.

-h Follow symbolic links, treating them as ordinary files and directories.

-j Don't generate sparse filesystem blocks on restoring files. By default, afio
creates sparse filesystem blocks (with 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 afio does not make much sense except in a historical way.)

-k Rather than complaining about unrecognizable input, skip unreadable data (or
partial file contents) at the 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 option). If, for example, a selective restore is done
with the fourth volume of a multi-volume afio archive, then the -k option
needs to be used, else afio will complain about the input not being a well-
formed archive.

-l With -o, write file contents with each hard link.

With -t, report hard links.

With -p, attempt to link files rather than copying them.

-m Mark output files with a common current timestamp (rather than with input
file modification times).

-n Protect newer existing files (comparing file modification times).

-s size Restrict each portion of a multi-volume archive to size characters. This
option recognizes the same size suffices as -b. Also, the suffix x denotes a
multiple of the -b block size (and must follow any -b specification). 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. If this option is used, the special character sequences
%V and %S in the input/output filename or command string are replaced by the
current volume number and volume size. Use %% to produce a single %
character. The -s 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
-s causes afio to prompt for the next volume if the specified volume length
is reached. The -s option will also cause afio to prompt if there is a
premature EOF while reading the input. The special case -s 0 will activate
this prompting for the next volume on premature EOF without setting a volume
length. When writing an archive, afio will prompt for the next volume on
end-of-media, even without -s 0 being supplied, if the device is capable of
reporting end-of-media. If the volume size specified is not a multiple of
the block size set with the -b option, then 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 -9 option: if -9 is used, afio(1) will write
a small block of data, smaller than the -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.

-u Report files with unseen links.

-v Verbose. Report pathnames (to stderr) as they are processed. When used with
-t, gives an ls -l style report (including link information) to stdout
instead. When used twice (-vv) with -o, gives an ls -l style report to
stdout while writing the archive. (But this use of -vv will not work if the
archive is also being written to stdout.)

-w filename Treats each line in filename as an -y pattern, see -y.

-x Retain file ownership and setuid/setgid permissions. This is the default for
the super-user; he may use -X to override it.

-y pattern Restrict processing of files to names matching shell wildcard pattern
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 `man 7 glob' for more information on shell
wildcard pattern matching. The only difference with shell wildcard pattern
matching is that in 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 -S option is given, any leading slash in the pattern or the
filename is ignored when matching, e.g. /etc/passwd will match etc/passwd.
Use -Y to supply patterns which are not to be processed. -Y overrides -y if
a filename matches both. See also -w and -W. See also the -7 option, which
can be used to modify the meaning of -y, -Y, -w, and -W when literal matching
without wildcard processing is needed. Note: if 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 '*'.

-z Print execution statistics. This is meant for human consumption; use by other
programs is officially discouraged.

-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.

-B If the -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 can be useful for doing quick selective restores.

-D controlscript
Set the control script name to controlscript, see the section on control
files below.

-E [+]filename | -E CS | -E CI
While creating an archive with compressed files using the -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 afio avoid
trying to use gzip on files that contain compressed data already. By
default, if no specific -E option is given, all files with the extensions .Z
.z .gz .bz2 .tgz .arc .zip .rar .lzh .lha .uc2 .tpz .taz .tgz .rpm .zoo .deb
.gif .jpeg .jpg .tif .tiff .png .pdf .arj .avi .bgb .cab .cpn .hqx .jar .mp3
.mpg .mpq .pic .pkz .psn .sit .ogg and .smk 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 -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 filename. filename
may contain comments preceded by a #. The extensions in 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
-E +filename form (with a + sign in front of 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 -E CS to the command line. The form -E CI invokes the
(default) case-insensitive comparison. See also the -6 option, which offers
an additional way to suppress compression.

-F This is a floppy disk, -s is required. Causes floppy writing in O_SYNC mode
under Linux. With kernel version 1.1.54 and above, this allows 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), 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)
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):

-G factor Specifies the gzip(1) compression speed factor, used when compressing files
with the -Z option. Factor 1 is the fastest with least compression, 9 is
slowest with best compression. The default value is 6. See also the gzip(1)
manual page. If you have a slow machine or a fast backup medium, you may
want to specify a low value for factor to speed up the backup. On large
(>200k) files, -G 1 typically zips twice as fast as -G 6, while still
achieving a better result than compress(1). The zip speed for small files is
mainly determined by the invocation time of gzip (1), see the -T option.

-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. afio executes the script
by taking the 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 afio
command line, by using a -H option value like -H "generic_promptscript
additional_arg_1 additional_arg_2".\

-J Try to continue after a media write error when doing a backup (normal
behavior is to abort with a fatal error).

-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
[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
Currently, 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.

-L Log_file_path
Specify the name of the file to log errors and the final totals to.

-M size Specifies the maximum amount of memory to use for the temporary storage of
compression results when using the -Z option. The default is -M 250m (250
megabytes). If the compressed version of a file is larger than this (or if
afio runs out of virtual memory), 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.

-P progname Use the program progname instead of the standard gzip(1) for compression and
decompression with the -Z option. For example, use the options -Z -P bzip2 to
write and install archives using bzip2(1) compression. If progname does not
have command line options (-c, -d, and -<number>) in the style of gzip(1)
then the -Q option can be used to supply the right options. The compression
program used must have the property that, if the output file size exceeds the
value of the -M option, then when the compression program is run for a second
time on the same input, it must produce an output with exactly the same size.
(See also the -M option description.) The GnuPG (gpg) encryption program
does not satisfy this lenght-preserving criterion unless its built-in
compression is disabled (see examples in the afio source script3/ directory).
See also the -Q, -U and -3 options.

-Q opt Pass the option opt to the compression or decompression program used with the
-Z option. For passing multiple options, use -Q multiple times. If no -Q
flag is present, the standard options are passed. The standard options are
-c -6 when the program is called for compression and -c -d when the program
is called for decompression. Use the special case -Q "" if no options at all
are to be passed to the program.

-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.

-S Do not ignore a leading slash in the pattern or the file name when matching
-y and -Y patterns. See also -A.

-T threshold Only compress a file when using the -Z option if its length is at least
threshold. The default is -T 0k. This is useful if you have a slow machine
or a fast backup medium. Specifying -T 3k typically halves the number of
invocations of gzip(1), saving some 30% computation time, while creating an
archive that is only 5% longer. The combination -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 -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 -2 option.

-U If used with the -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 -T and -2 options. This is
useful when the -P and -Q options are used to replace the compression program
gzip with an encryption program in order to make an archive with encrypted
files. Due to internal limitations of 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. WARNING: use of the -U option will also
cause compression (or whatever operation the -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.

-W filename Treats each line in filename as an -Y pattern, see -Y.

-Y pattern Do not process files whose names match shell wildcard pattern pattern. See
also -y and -W.

-Z Compress the files that go into the archive when creating an archive, or
uncompress them again when installing an archive. afio -Z will compress each
file in the archive individually, while keeping the archive headers
uncompressed. Compared to tar zc style archives, afio -Z archives are
therefore much more fault-tolerant against read errors on the backup medium.
When creating an archive with the -Z option, afio will run gzip on each file
encountered, and, if the result is smaller than the original, store the
compressed version of the file. Requires gzip(1) to be in your path. Mainly
to speed up afio operation, compression is not attempted on a file if: 1) the
file is very small (see the -T option), 2) the file is very large (see the -2
option), 3) the file has a certain extension, so it probably contains
compressed data already (see the -E option), 4) the file pathname matches a
certain pattern, as set by the -6 option, 5) the file has hard links (this
due to an internal limitation of afio, but this limitation does not apply if
the -l option is also used). Regardless of the above, if the -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 -Z
option needs to be used in order to make afio automatically uncompress the
files that it compressed earlier. The -P option can be used to do the
(un)compression with programs other than gzip, see the -P (and -Q and -3)
options in this manpage for details. See also the -G option which provides
yet another way to tune the compression process.

-0 Use filenames terminated with '\0' instead of '\n'. When used as follows:
find ... -print0 | afio -o -0 ..., it ensures that any input filename can be
handled, even a file name containing newlines. When used as afio -t -0 ... |
..., this allows the table of contents output to be parsed unambiguosly even
if the filenames contain newlines. The -0 option also affects the parsing of
the files supplied by -w file and -W file options: if the option -0 precedes
them in the command line then the pattern lines contained in the files should
be terminated with '\0' in stead of '\n'. A second use of -0 toggles the
option. This can be useful when using multiple pattern files or when
combining with the -t option.

-1 warnings-to-ignore
Control if 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 afio(1) from inside a backup
script or program. afio(1) will exit with a nonzero code on encountering
various 'hard' errors, and also (with the default value of the -1 option)
when it has printed certain warning messages during execution. warnings-to-
ignore is a list of letters which determines the behavior related to warning
messages. The default value for this option is -1 mc. For afio versions
2.4.3 and earlier, the default was -1 a. For afio versions 2.4.4 and 2.4.5,
the default was -1 ''. The defined warnings-to-ignore letters are as
follows. a is for for ignoring all possible warnings on exit: if this letter
is used, the printing of a warning message will never cause a nonzero exit
code. m is for ignoring in the exit code any warning about missing files,
which will be printed when, on creating an archive, a file whose name was
read from the standard input is not found. c is for ignoring in the exit
code the warning that the archive being created will not be not fully
compatible with cpio or afio versions 2.4.7 or lower. C is the same as c,
but in addition the warning message will not even be printed. M will
suppress the printing of all warning messages asssociated with Multivolume
archive handling, messages like "Output limit reached" and "Continuing". d
is for ignoring in the exit code any warnings about changed files, which will
be printed when, on creating an archive, a file that is being archived
changes while it is being written into the archive, where the changing is
detected by examining the file modification time stamp. r is for ignoring
certain warnings during the verify (-r) operation. If this letter is used,
some verification errors that are very probably due to changes in the
filesystem, during or after the backup was made, are ignored in determining
the exit code. The two verification errors that are ignored are: 1) a file
in the archive is no longer present on the filesystem, and 2) the file
contents in the archive and on the filesystem are different, but the file
lengths or the file modification times are also different, so the difference
in contents is probably due to the file on the file system having been
changed. n is for ignoring in the exit code a particular class of no-such-
file warnings: it ignores these warnings when they happen after the file has
already been successfully 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 -Z option is used, the n letter function is
(currently) only implemented for files with sizes smaller than indicated by
the -T option, so in that case the -T option is also needed for this letter
to have any effect.

-2 maximum-file-size-to-compress
Do not compress any files which are larger than this size when making a
compressed archive with the -Z option. The default value is -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 afio has stored in a compressed form,
then afio and 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 -2 0 eliminates any maximum size
cutoff.

-3 filedescriptor-nr
Rewind the filedescriptor before invoking the (un)compression program if
using the -Z option. This is useful when the -P and -Q options are used to
replace the compression program 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 -P program name matches 'pgp' or
'gpg', then the -3 option must be used to avoid afio(1) reporting an error.
Use the special case -3 0 to supress the error message without rewinding any
file descriptor. The -3 0 option may also be needed to successfully read
back encrypted archives made with afio version 2.4.5 and older.

-4 (Deprecated, the intended effect of this option is now achieved by default as
long as the -5 option is not used. This option could still be useful for
compatibility with machines running an older version of afio.) Write archive
with the `extended ASCII' format headers which use 4-byte inode numbers.
Archives using the extended ASCII format headers are 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.

-5 Refuse to create an archive that is incompatible with cpio(1). If this
option is used, afio will never write any `large ASCII' file headers that are
incompatible with 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.

-6 filename While creating an archive with compressed files using the -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
afio avoid trying to use gzip on files that contain compressed data already.
Reads shell wildcard patterns from filename, treating each line in the file
as a pattern. Files whose names match these patterns are not to be
compressed when using the -Z option. Pattern matching is done in exactly the
same way as described for the -y option. See also the -E option: the
(default) settings of the -E option will further restrict compression
attempts. The -E option controls compression attempts based on file
extensions; the -6 option is mainly intended as a method for excluding all
files in certain subdirectory trees from compression..

-7 Switch between shell wildcard pattern matching and exact name matching
(without interpreting any wildcard characters) for the patterns supplied in
the -y, -Y, -w, and -W options. If the -7 option is used in front of any
option -y, -Y, -w, or -W, then the patterns supplied in these options are not
intrerpreted as wildcard patterns, but as character strings that must match
exactly to the file name, except possibly in leading slashes. This option
can be useful for handling the exceptional cases where file names in the
archive, or the names of files to be archived, contain wildcard characters
themselves. For example, find /tmp -print0 | afio -ov -Y '*.jpg' -7 -Y
'/tmp/a[12]*4' -0 archive can be used to archive files all files under /tmp,
even files with a '\n' character in the name, except for .jpg files and the
file with the exact name /tmp/a[12]*4. A second use of -7 toggles the
matching for subsequently occuring -y, -Y, -w, and -W back to shell wildcard
pattern matching.

-9 Do not round down any -s volume sizes to the nearest -b block size. See the
-s option.

ARCHIVE PORTABILITY

afio archives are portable between different types of UNIX systems, as they contain only
ASCII-formatted header information.

Except in special cases discussed below, afio will create archives with the same format as
ASCII cpio(1) archives. Therefore cpio(1) can usually be used to restore an afio archive
in the case that afio is not available on a system. (With most cpio versions, to unpack an
ASCII format archive, use cpio -c, and for GNU cpio(1) use cpio -H odc.) When unpacking
with cpio, any compressed files inside an afio -Z archive are not uncompressed by cpio,
but will be created on the file system as compressed files with a .z extension.

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 cpio or
afio versions before 2.4.8.

When creating an archive, the `large ASCII' header is used by afio to cover the following
situations:

o A file has a size larger than 2 GB

o The archive contains more than 64K files which have hard links

o A file, directory, or special file has a UID or GID value larger than 65535.

The -5 option can be used to always preserve cpio compatibility, it will cause afio to
fail rather than produce an incompatible archive in the cases above.

Archives made using the (deprecated) -4 option are also not compatible with cpio, but they
are compatible with afio versions 2.4.4 and later.

ARCHIVE FILE FORMAT

An 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.

A multi-volume 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 afio, provided that the -k option is used.

The contents of hard linked files are (unless the -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.

NOTES

Special-case archive names:

o Specify - to read or write the standard input or output, respectively. This
disables multi-volume archive handling.

o Prefix a command string to be executed with an exclamation mark (!). The command is
executed once for each archive volume, with its standard input or output piped to
afio. It is expected to produce a zero exit code when all is well.

o Use system:file to access an archive in file on system. This is really just a
special case of pipelining. It requires a 4.2BSD-style remote shell (rsh(1C)) and a
remote copy of afio.

o A more elaborate case of the above is [user@]host[%rsh][=afio]:file where the
optional user@ component specifies the user name on the remote host, the optional
%rsh specifies the (local) name of the remote shell command to use, and the optional
=afio specifies the name of the remote copy of the afio command.

o Anything else specifies a local file or device. An output file will be created if
it does not already exist.

o When the -s option is used to invoke multi-volume archive processing, any %V in the
file/device name or command string is subsisuted by the current volume number, and
any %S by the current volume size. Use %% to produce a single % character.

Recognizes obsolete binary cpio(1) archives (including those from machines with reversed
byte order), but cannot write them.

Recovers from archive corruption by searching for a valid magic number. This is rather
simplistic, but, much like a disassembler, almost always works.

Optimizes pathnames with respect to the current and parent directories. For example,
./src/sh/../misc/afio.c becomes src/misc/afio.c.

CONTROL FILES

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 label and some data.
When afio encounters a control file in the archive it is reading, it will feed the label
and data to a so-called control script. The control script is supplied by the user. It
can perform special actions based on the label and data it receives from afio.

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.

To distinguish between different uses, the label of a control file should indicate the
program that made the contol file and the purpose of the control file data. It should
have the form

programname.kindofdata

where programname is the name of the backup program that generated the control file, and
kindofdata is the meaning of the control file data. Some examples are

tbackup.movelist tbackup.updatescript
blebberfiler.archivecontents
backup_script_of_Joe_User.archivedescription

The user-supplied control script should look at the label to decide what to do with the
control data. This way, control files with unknown labels can be ignored, and afio
archives maintain some degree of portability between different programs that restore or
index them.

Control file labels that are intended to be portable between different backup programs
could be defined in the future.

Making control files. When making an archive, afio reads a stream containing the names of
the files (directories, ...) to put in the archive. This stream may also contain `control
file generators', which are lines with the following format:

//--sourcename label

Here, the //-- sequence signals that a control file is to be made, sourcename is the path
to a file containing the control file data, and label is the control file label. The
sourcename must be a regular file or a symlink to a regular file.

A control file will show up as

//--CONTROL_FILE/label

in an archive listing, where label is the control file label.

Control scripts. A control script is supplied to afio with the

-D controlscript

command line option. The controlscript must be an executable program. The script is run
whenever afio encounters a control file while doing a -i -t or -r operation. Afio will
supply the control file label as an argument to the script. The script should read the
control file data from its standard input. If the script exits with a non-zero exit
status, afio will issue a warning message.

If a contol file is encountered and no -D option is given, afio will issue a warning
message. To suppress the warning message and ignore all control scripts, -D "" can be
used.

An example of a control script is

#!/bin/sh
if [ $1 = "afio_example.headertext" ]; then
#the headertext control file is supposed to be packed as the first
#entry of the archive
echo Archive header:
cat -
echo Unpack this archive? y/n
#stdout is still connected to the tty, read the reply from stdout
read yn <&1
if [ "$yn" = n ]; then
#abort
kill $PPID
fi
else
echo Ignoring unknown control file.
cat - >/dev/null
fi

Afio never compresses the control file data when storing it in an archive, even when the
-Z option is used. When a control file is encountered by cpio(1) or an afio with a
version number below 2.4.1, the data will be unpacked to the filesystem, and named
CONTROL_FILE/label where label is the control file label.

Use afio online using onworks.net services