X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=78cc8b1f02b36d1206fc4dd98e3c25d4b258c6bc;hb=1ee48e8576fefe6ab6e9395bdf7bda9590a3fa51;hp=ab7c1b5c0a61657676c695cc5123e3868c32d641;hpb=05b84a0990b40c36b9799ec7e37731492cba8ff1;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index ab7c1b5..78cc8b1 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -824,7 +824,8 @@ used with @samp{--list} causes @code{tar} to print a longer listing 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}.) +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 @@ -836,6 +837,9 @@ 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 @@ -874,6 +878,23 @@ 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 @@ -881,9 +902,10 @@ 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. +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 @@ -949,6 +971,14 @@ 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 @@ -1005,8 +1035,9 @@ 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; it @emph{only} affects the number used in the prompt.) +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 @@ -1015,7 +1046,59 @@ 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). +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 + +