From: François Pinard Date: Wed, 16 Nov 1994 02:52:19 +0000 (+0000) Subject: *** empty log message *** X-Git-Url: https://git.brokenzipper.com/gitweb?a=commitdiff_plain;h=8835bb37e9f1286f3e808279ddae58b8e090f29a;p=chaz%2Ftar *** empty log message *** --- diff --git a/doc/tar.texi b/doc/tar.texi index 932eef1..12b9ad2 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -636,13 +636,44 @@ 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, owner, and so forth, as the original file did when it -was placed in the archive. - -The @samp{--mo - +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} @@ -660,7 +691,10 @@ 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. +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 @@ -716,7 +750,7 @@ 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 Archiing +@chapter Changing the Names of Members when Archiving @section Changing Directory @@ -777,6 +811,125 @@ to the archive naming the target of the link. In that way, the 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}.) + +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. + +@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. + +@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 (@pxref{Making @code{tar} More Verbose}) +causes @code{tar} to print the name of each file or archive member as it +is processed. + +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. + + + XXXX MIB XXXX