AFIO(1)AFIO(1)NAMEafio - 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 stan‐
dard 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.
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 exist‐
ing archive.
Supports compression while archiving, with the -Z option. Will com‐
press individual files in the archive, not the entire archive datas‐
tream, 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).
ARCHIVE PORTABILITYafio 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 usu‐
ally 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 ar‐
chive 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 filesys‐
tem. 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.
OPTIONS
-@ address Send email to address when a volume change (tape change,
floppy change) is needed, and also when the entire opera‐
tion 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 stream‐
ing 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. Recog‐
nizes 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 com‐
pressed 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 begin‐
ning 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-vol‐
ume 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.
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 -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 pro‐
cessed. 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 over‐
ride it.
-y pattern Restrict processing of files to names matching shell wild‐
card 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 pat‐
tern '/usr/src/*' will match the file name
'/usr/src/linux/Makefile', and any other file name start‐
ing 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. 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 con‐
sumption; 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 cata‐
loging 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 sec‐
tion 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 and .smk
will not be compressed. Also by default, the file exten‐
sion matching is case-insensitive (to do the right thing
with respect to MS-DOS based filesystems). The -E file‐
name 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 con‐
tain 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 com‐
pression.
-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 speci‐
fication, 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 tem‐
porary storage of compression results when using the -Z
option. The default is -M 2m (2 megabytes). If the com‐
pressed 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. 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 refor‐
mat 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 for‐
matting 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 combina‐
tion 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. WARN‐
ING: 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 cor‐
rectly (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 pat‐
tern 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 uncom‐
pressed. Compared to tar zc style archives, afio-Z ar‐
chives 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 origi‐
nal, store the compressed version of the file. Requires
gzip(1) to be in your path. Mainly to speed up afio oper‐
ation, 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 cer‐
tain 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 Assume 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.
-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 some‐
times 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 cer‐
tain 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 warn‐
ings 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 com‐
patible 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 han‐
dling, messages like "Output limit reached" and "Continu‐
ing". 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 succes‐
fully opened. This unusual warning situation can occur
when archiving files on Windows smbfs filesystems -- due
to a Windows problem, smbfs files with non-ASCII charac‐
ters in their names can sometimes be opened but not read.
When the -Z option is used, the n letter function is (cur‐
rently) 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)compres‐
sion 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 sucessfully 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 AR‐
CHIVE 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 com‐
pressed 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 com‐
pressed 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.
-9 Do not round down any -s volume sizes to the nearest -b
block size. See the -s option.
NOTES
Special-case archive names:
o Specify - to read or write the standard input or output, respec‐
tively. 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.
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 ar‐
chive 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 porta‐
bility 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 con‐
taining the names of the files (directories, ...) to put in the ar‐
chive. 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 sta‐
tus, 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 ar‐
chive, even when the -Z option is used. When a control file is encoun‐
tered 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.
BUGS
There are too many options.
Restricts pathnames to 1023 characters, and 255 meaningful elements
(where each element is a pathname component separated by a /).
Does not use the same default block size as tar(1). tar(1) uses 10 KB,
afio uses 5 KB by default. Some tape drives only work with a 10 KB
block size, in that case the afio option -b 10k is needed to make the
tape work.
There is no sequence information within multi-volume archives. Input
sequence errors generally masquerade as data corruption. A solution
would probably be mutually exclusive with cpio(1) compatibility.
Degenerate uses of symbolic links are mangled by pathname optimization.
For example, assuming that "usr.src" is a symbolic link to "/usr/src",
the pathname "usr.src/../bin/cu" is mis-optimized into "bin/cu" (rather
than "/usr/bin/cu").
The afio code for handling floppies (-F and -f and -K options) has
buggy error handling. afio does not allow one to retry a failed
floppy write on a different floppy, and it cannot recover from a verify
error. If the floppy handling code is used and write or verify errors
do occur, it is best to restart afio completely. Making backups to
floppies should really be done with a more specialised backup program
that wraps afio.
The Linux floppy drivers below kernel version 1.1.54 do not allow afio
to find out about floppy write errors while writing. If you are run‐
ning a kernel below 1.1.54, afio will happily fail to write to (say) a
write protected disk and not report anything wrong! The only way to
find out about write errors in this case is by watching the kernel mes‐
sages, or by switching on the verify (-K) option.
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.
An archive created with a command like 'find /usr/src/linux -print |
afio-o ...' will not contain the ownership and permissions of the
/usr and /usr/src directories. If these directories are missing when
restoring the archive, afio will recreate them with some default owner‐
ship and permissions.
Afio can not restore time stamps on symlinks. Also, on operating sys‐
tems without an lchown(2) system call, afio can not restore owner/group
information on symlinks. (Linux has lchown since kernel version
2.1.86.)
Afio tries to restore modification time stamps of directories in the
archive correctly. However, if it exits prematurely, then the modifi‐
cation times will not be restored correctly.
A restore using decompression will fail if the gzip binary used by afio
is overwritten, by afio or by another program, during the restore. The
restore will also fail if any shared libraries needed to start gzip are
overwritten during the restore. afio should not normally be used to
overwrite the system files on a running system. If it is used in this
way, a flag like -Y /bin/gzip can often be added to prevent failure.
The -r option verifies the file contents of the files in the archive
against the files on the filesystem, but does not cross-check details
like permission bits on files, nor does it cross-check that archived
directories or other non-file entities still exist on the filesystem.
There are several problems with archiving hard links. 1) Due to inter‐
nal limitations, files with hard links cannot be stored in compressed
form, unless the -l or -U options are used which force each hard linked
file to be stored separately. 2) Archives which contain hard links and
which were made with older (pre-2.4.8) versions of afio or with cpio
can not always be correctly unpacked. This is really a problem in the
archives and not in the current version of afio. The risk of incorrect
unpacking will be greater if the number of files or hard links in the
archives is larger. 3) In a selective restore, if the selection predi‐
cates do not select the first copy of a file with archive-internal hard
links, then all subsequent copies, if selected, will not be correctly
restored. 4) Unless the -4 option is used, the inode number fields in
the archive headers for files with hard links of the archive will some‐
times not contain the actual (least significant 16 bits of) the inode
number of the original file.
Some Linux kernels no not allow one to create a hard link to a symbolic
link. afio will try to re-create such hard links when unpacking an ar‐
chive, but might fail due to kernel restrictions.
Due to internal limitations of afio, the use of the -U option forces
the writing of file content with each hard linked file, rather than
only once for every set of hard linked files.
When it is run without super-user priviliges, afio is not able to
unpack a file into a directory for which it has no write permissions,
even if it just created that directory itself. This can be a problem
when trying to restore directory structures created by some source code
control tools like RCS.
When block or character device files are packed into an archive on one
operating system (e.g. Linux) and unpacked on another operating system,
which uses different sizes for the major and minor device number data
types (e.g. Solaris), the major and minor numbers of the device files
will not be restored correctly. This can be a problem if the operating
systems share a cross-mounted filesystem. A workaround is to use
tar(1) for the device files.
EXAMPLES
Create an archive with compressed files:
find .... | afio-o -v -Z /dev/fd0H1440
Install (unpack) an archive with compressed files:
afio-i -v -Z achive
Install (unpack) an archive with compressed files, protecting newer
existing files:
afio-i -v -Z -n achive
Create an archive with compressed files on floppy disks:
find .... | afio-o -v -s 1440k -F -Z /dev/fd0H1440
Create an archive with all file contents encrypted by pgp:
export PGPPASSFD=3
find .... | afio-ovz -Z -U -P pgp -Q -fc -Q +verbose=0 -3 3 archive
3<passphrasefile
Create an archive on recordable CDs using the cdrecord utility to write
each CD:
find .... | afio-o -b 2048 -s325000x -v '!cdrecord .... -'
Extract a single named file from an archive on /dev/tape:
afio-i -v -Z -y /home/me/thedir/thefile /dev/tape
(If these do not exist yet, afio will also create the enclosing direc‐
tories home/me/myfiledir under current working directory.)
Extract files matching a pattern from an archive on /dev/tape:
afio-i -v -Z -y '/home/me/*' /dev/tape
(If these do not exist yet, afio will also create the enclosing direc‐
tories home/me under current working directory.)
If your filesystem cannot handle files larger than 2GB, but you want to
make an archive on that filesystem that is larger than 2GB, you use the
following trick to split the archive into multiple files of each 1 GB:
find /home | afio-o ... - | split -b1024m - archive.
the files will be called archive.aa, archive.ab, etc. You can restore
the whole archive using:
cat archive.* | afio-i ... -
The wildcard expansion by the shell will ensure that cat will read the
parts in the right (alphabetic) order.
SEE ALSOcpio(1), find(1), tar(1), compress(1), gzip(1).
WEB SITE AND INTERNET RESOURCES
There is no official web site for afio. However, the current main‐
tainer does post information on alpha, beta, and production releases at
http://freshmeat.net/projects/afio/
Production releases are announced on the comp.os.linux.announce news‐
group.
The current maintainer also tries to make sure that the latest produc‐
tion release is at the FTP site
ibiblio.org /pub/Linux/system/backup
(This FTP information is correct until they rename the site or directo‐
ries again.)
The Debian project maintains a binary distribution package of afio, see
http://packages.debian.org
Bug reporting on the Debian package can be done to the Debian project,
bugs with a scope beyond Debian will usually also reach the current
afio maintainer mentioned below.
For general bug reporting, patches, suggestions and status inquiries,
please e-mail the current afio maintainer. Though the maintenance and
distribution effort of afio is Linux-centered, correspondence with
respect to the use of afio on other operating systems is also welcome.
When mailing the maintainer, please use the word `afio' somewhere in
the subject line, this lowers the chance that your mail will get acci‐
dentally deleted. The current maintainer e-mail address is:
koen@hep.caltech.edu
(alternative e-mail if that does not work: k.holtman@chello.nl)
AUTHORS
Mark Brukhartz ..!ihnp4!laidbak!mdb
Jeff Buhrt uunet!sawmill!prslnk!buhrt
Dave Gymer dgymer@gdcarc.co.uk
Andrew Stevens as@prg.oxford.ac.uk
Koen Holtman (current maintainer) koen@hep.caltech.edu
Anders Baekgaard ab@osiris.cpk.auc.dk
Too many other people to list here have contributed code, patches,
ideas, and bug reports. Many of these are mentioned in the HISTORY
file that is included with the sources.
AFIO(1)
