+@chapter Basic @code{tar} Operations
+
+This chapter describes the basic operations supported by the @code{tar}
+program. A given invocation of @code{tar} will do exactly one of these
+operations.
+
+@section Creating a New Archive
+
+The @samp{--create} (@code{-c}) option causes @code{tar} to create a new
+archive. The files to be archived are then named on the command line.
+Each file will be added to the archive with a member name exactly the
+same as the name given on the command line. (When you give an absolute
+file name @code{tar} actually modifies it slightly, @ref{Absolute
+Paths}.) If you list no files to be archived, then an empty archive is
+created.
+
+If there are two many files to conveniently list on the command line,
+you can list the names in a file, and @code{tar} will read that file.
+@xref{Reading Names from a File}.
+
+If you name a directory, then @code{tar} will archive not only the
+directory, but all its contents, recursively. For example, if you name
+@file{/}, then @code{tar} will archive the entire filesystem.
+
+Do not use the option to add files to an existing archive; it will
+delete the archive and write a new one. Use @samp{--append} instead.
+(@xref{Adding to an Existing Archive}.)
+
+There are various ways of causing @code{tar} to skip over some files,
+and not archive them. @xref{Specifying Names to @code{tar}}.
+
+@section Adding to an Existing Archive
+
+The @samp{--append} (@code{-r}) option will case @code{tar} to add new
+files to an existing archive. It interprets file names and member names
+in exactly the same manner as @samp{--create}. Nothing happens if you
+don't list any names.
+
+This option never deletes members. If a new member is added under the
+same name as an existing member, then both will be in the archive, with
+the new member after the old one. For information on how this affects
+reading the archive, @ref{Multiple Members with the Same Name}.
+
+This operation cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats thoes tape drives use.
+
+@section Combining Archives
+
+The @samp{--catenate} (or @code{--concatenate}, or @code{-A}) causes
+@code{tar} to add the contents of several archives to an existing
+archive.
+
+Name the archives to be catenated on the command line. (Nothing happens
+if you don't list any.) The members, and their member names, will be
+copied verbatim from those archives. If this causes multiple members to
+have the same name, it does not delete either; all the members with the
+same name coexist. For information on how this affects reading the
+archive, @ref{Multiple Members with the Same Name}.
+
+You must use this option to concatenate archives. If you just combine
+them with @code{cat}, the result will not be a valid @code{tar} format
+archive.
+
+This operation cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats thoes tape drives use.
+
+@section Removing Archive Members
+
+You can use the @samp{--delete} option to remove members from an
+archive. Name the members on the command line to be deleted. This
+option will rewrite the archive; because of this, it does not work on
+tape drives. If you list no members to be deleted, nothing happens.
+
+@section Listing Archive Members
+
+The @samp{--list} (@samp{-t}) option will list the names of members of
+the archive. Name the members to be listed on the command line (to
+modify the way these names are interpreted, @pxref{Specifying Names to
+@code{tar}}). If you name no members, then @samp{--list} will list the
+names of all the members of the archive.
+
+To see more than just the names of the members, use the @samp{--verbose}
+option to cause @code{tar} to print out a listing similar to that of
+@samp{ls -l}.
+
+@section Extracting Archive Members
+
+Use @samp{--extract} (or @samp{--get}, or @samp{-x}) to extract members
+from an archive. For each member named (or for the entire archive if no
+members are named) on the command line (or with @samp{--files-from}) the
+a file is created with the contents of the archive member. The name of
+the file is the same as the member name.
+
+Various options cause @code{tar} to extract more than just file
+contents, such as the owner, the permissions, the modification date, and
+so forth.
+
+XXX
+The @samp{--same-permissions} (or @samp{--preserve-permissions}, or
+@samp{-p}) options cause @code{tar} to cause the new file to have the
+same permissions as the original file did when it was placed in the
+archive. Without this option, the current @code{umask} is used to
+affect the permissions.
+
+When extrating, @code{tar} normally sets the modification time of the
+file to the value recorded in the archive. The
+@samp{--modification-time} option causes @code{tar} to omit doing this.
+XXX
+
+@section Updating an Archive
+
+The @samp{--update} (or @samp{-u}) option updates a @code{tar} archive
+by comparing the date of the specified archive members against the date
+of the file with the same name. If the file has been modified more
+recently than the archive member, then the archive member is deleted (as
+with @samp{--delete}) and then the file is added to the archive (as with
+@samp{--append}). On media where the @samp{--delete} option cannot be
+performed (such as magnetic tapes), the @samp{--update} option similarly
+fails.
+
+If no archive members are named (either on the command line or via
+@samp{--files-from}), then the entire archive is processed in this
+manner.
+
+@section Comparing Archives Members with Files
+
+The @samp{--compare} (or @samp{--diff}, or @samp{-d}) option compares
+the contents of the specified archive members against the files with the
+same names, and reports its findings. If no members are named on the
+command line (or through @samp{--files-from}), then the entire archive
+is so compared.
+
+@chapter Specifying Names to @code{tar}
+
+When specifying the names of files or members to @code{tar}, it by
+default takes the names of the files from the command line. There are
+other ways, however, to specify file or member names, or to modify the
+manner in which @code{tar} selects the files or members upon which to
+operate. In general, these methods work both for specifying the names
+of files and archive members.
+
+@section Reading Names from a File
+
+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
+@samp{--files-from=@var{file-name-list}} (@samp{-T
+@var{file-name-list}}) option to @code{tar}. Give the name of the file
+which contains the list as the argument to @samp{--files-from}. The
+file names should be separated by newlines in the list. If you give a
+single dash as a filename for @samp{--files-from} (that is, you specify
+@samp{--files-from=-} or @samp{-T -}), then the filenames are read from
+standard input.
+
+If you want to specify names that might contain newlines, use the
+@samp{--null} option. Then, the filenames should be separated by NUL
+characters (ASCII 000) instead of newlines. In addition, the
+@samp{--null} option turns off the @samp{-C} option (@pxref{Changing
+Directory}).
+
+@section Excluding Some Files
+
+The @samp{--exclude=@var{pattern}} option will prevent any file or
+member which matches the regular expression @var{pattern} from being
+operated on. 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}.
+
+If there are many files you want to exclude, you can use the
+@samp{--exclude-from=@var{exclude-list}} (@samp{-X @var{exclude-list}})
+option. This works just like the
+@samp{--files-from=@var{file-name-list}} option: specify the name of a
+file as @var{exclude-list} which contains the list of patterns you want
+to exclude.
+
+@xref{Regular Expressions} for more information on the syntax and
+meaning of regular expressions.
+
+@section Operating Only on New Files
+
+The @samp{--newer=@var{date}} (@samp{--after-date=@var{date}} or
+@samp{-N @var{date}}) limits @code{tar} to only operating on files which
+have been modified after the date specified. (For more information on
+how to specify a date, @xref{Date Formats}.) A file is considered to
+have changed if the contents have been modified, or if the owner,
+permissions, and so forth, have been changed.
+
+If you only want @code{tar} make the date comparison on the basis of the
+actual contents of the file's modification, then use the
+@samp{--newer-mtime=@var{date}} option.
+
+You should never use this option for making incremental dumps. To learn
+how to use @code{tar} to make backups, @ref{Making Backups}.
+
+@section Crossing Filesystem Boundaries
+
+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
+(because it is a mounted filesystem in its own right), then @code{tar}
+will not archive that file, or (if it is a directory itself) anything
+beneath it.
+
+This does not necessarily limit @code{tar} to only archiving the
+contents of a single filesystem, because all files named on the command
+line (or through the @samp{--files-from} option) will always be
+archived.
+
+@chapter Changing the Names of Members when Archiving
+
+@section Changing Directory
+
+The @samp{--directory=@var{directory}} (@samp{-C @var{directory}})
+option causes @code{tar} to change its current working directory to
+@var{directory}. Unlike most options, this one is processed at the
+point it occurs within the list of files to be processed. Consider the
+following command:
+@example
+tar --create --file=foo.tar -C /etc passwd hosts -C /lib libc.a
+@end example
+
+This command will place the files @file{/etc/passwd}, @file{/etc/hosts},
+and @file{/lib/libc.a} into the archive. 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}. The @samp{--directory}
+option is frequently used to make the archive independent of the
+original name of the directory holding the files.
+
+Note that @samp{--directory} options are interpreted consecutively. If
+@samp{--directory} option specifies a relative pathname, 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.
+
+When using @samp{--files-from} (@pxref{Reading Names from a File}), 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 @samp{--null} option.)
+
+@section Absolute Path Names
+
+When @code{tar} extracts archive members from an archive, it strips any
+leading slashes (@code{/}) 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 an inferior @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 @samp{--absolute-paths} option, @code{tar} will do
+neither of these transformations.
+
+@section Symbolic Links
+
+Normally, when @code{tar} archives a symbolic link, it writes a record
+to the archive naming the target of the link. In that way, the
+@code{tar} archive is a faithful record of the filesystem contents.
+However, if you want @code{tar} to actually dump the contents of the
+target of the symbolic link, then use the @samp{--dereference} option.
+
+@chapter Making @code{tar} More Verbose
+
+Various options cause @code{tar} to print information as it progresses
+in its job.
+
+The @samp{--verbose} (or @samp{-v}) option causes @code{tar} to print
+the name of each archive member or file as it is processed. Since
+@samp{--list} already prints the names of the members, @samp{--verbose}
+used with @samp{--list} causes @code{tar} to print a longer listing
+(reminiscent of @samp{ls -l}) for each member.
+
+To see the progress of @code{tar} through the archive, the
+@samp{--record-number} option prints a message for each record read or
+writted. (@xref{Archive Structure}.) This option can be very helpful
+when trying to figure out where in the archive an error occurs.
+
+The @samp{--totals} option (which is only meaningful when used with
+@samp{--create}) causes @code{tar} to print the total amount written to
+the archive, after it has been fully created.
+
+The @samp{--checkpoint} option prints an occasional message as
+@code{tar} reads or writes the archive. It is designed for those who
+don't need the more detailed (and voluminous) output of
+@samp{--record-number}, but do want visual confirmation that @code{tar}
+is actually making forward progress.
+
+The @samp{--version} option will generate a message with the version of
+GNU @code{tar} you are using.
+
+@chapter Input and Output
+
+@section Changing the Archive Name
+
+By default, @code{tar} uses an archive file name compiled in when
+@code{tar} was built. Usually this refers to some physical tape drive
+on the machine. Often, the installer of @code{tar} didn't set the
+default to anything meaningful at all.
+
+As a result, most uses of @code{tar} need to tell @code{tar} where to
+find (or create) the archive. The @samp{--file=@var{archive-name}} (or
+@samp{-f @var{archive-name}} option selects another file to use as the
+archive.
+
+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 @code{/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 @samp{--force-local} option.
+
+If the filename you give to @samp{--file} is a single dash (@samp{-}),
+then @code{tar} will read the archive from (or write it to) standard
+input (or standard output).
+
+@section Extracting Members to Standard Output
+
+An archive member in normally extracted into a file with the same name
+as the archive member. However, you can use the @samp{--to-stdout} to
+cause @code{tar} to write extracted archive members to standard output.
+If you extract multiple members, they appear on standard output
+concatenated, in the order they are found in the archive.
+
+@section Dealing with Compressed Archives
+
+You can have archives be compressed by using the @samp{--gzip} (or
+@samp{-z}) option. This will arrange for @code{tar} to use the
+@code{gzip} program to be used to compress or uncompress the archive
+wren writing or reading it.
+
+To use the older, obsolete, @code{compress} program, use the
+@samp{--compress} (or @samp{-Z}) option. The GNU Project recommends you
+not use @code{compress}, because there is a patent covering the
+algorithm it uses. Merely by running @code{compress} you could be sued
+for patent infringment.
+
+When using either @samp{--gzip} or @samp{--compress}, @code{tar} does
+not do blocking (@pxref{Blocking}) correctly. Use @samp{--gzip-block}
+or @samp{--compress-block} instead when using real tape drives.
+
+@chapter Being More Careful
+
+When using @code{tar} with many options, particularly ones with
+complicated or difficult-to-predict behavior, it is possible to make
+serious mistakes. As a result, @code{tar} provides several options that
+make observing @code{tar} easier.
+
+The @samp{--verbose} option causes @code{tar} to print the name of each
+file or archive member as it is processed. This and the other options
+which make tar print status information can be useful in monitoring
+@code{tar}. @xref{Making @code{tar} More Verbose}.
+
+If you use @samp{--interactive} (or {@samp--confirm}), then @code{tar}
+will ask you for confirmation before each operation. For example, when
+extracting, it will prompt you before each archive member is extracted,
+and you can select that member for extraction or pass over to the next.
+
+The @samp{--verify} option, when using @samp{--create}, causes
+@code{tar}, after having finished creating the archive, to go back over
+it and compare its contents against the files that were placed in the
+archive.
+
+The @samp{--show-omitted-dirs} option, when reading an archive (with
+@samp{--list} or @samp{--extract}, for example), causes a message to be
+printed for each directory in the archive which is skipped. This
+happens regardless of the reason for skipping: the directory might not
+have been named on the command line (implicitly or explicitly), it might
+be excluded by the use of the @samp{--exclude} option, or some other
+reason.
+
+@chapter Using Real Tape Drives
+
+Many complexities surround the use of @code{tar} on tape drives. Since
+the creation and manipulation of archives located on magnetic tape was
+the original purpose of @code{tar}, it contains many features making
+such manipulation easier.
+
+@section Blocking
+
+When writing to tapes, @code{tar} writes the contents of the archive in
+chunks known as @dfn{blocks}. To change the default blocksize, use the
+@samp{--block-size=@var{blocking-factor}} (@samp{-b
+@var{blocking-factor}) option. Each block will then be composed of
+@var{blocking-factor} records. (Each @code{tar} record is 512 bytes.
+@xref{Archive Format}.) Each file written to the archive uses at least
+one full block. As a result, using a larger block size can result in
+more wasted space for small files. On the other hand, a larger block
+size can ofter be read and written much more efficiently.
+
+Further complicating the problem is that some tape drives ignore the
+blocking entirely. For these, a larger block size can still improve
+performance (because the software layers above the tape drive still
+honor the blocking), but not as dramatically as on tape drives that
+honor blocking.
+
+Wher reading an archive, @code{tar} can usually figure out the block
+size on itself. When this is the case, and a non-standard block size
+was used when the archive was created, @code{tar} will print a message
+about a non-standard blocking factor, and then operate normally. On
+some tape devices, however, @code{tar} cannot figure out the block size
+itself. On most of those, you can specify a blocking factor (with
+@samp{--block-size) larger than the actual blocking factor, and then use
+the @samp{--read-full-blocks} option. (If you specify a blocking factor
+with @samp{--block-size} and don't use the @samp{--read-full-blocks}
+option, then @code{tar} will not attempt to figure out the blocking size
+itself.) On some devices, you must always specify the block size
+exactly with @samp{--block-size} when reading, because @code{tar} cannot
+figure it out. In any case, use @samp{--list} before doing any
+extractions to see whether @code{tar} is reading the archive correctly.
+
+If you use a blocking factor larger than 20, older @code{tar} programs
+might not be able to read the archive, so we recommend this as a limit
+to use in practice. GNU @code{tar}, however, will support arbitrarily
+large block sizes, limited only by the amount of virtual memory or the
+physical characteristics of the tape device.
+
+If you are writing a compressed archive to tape with @samp{--compress}
+or @samp{--gzip} (@pxref{Input and Output}), @code{tar} will not block
+the archive correctly. This doesn't matter if you are writing the
+archive to a normal file or through a pipe, but if you are writing it to
+a tape drive, then this causes problems. Use @samp{--compress-block} or
+@samp{--gzip-block} instead, to cause @code{tar} to arrange to have
+blocking work correctly.
+
+@section Using Multiple Tapes
+
+Often you might want to write a large archive, one larger than will fit
+on the actual tape you are using. In such a case, you can run multiple
+@code{tar} commands, but this can be inconvenient, particularly if you
+are using options like @samp{--exclude} or dumping entire filesystems.
+Therefore, @code{tar} supports multiple tapes automatically.
+
+Use @samp{--multi-volume} on the command line, and then @code{tar} will,
+when it reaches the end of the tape, prompt for another tape, and
+continue the archive. Each tape will have an independent archive, and
+can be read without needing the other. (As an exception to this, the
+file that @code{tar} was archiving when it ran out of tape will usually
+be split between the two archives; in this case you need to extract from
+the first archive, using @samp{--multi-volume}, and then put in the
+second tape when prompted, so @code{tar} can restore both halves of the
+file.)
+
+When prompting for a new tape, @code{tar} accepts any of the following
+responses:
+
+@table @samp
+@item ?
+Request @code{tar} to explain possible responses
+@item q
+Request @code{tar} to exit immediately.
+@item n @var{file-name}
+Request @code{tar} to write the next volume on the file @var{file-name}.
+@item !
+Request @code{tar} to run a subshell.
+@item y
+Request @code{tar} to begin writing the next volume.
+@end table
+
+(You should only type @samp{y} after you have changed the tape;
+otherwise @code{tar} will write over the volume it just finished.)
+
+If you want more elaborate behavior than this, give @code{tar} the
+@samp{--info-script=@var{script-name}} option. The file
+@var{script-name} is expected to be a program (or shell script) to be
+run instead of the normal prompting procedure. When the program
+finishes, @code{tar} will immediately begin writing the next volume.
+(The behavior of the @samp{n} response to the normal tape-change prompt
+is not available if you use @samp{--info-script}.)
+
+The method @code{tar} uses to detect end of tape is not perfect, and
+fails on some operating systems or on some devices. You can use the
+@samp{--tape-length=@var{size}} (or @samp{-L @var{size}}) option if
+@code{tar} can't detect the end of the tape itself. The @var{size}
+argument should be the size of the tape.
+
+The volume number used by @code{tar} in its tape-change prompt can be
+changed; if you give the @samp{--volno-file=@var{file-name}} option,
+then @var{file-name} should contain a decimal number. That number will
+be used as the volume number of the first volume written. When
+@code{tar} is finished, it will rewrite the file with the now--current
+volume number. (This does not change the volume number written on a
+tape label (@pxref{Special Options for Archiving}; it @emph{only}
+affects the number used in the prompt.)
+
+If you want @code{tar} to cycle through a series of tape drives, then
+you can use the @samp{n} response to the tape-change prompt. This is
+error prone, however, and doesn't work at all with @samp{--info-script}.
+Therefore, if you give @code{tar} multiple @samp{--file} options, then
+the specified files will be used, in sequence, as the successive volumes
+of the archive. Only when the first one in the sequence needs to be
+used again will @code{tar} prompt for a tape change (or run the info
+script).
+
+@section Tape Files
+
+When @code{tar} writes an archive to tape, it creates a single tape
+file. If multiple archives are written to the same tape, one after the
+other, they each get written as separate tape files. When extracting,
+it is necessary to position the tape at the right place before running
+@code{tar}. To do this, use the @code{mt} command. For more
+information on the @code{mt} command and on the organization of tapes
+into a sequence of tape files, see XXX.
+
+@chapter Special Options for Archiving
+
+To give the archive a name which will be recorded in it, use the
+@samp{--label=@var{volume-label}} (or @samp{-V}) option. This will
+write a special record identifying @var{volume-label} as the name of the
+archive to the front of the archive which will be displayed when the
+archive is listed with @samp{--list}. If you are creating a
+multi-volume archive with @samp{--multi-volume} (@pxref{Using Multiple
+Tapes}), then the volume label will have @same{ Volume @var{nnn}}
+appended to the name you give, where @var{nnn} is the number of the
+volume of the archive. (If you use the @samp{--label} option when
+reading an archive, it checks to make sure the label on the tape matches
+the one you give. @xref{Special Options for Archiving}.)
+
+Files in the filesystem occasionally have ``holes.'' A hole in a file
+is a section of the file's contents which was never written. The
+contents of a hole read as all zeros. On many operating systems, actual@c
+disk storage is not allocated for holes, but they are counted in the
+length of the file. If you archive such a file, @code{tar} could create
+an archive longer than the original. To have @code{tar} attempt to
+recognize the holes in a file, use @samp{--sparse}. When you use the
+@samp{--sparse} option, then, for any file using less disk space than
+would be expected from its length, @code{tar} searches the file for
+consecutive stretches of zeros. It then records in the archive for the
+file where the consecutive stretches of zeros are, and only archives the
+``real contents'' of the file. On extraction (using @samp{--sparse} is
+not needed on extraction) any such files have hols created wherever the
+continuous stretches of zeros were found. Thus, if you use
+@samp{--sparse}, @code{tar} archives won't take more space than the
+original.
+
+When @code{tar} reads files, this causes them to have the access times
+updated. To have @code{tar} attempt to set the access times back to
+what they were before they were read, use the @samp{--atime-preserve}
+option. This doesn't work for files that you don't own, unless you're
+root, and it doesn't interact with incremental dumps nicely
+(@pxref{Making Backups}), but it is good enough for some purposes.
+
+@chapter Special Options for Reading Archives
+
+
+
+
+
+
+
+
+
+XXXX MIB XXXX
+
+
+