afio

AFIO(1)                     General Commands Manual                    AFIO(1)



NAME
       afio - manipulate archives and files

SYNOPSIS
       ...  | afio -o [ options ] archive  : write archive
       afio -i [ options ] archive  : install 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

       Frequently used options:
       -v -Z -F -K -n
       -s volsize -b blocksize -y pattern -Y pattern


DESCRIPTION
       Afio manipulates groups of files, copying them within the (collective)
       filesystem or between the filesystem and an afio archive. Note that
       afio archives are portable, as they contain only ASCII-formatted header
       information. They are also compatible with ASCII cpio(1) archives (ala
       cpio -c, for GNU cpio(1) also cpio -H odc).

       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.

       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.

       Generates sparse filesystem blocks (with lseek(2)) when possible.

       Removes leading slashes from pathnames when reading, writing, and
       cataloging an archive, unless instructed not to.

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

OPTIONS
       -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 and m denote multiples of 512, 1024 and 1048576,
                    respectively.  Defaults to 5120 for compatibility with
                    cpio(1).

       -c count     Buffer count archive blocks between I/O operations. A
                    large count is recommended with streaming magnetic tape
                    drives.

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

       -k           Skip corrupt data at the beginning of an archive (rather
                    than complaining about unrecognizable input).

       -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 limit     Restrict each portion of a multi-volume archive to limit
                    characters.  Recognizes the same suffices as -b.  Also,
                    the suffix x denotes a multiple of the -b block size (and
                    must follow any -b specification).  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, using -s
                    causes afio to prompt for the next disk if the specified
                    volume length is reached.  The -s 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 disk on EOF without setting a volume length.

       -u           Report files with unseen links.

       -v           Verbose. Report pathnames as they are processed. With -t,
                    gives an ls -l style report (including link information).

       -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 archive read to names matching
                    shell pattern pattern.  Specify once for each pattern to
                    be recognized.  Use -Y to supply patterns which are not to
                    be processed.  -Y overrides -y if a filename matches both.
                    Unless the -S option is given, leading slashes are ignored
                    when matching patterns, e.g.  /etc/passwd matches
                    etc/passwd.  See also -w and -W.

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

       -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
              Read file extensions, separated by whitespace, from filename.
              Files with these extensions are not to be compressed when using
              the -Z option.  filename may contain comments preceded by a #.
              If no -E is given, files with the extensions .Z .z .gz .arc .gif
              .zip .zoo .lha .jpeg .jpg .tpz .taz .tgz and .tzg will not be
              compressed.

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

       -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 for
              compression and decompression with the -Z option.  See also the
              -Q and -U 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     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 leading slashes 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.

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

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

       -Y pattern
              See -y.

       -Z     Gzip the files on the way out, in, and passing without links
              (valid w/ or w/o -F or -K), requires gzip(1) to be in your path.

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

       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 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 code for -F (and -f and -K ) is a complete mess.  It will probably
       work in the normal case, but don't expect it to handle a write/verify
       error correctly.  If you get such an error, best thing is to restart
       afio completely.

       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 will not restore time stamps on symlinks, and will often change
       the time stamp on a directory after having restored it.

       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.

SEE ALSO
       cpio(1), find(1), tar(1), compress(1), gzip(1).

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@win.tue.nl
       Anders Baekgaard ab@osiris.cpk.auc.dk




                                                                       AFIO(1)