'br $Header: /u/buhrt/src/afio/RCS/afio.1,v 2.3 1991/09/25 20:08:33 buhrt Exp $
.TH AFIO 1
.SH NAME
afio \- manipulate archives and files
.SH SYNOPSIS
.B ...
| 
.B afio -o
[
.I options
] archive  : write archive
.br
.B afio -i 
[
.I options
] archive  : install archive
.br
.B afio -t 
[
.I options
] archive  : list table-of-contents of archive
.br
.B afio -r
[
.I options
] archive  : verify archive against filesystem
.br
.B afio -p
[
.I options
] directory [ ... ] : copy files
.PP
.SH DESCRIPTION
.I Afio
manipulates groups of files, copying them within the (collective)
filesystem or between the filesystem and an
.I afio
archive. Note that
.I afio
archives are portable, as they contain only ASCII-formatted
header information. They are also compatible with ASCII
.IR cpio (1)
archives (ala
.IR "cpio \-c" ,
for GNU 
.IR cpio (1)
also
.IR "cpio -H odc" ).  
However, archives made with using
.BR \-4
option are
.BR not
portable.
.PP
With
.BR \-o ,
reads pathnames from the standard input
and writes an
.IR archive .
.PP
With
.BR \-t ,
reads an
.I archive
and writes a table-of-contents to the standard output.
.PP
With
.BR \-i ,
installs the contents of an
.I archive
relative to the working directory.
.PP
With
.BR \-p ,
reads pathnames from the standard input
and copies the files to each
.IR directory .
Cannot be combined with the
.B \-Z
option.
.PP
With
.BR \-r ,
reads
.IR archive
and verifies it against the filesystem.  This is useful for verifying
tape archives.
.PP
Creates missing directories as necessary, with permissions
to match their parents.
.PP
Removes leading slashes from pathnames when reading, writing, and cataloging
an archive, unless instructed not to.
.PP
Supports multi-volume archives during interactive operation
(i.e., when
.I /dev/tty
is accessible and
.I SIGINT
is not being ignored).
.PP
.SH OPTIONS
.TP 13
.BI "-@ " address
Send email to
.I address
when a volume change (tape change, floppy change) is needed, and also when
the entire operation is complete.  Uses
.IR sendmail (1)
to send the mail.
.TP
.B -a
Preserve the last access times (atimes) of the files read when
making or verifying an archive.
.B Warning:
if this option is used, 
.I afio
will change the last inode changed times (ctimes) of these files.
Thus, this option cannot be used together with an incremental backup
scheme that relies on the ctimes being preserved.
.TP
.BI \-b "\ size"
Read or write
.IR size -character
archive blocks.
Suffices of
.BR b ,
.BR k ,
.B m
and
.B g
denote multiples of
.IR 512 ,
.IR kilobytes ,
.IR megabytes
and
.IR gigabytes ,
respectively.
Defaults to
.I 5120
for compatibility with
.IR cpio (1).
In some cases, notably when using
.I ftape
with some tape drives,
.B \-b 10k
is needed for compatibility.  Note that 
.B \-b 10k
is the default block size used by 
.IR tar (1),
so it is usually a good choice if the tape setup is known to work
with 
.IR tar (1).
.TP
.BI \-c "\ count"
Buffer
.I count
archive blocks between I/O operations. A large
.I count
is recommended for efficient use with streaming magnetic tape drives, in
order to reduce the number of tape stops and restarts.
.TP
.B \-d
Don't create missing directories.
.TP
.BI \-e "\ bound"
Pad the archive to a multiple of
.I bound
characters.
Recognizes the same suffices as
.BR \-s .
Defaults to
.I 1x\^
(the
.B \-b
block size)
for compatibility with
.IR cpio (1).
.TP
.B \-f
Spawn a child process to actually write to the archive; provides
a clumsy form of double-buffering.
Requires
.B \-s
for multi-volume archive support.
.TP
.B \-g
Change to input file directories. Avoids quadratic filesystem
behavior with long similar pathnames. Requires all absolute
pathnames, including those for the
.B \-o
.I archive
and the
.B \-p
.IR directories .
.TP
.B \-h
Follow symbolic links, treating them as ordinary files and directories.
.TP
.B \-j
Don't generate sparse filesystem blocks on restoring files.
By default, 
.I afio 
creates sparse filesystem blocks (with
.IR lseek (2))
when possible when restoring files from an archive, 
but not if these files were stored in a compressed form.   Unless stored in
a compressed form, sparse files are not archived efficiently: 
they will take space equal to the full file length.  
(The sparse file handling in
.I afio
does not make much sense except in a historical way.)
.TP
.B \-k
Skip corrupt data at the
.I beginning
of an archive (rather
than complaining about unrecognizable input).
.TP
.B \-l
With
.BR \-o ,
write file contents with each hard link.
.sp
With
.BR \-t ,
report hard links.
.sp
With
.BR \-p ,
attempt to link files rather than copying them.
.TP
.B \-m
Mark output files with a common current timestamp
(rather than with input file modification times).
.TP
.B \-n
Protect newer existing files (comparing file modification times).
.TP
.BI \-s "\ size"
Restrict each portion of a multi-volume archive to
.I size
characters. This
option recognizes the same size suffices as
.BR \-b .
Also, the suffix
.B x
denotes a multiple of the
.B \-b
block size (and must follow any
.B \-b
specification).
.I size
can be a single size or a  comma-seperated list of sizes,
for example '2m,5m,8m', to specify different sizes for the
subsequent volumes.  If there are more volumes than sizes, the last
specified size is used for all remaining volumes.
This option is useful
with finite-length devices which do not return short
counts at end of media (sigh); output to magnetic tape typically
falls into this category.   When an archive is being read or written, using
.B \-s
causes
.I afio
to prompt for the next volume if the specified volume length is reached.
The 
.B \-s
option will also cause
.I afio
to prompt if there is a premature EOF while reading the input.
The special case
.B -s 0
will activate this prompting for the next volume on premature EOF without 
setting a volume length.   
When writing an archive, 
.I afio
will prompt for the next volume on end-of-media, even without
.B -s 0
being supplied, if the device is capable of reporting end-of-media.
If the volume
.I size 
specified is not a multiple of the block size set with the
.B -b
option, then
.I afio(1)
will silently round down the volume size to the nearest multiple of
the block size.  This rounding down can be suppressed using the 
.B -9
option: if
.B -9
is used, 
.I afio(1)
will write a small block of data, smaller than the 
.B -b
size, at the  end of the volume to completely fill it to the  specified 
size.  Some devices are not able to handle such small block writes.
.TP
.B \-u
Report files with unseen links.
.TP
.B \-v
Verbose. Report pathnames as they are processed. With
.BR \-t ,
gives an
.I "ls \-l"
style report (including link information).
.TP
.BI \-w "\ filename"
Treats each line in
.I filename
as an
.B \-y
pattern, see
.BR \-y .
.TP
.B \-x
Retain file ownership and setuid/setgid permissions.
This is the default for the super-user; he may use
.B \-X
to override it.
.TP
.BI \-y "\ pattern"
Restrict processing of files to names matching shell wildcard pattern
.IR pattern .
Use this flag once for each pattern to be recognized.
With the possible exception of the presence of a leading slash, the
complete file name as appearing in the archive table-of-contents must
match the pattern, for example the file name 'etc/passwd' is matched
by the pattern '*passwd' but NOT by the pattern 'passwd'.  See
.B `man 7 glob' 
for more information on shell wildcard pattern matching.
The only difference with shell wildcard pattern matching is that in 
.I afio
the wildcards will also match '/' characters in file
names.  For example the pattern '/usr/src/*' will match the 
file name '/usr/src/linux/Makefile', and any other file name
starting with '/usr/src'. Unless the 
.B -S
option is given, any leading slash in the pattern or the filename is
ignored when matching,
e.g. 
.I /etc/passwd 
will match
.IR etc/passwd .
Use
.B \-Y
to supply patterns which are
.I not
to be processed. 
.B \-Y
overrides
.B \-y
if a filename matches both. 
See also 
.BR \-w\  and\  \-W .
.B Note:
if 
.I afio
was compiled without using the GNU fnmatch library, then the full
shell wildcard pattern syntax cannot be used, 
and matching support is limited to patterns which are a full
literal file name and patterns which end in '*'.
.TP
.B \-z
Print execution statistics. This is meant for human consumption;
use by other programs is officially discouraged.
.TP
.B -A
Do not turn absolute paths into relative paths. That is don't remove
the leading slash.
.TP
.B -B
If the 
.B -v
option is used, prints the byte offset of the start of each file in
the archive.
If your tape drive can start reading at any position in an
archive, the output of 
.B -B
can be useful for doing quick selective restores.
.TP
.BI -D "\ controlscript"
Set the control script name to
.IR controlscript ,
see the section on
.B control files
below.
.TP
.BI -E "\ filename"
Read file extensions, separated by whitespace, from
.IR filename .
Files with these extensions are not to be compressed when using the
.B -Z
option.
.I filename
may contain comments preceded by a #.
If no
.B -E
is given, files with the extensions
.I  .Z .z .gz .bz2 .tgz
.I  .arc .zip .rar .lzh .lha 
.I  .uc2 .tpz .taz .tgz .rpm .zoo .deb
.I  .gif .jpeg .jpg .tif .tiff
and
.I .png
will not be compressed.
.TP
.B -F
This is a floppy disk, 
.B -s
is required.  Causes floppy writing in
.B O_SYNC
mode under Linux.  With kernel version 1.1.54 and above, this allows
.I afio
to detect some floppy errors while writing.
Uses shared memory if compiled in otherwise mallocs as needed (a 3b1
will not be able to malloc the needed memory w/o shared memory),
.I afio
assumes either way you can malloc/shmalloc a chunck of memory
the size of one disk. Examples: 795k: 3.5" (720k drive), 316k (360k drive)
.nf
At the end of each disk this message occurs:
 Ready for disk [#] on [output] 
 (remove the disk when the light goes out)
 Type "go" (or "GO") when ready to proceed
 (or "quit" to abort):
.fi
.TP
.BI \-G "\ factor"
Specifies the 
.IR gzip (1)
compression speed factor, used when compressing files with the 
.B -Z
option.
Factor 1 is the fastest with least compression, 9 is slowest with best
compression.
The default value is 6.  See also the 
.IR gzip (1)
manual page. 
If you have a slow machine or a fast backup medium, you may want to
specify a low value for
.I factor
to speed up the backup.  On large (>200k) files, 
.B -G 1
typically zips twice as fast as 
.BR "-G 6" ,
while still achieving a better result than 
.IR compress "(1)."
The zip speed for small files is mainly determined by the invocation time
of 
.I gzip 
(1), see the 
.B -T
option.
.TP
.BI "-H " promptscript
Specify a script to run, in stead of using the normal prompt, before
advancing to the next achive volume.  The script will be run with the
volume number, archive specification, and  the reason for changing to 
the next volume as arguments.  The script
should exit with 0 for OK and 1 for abort, other exit codes will be
treated as fatal errors.
.TP
.B -J
Try to continue after a media write error when doing a backup (normal
behavior is to abort with a fatal error).
.TP
.B -K
Verify the output against what is in the memory copy of the disk (-F required).
If the writing or verifying fails the following menu pops up
.nf
    [Writing/Verify] of disk [disk #] has FAILED!
	Enter 1 to RETRY this disk
	Enter 2 to REFORMAT this disk before a RETRY

	Enter quit to ABORT this backup
.fi
Currently,
.I afio
will not process the answers 1 and 2 in the right way.  The menu above
is only useful in that it signifies that something is wrong.
.TP
.BI "-L " Log_file_path
Specify the name of the file to log errors and the final totals to.
.TP
.BI \-M "\ size
Specifies the maximum amount of memory to use for the temporary storage of
compression results when using the
.B -Z
option. The default is 
.B -M 2m
(2 megabytes).  If the compressed version of a file is larger than
this (or if 
.I afio 
runs out of virtual memory), 
.IR gzip (1)
is run twice of the file,
the first time to determine the length of the result, the second time
to get the compressed data itself.
.TP
.BI \-P "\ progname"
Use the program 
.I progname
instead of the standard 
.I gzip
for compression and decompression with the
.B -Z
option.  See also the
.BR -Q ,
.B -U
and
.B -3
options.
.TP
.BI \-Q "\ opt"
Pass the option
.I "opt"
to the compression or decompression program used with the
.B -Z
option. For passing multiple options, use
.B -Q 
multiple times.  If no
.B -Q
flag is present, the standard options are passed.  The standard
options are
.B -c -6
when the program is called for compression and 
.B -c -d
when the program is called for decompression.  Use the special case
.B -Q 
""
if no options at all are to be passed to the program.
.TP
.BI -R "\ Disk format command string"
This is the command that is run when you enter 2 to reformat the disk after
a failed verify.
The default (fdformat /dev/fd0H1440) can be changed
to a given system's default by editing the Makefile.
You are also prompted for formatting whenever a disk change
is requested.
.TP
.BI -S
Do not ignore a leading slash in the pattern or the file name when matching 
.B \-y
and
.B -Y
patterns. See also 
.BR -A .
.TP
.BI -T "\ threshold"
Only compress a file when using the
.B -Z
option if its length is at least
.IR threshold .
The default is 
.BR "-T 0k" .
This is useful if you have a slow machine or a fast backup medium.
Specifying 
.B "-T 3k"
typically halves the number of invocations of
.IR gzip (1),
saving some 30% computation time, while creating an archive
that is only 5% longer.  The combination 
.B -T 8k -G 1
typically saves 70% computation time and gives a 20% size increase.
The latter combination may be a good alternative to not using 
.B -Z
at all.  These figures of course depend heavily on the kind of files
in the archive and the processor - i/o speed ratio on your machine.
.TP
.B -U
If used with the 
.B -Z
option, forces compressed versions to be stored of all files, even if
the compressed versions are bigger than the original versions, and 
disregarding any (default) values of the 
.B -T 
and 
.B -2 
options.  This is useful when the 
.B -P
and
.B -Q
options are used to replace the compression program 
.I gzip
with an encryption program in order to make an archive with encrypted files.
Due to internal limitations of 
.IR afio ,
use of this flag forces the writing of file content with each hard
linked file, rather than only once for every set of hard linked files.
.TP
.BI \-W "\ filename"
Treats each line in
.I filename
as an
.B \-Y
pattern, see
.BR \-Y .
.TP
.BI \-Y "\ pattern"
Do 
.I not 
process files whose names match shell wildcard pattern
.IR pattern .
See also 
.BR "\-y " and " -W" .
.TP
.B -Z
Gzip the files on the way out, in, and passing without links
(valid w/ or w/o 
.BR -F "\ or" "\ -K" ),
requires 
.IR gzip (1)
to be
in your path.  See also the
.BR -G ,
.BR -P ,
.BR -Q ,
.BR -T ,
.BR -2 ,
and
.B -3
options.
.TP
.B -0
Assume input filenames to be terminated with a '\\0' instead 
of a '\\n'. When used with 
.IR "find ... -print0" , 
can be used to ensure that any filename can be handled, 
even if it contains a newline.
.TP
.BI \-1 "\ warnings-to-ignore-on-exit"
Control if
.IR afio (1)
should exit with a nonzero code after printing warning messages.
This option is sometimes useful when calling 
.IR afio (1)
from inside a backup script or program. 
.IR afio (1) 
will exit with a nonzero code on encountering 
various 'hard' errors, and also (by default) when it has printed
certain warning messages during execution.
.I warnings-to-ignore-on-exit
is a list of letters which label the warning messages
that should 
.B not
lead to 
.IR afio (1) 
exiting with a nonzero code.
Defined letters are
.I a
for ignoring 
.IR a ll 
possible warnings on exit, and
.I m
for ignoring the warning about 
.IR m issing
files, which will occur when, on
creating an archive, a file whose name was read from the standard
input is not found.  The default is
.BR "-1 m" .
For 
.I afio 
versions 2.4.3 and earlier, the default was
.BR "-1 a" .
For 
.I afio 
versions 2.4.4 and 2.4.5, the default was
.BR "-1 ''" .
.TP
.BI "-2 " maximum-file-size-to-compress
Do not compress any files which
are larger than this size when making a compressed archive
with the
.B -Z
option. The default value is 
.BR "-2 200m"
(200 Megabytes). This maximum size cutoff lowers the risk that a major portion
of a large file
will be irrecoverable due to small media errors.   If a media error occurs
while reading a file that
.I afio
has stored in a compressed form, then
.I afio
and
.I gzip
will not be able to restore the entire remainder of that file. 
This is usually an acceptable risk for small files. However for very 
large files the risk of loosing a large amount of data because
of this effect will usually be too big.  The special case
.B "-2 0"
eliminates any maximum size cutoff.
.TP
.BI "-3 " filedescriptor-nr
Rewind the filedescriptor before invoking the (un)compression program
if using the 
.B -Z 
option. This
is useful when the 
.B -P
and
.B -Q
options are used to replace the compression program 
.I gzip
with some types of encryption programs in order to make or read an archive
with encrypted files.  The rewinding is needed to interface
correctly with some encryption programs that read their key from an open
filedescriptor.  If the
.B -P
program name matches 'pgp' or 'gpg', then the
.B -3
option 
.I must
be used to avoid 
.IR afio (1)
reporting an error.  Use the special case
.B "-3 0"
to supress the error message without rewinding any file descriptor.
The
.B "-3 0"
option may also be needed to sucessfully read back encrypted archives
made with 
.I afio 
version 2.4.5 and older.
.TP
.B -4
Write archive in  the `extended ASCII' format which uses 4-byte
inode numbers.  Archives using the extended ASCII format are
.B not
compatible with any other archiver.  This option should not be used
unless the set of files to be archived contains over 60 thousand hard
links and all set-internal hard links need to be preserved in the
archive.  A complete news spool could be an example of such a set of
files.  For such sets, the standard archive format would not
necessarily perserve all internal hard links (see the BUGS section).
.TP
.B -9
Do not round down any
.B -s
volume sizes to the nearest
.B -b
block size.  See the
.B -s
option.
.PP
.SH NOTES
Special-case archive names:
.RS 3
.TP 3
.B o
Specify
.I \-
to read or write the standard input or output, respectively.
This disables multi-volume archive handling.
.TP
.B o
Prefix a command string to be executed with an exclamation mark
.RI ( ! ).
The command is executed once for each archive volume,
with its standard input or output piped to
.IR afio .
It is expected to produce a zero exit code when all is well.
.TP
.B o
Use
.I system:file
to access an archive in
.I file
on
.IR system .
This is really just a special case of pipelining.
It requires a 4.2BSD-style remote shell
.RI ( rsh (1C))
and a remote copy of
.IR afio .
.TP
.B o
A more elaborate case of the above is
.I [user@]host[%rsh][=afio]:file
where the optional 
.I user@
component specifies the user name on the remote host, the optional
.I %rsh
specifies the (local) name of the remote shell command to use,
and the optional
.I =afio
specifies the name of the remote copy of the afio command.
.TP
.B o
Anything else specifies a local file or device.
An output file will be created if it does not already exist.
.RE
.PP
Recognizes obsolete binary
.IR cpio (1)
archives (including those from machines with reversed byte order),
but cannot write them.
.PP
Recovers from archive corruption by searching for a valid magic
number. This is rather simplistic, but, much like a disassembler,
almost always works.
.PP
Optimizes pathnames with respect to the current and parent
directories. For example, 
.I ./src/sh/../misc/afio.c
becomes
.IR src/misc/afio.c .
.SH CONTROL FILES
.I Afio
archives can contain so-called control files.  Unlike normal archive
entries, a control file in not unpacked to the filesystem.  A control
file has a
.I label
and some
.IR data .
When 
.I afio
encounters a control file in the archive it is reading, it will feed the
.I label
and
.I data
to a so-called control script.  The control script is supplied by
the user.  It can perform special actions based on the
.I label
and
.I data
it receives from 
.IR afio .
.PP
.B Control file labels.
The control file mechanism can be used for many things.  Examples are
putting archive descriptions at the beginning of the archive and
embedding lists of files to move before unpacking the rest or the
archive.
.PP
To distinguish between different uses, the
.I 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
.PP
.nf
   programname.kindofdata
.fi
.PP
where 
.I programname
is the name of the backup program that generated the control file, and
.I kindofdata
is the meaning of the control file data.  Some examples are
.PP
.nf
   tbackup.movelist  tbackup.updatescript
   blebberfiler.archivecontents
   backup_script_of_Joe_User.archivedescription
.fi
.PP
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.
.PP
Control file labels that are intended to be portable between different
backup programs could be defined in the future.
.PP
.B 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:
.PP
.nf
    //--sourcename label
.fi
.PP
Here, the //-- sequence signals that a control file is to be made, 
.I sourcename 
is the path to a file containing the control file data, and
.I label
is the control file label.  The 
.I sourcename 
must be a regular file or a symlink to a regular file.
.PP
A control file will show up as
.PP
.nf
   //--CONTROL_FILE/label
.fi
.PP
in an archive listing, where 
.I label
is the control file label.
.PP
.B Control scripts.
A control script is supplied to afio with the
.PP
.BI "  -D " controlscript
.PP
command line option.  The
.I controlscript
must be an executable program.  The script is
run whenever
.I afio
encounters a control file while doing a
.B -i -t
or
.B -r
operation.  Afio will supply the control file
.I label
as an argument to the script.  The script should read the control file
.I data
from its standard input.  If the script exits with a non-zero exit
status,
.I afio
will issue a warning message.
.PP
If a contol file is encountered and no
.B -D
option is given,
.I afio
will issue a warning message.  To suppress the warning message and
ignore all control scripts,
.B -D 
""
can be used.
.PP
An example of a control script is
.PP
.nf
  #!/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
.fi
.PP
.I Afio
never compresses the control file data when storing it in an archive,
even when the
.B -Z
option is used.  When a control file is encountered by
.I cpio(1)
or an
.I afio
with a version number below 2.4.1, the data will be unpacked to the
filesystem, and named
.I CONTROL_FILE/label
where
.I label
is the control file label.
.SH BUGS
There are too many options.
.PP
Restricts pathnames to 1023 characters, 
and 255 meaningful elements (where each element is a pathname 
component separated by a /).
.PP
Cannot archive of files larger than 2 GB,
even if compiled with large filesystem support.   
(Pre-2.4.7 versions of afio did not deal with this problem gracefully, 
see HISTORY file for details.)
.PP
Does not use the same default block size as 
.IR tar (1).
.IR tar (1)
uses 10 KB, 
.I afio
uses 5 KB by default. Some tape drives only work with a 10 KB block size,
in that case the 
.I afio 
option
.B \-b 10k
is needed to make the tape work.
.PP
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
.IR cpio (1)
compatibility.
.PP
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").
.PP
The
.I afio
code for handling floppies
.RB ( -F 
and 
.BR -f " and " -K 
options) has buggy error handling.   
.I 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
.I afio
completely.
Making backups to floppies should really be done with a more specialised 
backup program that wraps
.IR afio .
.PP
The Linux floppy drivers below kernel version 1.1.54 do not
allow
.I afio
to find out about floppy write errors while writing.  If you
are running a kernel below 1.1.54, 
.I 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
.RB ( -K )
option.
.PP
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.
.PP
An archive created with a command like
.I "'find /usr/src/linux -print | afio -o ...'"
will not contain the ownership and permissions of the 
.I /usr
and
.I /usr/src
directories. If these directories are missing when restoring the archive,
.I afio
will recreate them with some default ownership and permissions.
.PP
Afio will not restore time stamps and owner/group information on symlinks.  
Afio will often change
the time stamp on a directory after having restored it.
.PP
A restore using decompression will fail if the
.I gzip
binary used by
.I afio
is overwritten, by
.I afio
or by another program, during the restore.  The restore will also fail if
any shared libraries needed to start
.I gzip
are overwritten during the restore.
.I 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
.I -Y /bin/gzip
can often be added to prevent failure.
.PP
The 
.B -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.
.PP
There are several problems with archiving hard links.  
1) Due to internal limitations, files with hard links cannot be stored
in compressed form, unless the
.B -l 
or
.B -U
options are used which force each hard linked file to be stored separately.
2) By default,
unless the
.B \-t
option is used when writing an archive, 
.I afio
will store only one copy of each file with hard links in the archive,
and re-create the hard links on unpacking the archive.  However, the
capacity for storing hard links is limited to 64K files which have
hard links.  After processing 64K files with hardlinks (either
pointing inside or outside the set of files to be archived), 
each instance of a  new hard linked file will be stored separately and
separate files will be created when unpacking.  The limitation to 64K
files with hard links is not present when the
.B \-4
option is used. 3) Archives which contain hard links and which were
made with older (pre-2.4.4) versions of
.I afio
or with
.I cpio 
can not always be correctly unpacked.  This is really a problem in the
archives and not in the current version of
.IR afio .
The risk of incorrect unpacking will be greater if the number of files
or hard links in the archives is larger.  Unlike pre-2.4.4 versions of
.I afio
and
.IR cpio ,
the current version contains heuristics which greatly reduce the
risk of incorrect unpacking.  Use of  the current version of
.I afio
for unpacking older archives with hard links is strongly encouraged.
4) 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
.B \-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. 
.PP
Some Linux kernels no not allow one to create a hard link to a symbolic link.
.I afio 
will try to re-create such hard links when unpacking an archive, 
but might fail due to kernel restrictions.
.PP
Due to internal limitations of 
.IR afio ,
the use of the
.B -U
option forces the writing of file content with each hard linked file,
rather than only once for every set of hard linked files.
.PP
When it is run without super-user priviliges, 
.I 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.
.PP
.SH "EXAMPLES"
Create an archive with compressed files:
.br
.I "find .... | afio -o -v -Z /dev/fd0H1440"
.PP
Install (unpack) an archive with compressed files:
.br
.I "afio -i -v -Z achive"
.PP
Install (unpack) an archive with compressed files, protecting newer existing
files:
.br
.I "afio -i -v -Z -n achive"
.PP
Create an archive with compressed files on floppy disks:
.br
.I "find .... | afio -o -v -s 1440k -F -Z /dev/fd0H1440"
.PP
Create an archive with all file contents encrypted by pgp:
.br
.I "export PGPPASSFD=3"
.br
.I "find .... | afio -ovz -Z -U -P pgp -Q -fc -Q +verbose=0 -3 3 archive 3<passphrasefile" 
.PP
Create an archive on recordable CDs using the
.I cdrecord
utility to write each CD:
.br
.I "find .... | afio -o -b 2048 -s325000x -v '!cdrecord .... -'"
.PP
Extract a single named file from an archive on /dev/tape:
.br
.I "afio -i -v -Z -y /home/me/thedir/thefile /dev/tape"
.br
(If these do not exist yet, 
.I afio 
will also create the enclosing directories 
.I "home/me/myfiledir" 
under current working directory.)
.PP
Extract files matching a pattern from an archive on /dev/tape:
.br
.I afio -i -v -Z -y '/home/me/*' /dev/tape
.br
(If these do not exist yet, 
.I afio 
will also create the enclosing directories 
.I "home/me" 
under current working directory.)
.PP
.SH "SEE ALSO"
cpio(1), find(1), tar(1), compress(1), gzip(1).
.SH AUTHORS
Mark Brukhartz 
.I "..!ihnp4!laidbak!mdb"
.br
Jeff Buhrt 
.I "uunet!sawmill!prslnk!buhrt"
.br
Dave Gymer 
.I dgymer@gdcarc.co.uk
.br
Andrew Stevens 
.I as@prg.oxford.ac.uk
.br
Koen Holtman (current maintainer)
.I koen@hep.caltech.edu
.br
Anders Baekgaard
.I ab@osiris.cpk.auc.dk
.