Provided by: afio_2.5-5_i386 bug

NAME

       afio - manipulate archives and files

SYNOPSIS

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

DESCRIPTION

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

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

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

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

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

       With -r, reads archive and verifies it against the filesystem.  This is
       useful for verifying tape archives.

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

       Removes  leading  slashes  from pathnames, making all paths relative to
       the current directory.  This is a safety feature to prevent inadvertent
       overwriting  of  system  files  when  doing restores.  To suppress this
       safety feature, the -A option must be used while  writing  an  archive,
       but  also  when  reading  (installing),  verifying,  and  cataloging an
       existing archive.

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

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

ARCHIVE PORTABILITY

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

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

       Unfortunately, the ASCII cpio  archive  format  cannot  represent  some
       files  and  file  properties  that  can  be  present  in  a modern UNIX
       filesystem.  If afio creates an archive with such things, then it  uses
       an   afio-specific  'large  ASCII'  header  for  the  files  concerned.
       Archives with large ASCII headers cannot be unpacked completely by cpio
       or afio versions before 2.4.8.

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

          o  A file has a size larger than 2 GB

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

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

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

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

ARCHIVE FILE FORMAT

       An afio archive file has a simple format. The  archive  starts  with  a
       file  header  for the first file, followed by the contents of the first
       file (which will either be the exact  contents  byte-for-byte,  or  the
       exact  contents in some compressed format).  The data of the first file
       is immediately followed by the file header of the second file,  and  so
       on.   At  the  end, there is a special `end of archive' header, usually
       followed by some padding bytes.

       A multi-volume afio archive is simply a normal archive  split  up  into
       multiple  parts.  There are no special volume-level data headers.  This
       means that that volumes can be split and merged by  external  programs,
       as  long  as the data stays in the correct order.  It also implies that
       the contents of a single file can cross volume  boundaries.   Selective
       restores of files at known volume locations can be done by feeding only
       the needed volumes to afio, provided that the -k option is used.

       The contents of hard linked files are (unless the -l  option  is  used)
       only  stored  once  in  the  archive.  The file headers for the second,
       third, and later occurence of a hard linked file  have  no  data  after
       them.   This makes selective restores of hard-liked files difficult: if
       later occurences are to be  restored  correctly,  the  first  occurence
       always needs to be selected too.

OPTIONS

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

       -a           Preserve  the last access times (atimes) of the files read
                    when making or verifying an  archive.   Warning:  if  this
                    option  is  used,  afio will change the last inode changed
                    times (ctimes) of these files.  Thus, this  option  cannot
                    be  used  together  with an incremental backup scheme that
                    relies on the ctimes being preserved.

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

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

       -d           Don't create missing directories.

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

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

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

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

       -j           Don't  generate  sparse  filesystem  blocks  on  restoring
                    files.   By default, afio creates sparse filesystem blocks
                    (with lseek(2)) when possible when restoring files from an
                    archive,   but  not  if  these  files  were  stored  in  a
                    compressed form.   Unless stored  in  a  compressed  form,
                    sparse  files are not archived efficiently: they will take
                    space equal to the full file  length.   (The  sparse  file
                    handling  in  afio  does  not  make much sense except in a
                    historical way.)

       -k           Rather than complaining about unrecognizable  input,  skip
                    unreadable   data   (or  partial  file  contents)  at  the
                    beginning of the archive file being read, and  search  for
                    the  next  valid archive header.  This option is needed to
                    deal with certain types of backup  media  damage.   It  is
                    also  useful  to  support  quick  selective  restores from
                    multi-volume archives, or from searchable  block  devices,
                    if  the  volume  or location of the file to be restored is
                    known in advance (see the -B option).  If, for example,  a
                    selective  restore  is  done  with  the fourth volume of a
                    multi-volume afio archive, then the -k option needs to  be
                    used,  else afio will complain about the input not being a
                    well-formed archive.

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

                    With -t, report hard links.

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

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

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

       -s size      Restrict each portion of a multi-volume  archive  to  size
                    characters.  This option recognizes the same size suffices
                    as -b.  Also, the suffix x denotes a multiple  of  the  -b
                    block  size  (and must follow any -b specification).  size
                    can be a single size or a  comma-seperated list of  sizes,
                    for example '2m,5m,8m', to specify different sizes for the
                    subsequent volumes.  If there are more volumes than sizes,
                    the last specified size is used for all remaining volumes.
                    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
                    processed.  When used with -t, gives an ls -l style report
                    (including link information) to stdout instead.  When used
                    twice (-vv) with -o, gives an ls -l style report to stdout
                    while writing the archive. (But this use of -vv  will  not
                    work if the archive is also being written to stdout.)

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

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

       -y pattern   Restrict  processing  of  files  to  names  matching shell
                    wildcard pattern pattern.  Use this  flag  once  for  each
                    pattern  to be recognized.  With the possible exception of
                    the presence of a leading slash, the complete file name as
                    appearing  in the archive table-of-contents must match the
                    pattern, for example the file name 'etc/passwd' is matched
                    by  the pattern '*passwd' but NOT by the pattern 'passwd'.
                    See `man 7 glob' for more information  on  shell  wildcard
                    pattern matching.  The only difference with shell wildcard
                    pattern matching is that in afio the wildcards  will  also
                    match  '/'  characters  in  file  names.   For example the
                    pattern   '/usr/src/*'   will   match   the   file    name
                    '/usr/src/linux/Makefile',   and   any   other  file  name
                    starting with '/usr/src'. Unless the -S option  is  given,
                    any  leading  slash  in  the  pattern  or  the filename is
                    ignored  when  matching,  e.g.   /etc/passwd  will   match
                    etc/passwd.  Use -Y to supply patterns which are not to be
                    processed.  -Y overrides -y if a  filename  matches  both.
                    See  also  -w and -W.   Note: if afio was compiled without
                    using  the  GNU  fnmatch  library,  then  the  full  shell
                    wildcard  pattern  syntax  cannot  be  used,  and matching
                    support is limited to patterns which are  a  full  literal
                    file name and patterns which end in '*'.

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

       -A           Do  not  turn  absolute paths into relative paths. That is
                    don't remove the leading slash.  Applies to the path names
                    written in an archive, but also to the path names read out
                    of  an  archive  during  read   (install),   verify,   and
                    cataloging operations.

       -B           If  the  -v  option is used, prints the byte offset of the
                    start of each file in the archive.  If your tape drive can
                    start reading at any position in an archive, the output of
                    -B can be useful for doing quick selective restores.

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

       -E [+]filename | -E CS | -E CI
                    While  creating an archive with compressed files using the
                    -Z option, disable (attempts  at)  compression  for  files
                    with  particular  extensions.   This option can be used to
                    speed up the creation of the archive, by making afio avoid
                    trying  to  use gzip on files that contain compressed data
                    already.  By default, if no specific -E option  is  given,
                    all  files  with  the  extensions .Z .z .gz .bz2 .tgz .arc
                    .zip .rar .lzh .lha .uc2 .tpz .taz  .tgz  .rpm  .zoo  .deb
                    .gif  .jpeg  .jpg .tif .tiff .png .pdf .arj .avi .bgb .cab
                    .cpn .hqx .jar .mp3 .mpg .mpq .pic .pkz .psn .sit .ogg and
                    .smk  will  not  be compressed.  Also by default, the file
                    extension matching is case-insensitive (to  do  the  right
                    thing  with  respect  to  MS-DOS  based filesystems).  The
                    -E filename form of this option will replace  the  default
                    list  of  file  extensions  by  reading a new list of file
                    extensions,  separated  by  whitespace,   from   filename.
                    filename  may  contain  comments  preceded  by  a  #.  The
                    extensions in filename should usually  all  start  with  a
                    dot, but they do not need to start with a dot, for example
                    the extension 'tz' will match the file name 'hertz'.   The
                    -E +filename form (with a + sign in front of filename) can
                    be used to specify extensions in addition to the  built-in
                    default list, instead of replacing the whole default list.
                    To make extension matching case-sensitive, add the special
                    option  form  -E  CS  to the command line.  The form -E CI
                    invokes the (default)  case-insensitive  comparison.   See
                    also  the  -6  option,  which  offers an additional way to
                    suppress compression.

       -F           This is a floppy disk,  -s  is  required.   Causes  floppy
                    writing  in  O_SYNC mode under Linux.  With kernel version
                    1.1.54 and above, this allows afio to detect  some  floppy
                    errors  while  writing.  Uses shared memory if compiled in
                    otherwise mallocs as needed (a 3b1 will  not  be  able  to
                    malloc  the needed memory w/o shared memory), afio assumes
                    either way you can malloc/shmalloc a chunck of memory  the
                    size  of one disk. Examples: 795k: 3.5" (720k drive), 316k
                    (360k drive)
                    At the end of each disk this message occurs:
                     Ready for disk [#] on [output]
                     (remove the disk when the light goes out)
                     Type "go" (or "GO") when ready to proceed
                     (or "quit" to abort):

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

       -H promptscript
                    Specify a script to run, in  stead  of  using  the  normal
                    prompt,  before  advancing to the next achive volume.  The
                    script will be run with the next  volume  number,  archive
                    specification,  and  the  reason  for changing to the next
                    volume as arguments.  The script should exit with 0 for OK
                    and 1 for abort, other exit codes will be treated as fatal
                    errors.   afio  executes  the   script   by   taking   the
                    promptscript  string,  appending  the  arguments, and then
                    calling the shell to execute the resulting  command  line.
                    This  means  that  a  general-purpose prompt script can be
                    supplied with additional arguments, via the  afio  command
                    line,    by    using   a   -H   option   value   like   -H
                    "generic_promptscript additional_arg_1 additional_arg_2".

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

       -K           Verify  the  output  against what is in the memory copy of
                    the disk (-F required).  If the writing or verifying fails
                    the following menu pops up
                        [Writing/Verify] of disk [disk #] has FAILED!
                         Enter 1 to RETRY this disk
                         Enter 2 to REFORMAT this disk before a RETRY

                         Enter quit to ABORT this backup
                    Currently,  afio  will  not process the answers 1 and 2 in
                    the right way.  The menu above is only useful in  that  it
                    signifies that something is wrong.

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

       -M size      Specifies the maximum amount of  memory  to  use  for  the
                    temporary storage of compression results when using the -Z
                    option. The default  is  -M  2m  (2  megabytes).   If  the
                    compressed  version  of  a file is larger than this (or if
                    afio runs out of virtual memory), gzip(1) is run twice  of
                    the  file,  the  first time to determine the length of the
                    result, the second time to get the compressed data itself.

       -P progname  Use the program progname instead of the  standard  gzip(1)
                    for  compression and decompression with the -Z option. For
                    example, use the options -Z -P bzip2 to write and  install
                    archives using bzip2(1) compression.  If progname does not
                    have command line options (-c, -d, and -<number>)  in  the
                    style  of gzip(1) then the -Q option can be used to supply
                    the right options.  See also the -Q, -U and -3 options.

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

       -R Disk format command string
                    This  is  the  command  that  is  run  when you enter 2 to
                    reformat the disk after  a  failed  verify.   The  default
                    (fdformat   /dev/fd0H1440)  can  be  changed  to  a  given
                    system's default by editing the Makefile.   You  are  also
                    prompted   for   formatting  whenever  a  disk  change  is
                    requested.

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

       -T threshold Only  compress  a  file  when  using  the -Z option if its
                    length is at least threshold.  The default is -T 0k.  This
                    is  useful  if  you  have  a slow machine or a fast backup
                    medium.  Specifying -T 3k typically halves the  number  of
                    invocations  of gzip(1), saving some 30% computation time,
                    while creating an archive that is  only  5%  longer.   The
                    combination  -T  8k  -G  1 typically saves 70% computation
                    time  and  gives  a  20%  size   increase.    The   latter
                    combination  may  be a good alternative to not using -Z at
                    all.  These figures of course depend heavily on  the  kind
                    of  files  in  the  archive  and the processor - i/o speed
                    ratio on your machine.  See also the -2 option.

       -U           If used with the -Z option, forces compressed versions  to
                    be  stored  of  all files, even if the compressed versions
                    are bigger than the original  versions,  and  disregarding
                    any  (default)  values  of the -T and -2 options.  This is
                    useful when the -P and -Q options are used to replace  the
                    compression  program  gzip  with  an encryption program in
                    order to make an archive with  encrypted  files.   Due  to
                    internal  limitations of afio, use of this flag forces the
                    writing of file content with each hard linked file, rather
                    than  only  once  for  every  set  of  hard  linked files.
                    WARNING: use of the -U option will also cause  compression
                    (or  whatever  operation the -P option indicates) on files
                    larger than 2 GB, if these are present in the input.   Not
                    all  compression  programs  might  handle  such huge files
                    correctly (recent Linux versions of gzip, bzip2,  and  gpg
                    have  all  been tested and seem to work OK). If your setup
                    is obscure, some testing might be warranted.

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

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

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

       -0           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. When used with option -t the output
                    filenames will be separated by nullbytes. If a patternfile
                    is used with  -w  or  -W  it  has  also  to  use  '\0'  as
                    delimiter.

       -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".   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 succesfully opened. This  unusual  warning  situation
                    can   occur   when   archiving   files  on  Windows  smbfs
                    filesystems -- due to a Windows problem, smbfs files  with
                    non-ASCII  characters  in  their  names  can  sometimes be
                    opened but not read.  When the -Z option is  used,  the  n
                    letter  function is (currently) only implemented for files
                    with sizes smaller than indicated by the -T option, so  in
                    that  case the -T option is also needed for this letter to
                    have any effect.

       -2 maximum-file-size-to-compress
                    Do not compress any files which are larger than this  size
                    when  making  a compressed archive with the -Z option. The
                    default value is -2 200m  (200  Megabytes).  This  maximum
                    size  cutoff  lowers  the  risk  that a major portion of a
                    large file  will  be  irrecoverable  due  to  small  media
                    errors.    If  a  media  error occurs while reading a file
                    that afio has stored in a compressed form, then  afio  and
                    gzip  will  not be able to restore the entire remainder of
                    that file.  This is usually an acceptable risk  for  small
                    files.  However for very large files the risk of loosing a
                    large amount of data because of this effect  will  usually
                    be  too big.  The special case -2 0 eliminates any maximum
                    size cutoff.

       -3 filedescriptor-nr
                    Rewind   the   filedescriptor    before    invoking    the
                    (un)compression  program  if  using the -Z option. This is
                    useful when the -P and -Q options are used to replace  the
                    compression  program  gzip  with  some types of encryption
                    programs  in  order  to  make  or  read  an  archive  with
                    encrypted  files.   The  rewinding  is needed to interface
                    correctly with some encryption programs  that  read  their
                    key  from  an open filedescriptor.  If the -P program name
                    matches 'pgp' or 'gpg', then the -3 option must be used to
                    avoid afio(1) reporting an error.  Use the special case -3
                    0 to supress the error message without rewinding any  file
                    descriptor.   The  -3  0  option  may  also  be  needed to
                    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
                    ARCHIVE PORTABILITY section above for more information  on
                    the use of `large ASCII' file headers.

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

       -7           Disable globbing so that it is possible to use -W or -w to
                    specify a list of exact filenames to exclude or extract.

       -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,
             respectively.  This disables multi-volume archive handling.

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

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

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

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

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

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

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

CONTROL FILES

       Afio archives can  contain  so-called  control  files.   Unlike  normal
       archive  entries,  a control file in not unpacked to the filesystem.  A
       control file has a label and some data.  When afio encounters a control
       file in the archive it is reading, it will feed the label and data to a
       so-called control script.  The control script is supplied by the  user.
       It  can perform special actions based on the label and data it receives
       from afio.

       Control file labels.  The control file mechanism can be used  for  many
       things.   Examples are putting archive descriptions at the beginning of
       the archive and embedding lists of files to move before  unpacking  the
       rest or the archive.

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

          programname.kindofdata

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

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

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

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

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

           //--sourcename label

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

       A control file will show up as

          //--CONTROL_FILE/label

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

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

         -D controlscript

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

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

       An example of a control script is

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

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

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
       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) 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
       ownership and permissions.

       Afio  can  not  restore  time  stamps  on symlinks.  Also, on operating
       systems  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
       modification 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
       internal  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  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.   afio  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  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
       directories 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
       directories 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 ALSO

       cpio(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
       maintainer  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
       newsgroup.
       The current  maintainer  also  tries  to  make  sure  that  the  latest
       production release is at the FTP site
        ibiblio.org /pub/Linux/system/backup
       (This  FTP  information  is  correct  until  they  rename  the  site or
       directories 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
       accidentally 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)