X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=9c111a043b7d1fbd379c719210d136893458c78b;hb=9efbc4be3b8910063894d3ac933841edc683171a;hp=8f142655c9e6560298efe6b11c2a84f479916baa;hpb=ae2b0518322d2a35e27437db0002a2878539835a;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 8f14265..9c111a0 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -4,6 +4,7 @@ @settitle GNU tar @finalout @smallbook +@setchapternewpage odd @c %**end of header @c ====================================================================== @@ -196,7 +197,7 @@ @set xref-file @xref{file} @set pxref-file @pxref{file} -@set op-files-from @kbd{--files-from=@var{file-of-names}} (@kbd{-I @var{file-of-names}}, @kbd{-T @var{file-of-names}}) +@set op-files-from @kbd{--files-from=@var{file-of-names}} (@kbd{-T @var{file-of-names}}) @set ref-files-from @ref{files} @set xref-files-from @xref{files} @set pxref-files-from @pxref{files} @@ -462,19 +463,21 @@ @defindex op @syncodeindex op cp -@ifinfo +@dircategory GNU Packages +@direntry +* Tar: (tar). Making tape (or disk) archives. +@end direntry + +@dircategory Individual utilities @direntry -* tar: (tar). Making tape (or disk) archives. +* tar: (tar)tar invocation. Invoking @sc{gnu} @command{tar} @end direntry +@ifinfo This file documents @sc{gnu} @command{tar}, which creates and extracts files from archives. -Published by the Free Software Foundation, -59 Temple Place - Suite 330, -Boston, MA 02111-1307, USA - -Copyright 1992, 1994, 1995, 1996, 1997, 1999, 2000 Free Software +Copyright 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document @@ -487,8 +490,6 @@ Free Documentation License''. @end ifinfo -@setchapternewpage odd - @shorttitlepage @sc{gnu} @command{tar} @titlepage @@ -501,8 +502,8 @@ Free Documentation License''. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000 Free Software -Foundation, Inc. +Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001 +Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 @@ -528,6 +529,9 @@ The first part of this master menu lists the major nodes in this Info document. The rest of the menu lists all the lower level nodes. @end ifnottex +@c The master menu, created with texinfo-master-menu, goes here. +@c (However, getdate.texi's menu is interpolated by hand.) + @menu * Introduction:: * Tutorial:: @@ -538,11 +542,11 @@ document. The rest of the menu lists all the lower level nodes. * Date input formats:: * Formats:: * Media:: -* GNU Free Documentation License:: +* Free Software Needs Free Documentation:: +* Copying This Manual:: * Index:: @detailmenu - --- The Detailed Node Listing --- Introduction @@ -644,7 +648,7 @@ Updating an Archive * how to update:: -Options used by @code{--create} +Options Used by @code{--create} * Ignore Failed Read:: @@ -659,16 +663,13 @@ Options to Help Read Archives * read full records:: * Ignore Zeros:: -Changing How @command{tar} Extracts Files Over Preexisting Files +Changing How @command{tar} Writes Files * Dealing with Old Files:: * Overwrite Old Files:: * Keep Old Files:: * Unlink First:: * Recursive Unlink:: - -Changing How @command{tar} Writes Files - * Modification Times:: * Setting Access Permissions:: * Writing to Standard Output:: @@ -711,6 +712,7 @@ Reading Names from a File Excluding Some Files +* controlling pattern-patching with exclude:: * problems with exclude:: Crossing Filesystem Boundaries @@ -727,7 +729,7 @@ Date input formats * Day of week items:: Monday and others. * Relative items in date strings:: next tuesday, 2 years ago. * Pure numbers in date strings:: 19931219, 1440. -* Authors of getdate:: Bellovin, Eggert, Berets, Salz, et al. +* Authors of getdate:: Bellovin, Eggert, Salz, Berets, et al. Controlling the Archive Format @@ -778,6 +780,11 @@ Using Multiple Tapes * Multi-Volume Archives:: Archives Longer than One Tape or Disk * Tape Files:: Tape Files + +Copying This Manual + +* GNU Free Documentation License:: License for copying this manual + @end detailmenu @end menu @@ -2500,6 +2507,10 @@ member names. This option disables that behavior. @FIXME-xref{} (See @samp{--newer}.) @FIXME-pxref{} +@item --anchored +An exclude pattern must match an initial subsequence of the name's components. +@FIXME-xref{} + @item --atime-preserve Tells @command{tar} to preserve the access time field in a file's inode when @@ -2587,7 +2598,6 @@ performs operations on, rather than @command{tar}'s compilation dependent default. @FIXME-xref{} @item --files-from=@var{file} -@itemx -I @var{file} @itemx -T @var{file} @command{tar} will use the contents of @var{file} as a list of archive members @@ -2626,6 +2636,10 @@ archives transparently. @FIXME-xref{} @command{tar} will print out a short message summarizing the operations and options to @command{tar} and exit. @FIXME-xref{} +@item --ignore-case +Ignore case when excluding files. +@FIXME-xref{} + @item --ignore-failed-read Do not exit unsuccessfully merely because an unreadable file was encountered. @@ -2649,7 +2663,8 @@ compatibility only. @FIXME-xref{} @itemx -F @var{script-file} When @command{tar} is performing multi-tape backups, @var{script-file} is run -at the end of each tape. @FIXME-xref{} +at the end of each tape. If @var{script-file} exits with nonzero status, +@command{tar} fails immediately. @FIXME-xref{} @item --interactive @itemx --confirmation @@ -2713,18 +2728,28 @@ multi-volume @command{tar} archive. @FIXME-xref{} @itemx -N When creating an archive, @command{tar} will only add files that have changed -since @var{date}. @FIXME-xref{} +since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it +is taken to be the name of a file whose last-modified time specifies +the date. @FIXME-xref{} -@item --newer-mtime +@item --newer-mtime=@var{date} -In conjunction with @samp{--newer}, @command{tar} will only add files whose +Like @samp{--newer}, but add only files whose contents have changed (as opposed to just @samp{--newer}, which will also back up files for which any status information has changed). +@item --no-anchored +An exclude pattern can match any subsequence of the name's components. +@FIXME-xref{} + +@item --no-ignore-case +Use case-sensitive matching when excluding files. +@FIXME-xref{} + @item --no-recursion -With this option, @command{tar} will not recurse into directories unless a -directory is explicitly named as an argument to @command{tar}. @FIXME-xref{} +With this option, @command{tar} will not recurse into directories. +@FIXME-xref{} @item --no-same-owner @@ -2738,6 +2763,14 @@ When extracting an archive, subtract the user's umask from files from the permissions specified in the archive. This is the default behavior for ordinary users; this option has an effect only for the superuser. +@item --no-wildcards +Do not use wildcards when excluding files. +@FIXME-xref{} + +@item --no-wildcards-match-slash +Wildcards do not match @samp{/} when excluding files. +@FIXME-xref{} + @item --null When @command{tar} is using the @samp{--files-from} option, this option @@ -2822,6 +2855,11 @@ systems with buggy implementations. @xref{Reading}. Instructs @command{tar} to use @var{size} bytes per record when accessing the archive. @FIXME-xref{} +@item --recursion + +With this option, @command{tar} recurses into directories. +@FIXME-xref{} + @item --recursive-unlink Remove existing @@ -2947,6 +2985,14 @@ copyright message, some credits, and then exit. @FIXME-xref{} Used in conjunction with @samp{--multi-volume}. @command{tar} will keep track of which volume of a multi-volume archive its working in @var{file}. @FIXME-xref{} + +@item --wildcards +Use wildcards when excluding files. +@FIXME-xref{} + +@item --wildcards-match-slash +Wildcards match @samp{/} when excluding files. +@FIXME-xref{} @end table @node Short Option Summary @@ -2977,10 +3023,6 @@ them with the equivalent long option. @samp{--incremental} -@item -I - -@samp{--files-from} - @item -K @samp{--starting-file} @@ -4124,7 +4166,7 @@ To be more cautious and prevent existing files from being replaced, use the @value{op-keep-old-files} option. It causes @command{tar} to refuse to replace or update a file that already exists, i.e., a file with the same name as an archive member prevents extraction of that archive -member. +member. Instead, it reports an error. To be more aggressive about altering existing files, use the @value{op-overwrite} option. It causes @command{tar} to overwrite @@ -5281,14 +5323,13 @@ the list of files to archive with the @command{find} utility. @table @kbd @item --files-from=@var{file name} -@itemx -I @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{-I -}) or @samp{-T --}), then the file names are read from standard input. +you specify either @samp{--files-from=-} or @samp{-T -}), then the file +names are read from standard input. Unless you are running @command{tar} with @samp{--create}, you can not use both @samp{--files-from=-} and @samp{--file=-} (@samp{-f -}) in the same @@ -5376,21 +5417,6 @@ For example, to create an archive with all the contents of the directory @file{src} except for files whose names end in @file{.o}, use the command @samp{tar -cf src.tar --exclude='*.o' src}. -A @var{pattern} containing @samp{/} excludes a name if an initial -subsequence of the name's components matches @var{pattern}; a -@var{pattern} without @samp{/} excludes a name if it matches any of its -name components. For example, the pattern @samp{*b/RCS} contains -@samp{/}, so it excludes @file{blob/RCS} and @file{.blob/RCS/f} but not -@file{blob/RCSit/RCS} or @file{/blob/RCS}, whereas the pattern -@samp{RCS} excludes all these names. Conversely, the pattern @samp{*.o} -lacks @samp{/}, so it excludes @file{.f.o}, @file{d/f.o}, and -@file{d.o/f}. - -Other than optionally stripping leading @samp{/} from names -(@pxref{absolute}), patterns and candidate names are used as-is. For -example, trailing @samp{/} is not trimmed from a user-specified name -before deciding whether to exclude it. - You may give multiple @samp{--exclude} options. @table @kbd @@ -5402,8 +5428,8 @@ Causes @command{tar} to ignore files that match the patterns listed in @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}; @command{tar} will -ignore files matching those regular expressions. Thus if @command{tar} is +list of patterns, one per line, from @var{file}; @command{tar} will +ignore files matching those patterns. Thus if @command{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. @@ -5412,9 +5438,64 @@ added to the archive. newlines the same as the files-from option does?} @menu +* controlling pattern-patching with exclude:: * problems with exclude:: @end menu +@node controlling pattern-patching with exclude +@unnumberedsubsec Controlling Pattern-Matching with the @code{exclude} Options + +Normally, a pattern matches a name if an initial subsequence of the +name's components matches the pattern, where @samp{*}, @samp{?}, and +@samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards, +and wildcards can match @samp{/}. + +Other than optionally stripping leading @samp{/} from names +(@pxref{absolute}), patterns and names are used as-is. For +example, trailing @samp{/} is not trimmed from a user-specified name +before deciding whether to exclude it. + +However, this matching procedure can be altered by the options listed +below. These options accumulate. For example: + +@example +--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme' +@end example + +ignores case when excluding @samp{makefile}, but not when excluding +@samp{readme}. + +@table @option +@item --anchored +@itemx --no-anchored +If anchored (the default), a pattern must match an initial subsequence +of the name's components. Otherwise, the pattern can match any subsequence. + +@item --ignore-case +@itemx --no-ignore-case +When ignoring case, upper-case patterns match lower-case names and vice versa. +When not ignoring case (the default), matching is case-sensitive. + +@item --wildcards +@itemx --no-wildcards +When using wildcards (the default), @samp{*}, @samp{?}, and @samp{[...]} +are the usual shell wildcards, and @samp{\} escapes wildcards. +Otherwise, none of these characters are special, and patterns must match +names literally. + +@item --wildcards-match-slash +@itemx --no-wildcards-match-slash +When wildcards match slash (the default), a wildcard like @samp{*} in +the pattern can match a @samp{/} in the name. Otherwise, @samp{/} is +matched only by @samp{/}. + +@end table + +The @option{--recursion} and @option{--no-recursion} options +(@pxref{recurse}) also affect how exclude patterns are interpreted. If +recursion is in effect, a pattern excludes a name if it matches any of +the name's parent directories. + @node problems with exclude @unnumberedsubsec Problems with Using the @code{exclude} Options @@ -5468,7 +5549,7 @@ might fail. @item In earlier versions of @command{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}} 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. @@ -5547,7 +5628,9 @@ Your opinions on the matter are welcome. The @value{op-after-date} option causes @command{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, +given. If @var{date} starts with @samp{/} or @samp{.}, it is taken to +be a file name; the last-modified time of that file is used as the date. +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, @command{tar} will only extract files newer than the @var{date} you specify. @@ -5570,6 +5653,9 @@ 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. +If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file +name; the last-modified time of that file is used as the date. + @item --newer-mtime=@var{date} Acts like @value{op-after-date}, but only looks at modification times. @end table @@ -5605,17 +5691,6 @@ 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 @sc{gnu} -@command{date}, available in @sc{gnu} shell utilities 1.13 or later. It returns -the time stamp of the already-existing file; this time stamp 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 @FIXME{which tells -- need to fill this in!} @@ -5647,6 +5722,10 @@ archive; see @ref{files} for more information on using @command{find} with @table @kbd @item --no-recursion Prevents @command{tar} from recursively descending directories. + +@item --recursion +Requires @command{tar} to recursively descend directories. +This is the default. @end table When you use @samp{--no-recursion}, @sc{gnu} @command{tar} grabs directory entries @@ -5655,7 +5734,7 @@ themselves, but does not descend on them recursively. Many people use @command{tar} @emph{usually} recursively descends on directories, they have to use the @samp{@w{! -d}} option to @command{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} +all the files in a directory. They then use the @value{op-files-from} option to archive the files located via @command{find}. The problem when restoring files archived in this manner is that the @@ -5665,6 +5744,13 @@ might really like it to. Specifying @value{op-no-recursion} is a way to tell @command{tar} to grab only the directory entries given to it, adding no new files on its own. +The @value{op-no-recursion} option also applies when extracting: it +causes @command{tar} to extract only the matched directory entries, not +the files under those directories. + +The @value{op-no-recursion} option also affects how exclude patterns +are interpreted (@pxref{controlling pattern-patching with exclude}). + @FIXME{example here} @node one @@ -6729,7 +6815,7 @@ does not distinguish text files from binary files, and no translation of file contents is performed. The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and -@code{gname} are null-terminated character strings. All other fileds +@code{gname} are null-terminated character strings. All other fields are zero-filled octal numbers in ASCII. Each numeric field of width @var{w} contains @var{w} minus 2 digits, a space, and a null, except @code{size}, and @code{mtime}, which do not contain the trailing null. @@ -7219,8 +7305,8 @@ maximum tape length, you might avoid the problem entirely. @item -F @var{file} @itemx --info-script=@var{file} @itemx --new-volume-script=@var{file} -Execute @file{file} at end of each tape. This implies -@value{op-multi-volume}. +Execute @file{file} at end of each tape. If @file{file} exits with +nonzero status, exit. This implies @value{op-multi-volume}. @end table @node Remote Tape Server @@ -7978,8 +8064,9 @@ otherwise @command{tar} will write over the volume it just finished.) If you want more elaborate behavior than this, give @command{tar} the @value{op-info-script} 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, @command{tar} will -immediately begin writing the next volume. The behavior of the +prompting procedure. If the program fails, @command{tar} exits; +otherwise, @command{tar} begins writing the next volume. The behavior +of the @samp{n} response to the normal tape-change prompt is not available if you use @value{op-info-script}. @@ -8313,6 +8400,12 @@ The @value{op-verify} option will not work in conjunction with the @value{op-update} and @value{op-delete} operations. @xref{Operations}, for more information on these operations. +Also, since @command{tar} normally strips leading @samp{/} from file +names (@pxref{absolute}), a command like @samp{tar --verify -cf +/tmp/foo.tar /etc} will work as desired only if the working directory is +@file{/}, as @command{tar} uses the archive's relative member names +(e.g., @file{etc/motd}) when verifying the archive. + @node Write Protection @section Write Protection @@ -8329,10 +8422,21 @@ disabled) switch, a notch which can be popped out or covered, a ring which can be removed from the center of a tape reel, or some other changeable feature. +@node Free Software Needs Free Documentation +@appendix Free Software Needs Free Documentation +@include freemanuals.texi + +@node Copying This Manual +@appendix Copying This Manual + +@menu +* GNU Free Documentation License:: License for copying this manual +@end menu + @include fdl.texi @node Index -@unnumbered Index +@appendix Index @printindex cp