afio - manipulate archives and files
| afio -o
] archive : write (create) archive
] archive : install (unpack) archive
] archive : list table-of-contents of archive
] archive : verify archive against filesystem
] directory [ ... ] : copy files
manipulates groups of files, copying them within the (collective)
filesystem or between the filesystem and an afio
, reads pathnames from the standard input and writes an
, reads an archive
and writes a table-of-contents to the
, installs the contents of an archive
relative to the
, reads pathnames from the standard input and copies the files to
. Cannot be combined with the -Z
, 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
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
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
compressed archives much more robust than
Supports multi-volume archives during interactive operation (i.e., when
is accessible and SIGINT
is not being ignored).
- -@ 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.
- 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
- 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).
- Spawn a child process to actually write to the archive;
provides a clumsy form of double-buffering. Requires -s for
multi-volume archive support.
- 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
- Follow symbolic links, treating them as ordinary files and
- 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.)
- 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
- With -o, write file contents with each hard link.
With -t, report hard links.
With -p, attempt to link files rather than copying them.
- Mark output files with a common current timestamp (rather
than with input file modification times).
- Protect newer existing files (comparing file modification
- -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
- Report files with unseen links.
- 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.
- Retain file ownership and setuid/setgid permissions. This
is the default for the super-user; he may use -X to override
- -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 '*'.
- Print execution statistics. This is meant for human
consumption; use by other programs is officially discouraged.
- 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.
- 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
- 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.
- 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
- -H promptscript
- Specify a script to run, in stead of using the normal
prompt, before advancing to the next archive 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
- Try to continue after a media write error when doing a
backup (normal behavior is to abort with a fatal error).
- Verify the output against what is in the memory copy of the
disk (-F required). If the writing or verifying fails the following menu
[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
- -L Log_file_path
- Specify the name of the file to log errors and the final
- -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
- -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
- Do not ignore a leading slash in the pattern or the file
name when matching -y and -Y patterns. See also
- -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
- 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.
- 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.
- 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
- -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
suppress 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.
- (Deprecated, the intended effect of this option is now
archived 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.
- 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
- 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*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*4. A second use of -7 toggles the matching
for subsequently occurring -y, -Y, -w, and -W
back to shell wildcard pattern matching.
- Do not round down any -s volume sizes to the nearest
-b block size. See the -s option.
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
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
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
When creating an archive, the `large ASCII' header is used by afio
cover the following situations:
- A file has a size larger than 2 GB
- The archive contains more than 64K files which have hard
- A file, directory, or special file has a UID or GID value
larger than 65535.
option can be used to always preserve cpio
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
2.4.4 and later.
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
occurrence of a hard linked file have no data after them. This makes selective
restores of hard-liked files difficult: if later occurrences are to be
restored correctly, the first occurrence always needs to be selected too.
Special-case archive names:
- Specify - to read or write the standard input or
output, respectively. This disables multi-volume archive handling.
- 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.
- 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
- 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
- Anything else specifies a local file or device. An output
file will be created if it does not already exist.
- 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 %
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
archives can contain so-called control files. Unlike normal archive
entries, a control file in not unpacked to the filesystem. A control file has
and some data
. When afio
encounters a control
file in the archive it is reading, it will feed the label
to a so-called control script. The control script is supplied by
the user. It can perform special actions based on the label
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
To distinguish between different uses, the label
of a control file should
indicate the program that made the control file and the purpose of the control
file data. It should have the form
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
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:
Here, the //-- sequence signals that a control file is to be made,
is the path to a file containing the control file data, and
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
in an archive listing, where label
is the control file label.
A control script is supplied to afio with the
command line option. The controlscript
must be an executable program. The
script is run whenever afio
encounters a control file while doing a
operation. Afio will supply the control file
as an argument to the script. The script should read the control
from its standard input. If the script exits with a non-zero
exit status, afio
will issue a warning message.
If a control 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
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:
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
echo Ignoring unknown control file.
cat - >/dev/null
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
is the control file label.
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) uses 10
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
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").
code for handling floppies (-F
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
The Linux floppy drivers below kernel version 1.1.54 do not allow afio
find out about floppy write errors while writing. If you are running 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 messages, or by switching
on the verify (-K
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
directories. If these directories are missing when restoring
the archive, afio
will recreate them with some default ownership and
Afio can not restore time stamps on symlinks. Also, on operating systems without
(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 modification times will
not be restored correctly.
A restore using decompression will fail if the gzip
binary used by
is overwritten, by afio
or by another program, during the
restore. The restore will also fail if any shared libraries needed to start
are overwritten during the restore. afio
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
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 internal
limitations, files with hard links cannot be stored in compressed form, unless
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
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 predicates 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 sometimes 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.
will try to re-create such hard links when unpacking an archive,
but might fail due to kernel restrictions.
Due to internal limitations of afio
, the use of the -U
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 privileges, 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
Create an archive with compressed files:
find .... | afio -o -v -Z /dev/fd0H1440
Install (unpack) an archive with compressed files:
afio -i -v -Z archive
Install (unpack) an archive with compressed files, protecting newer existing
afio -i -v -Z -n archive
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:
find .... | afio -ovz -Z -U -P pgp -Q -fc -Q +verbose=0 -3 3 archive
Create an archive on recordable CDs using the cdrecord
utility to write
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
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
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
cat archive.* | afio -i ... -
The wildcard expansion by the shell will ensure that cat
will read the
parts in the right (alphabetic) order.
cpio(1), find(1), tar(1), compress(1), gzip(1).
The afio home page is at http://members.chello.nl/~k.holtman/afio.html
See the home page for information on submitting questions, bug reports, patches,
Koen Holtman (current maintainer) email@example.com
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.