MAN page from Other afio-2.4.7-134.i586.rpm


Section: User Commands (1)


afio - manipulate archives and files 


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



Afiomanipulates groups of files, copying them within the (collective)filesystem or between the filesystem and anafioarchive. Note thatafioarchives are portable, as they contain only ASCII-formattedheader information. They are also compatible with ASCIIcpio(1)archives (alacpio -c,for GNU cpio(1)alsocpio -H odc).However, archives made with using-4option arenotportable.

With-o,reads pathnames from the standard inputand writes anarchive.

With-t,reads anarchiveand writes a table-of-contents to the standard output.

With-i,installs the contents of anarchiverelative to the working directory.

With-p,reads pathnames from the standard inputand copies the files to eachdirectory.Cannot be combined with the-Zoption.

With-r,readsarchiveand verifies it against the filesystem. This is useful for verifyingtape archives.

Creates missing directories as necessary, with permissionsto match their parents.

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

Supports multi-volume archives during interactive operation(i.e., when/dev/ttyis accessible andSIGINTis not being ignored).



-@ address
Send email toaddresswhen a volume change (tape change, floppy change) is needed, and also whenthe entire operation is complete. Usessendmail(1)to send the mail.
Preserve the last access times (atimes) of the files read whenmaking or verifying an archive.Warning:if this option is used, afiowill change the last inode changed times (ctimes) of these files.Thus, this option cannot be used together with an incremental backupscheme that relies on the ctimes being preserved.
-b size
Read or writesize-characterarchive blocks.Suffices ofb,k,mandgdenote multiples of512,kilobytes,megabytesandgigabytes,respectively.Defaults to5120for compatibility withcpio(1).In some cases, notably when usingftapewith some tape drives,-b 10kis needed for compatibility. Note that -b 10kis the default block size used by tar(1),so it is usually a good choice if the tape setup is known to workwith tar(1).
-c count
Buffercountarchive blocks between I/O operations. A largecountis recommended for efficient use with streaming magnetic tape drives, inorder to reduce the number of tape stops and restarts.
Don't create missing directories.
-e bound
Pad the archive to a multiple ofboundcharacters.Recognizes the same suffices as-s.Defaults to1x(the-bblock size)for compatibility withcpio(1).
Spawn a child process to actually write to the archive; providesa clumsy form of double-buffering.Requires-sfor multi-volume archive support.
Change to input file directories. Avoids quadratic filesystembehavior with long similar pathnames. Requires all absolutepathnames, including those for the-oarchiveand the-pdirectories.
Follow symbolic links, treating them as ordinary files and directories.
Don't generate sparse filesystem blocks on restoring files.By default, afio creates sparse filesystem blocks (withlseek(2))when possible when restoring files from an archive, but not if these files were stored in a compressed form. Unless stored ina compressed form, sparse files are not archived efficiently: they will take space equal to the full file length. (The sparse file handling inafiodoes not make much sense except in a historical way.)
Skip corrupt data at thebeginningof an archive (ratherthan complaining about unrecognizable input).
With-o,write file contents with each hard link.

With-t,report hard links.

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

Mark output files with a common current timestamp(rather than with input file modification times).
Protect newer existing files (comparing file modification times).
-s size
Restrict each portion of a multi-volume archive tosizecharacters. Thisoption recognizes the same size suffices as-b.Also, the suffixxdenotes a multiple of the-bblock size (and must follow any-bspecification).sizecan be a single size or a comma-seperated list of sizes,for example '2m,5m,8m', to specify different sizes for thesubsequent volumes. If there are more volumes than sizes, the lastspecified size is used for all remaining volumes.This option is usefulwith finite-length devices which do not return shortcounts at end of media (sigh); output to magnetic tape typicallyfalls into this category. When an archive is being read or written, using-scausesafioto prompt for the next volume if the specified volume length is reached.The -soption will also causeafioto prompt if there is a premature EOF while reading the input.The special case-s 0will activate this prompting for the next volume on premature EOF without setting a volume length. When writing an archive, afiowill prompt for the next volume on end-of-media, even without-s 0being supplied, if the device is capable of reporting end-of-media.If the volumesize specified is not a multiple of the block size set with the-boption, thenafio(1)will silently round down the volume size to the nearest multiple ofthe block size. This rounding down can be suppressed using the -9option: if-9is used, afio(1)will write a small block of data, smaller than the -bsize, 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.
Report files with unseen links.
Verbose. Report pathnames as they are processed. With-t,gives anls -lstyle report (including link information).
-w filename
Treats each line infilenameas an-ypattern, see-y.
Retain file ownership and setuid/setgid permissions.This is the default for the super-user; he may use-Xto override it.
-y pattern
Restrict processing of files to names matching shell wildcard patternpattern.Use this flag once for each pattern to be recognized.With the possible exception of the presence of a leading slash, thecomplete file name as appearing in the archive table-of-contents mustmatch the pattern, for example the file name 'etc/passwd' is matchedby 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 afiothe wildcards will also match '/' characters in filenames. For example the pattern '/usr/src/*' will match the file name '/usr/src/linux/Makefile', and any other file namestarting with '/usr/src'. Unless the -Soption is given, any leading slash in the pattern or the filename isignored when matching,e.g. /etc/passwd will matchetc/passwd.Use-Yto supply patterns which arenotto be processed. -Yoverrides-yif a filename matches both. See also -w and -W.Note:if afiowas compiled without using the GNU fnmatch library, then the fullshell wildcard pattern syntax cannot be used, and matching support is limited to patterns which are a fullliteral file name and patterns which end in '*'.
Print execution statistics. This is meant for human consumption;use by other programs is officially discouraged.
Do not turn absolute paths into relative paths. That is don't removethe leading slash.
If the -voption is used, prints the byte offset of the start of each file inthe archive.If your tape drive can start reading at any position in anarchive, the output of -Bcan be useful for doing quick selective restores.
-D controlscript
Set the control script name tocontrolscript,see the section oncontrol filesbelow.
-E filename
Read file extensions, separated by whitespace, fromfilename.Files with these extensions are not to be compressed when using the-Zoption.filenamemay contain comments preceded by a #.If no-Eis given, 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 .tiffand.pngwill not be compressed.
This is a floppy disk, -sis required. Causes floppy writing inO_SYNCmode under Linux. With kernel version 1.1.54 and above, this allowsafioto detect some floppy errors while writing.Uses shared memory if compiled in otherwise mallocs as needed (a 3b1will not be able to malloc the needed memory w/o shared memory),afioassumes either way you can malloc/shmalloc a chunck of memorythe 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 -Zoption.Factor 1 is the fastest with least compression, 9 is slowest with bestcompression.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 tospecify a low value forfactorto speed up the backup. On large (>200k) files, -G 1typically 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 timeof gzip (1), see the -Toption.
-H promptscript
Specify a script to run, in stead of using the normal prompt, beforeadvancing to the next achive volume. The script will be run with thevolume number, archive specification, and the reason for changing to the next volume as arguments. The scriptshould exit with 0 for OK and 1 for abort, other exit codes will betreated as fatal errors.
Try to continue after a media write error when doing a backup (normalbehavior is to abort with a fatal error).
Verify the output against what is in the memory copy of the disk (-F required).If the writing or verifying fails the following menu 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,afiowill not process the answers 1 and 2 in the right way. The menu aboveis 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 ofcompression results when using the-Zoption. The default is -M 2m(2 megabytes). If the compressed version of a file is larger thanthis (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 timeto get the compressed data itself.
-P progname
Use the program prognameinstead of the standard gzipfor compression and decompression with the-Zoption. See also the-Q,-Uand-3options.
-Q opt
Pass the optionoptto the compression or decompression program used with the-Zoption. For passing multiple options, use-Q multiple times. If no-Qflag is present, the standard options are passed. The standardoptions are-c -6when the program is called for compression and -c -dwhen 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 aftera failed verify.The default (fdformat /dev/fd0H1440) can be changedto a given system's default by editing the Makefile.You are also prompted for formatting whenever a disk changeis requested.
Do not ignore a leading slash in the pattern or the file name when matching -yand-Ypatterns. See also -A.
-T threshold
Only compress a file when using the-Zoption if its length is at leastthreshold.The default is -T 0k.This is useful if you have a slow machine or a fast backup medium.Specifying -T 3ktypically halves the number of invocations ofgzip(1),saving some 30% computation time, while creating an archivethat is only 5% longer. The combination -T 8k -G 1typically saves 70% computation time and gives a 20% size increase.The latter combination may be a good alternative to not using -Zat all. These figures of course depend heavily on the kind of filesin the archive and the processor - i/o speed ratio on your machine.
If used with the -Zoption, forces compressed versions to be stored of all files, even ifthe compressed versions are bigger than the original versions, and disregarding any (default) values of the -T and -2 options. This is useful when the -Pand-Qoptions are used to replace the compression program gzipwith 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 hardlinked file, rather than only once for every set of hard linked files.
-W filename
Treats each line infilenameas an-Ypattern, see-Y.
-Y pattern
Do not process files whose names match shell wildcard patternpattern.See also -y and -W.
Gzip the files on the way out, in, and passing without links(valid w/ or w/o -F or -K),requires gzip(1)to bein your path. See also the-G,-P,-Q,-T,-2,and-3options.
Assume input filenames to be terminated with a '\0' instead of a '\n'. When used with find ... -print0,can be used to ensure that any filename can be handled, even if it contains a newline.
-1 warnings-to-ignore-on-exit
Control ifafio(1)should exit with a nonzero code after printing warning messages.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 (by default) when it has printedcertain warning messages during execution.warnings-to-ignore-on-exitis a list of letters which label the warning messagesthat should notlead to afio(1)exiting with a nonzero code.Defined letters areafor ignoring allpossible warnings on exit, andmfor ignoring the warning about missingfiles, which will occur when, oncreating an archive, a file whose name was read from the standardinput is not found. The default is-1 m.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 ''.
-2 maximum-file-size-to-compress
Do not compress any files whichare larger than this size when making a compressed archivewith the-Zoption. The default value is -2 200m(200 Megabytes). This maximum size cutoff lowers the risk that a major portionof a large filewill be irrecoverable due to small media errors. If a media error occurswhile reading a file thatafiohas stored in a compressed form, thenafioandgzipwill 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 becauseof this effect will usually be too big. The special case-2 0eliminates any maximum size cutoff.
-3 filedescriptor-nr
Rewind the filedescriptor before invoking the (un)compression programif using the -Z option. Thisis useful when the -Pand-Qoptions are used to replace the compression program gzipwith some types of encryption programs in order to make or read an archivewith encrypted files. The rewinding is needed to interfacecorrectly with some encryption programs that read their key from an openfiledescriptor. If the-Pprogram name matches 'pgp' or 'gpg', then the-3option mustbe used to avoid afio(1)reporting an error. Use the special case-3 0to supress the error message without rewinding any file descriptor.The-3 0option may also be needed to sucessfully read back encrypted archivesmade with afio version 2.4.5 and older.
Write archive in the `extended ASCII' format which uses 4-byteinode numbers. Archives using the extended ASCII format arenotcompatible with any other archiver. This option should not be usedunless the set of files to be archived contains over 60 thousand hardlinks and all set-internal hard links need to be preserved in thearchive. A complete news spool could be an example of such a set offiles. For such sets, the standard archive format would notnecessarily perserve all internal hard links (see the BUGS section).
Do not round down any-svolume sizes to the nearest-bblock size. See the-soption.



Special-case archive names:
Specify-to read or write the standard input or output, respectively.This disables multi-volume archive handling.
Prefix a command string to be executed with an exclamation mark(!).The command is executed once for each archive volume,with its standard input or output piped toafio.It is expected to produce a zero exit code when all is well.
Usesystem:fileto access an archive infileonsystem.This is really just a special case of pipelining.It requires a 4.2BSD-style remote shell(rsh(1C))and a remote copy ofafio.
A more elaborate case of the above is[user@]host[%rsh][=afio]:filewhere the optional user@component specifies the user name on the remote host, the optional%rshspecifies the (local) name of the remote shell command to use,and the optional=afiospecifies the name of the remote copy of the afio command.
Anything else specifies a local file or device.An output file will be created if it does not already exist.

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

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

Optimizes pathnames with respect to the current and parentdirectories. For example, ./src/sh/../misc/afio.cbecomessrc/misc/afio.c. 


Afioarchives can contain so-called control files. Unlike normal archiveentries, a control file in not unpacked to the filesystem. A controlfile has alabeland somedata.When afioencounters a control file in the archive it is reading, it will feed thelabelanddatato a so-called control script. The control script is supplied bythe user. It can perform special actions based on thelabelanddatait receives from afio.

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

To distinguish between different uses, thelabelof a control file should indicate the program that made the contolfile and the purpose of the control file data. It should have theform


where programnameis the name of the backup program that generated the control file, andkindofdatais 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 decidewhat to do with the control data. This way, control files withunknown labels can be ignored, and afio archives maintain some degreeof portability between different programs that restore or index them.

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

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

    //--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, andlabelis the control file label. The sourcename must be a regular file or a symlink to a regular file.

A control file will show up as


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

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

-D controlscript

command line option. Thecontrolscriptmust be an executable program. The script isrun wheneverafioencounters a control file while doing a-i -tor-roperation. Afio will supply the control filelabelas an argument to the script. The script should read the control filedatafrom its standard input. If the script exits with a non-zero exitstatus,afiowill issue a warning message.

If a contol file is encountered and no-Doption is given,afiowill issue a warning message. To suppress the warning message andignore 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

Afionever compresses the control file data when storing it in an archive,even when the-Zoption is used. When a control file is encountered bycpio(1)or anafiowith a version number below 2.4.1, the data will be unpacked to thefilesystem, and namedCONTROL_FILE/labelwherelabelis the control file label. 


There are too many options.

Restricts pathnames to 1023 characters, and 255 meaningful elements (where each element is a pathname component separated by a /).

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

Does not use the same default block size as tar(1).tar(1)uses 10 KB, afiouses 5 KB by default. Some tape drives only work with a 10 KB block size,in that case the afio option-b 10kis 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 withcpio(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" (ratherthan "/usr/bin/cu").

Theafiocode for handling floppies(-Fand -f and -Koptions) has buggy error handling. afiodoes 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 restartafiocompletely.Making backups to floppies should really be done with a more specialised backup program that wrapsafio.

The Linux floppy drivers below kernel version 1.1.54 do notallowafioto find out about floppy write errors while writing. If youare running a kernel below 1.1.54, afiowill happily fail to write to(say) a write protected disk and not report anything wrong! The onlyway to find out about write errors in this case is by watching thekernel messages, or by switching on the verify(-K)option.

The remote archive facilites (host:/file archive names) have not beenexhaustively tested. These facilities have seen a lot of real-life usethough. However, there may be bugs in the code for error handling anderror 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 /usrand/usr/srcdirectories. If these directories are missing when restoring the archive,afiowill recreate them with some default ownership and permissions.

Afio will not restore time stamps and owner/group information on symlinks. Afio will often changethe time stamp on a directory after having restored it.

A restore using decompression will fail if thegzipbinary used byafiois overwritten, byafioor by another program, during the restore. The restore will also fail ifany shared libraries needed to startgzipare overwritten during the restore.afioshould not normally be used to overwrite the system files on a runningsystem. If it is used in this way, a flag like-Y /bin/gzipcan often be added to prevent failure.

The -roption verifies the file contents of the files in the archive against the files on the filesystem, but does not cross-check detailslike permission bits on files, nor does it cross-check that archiveddirectories 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 storedin compressed form, unless the-l or-Uoptions are used which force each hard linked file to be stored separately.2) By default,unless the-toption is used when writing an archive, afiowill store only one copy of each file with hard links in the archive,and re-create the hard links on unpacking the archive. However, thecapacity for storing hard links is limited to 64K files which havehard links. After processing 64K files with hardlinks (eitherpointing inside or outside the set of files to be archived), each instance of a new hard linked file will be stored separately andseparate files will be created when unpacking. The limitation to 64Kfiles with hard links is not present when the-4option is used. 3) Archives which contain hard links and which weremade with older (pre-2.4.4) versions ofafioor withcpio can not always be correctly unpacked. This is really a problem in thearchives and not in the current version ofafio.The risk of incorrect unpacking will be greater if the number of filesor hard links in the archives is larger. Unlike pre-2.4.4 versions ofafioandcpio,the current version contains heuristics which greatly reduce therisk of incorrect unpacking. Use of the current version ofafiofor unpacking older archives with hard links is strongly encouraged.4) In a selective restore, if the selection predicates do not selectthe first copy of a file with archive-internal hard links, then allsubsequent copies, if selected, will not be correctly restored. 4)Unless the-4 option is used, the inode number fields in the archive headers forfiles with hard links of the archive will sometimes not contain theactual (least significant 16 bits of) the inode number of the originalfile.

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-Uoption 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 writepermissions, even if it just created that directory itself. This can be aproblem when trying to restore directory structurescreated by some source code control tools like RCS.



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 existingfiles:
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 thecrdrecordutility 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.)



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


Mark Brukhartz ..!ihnp4!laidbak!mdb
Jeff Buhrt uunet!sawmill!prslnk!buhrt
Dave Gymer
Andrew Stevens
Koen Holtman (current maintainer)




This document was created byman2html,using the manual pages.