+You should start the restore script with the media containing the
+first volume of the archive mounted. The script will prompt for other
+volumes as they are needed. If the archive is on tape, you don't need
+to rewind the tape to to its beginning---if the tape head is
+positioned past the beginning of the archive, the script will rewind
+the tape as needed. @FIXME-xref{Media}, for a discussion of tape
+positioning.
+
+If you specify @samp{--all} as the @var{files} argument, the
+@code{restore} script extracts all the files in the archived file
+system into the active file system.
+
+@quotation
+@strong{Warning:} The script will delete files from the active file
+system if they were not in the file system when the archive was made.
+@end quotation
+
+@value{xref-incremental}, and @value{ref-listed-incremental},
+for an explanation of how the script makes that determination.
+
+@FIXME{this may be an option, not a given}
+
+@end ifclear
+
+@node Choosing, Date input formats, Backups, Top
+@chapter Choosing Files and Names for @code{tar}
+@UNREVISED
+
+@FIXME{Melissa (still) Doesn't Really Like This ``Intro'' Paragraph!!!}
+
+Certain options to @code{tar} enable you to specify a name for your
+archive. Other options let you decide which files to include or exclude
+from the archive, based on when or whether files were modified, whether
+the file names do or don't match specified patterns, or whether files
+are in specified directories.
+
+@menu
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* Wildcards::
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing Filesystem Boundaries
+@end menu
+
+@node file, Selecting Archive Members, Choosing, Choosing
+@section Choosing and Naming Archive Files
+@cindex Naming an archive
+@cindex Archive Name
+@cindex Directing output
+@cindex Choosing an archive file
+@cindex Where is the archive?
+@UNREVISED
+
+@FIXME{should the title of this section actually be, "naming an
+archive"?}
+
+By default, @code{tar} uses an archive file name that was compiled when
+it was built on the system; usually this name refers to some physical
+tape drive on the machine. However, the person who installed @code{tar}
+on the system may not set the default to a meaningful value as far as
+most users are concerned. As a result, you will usually want to tell
+@code{tar} where to find (or create) the archive. The @value{op-file}
+option allows you to either specify or name a file to use as the archive
+instead of the default archive file location.
+
+@table @kbd
+@item --file=@var{archive-name}
+@itemx -f @var{archive-name}
+Name the archive to create or operate on. Use in conjunction with
+any operation.
+@end table
+
+For example, in this @code{tar} command,
+
+@example
+$ @kbd{tar -cvf collection.tar blues folk jazz}
+@end example
+
+@noindent
+@file{collection.tar} is the name of the archive. It must directly
+follow the @samp{-f} option, since whatever directly follows @samp{-f}
+@emph{will} end up naming the archive. If you neglect to specify an
+archive name, you may end up overwriting a file in the working directory
+with the archive you create since @code{tar} will use this file's name
+for the archive name.
+
+An archive can be saved as a file in the file system, sent through a
+pipe or over a network, or written to an I/O device such as a tape,
+floppy disk, or CD write drive.
+
+@cindex Writing new archives
+@cindex Archive creation
+If you do not name the archive, @code{tar} uses the value of the
+environment variable @code{TAPE} as the file name for the archive. If
+that is not available, @code{tar} uses a default, compiled-in archive
+name, usually that for tape unit zero (ie. @file{/dev/tu00}).
+@code{tar} always needs an archive name.
+
+If you use @file{-} as an @var{archive-name}, @code{tar} reads the
+archive from standard input (when listing or extracting files), or
+writes it to standard output (when creating an archive). If you use
+@file{-} as an @var{archive-name} when modifying an archive,
+@code{tar} reads the original archive from its standard input and
+writes the entire new archive to its standard output.
+
+@FIXME{might want a different example here; this is already used in
+"notable tar usages".}
+
+@example
+$ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
+@end example
+
+@FIXME{help!}
+
+@cindex Standard input and output
+@cindex tar to standard input and output
+To specify an archive file on a device attached to a remote machine,
+use the following:
+
+@example
+@kbd{--file=@var{hostname}:/@var{dev}/@var{file name}}
+@end example
+
+@noindent
+@code{tar} will complete the remote connection, if possible, and
+prompt you for a username and password. If you use
+@samp{--file=@@@var{hostname}:/@var{dev}/@var{file name}}, @code{tar}
+will complete the remote connection, if possible, using your username
+as the username on the remote machine.
+
+If the archive file name includes a colon (@samp{:}), then it is assumed
+to be a file on another machine. If the archive file is
+@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
+host @var{host}. The remote host is accessed using the @code{rsh}
+program, with a username of @var{user}. If the username is omitted
+(along with the @samp{@@} sign), then your user name will be used.
+(This is the normal @code{rsh} behavior.) It is necessary for the
+remote machine, in addition to permitting your @code{rsh} access, to
+have the @file{/usr/ucb/rmt} program installed. If you need to use a
+file whose name includes a colon, then the remote tape drive behavior
+can be inhibited by using the @value{op-force-local} option.
+
+@FIXME{i know we went over this yesterday, but bob (and now i do again,
+too) thinks it's out of the middle of nowhere. it doesn't seem to tie
+into what came before it well enough <<i moved it now, is it better
+here?>>. bob also comments that if Amanda isn't free software, we
+shouldn't mention it..}
+
+When the archive is being created to @file{/dev/null}, GNU @code{tar}
+tries to minimize input and output operations. The Amanda backup
+system, when used with GNU @code{tar}, has an initial sizing pass which
+uses this feature.
+
+@node Selecting Archive Members, files, file, Choosing
+@section Selecting Archive Members
+@cindex Specifying files to act on
+@cindex Specifying archive members
+
+@dfn{File Name arguments} specify which files in the file system
+@code{tar} operates on, when creating or adding to an archive, or which
+archive members @code{tar} operates on, when reading or deleting from
+an archive. @xref{Operations}.
+
+To specify file names, you can include them as the last arguments on
+the command line, as follows:
+@smallexample
+@kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}]
+@end smallexample
+
+If you specify a directory name as a file name argument, all the files
+in that directory are operated on by @code{tar}.
+
+If you do not specify files when @code{tar} is invoked with
+@value{op-create}, @code{tar} operates on all the non-directory files in
+the working directory. If you specify either @value{op-list} or
+@value{op-extract}, @code{tar} operates on all the archive members in the
+archive. If you specify any operation other than one of these three,
+@code{tar} does nothing.
+
+By default, @code{tar} takes file names from the command line. However,
+there are other ways to specify file or member names, or to modify the
+manner in which @code{tar} selects the files or members upon which to
+operate; @FIXME{add xref here}. In general, these methods work both for
+specifying the names of files and archive members.
+
+@node files, exclude, Selecting Archive Members, Choosing
+@section Reading Names from a File
+@UNREVISED
+
+@cindex Reading file names from a file
+@cindex Lists of file names
+@cindex File Name arguments, alternatives
+Instead of giving the names of files or archive members on the command
+line, you can put the names into a file, and then use the
+@value{op-files-from} option to @code{tar}. Give the name of the file
+which contains the list of files to include as the argument to
+@samp{--files-from}. In the list, the file names should be separated by
+newlines. You will frequently use this option when you have generated
+the list of files to archive with the @code{find} utility.
+
+@table @kbd
+@item --files-from=@var{file name}
+@itemx -T @var{file name}
+Get names to extract or create from file @var{file name}.
+@end table
+
+If you give a single dash as a file name for @samp{--files-from}, (i.e.,
+you specify either @samp{--files-from=-} or @samp{-T -}), then the file
+names are read from standard input.
+
+Unless you are running @code{tar} with @samp{--create}, you can not use
+both @samp{--files-from=-} and @samp{--file=-} (@samp{-f -}) in the same
+command.
+
+@FIXME{add bob's example, from his message on 2-10-97}
+
+The following example shows how to use @code{find} to generate a list of
+files smaller than 400K in length and put that list into a file
+called @file{small-files}. You can then use the @samp{-T} option to
+@code{tar} to specify the files from that file, @file{small-files}, to
+create the archive @file{little.tgz}. (The @samp{-z} option to
+@code{tar} compresses the archive with @code{gzip}; @pxref{gzip} for
+more information.)
+
+@example
+$ @kbd{find . -size -400 -print > small-files}
+$ @kbd{tar -c -v -z -T small-files -f little.tgz}
+@end example
+
+@noindent
+@FIXME{say more here to conclude the example/section?}
+
+@menu
+* nul::
+@end menu
+
+@node nul, , files, files
+@ifinfo
+@unnumberedsubsec @kbd{NUL} Terminated File Names
+@end ifinfo
+
+@cindex File names, terminated by @kbd{NUL}
+@cindex @kbd{NUL} terminated file names
+The @value{op-null} option causes @value{op-files-from} to read file
+names terminated by a @code{NUL} instead of a newline, so files whose
+names contain newlines can be archived using @samp{--files-from}.
+
+@table @kbd
+@item --null
+Only consider @kbd{NUL} terminated file names, instead of files that
+terminate in a newline.
+@end table
+
+The @samp{--null} option is just like the one in GNU @code{xargs} and
+@code{cpio}, and is useful with the @samp{-print0} predicate of GNU
+@code{find}. In @code{tar}, @samp{--null} also causes
+@value{op-directory} options to be treated as file names to archive, in
+case there are any files out there called @file{-C}.
+
+This example shows how to use @code{find} to generate a list of files
+larger than 800K in length and put that list into a file called
+@file{long-files}. The @samp{-print0} option to @code{find} just just
+like @samp{-print}, except that it separates files with a @kbd{NUL}
+rather than with a newline. You can then run @code{tar} with both the
+@samp{--null} and @samp{-T} options to specify that @code{tar} get the
+files from that file, @file{long-files}, to create the archive
+@file{big.tgz}. The @samp{--null} option to @code{tar} will cause
+@code{tar} to recognize the @kbd{NUL} separator between files.
+
+@example
+$ @kbd{find . -size +800 -print0 > long-files}
+$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
+@end example
+
+@FIXME{say anything else here to conclude the section?}
+
+@node exclude, Wildcards, files, Choosing
+@section Excluding Some Files
+@cindex File names, excluding files by
+@cindex Excluding files by name and pattern
+@cindex Excluding files by file system
+@UNREVISED
+
+To avoid operating on files whose names match a particular pattern,
+use the @value{op-exclude} or @value{op-exclude-from} options.
+
+@table @kbd
+@item --exclude=@var{pattern}
+Causes @code{tar} to ignore files that match the @var{pattern}.
+@end table
+
+@findex exclude
+The @value{op-exclude} option will prevent any file or member which
+matches the shell wildcards (@var{pattern}) from being operated on
+(@var{pattern} can be a single file name or a more complex expression).
+For example, if you want to create an archive with all the contents of
+@file{/tmp} except the file @file{/tmp/foo}, you can use the command
+@samp{tar --create --file=arch.tar --exclude=foo}. You may give
+multiple @samp{--exclude} options.
+
+@table @kbd
+@item --exclude-from=@var{file}
+@itemx -X @var{file}
+Causes @code{tar} to ignore files that match the patterns listed in
+@var{file}.
+@end table
+
+@findex exclude-from
+Use the @samp{--exclude-from=@var{file-of-patterns}} option to read a
+list of shell wildcards, one per line, from @var{file}; @code{tar} will
+ignore files matching those regular expressions. Thus if @code{tar} is
+called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a
+single line @file{*.o}, no files whose names end in @file{.o} will be
+added to the archive.
+
+@FIXME{do the exclude options files need to have stuff separated by
+newlines the same as the files-from option does?}
+
+@menu
+* problems with exclude::
+@end menu
+
+@node problems with exclude, , exclude, exclude
+@unnumberedsubsec Problems with Using the @code{exclude} Options
+
+@FIXME{put in for the editor's/editors' amusement, but should be taken
+out in the final draft, just in case! : }
+
+@ignore
+subtitled: getting screwed using exclewed
+@end ignore
+
+Some users find @samp{exclude} options confusing. Here are some common
+pitfalls:
+
+@itemize @bullet
+@item
+The main operating mode of @code{tar} will always act on file names
+listed on the command line, no matter whether or not there is an
+exclusion which would otherwise affect them. In the example above, if
+you create an archive and exclude files that end with @samp{*.o}, but
+explicitly name the file @samp{catc.o} after all the options have been
+listed, @samp{catc.o} @emph{will} be included in the archive.
+
+@item
+You can sometimes confuse the meanings of @value{op-exclude} and
+@value{op-exclude-from}. Be careful: use @value{op-exclude} when files
+to be excluded are given as a pattern on the command line. Use
+@samp{--exclude-from=@var{file-of-patterns}} to introduce the name of a
+file which contains a list of patterns, one per line; each of these
+patterns can exclude zero, one, or many files.
+
+@item
+When you use @value{op-exclude}, be sure to quote the @var{pattern}
+parameter, so GNU @code{tar} sees wildcard characters like @samp{*}.
+If you do not do this, the shell might expand the @samp{*} itself
+using files at hand, so @code{tar} might receive a list of files
+instead of one pattern, or none at all, making the command somewhat
+illegal. This might not correspond to what you want.
+
+For example, write:
+
+@example
+$ @kbd{tar -c -f @var{archive.tar} -X '*/tmp/*' @var{directory}}
+@end example
+
+@noindent
+rather than:
+
+@example
+$ @kbd{tar -c -f @var{archive.tar} -X */tmp/* @var{directory}}
+@end example
+
+@item
+You must use use shell syntax, or globbing, rather than @code{regexp}
+syntax, when using exclude options in @code{tar}. If you try to use
+@code{regexp} syntax to describe files to be excluded, your command
+might fail.
+
+@item
+In earlier versions of @code{tar}, what is now the
+@samp{--exclude-from=@var{file-of-patterns}} option was called
+@samp{--exclude-@var{pattern}} instead. Now,
+@samp{--exclude=@var{pattern}} applies to patterns listed on the command
+line and @samp{--exclude-from=@var{file-of-patterns}} applies to
+patterns listed in a file.
+
+@end itemize
+
+@node Wildcards, after, exclude, Choosing
+@section Wildcards Patterns and Matching
+
+@dfn{Globbing} is the operation by which @dfn{wildcard} characters,
+@samp{*} or @samp{?} for example, are replaced and expanded into all
+existing files matching the given pattern. However, @code{tar} often
+uses wildcard patterns for matching (or globbing) archive members instead
+of actual files in the filesystem. Wildcard patterns are also used for
+verifying volume labels of @code{tar} archives. This section has the
+purpose of explaining wildcard syntax for @code{tar}.
+
+@FIXME{the next few paragraphs need work.}
+
+A @var{pattern} should be written according to shell syntax, using wildcard
+characters to effect globbing. Most characters in the pattern stand
+for themselves in the matched string, and case is significant: @samp{a}
+will match only @samp{a}, and not @samp{A}. The character @samp{?} in the
+pattern matches any single character in the matched string. The character
+@samp{*} in the pattern matches zero, one, or more single characters in
+the matched string. The character @samp{\} says to take the following
+character of the pattern @emph{literally}; it is useful when one needs to
+match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
+
+The character @samp{[}, up to the matching @samp{]}, introduces a character
+class. A @dfn{character class} is a list of acceptable characters
+for the next single character of the matched string. For example,
+@samp{[abcde]} would match any of the first five letters of the alphabet.
+Note that within a character class, all of the ``special characters''
+listed above other than @samp{\} lose their special meaning; for example,
+@samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\},
+@samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints,
+the characters @samp{-} and @samp{]} must either come @emph{first} or
+@emph{last} in a character class.)
+
+@cindex Excluding characters from a character class
+@cindex Character class, excluding characters from
+If the first character of the class after the opening @samp{[}
+is @samp{!} or @samp{^}, then the meaning of the class is reversed.
+Rather than listing character to match, it lists those characters which
+are @emph{forbidden} as the next single character of the matched string.
+
+Other characters of the class stand for themselves. The special
+construction @samp{[@var{a}-@var{e}]}, using an hyphen between two
+letters, is meant to represent all characters between @var{a} and
+@var{e}, inclusive.
+
+@FIXME{need to add a sentence or so here to make this clear for those
+who don't have dan around.}
+
+Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
+special for wildcard matches. However, if a pattern completely matches
+a directory prefix of a matched string, then it matches the full matched
+string: excluding a directory also excludes all the files beneath it.
+
+There are some discussions floating in the air and asking for modifications
+in the way GNU @code{tar} accomplishes wildcard matches. We perceive
+any change of semantics in this area as a delicate thing to impose on
+GNU @code{tar} users. On the other hand, the GNU project should be
+progressive enough to correct any ill design: compatibility at all price
+is not always a good attitude. In conclusion, it is @emph{possible}
+that slight amendments be later brought to the previous description.
+Your opinions on the matter are welcome.
+
+@node after, recurse, Wildcards, Choosing
+@section Operating Only on New Files
+@cindex Excluding file by age
+@cindex Modification time, excluding files by
+@cindex Age, excluding files by
+@UNREVISED
+
+The @value{op-after-date} option causes @code{tar} to only work on files
+whose modification or inode-changed times are newer than the @var{date}
+given. If you use this option when creating or appending to an archive,
+the archive will only include new files. If you use @samp{--after-date}
+when extracting an archive, @code{tar} will only extract files newer
+than the @var{date} you specify.
+
+If you only want @code{tar} to make the date comparison based on
+modification of the actual contents of the file (rather than inode
+changes), then use the @value{op-newer-mtime} option.
+
+You may use these options with any operation. Note that these options
+differ from the @value{op-update} operation in that they allow you to
+specify a particular date against which @code{tar} can compare when
+deciding whether or not to archive the files.
+
+@table @kbd
+@item --after-date=@var{date}
+@itemx --newer=@var{date}
+@itemx -N @var{date}
+Only store files newer than @var{date}.
+
+Acts on files only if their modification or inode-changed times are
+later than @var{date}. Use in conjunction with any operation.
+
+@item --newer-mtime=@var{date}
+Acts like @value{op-after-date}, but only looks at modification times.
+@end table
+
+These options limit @code{tar} to only operating on files which have
+been modified after the date specified. A file is considered to have
+changed if the contents have been modified, or if the owner,
+permissions, and so forth, have been changed. (For more information on
+how to specify a date, see @ref{Date input formats}; remember that the
+entire date argument must be quoted if it contains any spaces.)
+
+Gurus would say that @value{op-after-date} tests both the @code{mtime}
+(time the contents of the file were last modified) and @code{ctime}
+(time the file's status was last changed: owner, permissions, etc)
+fields, while @value{op-newer-mtime} tests only @code{mtime} field.
+
+To be precise, @value{op-after-date} checks @emph{both} @code{mtime} and
+@code{ctime} and processes the file if either one is more recent than
+@var{date}, while @value{op-newer-mtime} only checks @code{mtime} and
+disregards @code{ctime}. Neither uses @code{atime} (the last time the
+contents of the file were looked at).
+
+Date specifiers can have embedded spaces. Because of this, you may need
+to quote date arguments to keep the shell from parsing them as separate
+arguments.
+
+@FIXME{Need example of --newer-mtime with quoted argument.}
+
+@quotation
+@strong{Please Note:} @value{op-after-date} and @value{op-newer-mtime}
+should not be used for incremental backups. Some files (such as those
+in renamed directories) are not selected properly by these options.
+@xref{incremental and listed-incremental}.
+@end quotation
+
+To select files newer than the modification time of a file that already
+exists, you can use the @samp{--reference} (@samp{-r}) option of GNU
+@code{date}, available in GNU shell utilities 1.13 or later. It returns
+the timestamp of that already existing file; this timestamp expands to
+become the referent date which @samp{--newer} uses to determine which
+files to archive. For example, you could say,
+
+@example
+$ @kbd{tar -cf @var{archive.tar} --newer="`date -r @var{file}`" /home}
+@end example
+
+@noindent
+which tells @FIXME{need to fill this in!}.
+
+@node recurse, one, after, Choosing
+@section Descending into Directories
+@cindex Avoiding recursion in directories
+@cindex Descending directories, avoiding
+@cindex Directories, avoiding recursion
+@cindex Recursion in directories, avoiding
+@UNREVISED
+
+@FIXME{arrggh! this is still somewhat confusing to me. :-< }
+
+@FIXME{show dan bob's comments, from 2-10-97}
+
+Usually, @code{tar} will recursively explore all directories (either
+those given on the command line or through the @value{op-files-from}
+option) for the various files they contain. However, you may not always
+want @code{tar} to act this way.
+
+The @value{op-no-recursion} option inhibits @code{tar}'s recursive descent
+into specified directories. If you specify @samp{--no-recursion}, you can
+use the @code{find} utility for hunting through levels of directories to
+construct a list of file names which you could then pass to @code{tar}.
+@code{find} allows you to be more selective when choosing which files to
+archive; see @ref{files} for more information on using @code{find} with
+@code{tar}, or look.
+
+@table @kbd
+@item --no-recursion
+Prevents @code{tar} from recursively descending directories.
+@end table
+
+When you use @samp{--no-recursion}, GNU @code{tar} grabs directory entries
+themselves, but does not descend on them recursively. Many people use
+@code{find} for locating files they want to back up, and since
+@code{tar} @emph{usually} recursively descends on directories, they have
+to use the @samp{@w{! -d}} option to @code{find} @FIXME{needs more
+explanation or a cite to another info file} as they usually do not want
+all the files in a directory. They then use the @value{op-file-from}
+option to archive the files located via @code{find}.
+
+The problem when restoring files archived in this manner is that the
+directories themselves are not in the archive; so the
+@value{op-same-permissions} option does not affect them---while users
+might really like it to. Specifying @value{op-no-recursion} is a way to
+tell @code{tar} to grab only the directory entries given to it, adding
+no new files on its own.
+
+@FIXME{example here}
+
+@node one, , recurse, Choosing
+@section Crossing Filesystem Boundaries
+@cindex File system boundaries, not crossing
+@UNREVISED
+
+@code{tar} will normally automatically cross file system boundaries in
+order to archive files which are part of a directory tree. You can
+change this behavior by running @code{tar} and specifying
+@value{op-one-file-system}. This option only affects files that are
+archived because they are in a directory that is being archived;
+@code{tar} will still archive files explicitly named on the command line
+or through @value{op-files-from}, regardless of where they reside.
+
+@table @kbd
+@item --one-file-system
+@itemx -l
+Prevents @code{tar} from crossing file system boundaries when
+archiving. Use in conjunction with any write operation.
+@end table
+
+The @samp{--one-file-system} option causes @code{tar} to modify its
+normal behavior in archiving the contents of directories. If a file in
+a directory is not on the same filesystem as the directory itself, then
+@code{tar} will not archive that file. If the file is a directory
+itself, @code{tar} will not archive anything beneath it; in other words,
+@code{tar} will not cross mount points.
+
+It is reported that using this option, the mount point is is archived,
+but nothing under it.
+
+This option is useful for making full or incremental archival backups of
+a file system. If this option is used in conjunction with
+@value{op-verbose}, files that are excluded are mentioned by name on the
+standard error.
+
+@menu
+* directory:: Changing Directory
+* absolute:: Absolute File Names
+@end menu
+
+@node directory, absolute, one, one
+@subsection Changing the Working Directory
+
+@FIXME{need to read over this node now for continuity; i've switched
+things around some.}
+
+@cindex Changing directory mid-stream
+@cindex Directory, changing mid-stream
+@cindex Working directory, specifying
+@UNREVISED
+
+To change the working directory in the middle of a list of file names,
+either on the command line or in a file specified using
+@value{op-files-from}, use @value{op-directory}. This will change the
+working directory to the directory @var{directory} after that point in
+the list.
+
+@table @kbd
+@item --directory=@var{directory}
+@itemx -C @var{directory}
+Changes the working directory in the middle of a command line.
+@end table
+
+For example,
+
+@example
+$ @kbd{tar -c -f jams.tar grape prune -C food cherry}
+@end example
+
+@noindent
+will place the files @file{grape} and @file{prune} from the current
+directory into the archive @file{jams.tar}, followed by the file
+@file{cherry} from the directory @file{food}. This option is especially
+useful when you have several widely separated files that you want to
+store in the same archive.
+
+Note that the file @file{cherry} is recorded in the archive under the
+precise name @file{cherry}, @emph{not} @file{food/cherry}. Thus, the
+archive will contain three files that all appear to have come from the
+same directory; if the archive is extracted with plain @samp{tar
+--extract}, all three files will be written in the current directory.
+
+Contrast this with the command,
+
+@example
+$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}
+@end example
+
+@noindent
+which records the third file in the archive under the name
+@file{red/cherry} so that, if the archive is extracted using
+@samp{tar --extract}, the third file will be written in a subdirectory
+named @file{orange-colored}.
+
+You can use the @samp{--directory} option to make the archive
+independent of the original name of the directory holding the files.
+The following command places the files @file{/etc/passwd},
+@file{/etc/hosts}, and @file{/lib/libc.a} into the archive
+@file{foo.tar}:
+
+@example
+$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}
+@end example
+
+@noindent
+However, the names of the archive members will be exactly what they were
+on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}.
+They will not appear to be related by file name to the original
+directories where those files were located.
+
+Note that @samp{--directory} options are interpreted consecutively. If
+@samp{--directory} specifies a relative file name, it is interpreted
+relative to the then current directory, which might not be the same as
+the original current working directory of @code{tar}, due to a previous
+@samp{--directory} option.
+
+@FIXME{dan: does this mean that you *can* use the short option form, but
+you can *not* use the long option form with --files-from? or is this
+totally screwed?}
+
+When using @samp{--files-from} (@pxref{files}), you can put @samp{-C}
+options in the file list. Unfortunately, you cannot put
+@samp{--directory} options in the file list. (This interpretation can
+be disabled by using the @value{op-null} option.)
+
+@node absolute, , directory, one
+@subsection Absolute File Names
+@UNREVISED
+
+@table @kbd
+@item -P
+@itemx --absolute-names
+Do not strip leading slashes from file names.
+@end table
+
+By default, GNU @code{tar} drops a leading @samp{/} on input or output.
+This option turns off this behavior; it is equivalent to changing to the
+root directory before running @code{tar} (except it also turns off the
+usual warning message).
+
+When @code{tar} extracts archive members from an archive, it strips any
+leading slashes (@samp{/}) from the member name. This causes absolute
+member names in the archive to be treated as relative file names. This
+allows you to have such members extracted wherever you want, instead of
+being restricted to extracting the member in the exact directory named
+in the archive. For example, if the archive member has the name
+@file{/etc/passwd}, @code{tar} will extract it as if the name were
+really @file{etc/passwd}.
+
+Other @code{tar} programs do not do this. As a result, if you create an
+archive whose member names start with a slash, they will be difficult
+for other people with a non-GNU @code{tar} program to use. Therefore,
+GNU @code{tar} also strips leading slashes from member names when
+putting members into the archive. For example, if you ask @code{tar} to
+add the file @file{/bin/ls} to an archive, it will do so, but the member
+name will be @file{bin/ls}.
+
+If you use the @value{op-absolute-names} option, @code{tar} will do
+neither of these transformations.
+
+To archive or extract files relative to the root directory, specify
+the @value{op-absolute-names} option.
+
+Normally, @code{tar} acts on files relative to the working
+directory---ignoring superior directory names when archiving, and
+ignoring leading slashes when extracting.
+
+When you specify @value{op-absolute-names}, @code{tar} stores file names
+including all superior directory names, and preserves leading slashes.
+If you only invoked @code{tar} from the root directory you would never
+need the @value{op-absolute-names} option, but using this option may be
+more convenient than switching to root.
+
+@FIXME{Should be an example in the tutorial/wizardry section using this
+to transfer files between systems.}
+
+@FIXME{Is write access an issue?}
+
+@table @kbd
+@item --absolute-names
+Preserves full file names (inclusing superior dirctory names) when
+archiving files. Preserves leading slash when extracting files.
+
+@end table
+
+@FIXME{this is still horrible; need to talk with dan on monday.}
+
+@code{tar} prints out a message about removing the @samp{/} from file
+names. This message appears once per GNU @code{tar} invocation. It
+represents something which ought to be told; ignoring what it means can
+cause very serious surprises, later.
+
+Some people, nevertheless, do not want to see this message. Wanting to
+play really dangerously, one may of course redirect @code{tar} standard
+error to the sink. For example, under @code{sh}:
+
+@example
+$ @kbd{tar -c -f archive.tar /home 2> /dev/null}
+@end example
+
+@noindent
+Another solution, both nicer and simpler, would be to change to
+the @file{/} directory first, and then avoid absolute notation.
+For example:
+
+@example
+$ @kbd{(cd / && tar -c -f archive.tar home)}
+$ @kbd{tar -c -f archive.tar -C / home}
+@end example
+
+@node Date input formats, Formats, Choosing, Top
+@chapter Date input formats
+
+@cindex date input formats
+@findex getdate
+
+@quotation
+Our units of temporal measurement, from seconds on up to months, are so
+complicated, asymmetrical and disjunctive so as to make coherent mental
+reckoning in time all but impossible. Indeed, had some tyrannical god
+contrived to enslave our minds to time, to make it all but impossible
+for us to escape subjection to sodden routines and unpleasant surprises,
+he could hardly have done better than handing down our present system.
+It is like a set of trapezoidal building blocks, with no vertical or
+horizontal surfaces, like a language in which the simplest thought
+demands ornate constructions, useless particles and lengthy
+circumlocutions. Unlike the more successful patterns of language and
+science, which enable us to face experience boldly or at least
+level-headedly, our system of temporal calculation silently and
+persistently encourages our terror of time.
+
+@dots{} It is as though architects had to measure length in feet, width
+in meters and height in ells; as though basic instruction manuals
+demanded a knowledge of five different languages. It is no wonder then
+that we often look into our own immediate past or future, last Tuesday
+or a week from Sunday, with feelings of helpless confusion. @dots{}
+
+--- Robert Grudin, @cite{Time and the Art of Living}.
+@end quotation
+
+This section describes the textual date representations that GNU
+programs accept. These are the strings you, as a user, can supply as
+arguments to the various programs. The C interface (via the
+@code{getdate} function) is not described here.
+
+@cindex beginning of time, for Unix
+@cindex epoch, for Unix
+Although the date syntax here can represent any possible time since zero
+A.D., computer integers are not big enough for such a (comparatively)
+long time. The earliest date semantically allowed on Unix systems is
+midnight, 1 January 1970 UCT.
+
+@menu
+* General date syntax:: Common rules.
+* Calendar date item:: 19 Dec 1994.
+* Time of day item:: 9:20pm.
+* Timezone item:: EST, DST, BST, UCT, AHST, ...
+* Day of week item:: Monday and others.
+* Relative item in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Authors of getdate:: Bellovin, Salz, Berets, et al.
+@end menu
+
+
+@node General date syntax, Calendar date item, Date input formats, Date input formats
+@section General date syntax
+
+@cindex general date syntax
+
+@cindex items in date strings
+A @dfn{date} is a string, possibly empty, containing many items
+separated by whitespace. The whitespace may be omitted when no
+ambiguity arises. The empty string means the beginning of today (i.e.,
+midnight). Order of the items is immaterial. A date string may contain
+many flavors of items:
+
+@itemize @bullet
+@item calendar date items
+@item time of the day items
+@item time zone items
+@item day of the week items
+@item relative items
+@item pure numbers.
+@end itemize
+
+@noindent We describe each of these item types in turn, below.
+
+@cindex numbers, written-out
+@cindex ordinal numbers
+@findex first @r{in date strings}
+@findex next @r{in date strings}
+@findex last @r{in date strings}
+A few numbers may be written out in words in most contexts. This is
+most useful for specifying day of the week items or relative items (see
+below). Here is the list: @samp{first} for 1, @samp{next} for 2,
+@samp{third} for 3, @samp{fourth} for 4, @samp{fifth} for 5,
+@samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
+@samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
+@samp{twelfth} for 12. Also, @samp{last} means exactly @math{-1}.
+
+@cindex months, written-out
+When a month is written this way, it is still considered to be written
+numerically, instead of being ``spelled in full''; this changes the
+allowed strings.
+
+@cindex case, ignored in dates
+@cindex comments, in dates
+Alphabetic case is completely ignored in dates. Comments may be introduced
+between round parentheses, as long as included parentheses are properly
+nested. Hyphens not followed by a digit are currently ignored. Leading
+zeros on numbers are ignored.
+
+
+@node Calendar date item, Time of day item, General date syntax, Date input formats
+@section Calendar date item
+
+@cindex calendar date item
+
+A @dfn{calendar date item} specifies a day of the year. It is
+specified differently, depending on whether the month is specified
+numerically or literally. All these strings specify the same calendar date:
+
+@example
+1970-09-17 # ISO 8601.
+70-9-17 # This century assumed by default.
+70-09-17 # Leading zeros are ignored.
+9/17/72 # Common U.S. writing.
+24 September 1972
+24 Sept 72 # September has a special abbreviation.
+24 Sep 72 # Three-letter abbreviations always allowed.
+Sep 24, 1972
+24-sep-72
+24sep72
+@end example
+
+The year can also be omitted. In this case, the last specified year is
+used, or the current year if none. For example:
+
+@example
+9/17
+sep 17
+@end example
+
+Here are the rules.
+
+@cindex ISO 8601 date format
+@cindex date format, ISO 8601
+For numeric months, the ISO 8601 format
+@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
+any positive number, @var{month} is a number between 01 and 12, and
+@var{day} is a number between 01 and 31. A leading zero must be present
+if a number is less than ten. If @var{year} is less than 100, then 1900
+is added to it to force a date in this century. The construct
+@samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
+is accepted. Also @samp{@var{month}/@var{day}}, omitting the year.
+
+@cindex month names in date strings
+@cindex abbreviations for months
+Literal months may be spelled out in full: @samp{January},
+@samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
+@samp{July}, @samp{August}, @samp{September}, @samp{October},
+@samp{November} or @samp{December}. Literal months may be abbreviated
+to their first three letters, possibly followed by an abbreviating dot.
+It is also permitted to write @samp{Sept} instead of @samp{September}.
+
+When months are written literally, the calendar date may be given as any
+of the following:
+
+@example
+@var{day} @var{month} @var{year}
+@var{day} @var{month}
+@var{month} @var{day} @var{year}
+@var{day}-@var{month}-@var{year}
+@end example
+
+Or, omitting the year:
+
+@example
+@var{month} @var{day}
+@end example
+
+
+@node Time of day item, Timezone item, Calendar date item, Date input formats
+@section Time of day item
+
+@cindex time of day item
+
+A @dfn{time of day item} in date strings specifies the time on a given
+day. Here are some examples, all of which represent the same time:
+
+@example
+20:02:0
+20:02
+8:02pm
+20:02-0500 # In EST (Eastern U.S. Standard Time).
+@end example
+
+More generally, the time of the day may be given as
+@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
+a number between 0 and 23, @var{minute} is a number between 0 and
+59, and @var{second} is a number between 0 and 59. Alternatively,
+@samp{:@var{second}} can be omitted, in which case it is taken to
+be zero.
+
+@findex am @r{in date strings}
+@findex pm @r{in date strings}
+@findex midnight @r{in date strings}
+@findex noon @r{in date strings}
+If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
+or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
+@samp{:@var{minute}} may be omitted (taken to be zero). @samp{am}
+indicates the first half of the day, @samp{pm} indicates the second
+half of the day. In this notation, 12 is the predecessor of 1:
+midnight is @samp{12am} while noon is @samp{12pm}.
+
+@cindex timezone correction
+@cindex minutes, timezone correction by
+The time may alternatively be followed by a timezone correction,
+expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
+or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
+of zone minutes. When a timezone correction is given this way, it
+forces interpretation of the time in UTC, overriding any previous
+specification for the timezone or the local timezone. The @var{minute}
+part of the time of the day may not be elided when a timezone correction
+is used. This is the only way to specify a timezone correction by
+fractional parts of an hour.
+
+Either @samp{am}/@samp{pm} or a timezone correction may be specified,
+but not both.
+
+
+@node Timezone item, Day of week item, Time of day item, Date input formats
+@section Timezone item
+
+@cindex timezone item
+
+A @dfn{timezone item} specifies an international timezone, indicated by
+a small set of letters. Any included period is ignored. Military
+timezone designations use a single letter. Currently, only integral
+zone hours may be represented in a timezone item. See the previous
+section for a finer control over the timezone correction.
+
+Here are many non-daylight-savings-time timezones, indexed by the zone
+hour value.
+
+@table @asis
+@item +000
+@cindex Greenwich Mean Time
+@cindex Universal Coordinated Time
+@cindex Western European Time
+@samp{GMT} for Greenwich Mean, @samp{UT} or @samp{UTC} for Universal
+(Coordinated), @samp{WET} for Western European and @samp{Z} for
+militaries.
+@item +100
+@cindex West African Time
+@samp{WAT} for West Africa and
+@samp{A} for militaries.
+@item +200
+@cindex Azores Time
+@samp{AT} for Azores and @samp{B} for militaries.
+@item +300
+@samp{C} for militaries.
+@item +400
+@cindex Atlantic Standard Time
+@samp{AST} for Atlantic Standard and @samp{D} for militaries.
+@item +500
+@cindex Eastern Standard Time
+@samp{E} for militaries and @samp{EST} for Eastern Standard.
+@item +600
+@cindex Central Standard Time
+@samp{CST} for Central Standard and @samp{F} for militaries.
+@item +700
+@cindex Mountain Standard Time
+@samp{G} for militaries and @samp{MST} for Mountain Standard.
+@item +800
+@cindex Pacific Standard Time
+@samp{H} for militaries and @samp{PST} for Pacific Standard.
+@item +900
+@cindex Yukon Standard Time
+@samp{I} for militaries and @samp{YST} for Yukon Standard.
+@item +1000
+@cindex Alaska-Hawaii Time
+@cindex Central Alaska Time
+@cindex Hawaii Standard Time
+@samp{AHST} for Alaska-Hawaii Standard, @samp{CAT} for Central Alaska,
+@samp{HST} for Hawaii Standard and @samp{K} for militaries.
+@item +1100
+@cindex Nome Standard Time
+@samp{L} for militaries and @samp{NT} for Nome.
+@item +1200
+@cindex International Date Line West
+@samp{IDLW} for International Date Line West and @samp{M} for
+militaries.
+@item -100
+@cindex Central European Time
+@cindex Middle European Time
+@cindex Middle European Winter Time
+@cindex French Winter Time
+@cindex Swedish Winter Time
+@samp{CET} for Central European, @samp{FWT} for French Winter,
+@samp{MET} for Middle European, @samp{MEWT} for Middle European
+Winter, @samp{N} for militaries and @samp{SWT} for Swedish Winter.
+@item -200
+@cindex Eastern European Time
+@cindex USSR Zone
+@samp{EET} for Eastern European, USSR Zone 1 and @samp{O} for militaries.
+@item -300
+@cindex Baghdad Time
+@samp{BT} for Baghdad, USSR Zone 2 and @samp{P} for militaries.
+@item -400
+@samp{Q} for militaries and @samp{ZP4} for USSR Zone 3.
+@item -500
+@samp{R} for militaries and @samp{ZP5} for USSR Zone 4.
+@item -600
+@samp{S} for militaries and @samp{ZP6} for USSR Zone 5.
+@item -700
+@cindex West Australian Standard Time
+@samp{T} for militaries and @samp{WAST} for West Australian Standard.
+@item -800
+@cindex China Coast Time
+@samp{CCT} for China Coast, USSR Zone 7 and @samp{U} for militaries.
+@item -900
+@cindex Japan Standard Time
+@samp{JST} for Japan Standard, USSR Zone 8 and @samp{V} for militaries.
+@item -1000
+@cindex East Australian Standard Time
+@cindex Guam Standard Time
+@samp{EAST} for East Australian Standard, @samp{GST} for Guam
+Standard, USSR Zone 9 and @samp{W} for militaries.
+@item -1100
+@samp{X} for militaries.
+@item -1200
+@cindex International Date Line East
+@cindex New Zealand Standard Time
+@samp{IDLE} for International Date Line East, @samp{NZST} for
+New Zealand Standard, @samp{NZT} for New Zealand and @samp{Y} for
+militaries.
+@end table
+
+@cindex daylight savings time
+Here are many DST timezones, indexed by the zone hour value. Also, by
+following a non-DST timezone by the string @samp{DST} in a separate word
+(that is, separated by some whitespace), the corresponding DST timezone
+may be specified.
+
+@table @asis
+@item 0
+@samp{BST} for British Summer.
+@item +400
+@samp{ADT} for Atlantic Daylight.
+@item +500
+@samp{EDT} for Eastern Daylight.
+@item +600
+@samp{CDT} for Central Daylight.
+@item +700
+@samp{MDT} for Mountain Daylight.
+@item +800
+@samp{PDT} for Pacific Daylight.
+@item +900
+@samp{YDT} for Yukon Daylight.
+@item +1000
+@samp{HDT} for Hawaii Daylight.
+@item -100
+@samp{MEST} for Middle European Summer, @samp{MESZ} for Middle European
+Summer, @samp{SST} for Swedish Summer and @samp{FST} for French Summer.
+@item -700
+@samp{WADT} for West Australian Daylight.
+@item -1000
+@samp{EADT} for Eastern Australian Daylight.
+@item -1200
+@samp{NZDT} for New Zealand Daylight.
+@end table
+
+
+@node Day of week item, Relative item in date strings, Timezone item, Date input formats
+@section Day of week item
+
+@cindex day of week item
+
+The explicit mention of a day of the week will forward the date
+(only if necessary) to reach that day of the week in the future.
+
+Days of the week may be spelled out in full: @samp{Sunday},
+@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
+@samp{Friday} or @samp{Saturday}. Days may be abbreviated to their
+first three letters, optionally followed by a period. The special
+abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
+@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
+also allowed.
+
+@findex next @var{day}
+@findex last @var{day}
+A number may precede a day of the week item to move forward
+supplementary weeks. It is best used in expression like @samp{third
+monday}. In this context, @samp{last @var{day}} or @samp{next
+@var{day}} is also acceptable; they move one week before or after
+the day that @var{day} by itself would represent.
+
+A comma following a day of the week item is ignored.
+
+
+@node Relative item in date strings, Pure numbers in date strings, Day of week item, Date input formats
+@section Relative item in date strings
+
+@cindex relative items in date strings
+@cindex displacement of dates
+
+@dfn{Relative items} adjust a date (or the current date if none) forward
+or backward. The effects of relative items accumulate. Here are some
+examples:
+
+@example
+1 year
+1 year ago
+3 years
+2 days
+@end example
+
+@findex year @r{in date strings}
+@findex month @r{in date strings}
+@findex fortnight @r{in date strings}
+@findex week @r{in date strings}
+@findex day @r{in date strings}
+@findex hour @r{in date strings}
+@findex minute @r{in date strings}
+The unit of time displacement may be selected by the string @samp{year}
+or @samp{month} for moving by whole years or months. These are fuzzy
+units, as years and months are not all of equal duration. More precise
+units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
+days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
+@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
+@samp{sec} worth one second. An @samp{s} suffix on these units is
+accepted and ignored.
+
+@findex ago @r{in date strings}
+The unit of time may be preceded by a multiplier, given as an optionally
+signed number. Unsigned numbers are taken as positively signed. No
+number at all implies 1 for a multiplier. Following a relative item by
+the string @samp{ago} is equivalent to preceding the unit by a
+multiplicator with value @math{-1}.
+
+@findex day @r{in date strings}
+@findex tomorrow @r{in date strings}
+@findex yesterday @r{in date strings}
+The string @samp{tomorrow} is worth one day in the future (equivalent
+to @samp{day}), the string @samp{yesterday} is worth
+one day in the past (equivalent to @samp{day ago}).
+
+@findex now @r{in date strings}
+@findex today @r{in date strings}
+@findex this @r{in date strings}
+The strings @samp{now} or @samp{today} are relative items corresponding
+to zero-valued time displacement, these strings come from the fact
+a zero-valued time displacement represents the current time when not
+otherwise change by previous items. They may be used to stress other
+items, like in @samp{12:00 today}. The string @samp{this} also has
+the meaning of a zero-valued time displacement, but is preferred in
+date strings like @samp{this thursday}.
+
+When a relative item makes the resulting date to cross the boundary
+between DST and non-DST (or vice-versa), the hour is adjusted according
+to the local time.
+
+
+@node Pure numbers in date strings, Authors of getdate, Relative item in date strings, Date input formats
+@section Pure numbers in date strings
+
+@cindex pure numbers in date strings
+
+The precise intepretation of a pure decimal number is dependent of
+the context in the date string.
+
+If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
+other calendar date item (@pxref{Calendar date item}) appears before it
+in the date string, then @var{yyyy} is read as the year, @var{mm} as the
+month number and @var{dd} as the day of the month, for the specified
+calendar date.
+
+If the decimal number is of the form @var{hh}@var{mm} and no other time
+of day item appears before it in the date string, then @var{hh} is read
+as the hour of the day and @var{mm} as the minute of the hour, for the
+specified time of the day. @var{mm} can also be omitted.
+
+If both a calendar date and a time of day appear to the left of a number
+in the date string, but no relative item, then the number overrides the
+year.
+
+
+@node Authors of getdate, , Pure numbers in date strings, Date input formats
+@section Authors of @code{getdate}
+
+@cindex authors of @code{getdate}
+
+@cindex Bellovin, Steven M.
+@cindex Salz, Rich
+@cindex Berets, Jim
+@cindex MacKenzie, David
+@cindex Meyering, Jim
+@code{getdate} was originally implemented by Steven M. Bellovin
+(@samp{smb@@research.att.com}) while at the University of North Carolina
+at Chapel Hill. The code was later tweaked by a couple of people on
+Usenet, then completely overhauled by Rich $alz (@samp{rsalz@@bbn.com})
+and Jim Berets (@samp{jberets@@bbn.com}) in August, 1990. Various
+revisions for the GNU system were made by David MacKenzie, Jim Meyering,
+and others.
+
+@cindex Pinard, F.
+@cindex Berry, K.
+This chapter was originally produced by Fran@,{c}ois Pinard
+(@samp{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
+and then edited by K.@: Berry (@samp{kb@@cs.umb.edu}).
+
+@node Formats, Media, Date input formats, Top
+@chapter Controlling the Archive Format
+
+@FIXME{need an intro here}
+
+@menu
+* Portability:: Making @code{tar} Archives More Portable
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Standard:: The Standard Format
+* Extensions:: GNU Extensions to the Archive Format
+* cpio:: Comparison of @code{tar} and @code{cpio}
+@end menu
+
+@node Portability, Compression, Formats, Formats
+@section Making @code{tar} Archives More Portable
+
+Creating a @code{tar} archive on a particular system that is meant to be
+useful later on many other machines and with other versions of @code{tar}
+is more challenging than you might think. @code{tar} archive formats
+have been evolving since the first versions of Unix. Many such formats
+are around, and are not always comptible with each other. This section
+discusses a few problems, and gives some advice about making @code{tar}
+archives more portable.
+
+One golden rule is simplicity. For example, limit your @code{tar}
+archives to contain only regular files and directories, avoiding
+other kind of special files. Do not attempt to save sparse files or
+contiguous files as such. Let's discuss a few more problems, in turn.
+
+@menu
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* old:: Old V7 Archives
+* posix:: POSIX archives
+* Checksumming:: Checksumming Problems
+@end menu
+
+@node Portable Names, dereference, Portability, Portability
+@subsection Portable Names
+
+Use @emph{straight} file and directory names, made up of printable
+ASCII characters, avoiding colons, slashes, backslashes, spaces, and
+other @emph{dangerous} characters. Avoid deep directory nesting.
+Accounting for oldish System V machines, limit your file and directory
+names to 14 characters or less.
+
+If you intend to have your @code{tar} archives to be read under MSDOS,
+you should not rely on case distinction for file names, and you might
+use the GNU @code{doschk} program for helping you further diagnosing
+illegal MSDOS names, which are even more limited than System V's.
+
+@node dereference, old, Portable Names, Portability
+@subsection Symbolic Links
+@cindex File names, using symbolic links
+@cindex Symbolic link as file name
+
+Normally, when @code{tar} archives a symbolic link, it writes a
+block to the archive naming the target of the link. In that way, the
+@code{tar} archive is a faithful record of the filesystem contents.
+@value{op-dereference} is used with @value{op-create}, and causes @code{tar}
+to archive the files symbolic links point to, instead of the links
+themselves. When this option is used, when @code{tar} encounters a
+symbolic link, it will archive the linked-to file, instead of simply
+recording the presence of a symbolic link.
+
+The name under which the file is stored in the file system is not
+recorded in the archive. To record both the symbolic link name and
+the file name in the system, archive the file under both names. If
+all links were recorded automatically by @code{tar}, an extracted file
+might be linked to a file name that no longer exists in the file
+system.
+
+If a linked-to file is encountered again by @code{tar} while creating
+the same archive, an entire second copy of it will be stored. (This
+@emph{might} be considered a bug.)
+
+So, for portable archives, do not archive symbolic links as such,
+and use @value{op-dereference}: many systems do not support
+symbolic links, and moreover, your distribution might be unusable if
+it contains unresolved symbolic links.
+
+@node old, posix, dereference, Portability
+@subsection Old V7 Archives
+@cindex Format, old style
+@cindex Old style format
+@cindex Old style archives
+
+Certain old versions of @code{tar} cannot handle additional
+information recorded by newer @code{tar} programs. To create an
+archive in V7 format (not ANSI), which can be read by these old
+versions, specify the @value{op-old-archive} option in
+conjunction with the @value{op-create}. @code{tar} also
+accepts @samp{--portability} for this option. When you specify it,
+@code{tar} leaves out information about directories, pipes, fifos,
+contiguous files, and device files, and specifies file ownership by
+group and user IDs instead of group and user names.
+
+When updating an archive, do not use @value{op-old-archive}
+unless the archive was created with using this option.
+
+In most cases, a @emph{new} format archive can be read by an @emph{old}
+@code{tar} program without serious trouble, so this option should
+seldom be needed. On the other hand, most modern @code{tar}s are
+able to read old format archives, so it might be safer for you to
+always use @value{op-old-archive} for your distributions.
+
+@node posix, Checksumming, old, Portability
+@subsection GNU @code{tar} and POSIX @code{tar}
+
+GNU @code{tar} was based on an early draft of the POSIX 1003.1
+@code{ustar} standard. GNU extensions to @code{tar}, such as the
+support for file names longer than 100 characters, use portions of the
+@code{tar} header record which were specified in that POSIX draft as
+unused. Subsequent changes in POSIX have allocated the same parts of
+the header record for other purposes. As a result, GNU @code{tar} is
+incompatible with the current POSIX spec, and with @code{tar} programs
+that follow it.
+
+We plan to reimplement these GNU extensions in a new way which is
+upward compatible with the latest POSIX @code{tar} format, but we
+don't know when this will be done.
+
+In the mean time, there is simply no telling what might happen if you
+read a GNU @code{tar} archive, which uses the GNU extensions, using
+some other @code{tar} program. So if you want to read the archive
+with another @code{tar} program, be sure to write it using the
+@samp{--old-archive} option (@samp{-o}).
+
+@FIXME{is there a way to tell which flavor of tar was used to write a
+particular archive before you try to read it?}
+
+Traditionally, old @code{tar}s have a limit of 100 characters. GNU
+@code{tar} attempted two different approaches to overcome this limit,
+using and extending a format specified by a draft of some P1003.1.
+The first way was not that successful, and involved @file{@@MaNgLeD@@}
+file names, or such; while a second approach used @file{././@@LongLink}
+and other tricks, yielding better success. In theory, GNU @code{tar}
+should be able to handle file names of practically unlimited length.
+So, if GNU @code{tar} fails to dump and retrieve files having more
+than 100 characters, then there is a bug in GNU @code{tar}, indeed.
+
+But, being strictly POSIX, the limit was still 100 characters.
+For various other purposes, GNU @code{tar} used areas left unassigned
+in the POSIX draft. POSIX later revised P1003.1 @code{ustar} format by
+assigning previously unused header fields, in such a way that the upper
+limit for file name length was raised to 256 characters. However, the
+actual POSIX limit oscillates between 100 and 256, depending on the
+precise location of slashes in full file name (this is rather ugly).
+Since GNU @code{tar} use the same fields for quite other purposes,
+it became incompatible with the latest POSIX standards.
+
+For longer or non-fitting file names, we plan to use yet another set
+of GNU extensions, but this time, complying with the provisions POSIX
+offers for extending the format, rather than conflicting with it.
+Whenever an archive uses old GNU @code{tar} extension format or POSIX
+extensions, would it be for very long file names or other specialities,
+this archive becomes non-portable to other @code{tar} implementations.
+In fact, anything can happen. The most forgiving @code{tar}s will
+merely unpack the file using a wrong name, and maybe create another
+file named something like @file{@@LongName}, with the true file name
+in it. @code{tar}s not protecting themselves may segment violate!
+
+Compatibility concerns make all this thing more difficult, as we
+will have to support @emph{all} these things together, for a while.
+GNU @code{tar} should be able to produce and read true POSIX format
+files, while being able to detect old GNU @code{tar} formats, besides
+old V7 format, and process them conveniently. It would take years
+before this whole area stabilizes@dots{}
+
+There are plans to raise this 100 limit to 256, and yet produce POSIX
+conformant archives. Past 256, I do not know yet if GNU @code{tar}
+will go non-POSIX again, or merely refuse to archive the file.
+
+There are plans so GNU @code{tar} support more fully the latest POSIX
+format, while being able to read old V7 format, GNU (semi-POSIX plus
+extension), as well as full POSIX. One may ask if there is part of
+the POSIX format that we still cannot support. This simple question
+has a complex answer. Maybe that, on intimate look, some strong
+limitations will pop up, but until now, nothing sounds too difficult
+(but see below). I only have these few pages of POSIX telling about
+`Extended tar Format' (P1003.1-1990 -- section 10.1.1), and there are
+references to other parts of the standard I do not have, which should
+normally enforce limitations on stored file names (I suspect things
+like fixing what @kbd{/} and @kbd{@key{NUL}} means). There are also
+some points which the standard does not make clear, Existing practice
+will then drive what I should do.
+
+POSIX mandates that, when a file name cannot fit within 100 to
+256 characters (the variance comes from the fact a @kbd{/} is
+ideally needed as the 156'th character), or a link name cannot
+fit within 100 characters, a warning should be issued and the file
+@emph{not} be stored. Unless some @value{op-posix} option is given
+(or @code{POSIXLY_CORRECT} is set), I suspect that GNU @code{tar}
+should disobey this specification, and automatically switch to using
+GNU extensions to overcome file name or link name length limitations.
+
+There is a problem, however, which I did not intimately studied yet.
+Given a truly POSIX archive with names having more than 100 characters,
+I guess that GNU @code{tar} up to 1.11.8 will process it as if it were an
+old V7 archive, and be fooled by some fields which are coded differently.
+So, the question is to decide if the next generation of GNU @code{tar}
+should produce POSIX format by default, whenever possible, producing
+archives older versions of GNU @code{tar} might not be able to read
+correctly. I fear that we will have to suffer such a choice one of these
+days, if we want GNU @code{tar} to go closer to POSIX. We can rush it.
+Another possibility is to produce the current GNU @code{tar} format
+by default for a few years, but have GNU @code{tar} versions from some
+1.@var{POSIX} and up able to recognize all three formats, and let older
+GNU @code{tar} fade out slowly. Then, we could switch to producing POSIX
+format by default, with not much harm to those still having (very old at
+that time) GNU @code{tar} versions prior to 1.@var{POSIX}.
+
+POSIX format cannot represent very long names, volume headers,
+splitting of files in multi-volumes, sparse files, and incremental
+dumps; these would be all disallowed if @value{op-posix} or
+@code{POSIXLY_CORRECT}. Otherwise, if @code{tar} is given long
+names, or @samp{-[VMSgG]}, then it should automatically go non-POSIX.
+I think this is easily granted without much discussion.
+
+Another point is that only @code{mtime} is stored in POSIX
+archives, while GNU @code{tar} currently also store @code{atime}
+and @code{ctime}. If we want GNU @code{tar} to go closer to POSIX,
+my choice would be to drop @code{atime} and @code{ctime} support on
+average. On the other hand, I perceive that full dumps or incremental
+dumps need @code{atime} and @code{ctime} support, so for those special
+applications, POSIX has to be avoided altogether.
+
+A few users requested that @value{op-sparse} be always active by
+default, I think that before replying to them, we have to decide
+if we want GNU @code{tar} to go closer to POSIX on average, while
+producing files. My choice would be to go closer to POSIX in the
+long run. Besides possible double reading, I do not see any point
+of not trying to save files as sparse when creating archives which
+are neither POSIX nor old-V7, so the actual @value{op-sparse} would
+become selected by default when producing such archives, whatever
+the reason is. So, @value{op-sparse} alone might be redefined to force
+GNU-format archives, and recover its previous meaning from this fact.
+
+GNU-format as it exists now can easily fool other POSIX @code{tar},
+as it uses fields which POSIX considers to be part of the file name
+prefix. I wonder if it would not be a good idea, in the long run,
+to try changing GNU-format so any added field (like @code{ctime},
+@code{atime}, file offset in subsequent volumes, or sparse file
+descriptions) be wholly and always pushed into an extension block,
+instead of using space in the POSIX header block. I could manage
+to do that portably between future GNU @code{tar}s. So other POSIX
+@code{tar}s might be at least able to provide kind of correct listings
+for the archives produced by GNU @code{tar}, if not able to process
+them otherwise.
+
+Using these projected extensions might induce older @code{tar}s to fail.
+We would use the same approach as for POSIX. I'll put out a @code{tar}
+capable of reading POSIXier, yet extended archives, but will not produce
+this format by default, in GNU mode. In a few years, when newer GNU
+@code{tar}s will have flooded out @code{tar} 1.11.X and previous, we
+could switch to producing POSIXier extended archives, with no real harm
+to users, as almost all existing GNU @code{tar}s will be ready to read
+POSIXier format. In fact, I'll do both changes at the same time, in a
+few years, and just prepare @code{tar} for both changes, without effecting
+them, from 1.@var{POSIX}. (Both changes: 1---using POSIX convention for
+getting over 100 characters; 2---avoiding mangling POSIX headers for GNU
+extensions, using only POSIX mandated extension techniques).
+
+So, a future @code{tar} will have a @value{op-posix}
+flag forcing the usage of truly POSIX headers, and so, producing
+archives previous GNU @code{tar} will not be able to read.
+So, @emph{once} pretest will announce that feature, it would be
+particularly useful that users test how exchangeable will be archives
+between GNU @code{tar} with @value{op-posix} and other POSIX @code{tar}.
+
+In a few years, when GNU @code{tar} will produce POSIX headers by
+default, @value{op-posix} will have a strong meaning and will disallow
+GNU extensions. But in the meantime, for a long while, @value{op-posix}
+in GNU tar will not disallow GNU extensions like @value{op-label},
+@value{op-multi-volume}, @value{op-sparse}, or very long file or link names.
+However, @value{op-posix} with GNU extensions will use POSIX
+headers with reserved-for-users extensions to headers, and I will be
+curious to know how well or bad POSIX @code{tar}s will react to these.
+
+GNU @code{tar} prior to 1.@var{POSIX}, and after 1.@var{POSIX} without
+@value{op-posix}, generates and checks @samp{ustar@w{ }@w{ }}, with two
+suffixed spaces. This is sufficient for older GNU @code{tar} not to
+recognize POSIX archives, and consequently, wrongly decide those archives
+are in old V7 format. It is a useful bug for me, because GNU @code{tar}
+has other POSIX incompatibilities, and I need to segregate GNU @code{tar}
+semi-POSIX archives from truly POSIX archives, for GNU @code{tar} should
+be somewhat compatible with itself, while migrating closer to latest
+POSIX standards. So, I'll be very careful about how and when I will do
+the correction.
+
+@node Checksumming, , posix, Portability
+@subsection Checksumming Problems
+
+SunOS and HP-UX @code{tar} fail to accept archives created using GNU
+@code{tar} and containing non-ASCII file names, that is, file names
+having characters with the eight bit set, because they use signed
+checksums, while GNU @code{tar} uses unsigned checksums while creating
+archives, as per POSIX standards. On reading, GNU @code{tar} computes
+both checksums and accept any. It is somewhat worrying that a lot of
+people may go around doing backup of their files using faulty (or at
+least non-standard) software, not learning about it until it's time
+to restore their missing files with an incompatible file extractor,
+or vice versa.
+
+GNU @code{tar} compute checksums both ways, and accept any on read,
+so GNU tar can read Sun tapes even with their wrong checksums.
+GNU @code{tar} produces the standard checksum, however, raising
+incompatibilities with Sun. That is to say, GNU @code{tar} has not
+been modified to @emph{produce} incorrect archives to be read by buggy
+@code{tar}'s. I've been told that more recent Sun @code{tar} now
+read standard archives, so maybe Sun did a similar patch, after all?
+
+The story seems to be that when Sun first imported @code{tar}
+sources on their system, they recompiled it without realizing that
+the checksums were computed differently, because of a change in
+the default signing of @code{char}'s in their compiler. So they
+started computing checksums wrongly. When they later realized their
+mistake, they merely decided to stay compatible with it, and with
+themselves afterwards. Presumably, but I do not really know, HP-UX
+has chosen that their @code{tar} archives to be compatible with Sun's.
+The current standards do not favor Sun @code{tar} format. In any
+case, it now falls on the shoulders of SunOS and HP-UX users to get
+a @code{tar} able to read the good archives they receive.
+
+@node Compression, Attributes, Portability, Formats
+@section Using Less Space through Compression
+
+@menu
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
+@end menu
+
+@node gzip, sparse, Compression, Compression
+@subsection Creating and Reading Compressed Archives
+@cindex Compressed archives
+@cindex Storing archives in compressed format
+@UNREVISED
+
+@table @kbd
+@item -z
+@itemx --gzip
+@itemx --ungzip
+Filter the archive through @code{gzip}.
+@end table
+
+@FIXME{ach; these two bits orig from "compare" (?). where to put?} Some
+format parameters must be taken into consideration when modifying an
+archive: @FIXME{???}. Compressed archives cannot be modified.
+
+You can use @samp{--gzip} and @samp{--gunzip} on physical devices
+(tape drives, etc.) and remote files as well as on normal files; data
+to or from such devices or remote files is reblocked by another copy
+of the @code{tar} program to enforce the specified (or default) record
+size. The default compression parameters are used; if you need to
+override them, avoid the @value{op-gzip} option and run @code{gzip}
+explicitly. (Or set the @samp{GZIP} environment variable.)
+
+The @value{op-gzip} option does not work with the @value{op-multi-volume}
+option, or with the @value{op-update}, @value{op-append},
+@value{op-concatenate}, or @value{op-delete} operations.
+
+It is not exact to say that GNU @code{tar} is to work in concert
+with @code{gzip} in a way similar to @code{zip}, say. Surely, it is
+possible that @code{tar} and @code{gzip} be done with a single call,
+like in:
+
+@example
+$ @kbd{tar cfz archive.tar.gz subdir}
+@end example
+
+@noindent
+to save all of @samp{subdir} into a @code{gzip}'ed archive. Later you
+can do:
+
+@example
+$ @kbd{tar xfz archive.tar.gz}
+@end example