X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=8d09671dc294ed96bea75330c880d4ead96b2105;hb=c7ab8eaba40ef39f7b50cce4cb9228bf4ca09d2a;hp=d148581bdce962e2438ed3d8899c7c708b30a5b1;hpb=ecce6f3e9abab89b4eadd064884c0757faca1b55;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index d148581..8d09671 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -227,7 +227,7 @@ Changing How @command{tar} Writes Files * Keep Newer Files:: * Unlink First:: * Recursive Unlink:: -* Modification Times:: +* Data Modification Times:: * Setting Access Permissions:: * Writing to Standard Output:: * remove files:: @@ -262,7 +262,7 @@ Choosing Files and Names for @command{tar} * Wildcards:: * after:: Operating Only on New Files * recurse:: Descending into Directories -* one:: Crossing Filesystem Boundaries +* one:: Crossing File System Boundaries Reading Names from a File @@ -270,10 +270,10 @@ Reading Names from a File Excluding Some Files -* controlling pattern-patching with exclude:: +* controlling pattern-matching with exclude:: * problems with exclude:: -Crossing Filesystem Boundaries +Crossing File System Boundaries * directory:: Changing Directory * absolute:: Absolute File Names @@ -427,7 +427,7 @@ The @command{tar} program is used to create and manipulate @command{tar} archives. An @dfn{archive} is a single file which contains the contents of many files, while still identifying the names of the files, their owner(s), and so forth. (In addition, archives record access -permissions, user and group, size in bytes, and last modification time. +permissions, user and group, size in bytes, and data modification time. Some archives also record the file names in each archived directory, as well as other file and directory information.) You can use @command{tar} to @dfn{create} a new archive in a specified directory. @@ -440,14 +440,14 @@ The files inside an archive are called @dfn{members}. Within this manual, we use the term @dfn{file} to refer only to files accessible in the normal ways (by @command{ls}, @command{cat}, and so forth), and the term @dfn{member} to refer only to the members of an archive. Similarly, a -@dfn{file name} is the name of a file, as it resides in the filesystem, +@dfn{file name} is the name of a file, as it resides in the file system, and a @dfn{member name} is the name of an archive member within the archive. @cindex extraction @cindex unpacking The term @dfn{extraction} refers to the process of copying an archive -member (or multiple members) into a file in the filesystem. Extracting +member (or multiple members) into a file in the file system. Extracting all the members of an archive is often called @dfn{extracting the archive}. The term @dfn{unpack} can also be used to refer to the extraction of many or all the members of an archive. Extracting an @@ -511,7 +511,7 @@ projects) together on a disk or a tape. This guards against accidental destruction of the information in those files. @GNUTAR{} has special features that allow it to be used to make incremental and full dumps of all the files in a -filesystem. +file system. @item Transportation You can create an archive on one system, transfer it to another system, @@ -692,7 +692,7 @@ about how Unix-type operating systems work, and you should know how to use some basic utilities. For example, you should know how to create, list, copy, rename, edit, and delete files and directories; how to change between directories; and how to figure out where you are in the -filesystem. You should have some basic understanding of directory +file system. You should have some basic understanding of directory structure and how files are named according to which directory they are in. You should understand concepts such as standard output and standard input, what various definitions of the term ``argument'' mean, and the @@ -1010,10 +1010,10 @@ working directory with the archive name you intend to use (in this case, Whenever you use @samp{create}, @command{tar} will erase the current contents of the file named by @value{op-file} if it exists. @command{tar} will not tell you if you are about to overwrite an archive unless you -specify an option which does this. @FIXME{xref to the node for ---backup!}To add files to an existing archive, you need to use a -different option, such as @value{op-append}; see @ref{append} for -information on how to do this. +specify an option which does this (@pxref{backup}, for the +information on how to do so). To add files to an existing archive, +you need to use a different option, such as @value{op-append}; see +@ref{append} for information on how to do this. @node Creating the archive @subsection Creating the Archive @@ -1470,11 +1470,8 @@ To extract specific archive members, give their exact member names as arguments, as printed by @value{op-list}. If you had mistakenly deleted one of the files you had placed in the archive @file{collection.tar} earlier (say, @file{blues}), you can extract it from the archive without -changing the archive's structure. It will be identical to the original -file @file{blues} that you deleted. @FIXME{At the time of this -writing, atime and ctime are not restored. Since this is a tutorial -for a beginnig user, it should hardly be mentioned here. Maybe in -a footnote? --gray}. +changing the archive's structure. Its contents will be identical to the +original file @file{blues} that you deleted. First, make sure you are in the @file{practice} directory, and list the files in the directory. Now, delete the file, @samp{blues}, and list @@ -1489,7 +1486,7 @@ $ @kbd{tar --extract --file=collection.tar blues} @noindent If you list the files in the directory again, you will see that the file -@file{blues} has been restored, with its original permissions, creation +@file{blues} has been restored, with its original permissions, data modification times, and owner.@FIXME{This is only accidentally true, but not in general. In most cases, one has to be root for restoring the owner, and use a special option for restoring permissions. Here, it just happens @@ -1735,7 +1732,7 @@ option). @value{xref-absolute-names}, for more information about If you give the name of a directory as either a file name or a member name, then @command{tar} acts recursively on all the files and directories beneath that directory. For example, the name @file{/} identifies all -the files in the filesystem to @command{tar}. +the files in the file system to @command{tar}. The distinction between file names and archive member names is especially important when shell globbing is used, and sometimes a source of confusion @@ -1806,6 +1803,8 @@ You will likely use some options frequently, while you will only use others infrequently, or not at all. (A full list of options is available in @pxref{All Options}.) +@vrindex TAR_OPTIONS, environment variable +@anchor{TAR_OPTIONS} The @env{TAR_OPTIONS} environment variable specifies default options to be placed in front of any explicit options. For example, if @code{TAR_OPTIONS} is @samp{-v --unlink-first}, @command{tar} behaves as @@ -2207,29 +2206,63 @@ Normally when creating an archive, @command{tar} strips an initial @item --after-date -(See @option{--newer}.) @FIXME-pxref{} +(See @option{--newer}, @pxref{after}) @item --anchored An exclude pattern must match an initial subsequence of the name's components. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. @item --atime-preserve - -Tells @command{tar} to preserve the access time field in a file's inode when -reading it. Due to limitations in the @code{utimes} system call, the -modification time field is also preserved, which may cause problems if -the file is simultaneously being modified by another program. -This option is incompatible with incremental backups, because -preserving the access time involves updating the last-changed time. -Also, this option does not work on files that you do not own, -unless you're root. -@FIXME-xref{} +@itemx --atime-preserve=replace +@itemx --atime-preserve=system + +Attempt to preserve the access time of files when reading them. This +option currently is effective only on files that you own, unless you +have superuser privileges. + +@value{op-atime-preserve-replace} remembers the access time of a file +before reading it, and then restores the access time afterwards. This +may cause problems if other programs are reading the file at the same +time, as the times of their accesses will be lost. On most platforms +restoring the access time also requires @command{tar} to restore the +data modification time too, so this option may also cause problems if +other programs are writing the file at the same time. (Tar attempts +to detect this situation, but cannot do so reliably due to race +conditions.) Worse, on most platforms restoring the access time also +updates the status change time, which means that this option is +incompatible with incremental backups. + +@value{op-atime-preserve-system} avoids changing time stamps on files, +without interfering with time stamp updates +caused by other programs, so it works better with incremental backups. +However, it requires a special @code{O_NOATIME} option from the +underlying operating and file system implementation, and it also requires +that searching directories does not update their access times. As of +this writing (November 2005) this works only with Linux, and only with +Linux kernels 2.6.8 and later. Worse, there is currently no reliable +way to know whether this feature actually works. Sometimes +@command{tar} knows that it does not work, and if you use +@value{op-atime-preserve-system} then @command{tar} complains and +exits right away. But other times @command{tar} might think that the +option works when it actually does not. + +Currently @option{--atime-preserve} with no operand defaults to +@value{op-atime-preserve-replace}, but this may change in the future +as support for @value{op-atime-preserve-system} improves. + +If your operating system does not support +@value{op-atime-preserve-system}, you might be able to preserve access +times reliably by by using the @command{mount} command. For example, +you can mount the file system read-only, or access the file system via +a read-only loopback mount, or use the @samp{noatime} mount option +available on some systems. However, mounting typically requires +superuser privileges and can be a pain to manage. @item --backup=@var{backup-type} Rather than deleting files from the file system, @command{tar} will back them up using simple or numbered backups, depending upon -@var{backup-type}. @FIXME-xref{} +@var{backup-type}. @xref{backup}. @item --block-number @itemx -R @@ -2241,13 +2274,13 @@ with the block number in the archive file. @FIXME-xref{} @itemx -b @var{blocking} Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per -record. @FIXME-xref{} +record. @value{xref-blocking-factor}. @item --bzip2 @itemx -j This option tells @command{tar} to read or write archives through -@code{bzip2}. @FIXME-xref{} +@code{bzip2}. @xref{gzip}. @item --checkpoint @@ -2293,43 +2326,43 @@ symlink. @FIXME-xref{} When this option is specified, @command{tar} will change its current directory to @var{dir} before performing any operations. When this option is used -during archive creation, it is order sensitive. @FIXME-xref{} +during archive creation, it is order sensitive. @xref{directory}. @item --exclude=@var{pattern} When performing operations, @command{tar} will skip files that match -@var{pattern}. @FIXME-xref{} +@var{pattern}. @xref{exclude}. @item --exclude-from=@var{file} @itemx -X @var{file} Similar to @option{--exclude}, except @command{tar} will use the list of -patterns in the file @var{file}. @FIXME-xref{} +patterns in the file @var{file}. @xref{exclude}. @item --exclude-caches Automatically excludes all directories -containing a cache directory tag. @FIXME-xref{} +containing a cache directory tag. @xref{exclude}. @item --file=@var{archive} @itemx -f @var{archive} @command{tar} will use the file @var{archive} as the @command{tar} archive it performs operations on, rather than @command{tar}'s compilation dependent -default. @FIXME-xref{} +default. @xref{file tutorial}. @item --files-from=@var{file} @itemx -T @var{file} @command{tar} will use the contents of @var{file} as a list of archive members or files to operate on, in addition to those specified on the -command-line. @FIXME-xref{} +command-line. @xref{files}. @item --force-local Forces @command{tar} to interpret the filename given to @option{--file} as a local file, even if it looks like a remote tape drive name. -@FIXME-xref{} +@xref{local and remote archives}. @item --format=@var{format} @@ -2375,16 +2408,19 @@ Also see the comments for the @value{op-owner} option. This option tells @command{tar} to read or write archives through @command{gzip}, allowing @command{tar} to directly operate on several -kinds of compressed archives transparently. @FIXME-xref{} +kinds of compressed archives transparently. @xref{gzip}. @item --help @command{tar} will print out a short message summarizing the operations and -options to @command{tar} and exit. @FIXME-xref{} +options to @command{tar} and exit. @xref{help}. @item --ignore-case -Ignore case when excluding files. -@FIXME-xref{} +Ignore case when excluding files. @xref{controlling pattern-matching +with exclude}. + +@item --ignore-command-error +Ignore exit codes of subprocesses. @xref{Writing to an External Program}. @item --ignore-failed-read @@ -2403,7 +2439,7 @@ archive, which normally signals EOF. @xref{Reading}. Used to inform @command{tar} that it is working with an old @acronym{GNU}-format incremental backup archive. It is intended primarily for backwards compatibility only. @FIXME{incremental and -listed-incremental}. +listed-incremental}. @item --index-file=@var{file} @@ -2415,7 +2451,8 @@ Send verbose output to @var{file} instead of to standard output. When @command{tar} is performing multi-tape backups, @var{script-file} is run at the end of each tape. If @var{script-file} exits with nonzero status, -@command{tar} fails immediately. @FIXME-xref{} +@command{tar} fails immediately. @xref{info-script}, for a detailed +discussion of @var{script-file}. @item --interactive @itemx --confirmation @@ -2434,7 +2471,7 @@ when extracting files from an archive. @itemx -k Do not overwrite existing files when extracting files from an archive. -@xref{Writing}. +@xref{Keep Old Files}. @item --label=@var{name} @itemx -V @var{name} @@ -2442,7 +2479,7 @@ Do not overwrite existing files when extracting files from an archive. When creating an archive, instructs @command{tar} to write @var{name} as a name record in the archive. When extracting or listing archives, @command{tar} will only operate on archives that have a label matching -the pattern specified in @var{name}. @FIXME-xref{} +the pattern specified in @var{name}. @xref{Tape Files}. @item --listed-incremental=@var{snapshot-file} @itemx -g @var{snapshot-file} @@ -2474,7 +2511,7 @@ or on any other file already marked as executable. @itemx -M Informs @command{tar} that it should create or otherwise operate on a -multi-volume @command{tar} archive. @FIXME-xref{} +multi-volume @command{tar} archive. @xref{Using Multiple Tapes}. @item --new-volume-script @@ -2494,8 +2531,8 @@ in cases when such recognition fails. When creating an archive, @command{tar} will only add files that have changed 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{} +is taken to be the name of a file whose data modification time specifies +the date. @xref{after}. @item --newer-mtime=@var{date} @@ -2505,16 +2542,20 @@ 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{} +@xref{controlling pattern-matching with exclude}. @item --no-ignore-case Use case-sensitive matching when excluding files. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. + +@item --no-ignore-command-error +Print warnings about subprocesses terminated with a non-zero exit +code. @xref{Writing to an External Program}. @item --no-recursion With this option, @command{tar} will not recurse into directories. -@FIXME-xref{} +@xref{recurse}. @item --no-same-owner @itemx -o @@ -2531,24 +2572,24 @@ for ordinary users. @item --no-wildcards Do not use wildcards when excluding files. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. @item --no-wildcards-match-slash Wildcards do not match @samp{/} when excluding files. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. @item --null When @command{tar} is using the @option{--files-from} option, this option instructs @command{tar} to expect filenames terminated with @option{NUL}, so @command{tar} can correctly work with file names that contain newlines. -@FIXME-xref{} +@xref{nul}. @item --numeric-owner This option will notify @command{tar} that it should use numeric user and group IDs when creating a @command{tar} file, rather than names. -@FIXME-xref{} +@xref{Attributes}. @item -o When extracting files, this option is a synonym for @@ -2625,14 +2666,14 @@ This option does not affect extraction from archives. @item --pax-option=@var{keyword-list} This option is meaningful only with @acronym{POSIX.1-2001} archives -(@FIXME-xref{}). It modifies the way @command{tar} handles the +(@pxref{posix}). It modifies the way @command{tar} handles the extended header keywords. @var{Keyword-list} is a comma-separated list of keyword options, each keyword option taking one of the following forms: @table @asis @item delete=@var{pattern} -When used with one of archive-creation command (@FIXME-xref{}), +When used with one of archive-creation commands, this option instructs @command{tar} to omit from extended header records that it produces any keywords matching the string @var{pattern}. @@ -2742,7 +2783,7 @@ Same as @option{--format=posix}. @item --preserve Synonymous with specifying both @option{--preserve-permissions} and -@option{--same-order}. @FIXME-xref{} +@option{--same-order}. @xref{Setting Access Permissions}. @item --preserve-order @@ -2756,7 +2797,7 @@ When @command{tar} is extracting an archive, it normally subtracts the users' umask from the permissions specified in the archive and uses that number as the permissions to create the destination file. Specifying this option instructs @command{tar} that it should use the -permissions directly from the archive. @xref{Writing}. +permissions directly from the archive. @xref{Setting Access Permissions}. @item --read-full-records @itemx -B @@ -2767,23 +2808,29 @@ from pipes on systems with buggy implementations. @xref{Reading}. @item --record-size=@var{size} Instructs @command{tar} to use @var{size} bytes per record when accessing the -archive. @FIXME-xref{} +archive. @value{xref-blocking-factor}. @item --recursion With this option, @command{tar} recurses into directories. -@FIXME-xref{} +@xref{recurse}. @item --recursive-unlink Remove existing directory hierarchies before extracting directories of the same name -from the archive. @xref{Writing}. +from the archive. @xref{Recursive Unlink}. @item --remove-files Directs @command{tar} to remove the source file from the file system after -appending it to an archive. @FIXME-xref{} +appending it to an archive. @xref{remove files}. + +@item --restrict + +Disable use of some potentially harmful @command{tar} options. +Currently this option disables shell invocaton from multi-volume menu +(@pxref{Using Multiple Tapes}). @item --rmt-command=@var{cmd} @@ -2793,7 +2840,7 @@ the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}). @item --rsh-command=@var{cmd} Notifies @command{tar} that is should use @var{cmd} to communicate with remote -devices. @FIXME-xref{} +devices. @xref{Device}. @item --same-order @itemx --preserve-order @@ -2809,11 +2856,11 @@ archive. @xref{Reading}. When extracting an archive, @command{tar} will attempt to preserve the owner specified in the @command{tar} archive with this option present. This is the default behavior for the superuser; this option has an -effect only for ordinary users. @FIXME-xref{} +effect only for ordinary users. @xref{Attributes}. @item --same-permissions -(See @option{--preserve-permissions}; @pxref{Writing}.) +(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.) @item --show-defaults @@ -2829,7 +2876,7 @@ $ tar --show-defaults @item --show-omitted-dirs Instructs @command{tar} to mention directories its skipping over when -operating on a @command{tar} archive. @FIXME-xref{} +operating on a @command{tar} archive. @xref{show-omitted-dirs}. @item --show-stored-names @@ -2842,7 +2889,7 @@ names. @xref{listing member and file names}. @itemx -S Invokes a @acronym{GNU} extension when adding files to an archive that handles -sparse files efficiently. @FIXME-xref{} +sparse files efficiently. @xref{sparse}. @item --starting-file=@var{name} @itemx -K @var{name} @@ -2867,55 +2914,60 @@ would extracted this file to file @file{name}. @item --suffix=@var{suffix} Alters the suffix @command{tar} uses when backing up files from the default -@samp{~}. @FIXME-xref{} +@samp{~}. @xref{backup}. @item --tape-length=@var{num} @itemx -L @var{num} Specifies the length of tapes that @command{tar} is writing as being -@w{@var{num} x 1024} bytes long. @FIXME-xref{} +@w{@var{num} x 1024} bytes long. @xref{Using Multiple Tapes}. @item --test-label Reads the volume label. If an argument is specified, test whether it matches the volume label. @xref{--test-label option}. +@item --to-command=@var{command} + +During extraction @command{tar} will pipe extracted files to the +standard input of @var{command}. @xref{Writing to an External Program}. + @item --to-stdout @itemx -O During extraction, @command{tar} will extract files to stdout rather -than to the file system. @xref{Writing}. +than to the file system. @xref{Writing to Standard Output}. @item --totals Displays the total number of bytes written after creating an archive. -@FIXME-xref{} +@xref{verbose}. @item --touch @itemx -m -Sets the modification time of extracted files to the extraction time, -rather than the modification time stored in the archive. -@xref{Writing}. +Sets the data modification time of extracted files to the extraction time, +rather than the data modification time stored in the archive. +@xref{Data Modification Times}. @item --uncompress -(See @option{--compress}.) @FIXME-pxref{} +(See @option{--compress}. @pxref{gzip}) @item --ungzip -(See @option{--gzip}.) @FIXME-pxref{} +(See @option{--gzip}. @pxref{gzip}) @item --unlink-first @itemx -U Directs @command{tar} to remove the corresponding file from the file -system before extracting it from the archive. @xref{Writing}. +system before extracting it from the archive. @xref{Unlink First}. @item --use-compress-program=@var{prog} Instructs @command{tar} to access the archive through @var{prog}, which is -presumed to be a compression program of some sort. @FIXME-xref{} +presumed to be a compression program of some sort. @xref{gzip}. @item --utc @@ -2927,33 +2979,34 @@ Display file modification dates in @acronym{UTC}. This option implies Specifies that @command{tar} should be more verbose about the operations its performing. This option can be specified multiple times for some -operations to increase the amount of information displayed. @FIXME-xref{} +operations to increase the amount of information displayed. +@xref{verbose}. @item --verify @itemx -W Verifies that the archive was correctly written when creating an -archive. @FIXME-xref{} +archive. @xref{verify}. @item --version @command{tar} will print an informational message about what version it is and a copyright message, some credits, and then exit. -@FIXME-xref{} +@xref{help}. @item --volno-file=@var{file} Used in conjunction with @option{--multi-volume}. @command{tar} will keep track of which volume of a multi-volume archive its working in @var{file}. -@FIXME-xref{} +@xref{volno-file}. @item --wildcards Use wildcards when excluding files. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. @item --wildcards-match-slash Wildcards match @samp{/} when excluding files. -@FIXME-xref{} +@xref{controlling pattern-matching with exclude}. @end table @node Short Option Summary @@ -3292,6 +3345,7 @@ is actually making forward progress. @FIXME{There is some confusion here. It seems that -R once wrote a message at @samp{every} record read or written.} +@anchor{show-omitted-dirs} The @value{op-show-omitted-dirs} option, when reading an archive---with @value{op-list} or @value{op-extract}, for example---causes a message to be printed for each directory in the archive which is skipped. @@ -3538,7 +3592,7 @@ complex. @command{tar} @emph{allows} you to have infinite number of files with the same name. Some operations treat these same-named members no differently than any other set of archive members: for example, if you view an archive with @value{op-list}, you will see all of those members -listed, with their modification times, owners, etc. +listed, with their data modification times, owners, etc. Other operations don't deal with these members as perfectly as you might prefer; if you were to use @value{op-extract} to extract the archive, @@ -4018,7 +4072,7 @@ Do not exit with nonzero on unreadable files or directories. there's a better way of organizing them.} The previous chapter showed how to use @value{op-extract} to extract -an archive into the filesystem. Various options cause @command{tar} to +an archive into the file system. Various options cause @command{tar} to extract more information than just file contents, such as the owner, the permissions, the modification date, and so forth. This section presents options to be used with @option{--extract} when certain special @@ -4111,13 +4165,6 @@ encountered while reading an archive. Use in conjunction with @node Writing @subsection Changing How @command{tar} Writes Files -@cindex Overwriting old files, prevention -@cindex Protecting old files -@cindex Modification times of extracted files -@cindex Permissions of extracted files -@cindex Modes of extracted files -@cindex Writing extracted files to standard output -@cindex Standard output, writing extracted files to @UNREVISED @FIXME{need to mention the brand new option, --backup} @@ -4129,9 +4176,10 @@ encountered while reading an archive. Use in conjunction with * Keep Newer Files:: * Unlink First:: * Recursive Unlink:: -* Modification Times:: +* Data Modification Times:: * Setting Access Permissions:: * Writing to Standard Output:: +* Writing to an External Program:: * remove files:: @end menu @@ -4148,6 +4196,7 @@ permission, etc.). The @option{--overwrite-dir} option enables this default behavior. To be more cautious and preserve the metadata of such a directory, use the @option{--no-overwrite-dir} option. +@cindex Overwriting old files, prevention To be even 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 @@ -4158,10 +4207,11 @@ To be more aggressive about altering existing files, use the @value{op-overwrite} option. It causes @command{tar} to overwrite existing files and to follow existing symbolic links when extracting. +@cindex Protecting old files Some people argue that @GNUTAR{} should not hesitate to overwrite files with other files when extracting. When extracting a @command{tar} archive, they expect to see a faithful copy of the -state of the filesystem when the archive was created. It is debatable +state of the file system when the archive was created. It is debatable that this would always be a proper behavior. For example, suppose one has an archive in which @file{usr/local} is a link to @file{usr/local2}. Since then, maybe the site removed the link and @@ -4260,22 +4310,24 @@ If you specify the @value{op-recursive-unlink} option, as far as current permissions will allow it. This could include removal of the contents of a full directory hierarchy. -@node Modification Times -@unnumberedsubsubsec Setting Modification Times +@node Data Modification Times +@unnumberedsubsubsec Setting Data Modification Times -Normally, @command{tar} sets the modification times of extracted files to -the modification times recorded for the files in the archive, but +@cindex Data modification times of extracted files +@cindex Modification times of extracted files +Normally, @command{tar} sets the data modification times of extracted +files to the corresponding times recorded for the files in the archive, but limits the permissions of extracted files by the current @code{umask} setting. -To set the modification times of extracted files to the time when +To set the data modification times of extracted files to the time when the files were extracted, use the @value{op-touch} option in conjunction with @value{op-extract}. @table @option @item --touch @itemx -m -Sets the modification time of extracted archive members to the time +Sets the data modification time of extracted archive members to the time they were extracted, not the time recorded for them in the archive. Use in conjunction with @value{op-extract}. @end table @@ -4283,6 +4335,8 @@ Use in conjunction with @value{op-extract}. @node Setting Access Permissions @unnumberedsubsubsec Setting Access Permissions +@cindex Permissions of extracted files +@cindex Modes of extracted files To set the modes (access permissions) of extracted files to those recorded for those files in the archive, use @option{--same-permissions} in conjunction with the @value{op-extract} operation. @FIXME{Should be @@ -4291,20 +4345,18 @@ aliased to ignore-umask.} @table @option @item --preserve-permission @itemx --same-permission -@itemx --ignore-umask +@c @itemx --ignore-umask @itemx -p Set modes of extracted archive members to those recorded in the archive, instead of current umask settings. Use in conjunction with @value{op-extract}. @end table -@FIXME{Following paragraph needs to be rewritten: why doesn't this cat -files together, why is this useful. is it really useful with -more than one file?} - @node Writing to Standard Output @unnumberedsubsubsec Writing to Standard Output +@cindex Writing extracted files to standard output +@cindex Standard output, writing extracted files to To write the extracted files to the standard output, instead of creating the files on the file system, use @value{op-to-stdout} in conjunction with @value{op-extract}. This option is useful if you are @@ -4316,12 +4368,12 @@ found in the archive. @table @option @item --to-stdout @itemx -O -Writes files to the standard output. Used in conjunction with -@value{op-extract}. Extract files to standard output. When this option -is used, instead of creating the files specified, @command{tar} writes -the contents of the files extracted to its standard output. This may -be useful if you are only extracting the files in order to send them -through a pipe. This option is meaningless with @value{op-list}. +Writes files to the standard output. Use only in conjunction with +@value{op-extract}. When this option is used, instead of creating the +files specified, @command{tar} writes the contents of the files +extracted to its standard output. This may be useful if you are only +extracting the files in order to send them through a pipe. This +option is meaningless with @value{op-list}. @end table This can be useful, for example, if you have a tar archive containing @@ -4338,6 +4390,121 @@ or even like this if you want to process the concatenation of the files: tar -xOzf foo.tgz bigfile1 bigfile2 | process @end smallexample +Hovewer, @option{--to-command} may be more convenient for use with +multiple files. See the next section. + +@node Writing to an External Program +@unnumberedsubsubsec Writing to an External Program + +You can instruct @command{tar} to send the contents of each extracted +file to the standard input of an external program: + +@table @option +@item --to-program=@var{command} +Extract files and pipe their contents to the standard input of +@var{command}. When this option is used, instead of creating the +files specified, @command{tar} invokes @var{command} and pipes the +contents of the files to its standard output. @var{Command} may +contain command line arguments. The program is executed via +@code{sh -c}. Notice, that @var{command} is executed once for each regular file +extracted. Non-regular files (directories, etc.) are ignored when this +option is used. +@end table + +The command can obtain the information about the file it processes +from the following environment variables: + +@table @var +@vrindex TAR_FILETYPE, to-command environment +@item TAR_FILETYPE +Type of the file. It is a single letter with the following meaning: + +@multitable @columnfractions 0.10 0.90 +@item f @tab Regular file +@item d @tab Directory +@item l @tab Symbolic link +@item h @tab Hard link +@item b @tab Block device +@item c @tab Character device +@end multitable + +Currently only regular files are supported. + +@vrindex TAR_MODE, to-command environment +@item TAR_MODE +File mode, an octal number. + +@vrindex TAR_FILENAME, to-command environment +@item TAR_FILENAME +The name of the file. + +@vrindex TAR_REALNAME, to-command environment +@item TAR_REALNAME +Name of the file as stored in the archive. + +@vrindex TAR_UNAME, to-command environment +@item TAR_UNAME +Name of the file owner. + +@vrindex TAR_GNAME, to-command environment +@item TAR_GNAME +Name of the file owner group. + +@vrindex TAR_ATIME, to-command environment +@item TAR_ATIME +Time of last access. It is a decimal number, representing seconds +since the epoch. If the archive provides times with nanosecond +precision, the nanoseconds are appended to the timestamp after a +decimal point. + +@vrindex TAR_MTIME, to-command environment +@item TAR_MTIME +Time of last modification. + +@vrindex TAR_CTIME, to-command environment +@item TAR_CTIME +Time of last status change. + +@vrindex TAR_SIZE, to-command environment +@item TAR_SIZE +Size of the file. + +@vrindex TAR_UID, to-command environment +@item TAR_UID +UID of the file owner. + +@vrindex TAR_GID, to-command environment +@item TAR_GID +GID of the file owner. +@end table + +In addition to these variables, @env{TAR_VERSION} contains the +@GNUTAR{} version number. + +If @var{command} exits with a non-0 status, @command{tar} will print +an error message similar to the following: + +@smallexample +tar: 2345: Child returned status 1 +@end smallexample + +Here, @samp{2345} is the PID of the finished process. + +If this behavior is not wanted, use @option{--ignore-command-error}: + +@table @option +@item --ignore-command-error +Ignore exit codes of subprocesses. Notice that if the program +exits on signal or otherwise terminates abnormally, the error message +will be printed even if this option is used. + +@item --no-ignore-command-error +Cancel the effect of any previous @option{--ignore-command-error} +option. This option is useful if you have set +@option{--ignore-command-error} in @env{TAR_OPTIONS} +(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it. +@end table + @node remove files @unnumberedsubsubsec Removing Files @@ -4666,7 +4833,7 @@ called @dfn{dumps}. @cindex corrupted archives Full dumps should only be made when no other people or programs -are modifying files in the filesystem. If files are modified while +are modifying files in the file system. If files are modified while @command{tar} is making the backup, they may not be stored properly in the archive, in which case you won't be able to restore them if you have to. (Files not being modified are written with no trouble, and do @@ -4676,18 +4843,18 @@ You will want to use the @value{op-label} option to give the archive a volume label, so you can tell what this archive is even if the label falls off the tape, or anything like that. -Unless the filesystem you are dumping is guaranteed to fit on +Unless the file system you are dumping is guaranteed to fit on one volume, you will need to use the @value{op-multi-volume} option. Make sure you have enough tapes on hand to complete the backup. -If you want to dump each filesystem separately you will need to use +If you want to dump each file system separately you will need to use the @value{op-one-file-system} option to prevent @command{tar} from crossing -filesystem boundaries when storing (sub)directories. +file system boundaries when storing (sub)directories. -The @value{op-incremental} (@FIXME-pxref{}) option is not needed, -since this is a complete copy of everything in the filesystem, and a +The @value{op-incremental} (@value{pxref-incremental}) option is not needed, +since this is a complete copy of everything in the file system, and a full restore from this backup would only be done onto a completely -empty disk. +empty disk. Unless you are in a hurry, and trust the @command{tar} program (and your tapes), it is a good idea to use the @value{op-verify} option, to make @@ -4700,16 +4867,16 @@ capable of being verified, unfortunately. @section Using @command{tar} to Perform Incremental Dumps @dfn{Incremental backup} is a special form of @GNUTAR{} archive that -stores additional metadata so that exact state of the filesystem -can be restored when extracting the archive. +stores additional metadata so that exact state of the file system +can be restored when extracting the archive. @GNUTAR{} currently offers two options for handling incremental -backups: @value{op-listed-incremental} and @value{op-incremental}. +backups: @value{op-listed-incremental} and @value{op-incremental}. The option @option{--listed-incremental} instructs tar to operate on an incremental archive with additional metadata stored in a standalone -file, called @dfn{snapshot file}. The purpose of this file is to help -determine what files have been changed, added or deleted since the +file, called a @dfn{snapshot file}. The purpose of this file is to help +determine which files have been changed, added or deleted since the last backup, so that the next incremental backup will contain only modified files. The name of the snapshot file is given as an argument to the option: @@ -4732,13 +4899,13 @@ $ @kbd{tar --create \ @end smallexample This will create in @file{archive.1.tar} an incremental backup of -@file{/usr} filesystem, storing additional metadata in the file +the @file{/usr} file system, storing additional metadata in the file @file{/var/log/usr.snar}. If this file does not exist, it will be -created. The created archive will then be called @dfn{level 0 backup} -(see the next section for more info on backup levels). +created. The created archive will then be a @dfn{level 0 backup}; +please see the next section for more on backup levels. -Otherwise, if the file @file{/var/log/usr.snar} exists, it is used to -determine the modified files. In this case only these files will be +Otherwise, if the file @file{/var/log/usr.snar} exists, it +determines which files are modified. In this case only these files will be stored in the archive. Suppose, for example, that after running the above command, you delete file @file{/usr/doc/old} and create directory @file{/usr/local/db} with the following contents: @@ -4749,7 +4916,7 @@ $ @kbd{ls /usr/local/db} /usr/local/db/index @end smallexample -Some time later you create another incremental backup. You will +Some time later you create another incremental backup. You will then see: @smallexample @@ -4765,7 +4932,7 @@ usr/local/db/index @noindent The created archive @file{archive.2.tar} will contain only these -three members. This archive is called @dfn{level 1 backup}. Notice, +three members. This archive is called a @dfn{level 1 backup}. Notice that @file{/var/log/usr.snar} will be updated with the new data, so if you plan to create more @samp{level 1} backups, it is necessary to create a working copy of the snapshot file before running @@ -4781,17 +4948,17 @@ $ @kbd{tar --create \ Incremental dumps depend crucially on time stamps, so the results are unreliable if you modify a file's time stamps during dumping (e.g., -with the @option{--atime-preserve} option), or if you set the clock +with the @option{--atime-preserve=replace} option), or if you set the clock backwards. Metadata stored in snapshot files include device numbers, which, obviously is supposed to be a non-volatile value. However, it turns -out that NFS devices have non-dependable values when an automounter +out that NFS devices have undependable values when an automounter gets in the picture. This can lead to a great deal of spurious redumping in incremental dumps, so it is somewhat useless to compare two NFS devices numbers over time. The solution implemented currently is to considers all NFS devices as being equal when it comes to -comparing directories; this is fairly gross, but there does not seem +comparing directories; this is fairly gross, but there does not seem to be a better way to go. Note that incremental archives use @command{tar} extensions and may @@ -4799,9 +4966,9 @@ not be readable by non-@acronym{GNU} versions of the @command{tar} program. To extract from the incremental dumps, use @option{--listed-incremental} together with @option{--extract} -option (@pxref{extracting files}). In this case, @command{tar} does +option (@pxref{extracting files}). In this case, @command{tar} does not need to access snapshot file, since all the data necessary for -extraction are stored in the archive itself. So, when extracting, you +extraction are stored in the archive itself. So, when extracting, you can give whatever argument to @option{--listed-incremental}, the usual practice is to use @option{--listed-incremental=/dev/null}. Alternatively, you can use @option{--incremental}, which needs no @@ -4817,10 +4984,10 @@ system that did not exist in their directories when the archive was created. If you have created several levels of incremental files, then in order to restore the exact contents the file system had when the last level was created, you will need to restore from all backups -in turn. Continuing our example, to restore the state of @file{/usr} +in turn. Continuing our example, to restore the state of @file{/usr} file system, one would do@footnote{Notice, that since both archives were created withouth @option{-P} option (@pxref{absolute}), these -commands should be run from the root filesystem.}: +commands should be run from the root file system.}: @smallexample $ @kbd{tar --extract \ @@ -4832,7 +4999,7 @@ $ @kbd{tar --extract \ @end smallexample To list the contents of an incremental archive, use @option{--list} -(@pxref{list}), as usual. To obtain more information about the +(@pxref{list}), as usual. To obtain more information about the archive, use @option{--listed-incremental} or @option{--incremental} combined with two @option{--verbose} options@footnote{Two @option{--verbose} options were selected to avoid breaking usual @@ -4865,7 +5032,7 @@ if the file is present in the archive, @samp{N} if the file is not included in the archive, or a @samp{D} if the file is a directory (and is included in the archive).@FIXME-xref{dumpdir format}. Each such line is terminated by a newline character. The last line is followed -by an additional newline to indicate the end of the data. +by an additional newline to indicate the end of the data. @anchor{incremental-op}The option @option{--incremental} (@option{-G}) gives the same behavior as @option{--listed-incremental} when used @@ -4906,9 +5073,9 @@ and @command{tar} commands by hand. Before you use these scripts, you need to edit the file @file{backup-specs}, which specifies parameters used by the backup scripts and by the restore script. This file is usually located -in @file{/etc/backup} directory. @FIXME-xref{Script Syntax} Once the -backup parameters are set, you can perform backups or restoration by -running the appropriate script. +in @file{/etc/backup} directory. @xref{Backup Parameters}, for its +detailed description. Once the backup parameters are set, you can +perform backups or restoration by running the appropriate script. The name of the backup script is @code{backup}. The name of the restore script is @code{restore}. The following sections describe @@ -4919,7 +5086,7 @@ designed to be used together. While it is possible to restore files by hand from an archive which was created using a backup script, and to create an archive by hand which could then be extracted using the restore script, it is easier to use the scripts. @value{xref-incremental}, before -making such an attempt. +making such an attempt. @node Backup Parameters @section Setting Parameters for Backups and Restoration @@ -5006,7 +5173,7 @@ in a separate file. This file is usually named @defvr {Backup variable} DIRLIST -A path to the file containing the list of the filesystems to backup +A path to the file containing the list of the file systems to backup or restore. By default it is @file{/etc/backup/dirs}. @end defvr @@ -5050,7 +5217,7 @@ of @GNUTAR{}. @defvr {Backup variable} VOLNO_FILE Name of temporary file to hold volume numbers. This needs to be accessible -by all the machines which have filesystems to be dumped. +by all the machines which have file systems to be dumped. @end defvr @defvr {Backup variable} XLIST @@ -5067,7 +5234,7 @@ This variable affects only @code{backup}. @defvr {Backup variable} SLEEP_TIME -Time to sleep between dumps of any two successive filesystems +Time to sleep between dumps of any two successive file systems This variable affects only @code{backup}. @end defvr @@ -5174,10 +5341,10 @@ Current backup or restore level. Name or IP address of the host machine being dumped or restored. @item fs -Full path name to the filesystem being dumped or restored. +Full path name to the file system being dumped or restored. @item fsname -Filesystem name with directory separators replaced with colons. This +File system name with directory separators replaced with colons. This is useful, e.g., for creating unique files. @end table @end deffn @@ -5185,19 +5352,19 @@ is useful, e.g., for creating unique files. Following variables keep the names of user hook functions @defvr {Backup variable} DUMP_BEGIN -Dump begin function. It is executed before dumping the filesystem. +Dump begin function. It is executed before dumping the file system. @end defvr @defvr {Backup variable} DUMP_END -Executed after dumping the filesystem. +Executed after dumping the file system. @end defvr @defvr {Backup variable} RESTORE_BEGIN -Executed before restoring the filesystem. +Executed before restoring the file system. @end defvr @defvr {Backup variable} RESTORE_END -Executed after restoring the filesystem. +Executed after restoring the file system. @end defvr @node backup-specs example @@ -5353,10 +5520,10 @@ Display program version and exit. To restore files that were archived using a scripted backup, use the @code{restore} script. Its usage is quite straightforward. In the simplest form, invoke @code{restore --all}, it will -then restore all the filesystems and files specified in +then restore all the file systems and files specified in @file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}). -You may select the filesystems (and/or files) to restore by +You may select the file systems (and/or files) to restore by giving @code{restore} list of @dfn{patterns} in its command line. For example, running @@ -5365,7 +5532,7 @@ restore 'albert:*' @end smallexample @noindent -will restore all filesystems on the machine @samp{albert}. A more +will restore all file systems on the machine @samp{albert}. A more complicated example: @smallexample @@ -5373,8 +5540,8 @@ restore 'albert:*' '*:/var' @end smallexample @noindent -This command will restore all filesystems on the machine @samp{albert} -as well as @file{/var} filesystem on all machines. +This command will restore all file systems on the machine @samp{albert} +as well as @file{/var} file system on all machines. By default @code{restore} will start restoring files from the lowest available dump level (usually zero) and will continue through @@ -5392,7 +5559,7 @@ The full list of options accepted by @code{restore} follows: @table @option @item -a @itemx --all -Restore all filesystems and files specified in @file{backup-specs} +Restore all file systems and files specified in @file{backup-specs} @item -l @var{level} @itemx --level=@var{level} @@ -5431,7 +5598,7 @@ system if they were not in the file system when the archive was made. @end quotation @value{xref-incremental}, for an explanation of how the script makes -that determination. +that determination. @node Choosing @chapter Choosing Files and Names for @command{tar} @@ -5453,7 +5620,7 @@ are in specified directories. * Wildcards:: * after:: Operating Only on New Files * recurse:: Descending into Directories -* one:: Crossing Filesystem Boundaries +* one:: Crossing File System Boundaries @end menu @node file @@ -5543,6 +5710,8 @@ prompt you for a username and password. If you use will complete the remote connection, if possible, using your username as the username on the remote machine. +@cindex Local and remote archives +@anchor{local and remote archives} 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 @@ -5820,24 +5989,21 @@ Causes @command{tar} to ignore directories containing a cache directory tag. @end table @findex exclude-caches -When creating an archive, -the @option{--exclude-caches} option -causes @command{tar} to exclude all directories -that contain a @dfn{cache directory tag}. -A cache directory tag is a short file -with the well-known name @file{CACHEDIR.TAG} -and having a standard header +When creating an archive, the @option{--exclude-caches} option causes +@command{tar} to exclude all directories that contain a @dfn{cache +directory tag}. A cache directory tag is a short file with the +well-known name @file{CACHEDIR.TAG} and having a standard header specified in @url{http://www.brynosaurus.com/cachedir/spec.html}. -Various applications write cache directory tags -into directories they use to hold regenerable, non-precious data, -so that such data can be more easily excluded from backups. +Various applications write cache directory tags into directories they +use to hold regenerable, non-precious data, so that such data can be +more easily excluded from backups. @menu -* controlling pattern-patching with exclude:: +* controlling pattern-matching with exclude:: * problems with exclude:: @end menu -@node controlling pattern-patching with exclude +@node controlling pattern-matching with exclude @unnumberedsubsec Controlling Pattern-Matching with the @code{exclude} Options Normally, a pattern matches a name if an initial subsequence of the @@ -5959,7 +6125,7 @@ patterns listed in a file. @samp{*} or @samp{?} for example, are replaced and expanded into all existing files matching the given pattern. However, @command{tar} often uses wildcard patterns for matching (or globbing) archive members instead -of actual files in the filesystem. Wildcard patterns are also used for +of actual files in the file system. Wildcard patterns are also used for verifying volume labels of @command{tar} archives. This section has the purpose of explaining wildcard syntax for @command{tar}. @@ -6009,21 +6175,22 @@ string: excluding a directory also excludes all the files beneath it. @node after @section Operating Only on New Files @cindex Excluding file by age +@cindex Data Modification time, excluding files by @cindex Modification time, excluding files by @cindex Age, excluding files by @UNREVISED 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} +whose data modification or status change times are newer than the @var{date} 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. +be a file name; the data modification 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 @option{--after-date} when extracting an archive, @command{tar} will only extract files newer than the @var{date} you specify. If you only want @command{tar} to make the date comparison based on -modification of the actual contents of the file (rather than inode +modification of the file's data (rather than status changes), then use the @value{op-newer-mtime} option. You may use these options with any operation. Note that these options @@ -6037,27 +6204,29 @@ deciding whether or not to archive the files. @itemx -N @var{date} Only store files newer than @var{date}. -Acts on files only if their modification or inode-changed times are +Acts on files only if their data modification or status change 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. +name; the data modification 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. +Acts like @value{op-after-date}, but only looks at data modification times. @end table -These options limit @command{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, +These options limit @command{tar} to operate only on files which have +been modified after the date specified. A file's status is considered to have +changed if its contents have been modified, or if its 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. +Gurus would say that @value{op-after-date} tests both the data +modification time (@code{mtime}, the time the contents of the file +were last modified) and the status change time (@code{ctime}, the time +the file's status was last changed: owner, permissions, etc.@:) +fields, while @value{op-newer-mtime} tests only the @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 @@ -6137,7 +6306,7 @@ 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}). +are interpreted (@pxref{controlling pattern-matching with exclude}). The @option{--no-recursion} and @option{--recursion} options apply to later options and operands, and can be overridden by later occurrences @@ -6153,7 +6322,7 @@ contents of @file{grape/concord}, but no entries under @file{grape} other than @file{grape/concord}. @node one -@section Crossing Filesystem Boundaries +@section Crossing File System Boundaries @cindex File system boundaries, not crossing @UNREVISED @@ -6174,7 +6343,7 @@ archiving. Use in conjunction with any write operation. The @option{--one-file-system} option causes @command{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 +a directory is not on the same file system as the directory itself, then @command{tar} will not archive that file. If the file is a directory itself, @command{tar} will not archive anything beneath it; in other words, @command{tar} will not cross mount points. @@ -6566,7 +6735,7 @@ than System V's. Normally, when @command{tar} archives a symbolic link, it writes a block to the archive naming the target of the link. In that way, the -@command{tar} archive is a faithful record of the filesystem contents. +@command{tar} archive is a faithful record of the file system contents. @value{op-dereference} is used with @value{op-create}, and causes @command{tar} to archive the files symbolic links point to, instead of the links themselves. When this option is used, when @command{tar} @@ -6930,7 +7099,7 @@ treatment of sparse files may be done automatically with any special @acronym{GNU} options. For now, it is an option needing to be specified on the command line with the creation or updating of an archive. -Files in the filesystem occasionally have ``holes.'' A hole in a file +Files in the file system 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 disk storage is not allocated for holes, but they are counted @@ -7027,29 +7196,44 @@ get it right. @section Handling File Attributes @UNREVISED -When @command{tar} reads files, this causes them to have the access -times updated. To have @command{tar} attempt to set the access times -back to what they were before they were read, use the -@value{op-atime-preserve} option. +When @command{tar} reads files, it updates their access times. To +avoid this, use the @value{op-atime-preserve} option, which can either +reset the access time retroactively or avoid changing it in the first +place. Handling of file attributes @table @option @item --atime-preserve -Preserve access times on files that are read. -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{Backups}), and it can set access or -modification times incorrectly if other programs access the file while -@command{tar} is running; but it is good enough for some purposes. +@itemx --atime-preserve=replace +@itemx --atime-preserve=system +Preserve the access times of files that are read. This works only for +files that you own, unless you have superuser privileges. + +@value{op-atime-preserve-replace} works on most systems, but it also +restores the data modification time and updates the status change +time. Hence it doesn't interact with incremental dumps nicely +(@pxref{Backups}), and it can set access or data modification times +incorrectly if other programs access the file while @command{tar} is +running. + +@value{op-atime-preserve-system} avoids changing the access time in +the first place, if the operating system supports this. +Unfortunately, this may or may not work on any given operating system +or file system. If @command{tar} knows for sure it won't work, it +complains right away. + +Currently @option{--atime-preserve} with no operand defaults to +@value{op-atime-preserve-replace}, but this is intended to change to +@value{op-atime-preserve-system} when the latter is better-supported. @item -m @itemx --touch -Do not extract file modified time. +Do not extract data modification time. -When this option is used, @command{tar} leaves the modification times -of the files it extracts as the time when the files were extracted, -instead of setting it to the time recorded in the archive. +When this option is used, @command{tar} leaves the data modification times +of the files it extracts as the times when the files were extracted, +instead of setting it to the times recorded in the archive. This option is meaningless with @value{op-list}. @@ -7090,7 +7274,7 @@ This is useful in certain circumstances, when restoring a backup from an emergency floppy with different passwd/group files for example. It is otherwise impossible to extract files with the right ownerships if the password file in use during the extraction does not match the -one belonging to the filesystem(s) being extracted. This occurs, +one belonging to the file system(s) being extracted. This occurs, for example, if you are restoring your files after a major crash and had booted from an emergency floppy with no password file or put your disk into another machine to do the restore. @@ -7244,9 +7428,10 @@ The @code{size} field is the size of the file in bytes; linked files are archived with this field specified as zero. @FIXME-xref{Modifiers, in particular the @value{op-incremental} option.} -The @code{mtime} field is the modification time of the file at the time -it was archived. It is the ASCII representation of the octal value of -the last time the file was modified, represented as an integer number of +The @code{mtime} field is the data modification time of the file at +the time it was archived. It is the ASCII representation of the octal +value of the last time the file's contents were modified, represented +as an integer number of seconds since January 1, 1970, 00:00 Coordinated Universal Time. The @code{chksum} field is the ASCII representation of the octal value @@ -7262,8 +7447,8 @@ type, the file will be extracted as if it were a regular file. As this action occurs, @command{tar} issues a warning to the standard error. The @code{atime} and @code{ctime} fields are used in making incremental -backups; they store, respectively, the particular file's access time -and last inode-change time. +backups; they store, respectively, the particular file's access and +status change times. The @code{offset} is used by the @value{op-multi-volume} option, when making a multi-volume archive. The offset is number of bytes into @@ -7716,8 +7901,9 @@ 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. If @file{file} exits with -nonzero status, exit. This implies @value{op-multi-volume}. +Execute @file{file} at end of each tape. This implies +@value{op-multi-volume}. @xref{info-script}, for a detailed +description of this option. @end table @node Remote Tape Server @@ -8426,7 +8612,7 @@ failed. 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 @command{tar} commands, but this can be inconvenient, particularly if you -are using options like @value{op-exclude} or dumping entire filesystems. +are using options like @value{op-exclude} or dumping entire file systems. Therefore, @command{tar} supports multiple tapes automatically. Use @value{op-multi-volume} on the command line, and then @command{tar} will, @@ -8439,9 +8625,8 @@ the first archive, using @value{op-multi-volume}, and then put in the second tape when prompted, so @command{tar} can restore both halves of the file.) -@GNUTAR{} multi-volume archives do not use a truly -portable format. You need @GNUTAR{} at both end to -process them properly. +@GNUTAR{} multi-volume archives do not use a truly portable format. +You need @GNUTAR{} at both ends to process them properly. When prompting for a new tape, @command{tar} accepts any of the following responses: @@ -8454,7 +8639,8 @@ Request @command{tar} to exit immediately. @item n @var{file name} Request @command{tar} to write the next volume on the file @var{file name}. @item ! -Request @command{tar} to run a subshell. +Request @command{tar} to run a subshell. This option can be disabled +by giving @option{--restrict} command line option to @command{tar}. @item y Request @command{tar} to begin writing the next volume. @end table @@ -8462,14 +8648,46 @@ Request @command{tar} to begin writing the next volume. (You should only type @samp{y} after you have changed the tape; otherwise @command{tar} will write over the volume it just finished.) +@cindex End-of-archive info script +@cindex Info script +@anchor{info-script} 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. 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}. +prompting procedure. It is executed without any command line +arguments. Additional data is passed to it via the following +environment variables: + +@table @env +@vrindex TAR_VERSION, info script environment variable +@item TAR_VERSION +@GNUTAR{} version number. + +@vrindex TAR_ARCHIVE, info script environment variable +@item TAR_ARCHIVE +The name of the archive @command{tar} is processing. + +@vrindex TAR_VOLUME, info script environment variable +@item TAR_VOLUME +Ordinal number of the volume @command{tar} is about to start. + +@vrindex TAR_SUBCOMMAND, info script environment variable +@item TAR_SUBCOMMAND +Short option describing the operation @command{tar} is executed. +@xref{Operations}, for a complete list of subcommand options. + +@vrindex TAR_FORMAT, info script environment variable +@item TAR_FORMAT +Format of the archive being processed. @xref{Formats}, for a complete +list of archive format names. +@end table + +The info script can instruct @command{tar} to use new archive name, +by writing in to file descriptor 3 (see below for an +example). + +If the info script fails, @command{tar} exits; otherwise, it begins +writing the next volume. The method @command{tar} uses to detect end of tape is not perfect, and fails on some operating systems or on some devices. You can use the @@ -8479,6 +8697,9 @@ The @var{size} argument should then be the usable size of the tape. But for many devices, and floppy disks in particular, this option is never required for real, as far as we know. +@cindex Volume number file +@cindex volno file +@anchor{volno-file} The volume number used by @command{tar} in its tape-change prompt can be changed; if you give the @value{op-volno-file} option, then @var{file-of-number} should be an unexisting file to be created, or else, @@ -8489,21 +8710,33 @@ finished, it will rewrite the file with the now-current volume number. per @value{ref-label}, it @emph{only} affects the number used in the prompt.) -If you want @command{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 @value{op-info-script}. -Therefore, if you give @command{tar} multiple @value{op-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 @command{tar} prompt for a tape change (or run the info -script). +If you want @command{tar} to cycle through a series of files or tape +drives, there are three approaches to choose from. First of all, you +can give @command{tar} multiple @value{op-file} options. In this case +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 @command{tar} prompt for a tape change (or run +the info script). Secondly, you can use the @samp{n} response to the +tape-change prompt, and, finally, you can use an info script, that +writes new archive name to file descriptor. The following example +illustrates this approach: -Multi-volume archives - -With @value{op-multi-volume}, @command{tar} will not abort when it cannot -read or write any more data. Instead, it will ask you to prepare a new -volume. If the archive is on a magnetic tape, you should change tapes -now; if the archive is on a floppy disk, you should change disks, etc. +@smallexample +@group +#! /bin/sh +echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE. + +name=`expr $TAR_ARCHIVE : '\(.*\)-.*'` +case $TAR_SUBCOMMAND in +-c) ;; +-d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1 + ;; +*) exit 1 +esac + +echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&3 +@end group +@end smallexample Each volume of a multi-volume archive is an independent @command{tar} archive, complete in itself. For example, you can list or extract any @@ -8564,13 +8797,14 @@ should load the volume where the archive member starts, and use volumes as it needs them. @xref{extracting archives}, for more information about extracting archives. -@value{op-info-script} is like @value{op-multi-volume}, except that -@command{tar} does not prompt you directly to change media volumes when -a volume is full---instead, @command{tar} runs commands you have stored -in @var{script-name}. For example, this option can be used to eject -cassettes, or to broadcast messages such as @samp{Someone please come -change my tape} when performing unattended backups. When @var{script-name} -is done, @command{tar} will assume that the media has been changed. +@value{op-info-script} (@pxref{info-script}) is like +@value{op-multi-volume}, except that @command{tar} does not prompt you +directly to change media volumes when a volume is full---instead, +@command{tar} runs commands you have stored in @var{script-name}. For +example, this option can be used to eject cassettes, or to broadcast +messages such as @samp{Someone please come change my tape} when +performing unattended backups. When @var{script-name} is done, +@command{tar} will assume that the media has been changed. Multi-volume archives can be modified like any other archive. To add files to a multi-volume archive, you need to only mount the last @@ -8600,7 +8834,7 @@ operation. @item --info-script=@var{program-file} @itemx -F @var{program-file} Creates a multi-volume archive via a script. Used in conjunction with -@value{op-create}. +@value{op-create}. @xref{info-script}, dor a detailed discussion. @end table Beware that there is @emph{no} real standard about the proper way, for @@ -8670,7 +8904,7 @@ the first volume file and to decide how to process the rest of the files. However, it makes no attempt to verify whether the files are given in order or even if they are valid @command{tar} archives. It uses @command{dd} and does not filter its standard error, so you -will usually see lots of spurious messages. +will usually see lots of spurious messages. @FIXME{The script is not installed. Should we install it?}