diff options
Diffstat (limited to 'doc/tar.info-2')
| -rw-r--r-- | doc/tar.info-2 | 4783 |
1 files changed, 4783 insertions, 0 deletions
diff --git a/doc/tar.info-2 b/doc/tar.info-2 new file mode 100644 index 0000000..7da7165 --- /dev/null +++ b/doc/tar.info-2 @@ -0,0 +1,4783 @@ +This is tar.info, produced by makeinfo version 4.8 from tar.texi. + + This manual is for GNU `tar' (version 1.17, 8 June 2007), which +creates and extracts files from archives. + + Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003, +2004, 2005, 2006, 2007 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 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover Texts + being "A GNU Manual," and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + "GNU Free Documentation License". + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify + this GNU Manual. Buying copies from GNU Press supports the FSF in + developing GNU and promoting software freedom." + +INFO-DIR-SECTION Archiving +START-INFO-DIR-ENTRY +* Tar: (tar). Making tape (or disk) archives. +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* tar: (tar)tar invocation. Invoking GNU `tar'. +END-INFO-DIR-ENTRY + + +File: tar.info, Node: Portability, Next: cpio, Prev: Attributes, Up: Formats + +8.3 Making `tar' Archives More Portable +======================================= + +Creating a `tar' archive on a particular system that is meant to be +useful later on many other machines and with other versions of `tar' is +more challenging than you might think. `tar' archive formats have been +evolving since the first versions of Unix. Many such formats are +around, and are not always compatible with each other. This section +discusses a few problems, and gives some advice about making `tar' +archives more portable. + + One golden rule is simplicity. For example, limit your `tar' +archives to contain only regular files and directories, avoiding other +kind of special files. Do not attempt to save sparse files or +contiguous files as such. Let's discuss a few more problems, in turn. + +* Menu: + +* Portable Names:: Portable Names +* dereference:: Symbolic Links +* old:: Old V7 Archives +* ustar:: Ustar Archives +* gnu:: GNU and old GNU format archives. +* posix:: POSIX archives +* Checksumming:: Checksumming Problems +* Large or Negative Values:: Large files, negative time stamps, etc. +* Other Tars:: How to Extract GNU-Specific Data Using + Other `tar' Implementations + + +File: tar.info, Node: Portable Names, Next: dereference, Up: Portability + +8.3.1 Portable Names +-------------------- + +Use portable file and member names. A name is portable if it contains +only ASCII letters and digits, `/', `.', `_', and `-'; it cannot be +empty, start with `-' or `//', or contain `/-'. Avoid deep directory +nesting. For portability to old Unix hosts, limit your file name +components to 14 characters or less. + + If you intend to have your `tar' archives to be read under MSDOS, +you should not rely on case distinction for file names, and you might +use the GNU `doschk' program for helping you further diagnosing illegal +MSDOS names, which are even more limited than System V's. + + +File: tar.info, Node: dereference, Next: old, Prev: Portable Names, Up: Portability + +8.3.2 Symbolic Links +-------------------- + +Normally, when `tar' archives a symbolic link, it writes a block to the +archive naming the target of the link. In that way, the `tar' archive +is a faithful record of the file system contents. `--dereference' +(`-h') is used with `--create' (`-c'), and causes `tar' to archive the +files symbolic links point to, instead of the links themselves. When +this option is used, when `tar' encounters a symbolic link, it will +archive the linked-to file, instead of simply recording the presence of +a symbolic link. + + The name under which the file is stored in the file system is not +recorded in the archive. To record both the symbolic link name and the +file name in the system, archive the file under both names. If all +links were recorded automatically by `tar', an extracted file might be +linked to a file name that no longer exists in the file system. + + If a linked-to file is encountered again by `tar' while creating the +same archive, an entire second copy of it will be stored. (This +_might_ be considered a bug.) + + So, for portable archives, do not archive symbolic links as such, +and use `--dereference' (`-h'): many systems do not support symbolic +links, and moreover, your distribution might be unusable if it contains +unresolved symbolic links. + + +File: tar.info, Node: old, Next: ustar, Prev: dereference, Up: Portability + +8.3.3 Old V7 Archives +--------------------- + +Certain old versions of `tar' cannot handle additional information +recorded by newer `tar' programs. To create an archive in V7 format +(not ANSI), which can be read by these old versions, specify the +`--format=v7' option in conjunction with the `--create' (`-c') (`tar' +also accepts `--portability' or `--old-archive' for this option). When +you specify it, `tar' leaves out information about directories, pipes, +fifos, contiguous files, and device files, and specifies file ownership +by group and user IDs instead of group and user names. + + When updating an archive, do not use `--format=v7' unless the +archive was created using this option. + + In most cases, a _new_ format archive can be read by an _old_ `tar' +program without serious trouble, so this option should seldom be +needed. On the other hand, most modern `tar's are able to read old +format archives, so it might be safer for you to always use +`--format=v7' for your distributions. Notice, however, that `ustar' +format is a better alternative, as it is free from many of `v7''s +drawbacks. + + +File: tar.info, Node: ustar, Next: gnu, Prev: old, Up: Portability + +8.3.4 Ustar Archive Format +-------------------------- + +Archive format defined by POSIX.1-1988 specification is called `ustar'. +Although it is more flexible than the V7 format, it still has many +restrictions (*Note ustar: Formats, for the detailed description of +`ustar' format). Along with V7 format, `ustar' format is a good choice +for archives intended to be read with other implementations of `tar'. + + To create archive in `ustar' format, use `--format=ustar' option in +conjunction with the `--create' (`-c'). + + +File: tar.info, Node: gnu, Next: posix, Prev: ustar, Up: Portability + +8.3.5 GNU and old GNU `tar' format +---------------------------------- + +GNU `tar' was based on an early draft of the POSIX 1003.1 `ustar' +standard. GNU extensions to `tar', such as the support for file names +longer than 100 characters, use portions of the `tar' header record +which were specified in that POSIX draft as unused. Subsequent changes +in POSIX have allocated the same parts of the header record for other +purposes. As a result, GNU `tar' format is incompatible with the +current POSIX specification, and with `tar' programs that follow it. + + In the majority of cases, `tar' will be configured to create this +format by default. This will change in future releases, since we plan +to make `POSIX' format the default. + + To force creation a GNU `tar' archive, use option `--format=gnu'. + + +File: tar.info, Node: posix, Next: Checksumming, Prev: gnu, Up: Portability + +8.3.6 GNU `tar' and POSIX `tar' +------------------------------- + +Starting from version 1.14 GNU `tar' features full support for +POSIX.1-2001 archives. + + A POSIX conformant archive will be created if `tar' was given +`--format=posix' (`--format=pax') option. No special option is +required to read and extract from a POSIX archive. + +* Menu: + +* PAX keywords:: Controlling Extended Header Keywords. + + +File: tar.info, Node: PAX keywords, Up: posix + +8.3.6.1 Controlling Extended Header Keywords +............................................ + +`--pax-option=KEYWORD-LIST' + Handle keywords in PAX extended headers. This option is + equivalent to `-o' option of the `pax' utility. + + KEYWORD-LIST is a comma-separated list of keyword options, each +keyword option taking one of the following forms: + +`delete=PATTERN' + When used with one of archive-creation commands, this option + instructs `tar' to omit from extended header records that it + produces any keywords matching the string PATTERN. + + When used in extract or list mode, this option instructs tar to + ignore any keywords matching the given PATTERN in the extended + header records. In both cases, matching is performed using the + pattern matching notation described in POSIX 1003.2, 3.13 (*note + wildcards::). For example: + + --pax-option delete=security.* + + would suppress security-related information. + +`exthdr.name=STRING' + This keyword allows user control over the name that is written + into the ustar header blocks for the extended headers. The name + is obtained from STRING after making the following substitutions: + + Meta-character Replaced By + -------------------------------------------------------- + %d The directory name of the file, + equivalent to the result of the + `dirname' utility on the translated + file name. + %f The name of the file with the + directory information stripped, + equivalent to the result of the + `basename' utility on the translated + file name. + %p The process ID of the `tar' process. + %% A `%' character. + + Any other `%' characters in STRING produce undefined results. + + If no option `exthdr.name=string' is specified, `tar' will use the + following default value: + + %d/PaxHeaders.%p/%f + +`globexthdr.name=STRING' + This keyword allows user control over the name that is written into + the ustar header blocks for global extended header records. The + name is obtained from the contents of STRING, after making the + following substitutions: + + Meta-character Replaced By + -------------------------------------------------------- + %n An integer that represents the + sequence number of the global + extended header record in the + archive, starting at 1. + %p The process ID of the `tar' process. + %% A `%' character. + + Any other `%' characters in STRING produce undefined results. + + If no option `globexthdr.name=string' is specified, `tar' will use + the following default value: + + $TMPDIR/GlobalHead.%p.%n + + where `$TMPDIR' represents the value of the TMPDIR environment + variable. If TMPDIR is not set, `tar' uses `/tmp'. + +`KEYWORD=VALUE' + When used with one of archive-creation commands, these + keyword/value pairs will be included at the beginning of the + archive in a global extended header record. When used with one of + archive-reading commands, `tar' will behave as if it has + encountered these keyword/value pairs at the beginning of the + archive in a global extended header record. + +`KEYWORD:=VALUE' + When used with one of archive-creation commands, these + keyword/value pairs will be included as records at the beginning + of an extended header for each file. This is effectively + equivalent to KEYWORD=VALUE form except that it creates no global + extended header records. + + When used with one of archive-reading commands, `tar' will behave + as if these keyword/value pairs were included as records at the + end of each extended header; thus, they will override any global or + file-specific extended header record keywords of the same names. + For example, in the command: + + tar --format=posix --create \ + --file archive --pax-option gname:=user . + + the group name will be forced to a new value for all files stored + in the archive. + + +File: tar.info, Node: Checksumming, Next: Large or Negative Values, Prev: posix, Up: Portability + +8.3.7 Checksumming Problems +--------------------------- + +SunOS and HP-UX `tar' fail to accept archives created using GNU `tar' +and containing non-ASCII file names, that is, file names having +characters with the eight bit set, because they use signed checksums, +while GNU `tar' uses unsigned checksums while creating archives, as per +POSIX standards. On reading, GNU `tar' computes both checksums and +accept any. It is somewhat worrying that a lot of people may go around +doing backup of their files using faulty (or at least non-standard) +software, not learning about it until it's time to restore their +missing files with an incompatible file extractor, or vice versa. + + GNU `tar' compute checksums both ways, and accept any on read, so +GNU tar can read Sun tapes even with their wrong checksums. GNU `tar' +produces the standard checksum, however, raising incompatibilities with +Sun. That is to say, GNU `tar' has not been modified to _produce_ +incorrect archives to be read by buggy `tar''s. I've been told that +more recent Sun `tar' now read standard archives, so maybe Sun did a +similar patch, after all? + + The story seems to be that when Sun first imported `tar' sources on +their system, they recompiled it without realizing that the checksums +were computed differently, because of a change in the default signing +of `char''s in their compiler. So they started computing checksums +wrongly. When they later realized their mistake, they merely decided +to stay compatible with it, and with themselves afterwards. +Presumably, but I do not really know, HP-UX has chosen that their `tar' +archives to be compatible with Sun's. The current standards do not +favor Sun `tar' format. In any case, it now falls on the shoulders of +SunOS and HP-UX users to get a `tar' able to read the good archives +they receive. + + +File: tar.info, Node: Large or Negative Values, Next: Other Tars, Prev: Checksumming, Up: Portability + +8.3.8 Large or Negative Values +------------------------------ + + _(This message will disappear, once this node revised.)_ + +The above sections suggest to use `oldest possible' archive format if +in doubt. However, sometimes it is not possible. If you attempt to +archive a file whose metadata cannot be represented using required +format, GNU `tar' will print error message and ignore such a file. You +will than have to switch to a format that is able to handle such +values. The format summary table (*note Formats::) will help you to do +so. + + In particular, when trying to archive files larger than 8GB or with +timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16 +12:56:31 UTC, you will have to chose between GNU and POSIX archive +formats. When considering which format to choose, bear in mind that +the GNU format uses two's-complement base-256 notation to store values +that do not fit into standard ustar range. Such archives can generally +be read only by a GNU `tar' implementation. Moreover, they sometimes +cannot be correctly restored on another hosts even by GNU `tar'. For +example, using two's complement representation for negative time stamps +that assumes a signed 32-bit `time_t' generates archives that are not +portable to hosts with differing `time_t' representations. + + On the other hand, POSIX archives, generally speaking, can be +extracted by any tar implementation that understands older ustar +format. The only exception are files larger than 8GB. + + +File: tar.info, Node: Other Tars, Prev: Large or Negative Values, Up: Portability + +8.3.9 How to Extract GNU-Specific Data Using Other `tar' Implementations +------------------------------------------------------------------------ + +In previous sections you became acquainted with various quirks +necessary to make your archives portable. Sometimes you may need to +extract archives containing GNU-specific members using some third-party +`tar' implementation or an older version of GNU `tar'. Of course your +best bet is to have GNU `tar' installed, but if it is for some reason +impossible, this section will explain how to cope without it. + + When we speak about "GNU-specific" members we mean two classes of +them: members split between the volumes of a multi-volume archive and +sparse members. You will be able to always recover such members if the +archive is in PAX format. In addition split members can be recovered +from archives in old GNU format. The following subsections describe +the required procedures in detail. + +* Menu: + +* Split Recovery:: Members Split Between Volumes +* Sparse Recovery:: Sparse Members + + +File: tar.info, Node: Split Recovery, Next: Sparse Recovery, Up: Other Tars + +8.3.9.1 Extracting Members Split Between Volumes +................................................ + +If a member is split between several volumes of an old GNU format +archive most third party `tar' implementation will fail to extract it. +To extract it, use `tarcat' program (*note Tarcat::). This program is +available from GNU `tar' home page +(http://www.gnu.org/software/tar/utils/tarcat.html). It concatenates +several archive volumes into a single valid archive. For example, if +you have three volumes named from `vol-1.tar' to `vol-3.tar', you can +do the following to extract them using a third-party `tar': + + $ tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf - + + You could use this approach for most (although not all) PAX format +archives as well. However, extracting split members from a PAX archive +is a much easier task, because PAX volumes are constructed in such a +way that each part of a split member is extracted to a different file +by `tar' implementations that are not aware of GNU extensions. More +specifically, the very first part retains its original name, and all +subsequent parts are named using the pattern: + + %d/GNUFileParts.%p/%f.%n + +where symbols preceeded by `%' are "macro characters" that have the +following meaning: + +Meta-character Replaced By +------------------------------------------------------------ +%d The directory name of the file, + equivalent to the result of the + `dirname' utility on its full name. +%f The file name of the file, equivalent + to the result of the `basename' utility + on its full name. +%p The process ID of the `tar' process that + created the archive. +%n Ordinal number of this particular part. + + For example, if the file `var/longfile' was split during archive +creation between three volumes, and the creator `tar' process had +process ID `27962', then the member names will be: + + var/longfile + var/GNUFileParts.27962/longfile.1 + var/GNUFileParts.27962/longfile.2 + + When you extract your archive using a third-party `tar', these files +will be created on your disk, and the only thing you will need to do to +restore your file in its original form is concatenate them in the +proper order, for example: + + $ cd var + $ cat GNUFileParts.27962/longfile.1 \ + GNUFileParts.27962/longfile.2 >> longfile + $ rm -f GNUFileParts.27962 + + Notice, that if the `tar' implementation you use supports PAX format +archives, it will probably emit warnings about unknown keywords during +extraction. They will look like this: + + Tar file too small + Unknown extended header keyword 'GNU.volume.filename' ignored. + Unknown extended header keyword 'GNU.volume.size' ignored. + Unknown extended header keyword 'GNU.volume.offset' ignored. + +You can safely ignore these warnings. + + If your `tar' implementation is not PAX-aware, you will get more +warnings and more files generated on your disk, e.g.: + + $ tar xf vol-1.tar + var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as + normal file + Unexpected EOF in archive + $ tar xf vol-2.tar + tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file + GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type + 'x', extracted as normal file + + Ignore these warnings. The `PaxHeaders.*' directories created will +contain files with "extended header keywords" describing the extracted +files. You can delete them, unless they describe sparse members. Read +further to learn more about them. + + +File: tar.info, Node: Sparse Recovery, Prev: Split Recovery, Up: Other Tars + +8.3.9.2 Extracting Sparse Members +................................. + +Any `tar' implementation will be able to extract sparse members from a +PAX archive. However, the extracted files will be "condensed", i.e., +any zero blocks will be removed from them. When we restore such a +condensed file to its original form, by adding zero blocks (or "holes") +back to their original locations, we call this process "expanding" a +compressed sparse file. + + To expand a file, you will need a simple auxiliary program called +`xsparse'. It is available in source form from GNU `tar' home page +(http://www.gnu.org/software/tar/utils/xsparse.html). + + Let's begin with archive members in "sparse format version 1.0"(1), +which are the easiest to expand. The condensed file will contain both +file map and file data, so no additional data will be needed to restore +it. If the original file name was `DIR/NAME', then the condensed file +will be named `DIR/GNUSparseFile.N/NAME', where N is a decimal +number(2). + + To expand a version 1.0 file, run `xsparse' as follows: + + $ xsparse `cond-file' + +where `cond-file' is the name of the condensed file. The utility will +deduce the name for the resulting expanded file using the following +algorithm: + + 1. If `cond-file' does not contain any directories, `../cond-file' + will be used; + + 2. If `cond-file' has the form `DIR/T/NAME', where both T and NAME + are simple names, with no `/' characters in them, the output file + name will be `DIR/NAME'. + + 3. Otherwise, if `cond-file' has the form `DIR/NAME', the output file + name will be `NAME'. + + In the unlikely case when this algorithm does not suit your needs, +you can explicitly specify output file name as a second argument to the +command: + + $ xsparse `cond-file' `out-file' + + It is often a good idea to run `xsparse' in "dry run" mode first. +In this mode, the command does not actually expand the file, but +verbosely lists all actions it would be taking to do so. The dry run +mode is enabled by `-n' command line argument: + + $ xsparse -n /home/gray/GNUSparseFile.6058/sparsefile + Reading v.1.0 sparse map + Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to + `/home/gray/sparsefile' + Finished dry run + + To actually expand the file, you would run: + + $ xsparse /home/gray/GNUSparseFile.6058/sparsefile + +The program behaves the same way all UNIX utilities do: it will keep +quiet unless it has simething important to tell you (e.g. an error +condition or something). If you wish it to produce verbose output, +similar to that from the dry run mode, use `-v' option: + + $ xsparse -v /home/gray/GNUSparseFile.6058/sparsefile + Reading v.1.0 sparse map + Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to + `/home/gray/sparsefile' + Done + + Additionally, if your `tar' implementation has extracted the +"extended headers" for this file, you can instruct `xstar' to use them +in order to verify the integrity of the expanded file. The option `-x' +sets the name of the extended header file to use. Continuing our +example: + + $ xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \ + /home/gray/GNUSparseFile.6058/sparsefile + Reading extended header file + Found variable GNU.sparse.major = 1 + Found variable GNU.sparse.minor = 0 + Found variable GNU.sparse.name = sparsefile + Found variable GNU.sparse.realsize = 217481216 + Reading v.1.0 sparse map + Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to + `/home/gray/sparsefile' + Done + + An "extended header" is a special `tar' archive header that precedes +an archive member and contains a set of "variables", describing the +member properties that cannot be stored in the standard `ustar' header. +While optional for expanding sparse version 1.0 members, the use of +extended headers is mandatory when expanding sparse members in older +sparse formats: v.0.0 and v.0.1 (The sparse formats are described in +detail in *note Sparse Formats::.) So, for these formats, the question +is: how to obtain extended headers from the archive? + + If you use a `tar' implementation that does not support PAX format, +extended headers for each member will be extracted as a separate file. +If we represent the member name as `DIR/NAME', then the extended header +file will be named `DIR/PaxHeaders.N/NAME', where N is an integer +number. + + Things become more difficult if your `tar' implementation does +support PAX headers, because in this case you will have to manually +extract the headers. We recommend the following algorithm: + + 1. Consult the documentation of your `tar' implementation for an + option that prints "block numbers" along with the archive listing + (analogous to GNU `tar''s `-R' option). For example, `star' has + `-block-number'. + + 2. Obtain verbose listing using the `block number' option, and find + block numbers of the sparse member in question and the member + immediately following it. For example, running `star' on our + archive we obtain: + + $ star -t -v -block-number -f arc.tar + ... + star: Unknown extended header keyword 'GNU.sparse.size' ignored. + star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored. + star: Unknown extended header keyword 'GNU.sparse.name' ignored. + star: Unknown extended header keyword 'GNU.sparse.map' ignored. + block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile + block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README + ... + + (as usual, ignore the warnings about unknown keywords.) + + 3. Let SIZE be the size of the sparse member, BS be its block number + and BN be the block number of the next member. Compute: + + N = BS - BN - SIZE/512 - 2 + + This number gives the size of the extended header part in tar + "blocks". In our example, this formula gives: `897 - 56 - 425984 + / 512 - 2 = 7'. + + 4. Use `dd' to extract the headers: + + dd if=ARCHIVE of=HNAME bs=512 skip=BS count=N + + where ARCHIVE is the archive name, HNAME is a name of the file to + store the extended header in, BS and N are computed in previous + steps. + + In our example, this command will be + + $ dd if=arc.tar of=xhdr bs=512 skip=56 count=7 + + Finally, you can expand the condensed file, using the obtained +header: + + $ xsparse -v -x xhdr GNUSparseFile.6058/sparsefile + Reading extended header file + Found variable GNU.sparse.size = 217481216 + Found variable GNU.sparse.numblocks = 208 + Found variable GNU.sparse.name = sparsefile + Found variable GNU.sparse.map = 0,2048,1050624,2048,... + Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile' + Done + + ---------- Footnotes ---------- + + (1) *Note PAX 1::. + + (2) technically speaking, N is a "process ID" of the `tar' process +which created the archive (*note PAX keywords::). + + +File: tar.info, Node: cpio, Prev: Portability, Up: Formats + +8.4 Comparison of `tar' and `cpio' +================================== + + _(This message will disappear, once this node revised.)_ + +The `cpio' archive formats, like `tar', do have maximum file name +lengths. The binary and old ASCII formats have a maximum file length +of 256, and the new ASCII and CRC ASCII formats have a max file length +of 1024. GNU `cpio' can read and write archives with arbitrary file +name lengths, but other `cpio' implementations may crash unexplainedly +trying to read them. + + `tar' handles symbolic links in the form in which it comes in BSD; +`cpio' doesn't handle symbolic links in the form in which it comes in +System V prior to SVR4, and some vendors may have added symlinks to +their system without enhancing `cpio' to know about them. Others may +have enhanced it in a way other than the way I did it at Sun, and which +was adopted by AT&T (and which is, I think, also present in the `cpio' +that Berkeley picked up from AT&T and put into a later BSD release--I +think I gave them my changes). + + (SVR4 does some funny stuff with `tar'; basically, its `cpio' can +handle `tar' format input, and write it on output, and it probably +handles symbolic links. They may not have bothered doing anything to +enhance `tar' as a result.) + + `cpio' handles special files; traditional `tar' doesn't. + + `tar' comes with V7, System III, System V, and BSD source; `cpio' +comes only with System III, System V, and later BSD (4.3-tahoe and +later). + + `tar''s way of handling multiple hard links to a file can handle +file systems that support 32-bit inumbers (e.g., the BSD file system); +`cpio's way requires you to play some games (in its "binary" format, +i-numbers are only 16 bits, and in its "portable ASCII" format, they're +18 bits--it would have to play games with the "file system ID" field of +the header to make sure that the file system ID/i-number pairs of +different files were always different), and I don't know which `cpio's, +if any, play those games. Those that don't might get confused and +think two files are the same file when they're not, and make hard links +between them. + + `tar's way of handling multiple hard links to a file places only one +copy of the link on the tape, but the name attached to that copy is the +_only_ one you can use to retrieve the file; `cpio's way puts one copy +for every link, but you can retrieve it using any of the names. + + What type of check sum (if any) is used, and how is this + calculated. + + See the attached manual pages for `tar' and `cpio' format. `tar' +uses a checksum which is the sum of all the bytes in the `tar' header +for a file; `cpio' uses no checksum. + + If anyone knows why `cpio' was made when `tar' was present at the + unix scene, + + It wasn't. `cpio' first showed up in PWB/UNIX 1.0; no +generally-available version of UNIX had `tar' at the time. I don't +know whether any version that was generally available _within AT&T_ had +`tar', or, if so, whether the people within AT&T who did `cpio' knew +about it. + + On restore, if there is a corruption on a tape `tar' will stop at +that point, while `cpio' will skip over it and try to restore the rest +of the files. + + The main difference is just in the command syntax and header format. + + `tar' is a little more tape-oriented in that everything is blocked +to start on a record boundary. + + Is there any differences between the ability to recover crashed + archives between the two of them. (Is there any chance of + recovering crashed archives at all.) + + Theoretically it should be easier under `tar' since the blocking +lets you find a header with some variation of `dd skip=NN'. However, +modern `cpio''s and variations have an option to just search for the +next file header after an error with a reasonable chance of resyncing. +However, lots of tape driver software won't allow you to continue past +a media error which should be the only reason for getting out of sync +unless a file changed sizes while you were writing the archive. + + If anyone knows why `cpio' was made when `tar' was present at the + unix scene, please tell me about this too. + + Probably because it is more media efficient (by not blocking +everything and using only the space needed for the headers where `tar' +always uses 512 bytes per file header) and it knows how to archive +special files. + + You might want to look at the freely available alternatives. The +major ones are `afio', GNU `tar', and `pax', each of which have their +own extensions with some backwards compatibility. + + Sparse files were `tar'red as sparse files (which you can easily +test, because the resulting archive gets smaller, and GNU `cpio' can no +longer read it). + + +File: tar.info, Node: Media, Next: Changes, Prev: Formats, Up: Top + +9 Tapes and Other Archive Media +******************************* + + _(This message will disappear, once this node revised.)_ + +A few special cases about tape handling warrant more detailed +description. These special cases are discussed below. + + Many complexities surround the use of `tar' on tape drives. Since +the creation and manipulation of archives located on magnetic tape was +the original purpose of `tar', it contains many features making such +manipulation easier. + + Archives are usually written on dismountable media--tape cartridges, +mag tapes, or floppy disks. + + The amount of data a tape or disk holds depends not only on its size, +but also on how it is formatted. A 2400 foot long reel of mag tape +holds 40 megabytes of data when formatted at 1600 bits per inch. The +physically smaller EXABYTE tape cartridge holds 2.3 gigabytes. + + Magnetic media are re-usable--once the archive on a tape is no longer +needed, the archive can be erased and the tape or disk used over. +Media quality does deteriorate with use, however. Most tapes or disks +should be discarded when they begin to produce data errors. EXABYTE +tape cartridges should be discarded when they generate an "error count" +(number of non-usable bits) of more than 10k. + + Magnetic media are written and erased using magnetic fields, and +should be protected from such fields to avoid damage to stored data. +Sticking a floppy disk to a filing cabinet using a magnet is probably +not a good idea. + +* Menu: + +* Device:: Device selection and switching +* Remote Tape Server:: +* Common Problems and Solutions:: +* Blocking:: Blocking +* Many:: Many archives on one tape +* Using Multiple Tapes:: Using Multiple Tapes +* label:: Including a Label in the Archive +* verify:: +* Write Protection:: + + +File: tar.info, Node: Device, Next: Remote Tape Server, Up: Media + +9.1 Device Selection and Switching +================================== + + _(This message will disappear, once this node revised.)_ + +`-f [HOSTNAME:]FILE' +`--file=[HOSTNAME:]FILE' + Use archive file or device FILE on HOSTNAME. + + This option is used to specify the file name of the archive `tar' +works on. + + If the file name is `-', `tar' reads the archive from standard input +(when listing or extracting), or writes it to standard output (when +creating). If the `-' file name is given when updating an archive, +`tar' will read the original archive from its standard input, and will +write the entire new archive to its standard output. + + If the file name contains a `:', it is interpreted as `hostname:file +name'. If the HOSTNAME contains an "at" sign (`@'), it is treated as +`user@hostname:file name'. In either case, `tar' will invoke the +command `rsh' (or `remsh') to start up an `/usr/libexec/rmt' on the +remote machine. If you give an alternate login name, it will be given +to the `rsh'. Naturally, the remote machine must have an executable +`/usr/libexec/rmt'. This program is free software from the University +of California, and a copy of the source code can be found with the +sources for `tar'; it's compiled and installed by default. The exact +path to this utility is determined when configuring the package. It is +`PREFIX/libexec/rmt', where PREFIX stands for your installation prefix. +This location may also be overridden at runtime by using +`rmt-command=COMMAND' option (*Note --rmt-command: Option Summary, for +detailed description of this option. *Note Remote Tape Server::, for +the description of `rmt' command). + + If this option is not given, but the environment variable `TAPE' is +set, its value is used; otherwise, old versions of `tar' used a default +archive name (which was picked when `tar' was compiled). The default +is normally set up to be the "first" tape drive or other transportable +I/O medium on the system. + + Starting with version 1.11.5, GNU `tar' uses standard input and +standard output as the default device, and I will not try anymore +supporting automatic device detection at installation time. This was +failing really in too many cases, it was hopeless. This is now +completely left to the installer to override standard input and +standard output for default device, if this seems preferable. Further, +I think _most_ actual usages of `tar' are done with pipes or disks, not +really tapes, cartridges or diskettes. + + Some users think that using standard input and output is running +after trouble. This could lead to a nasty surprise on your screen if +you forget to specify an output file name--especially if you are going +through a network or terminal server capable of buffering large amounts +of output. We had so many bug reports in that area of configuring +default tapes automatically, and so many contradicting requests, that +we finally consider the problem to be portably intractable. We could +of course use something like `/dev/tape' as a default, but this is +_also_ running after various kind of trouble, going from hung processes +to accidental destruction of real tapes. After having seen all this +mess, using standard input and output as a default really sounds like +the only clean choice left, and a very useful one too. + + GNU `tar' reads and writes archive in records, I suspect this is the +main reason why block devices are preferred over character devices. +Most probably, block devices are more efficient too. The installer +could also check for `DEFTAPE' in `<sys/mtio.h>'. + +`--force-local' + Archive file is local even if it contains a colon. + +`--rsh-command=COMMAND' + Use remote COMMAND instead of `rsh'. This option exists so that + people who use something other than the standard `rsh' (e.g., a + Kerberized `rsh') can access a remote device. + + When this command is not used, the shell command found when the + `tar' program was installed is used instead. This is the first + found of `/usr/ucb/rsh', `/usr/bin/remsh', `/usr/bin/rsh', + `/usr/bsd/rsh' or `/usr/bin/nsh'. The installer may have + overridden this by defining the environment variable `RSH' _at + installation time_. + +`-[0-7][lmh]' + Specify drive and density. + +`-M' +`--multi-volume' + Create/list/extract multi-volume archive. + + This option causes `tar' to write a "multi-volume" archive--one + that may be larger than will fit on the medium used to hold it. + *Note Multi-Volume Archives::. + +`-L NUM' +`--tape-length=NUM' + Change tape after writing NUM x 1024 bytes. + + This option might be useful when your tape drivers do not properly + detect end of physical tapes. By being slightly conservative on + the maximum tape length, you might avoid the problem entirely. + +`-F FILE' +`--info-script=FILE' +`--new-volume-script=FILE' + Execute `file' at end of each tape. This implies `--multi-volume' + (`-M'). *Note info-script::, for a detailed description of this + option. + + +File: tar.info, Node: Remote Tape Server, Next: Common Problems and Solutions, Prev: Device, Up: Media + +9.2 The Remote Tape Server +========================== + +In order to access the tape drive on a remote machine, `tar' uses the +remote tape server written at the University of California at Berkeley. +The remote tape server must be installed as `PREFIX/libexec/rmt' on +any machine whose tape drive you want to use. `tar' calls `rmt' by +running an `rsh' or `remsh' to the remote machine, optionally using a +different login name if one is supplied. + + A copy of the source for the remote tape server is provided. It is +Copyright (C) 1983 by the Regents of the University of California, but +can be freely distributed. It is compiled and installed by default. + + Unless you use the `--absolute-names' (`-P') option, GNU `tar' will +not allow you to create an archive that contains absolute file names (a +file name beginning with `/'.) If you try, `tar' will automatically +remove the leading `/' from the file names it stores in the archive. +It will also type a warning message telling you what it is doing. + + When reading an archive that was created with a different `tar' +program, GNU `tar' automatically extracts entries in the archive which +have absolute file names as if the file names were not absolute. This +is an important feature. A visitor here once gave a `tar' tape to an +operator to restore; the operator used Sun `tar' instead of GNU `tar', +and the result was that it replaced large portions of our `/bin' and +friends with versions from the tape; needless to say, we were unhappy +about having to recover the file system from backup tapes. + + For example, if the archive contained a file `/usr/bin/computoy', +GNU `tar' would extract the file to `usr/bin/computoy', relative to the +current directory. If you want to extract the files in an archive to +the same absolute names that they had when the archive was created, you +should do a `cd /' before extracting the files from the archive, or you +should either use the `--absolute-names' option, or use the command +`tar -C / ...'. + + Some versions of Unix (Ultrix 3.1 is known to have this problem), +can claim that a short write near the end of a tape succeeded, when it +actually failed. This will result in the -M option not working +correctly. The best workaround at the moment is to use a significantly +larger blocking factor than the default 20. + + In order to update an archive, `tar' must be able to backspace the +archive in order to reread or rewrite a record that was just read (or +written). This is currently possible only on two kinds of files: normal +disk files (or any other file that can be backspaced with `lseek'), and +industry-standard 9-track magnetic tape (or any other kind of tape that +can be backspaced with the `MTIOCTOP' `ioctl'. + + This means that the `--append', `--concatenate', and `--delete' +commands will not work on any other kind of file. Some media simply +cannot be backspaced, which means these commands and options will never +be able to work on them. These non-backspacing media include pipes and +cartridge tape drives. + + Some other media can be backspaced, and `tar' will work on them once +`tar' is modified to do so. + + Archives created with the `--multi-volume', `--label', and +`--incremental' (`-G') options may not be readable by other version of +`tar'. In particular, restoring a file that was split over a volume +boundary will require some careful work with `dd', if it can be done at +all. Other versions of `tar' may also create an empty file whose name +is that of the volume header. Some versions of `tar' may create normal +files instead of directories archived with the `--incremental' (`-G') +option. + + +File: tar.info, Node: Common Problems and Solutions, Next: Blocking, Prev: Remote Tape Server, Up: Media + +9.3 Some Common Problems and their Solutions +============================================ + +errors from system: +permission denied +no such file or directory +not owner + +errors from `tar': +directory checksum error +header format error + +errors from media/system: +i/o error +device busy + + +File: tar.info, Node: Blocking, Next: Many, Prev: Common Problems and Solutions, Up: Media + +9.4 Blocking +============ + + _(This message will disappear, once this node revised.)_ + +"Block" and "record" terminology is rather confused, and it is also +confusing to the expert reader. On the other hand, readers who are new +to the field have a fresh mind, and they may safely skip the next two +paragraphs, as the remainder of this manual uses those two terms in a +quite consistent way. + + John Gilmore, the writer of the public domain `tar' from which GNU +`tar' was originally derived, wrote (June 1995): + + The nomenclature of tape drives comes from IBM, where I believe + they were invented for the IBM 650 or so. On IBM mainframes, what + is recorded on tape are tape blocks. The logical organization of + data is into records. There are various ways of putting records + into blocks, including `F' (fixed sized records), `V' (variable + sized records), `FB' (fixed blocked: fixed size records, N to a + block), `VB' (variable size records, N to a block), `VSB' + (variable spanned blocked: variable sized records that can occupy + more than one block), etc. The `JCL' `DD RECFORM=' parameter + specified this to the operating system. + + The Unix man page on `tar' was totally confused about this. When + I wrote `PD TAR', I used the historically correct terminology + (`tar' writes data records, which are grouped into blocks). It + appears that the bogus terminology made it into POSIX (no surprise + here), and now Franc,ois has migrated that terminology back into + the source code too. + + The term "physical block" means the basic transfer chunk from or to +a device, after which reading or writing may stop without anything +being lost. In this manual, the term "block" usually refers to a disk +physical block, _assuming_ that each disk block is 512 bytes in length. +It is true that some disk devices have different physical blocks, but +`tar' ignore these differences in its own format, which is meant to be +portable, so a `tar' block is always 512 bytes in length, and "block" +always mean a `tar' block. The term "logical block" often represents +the basic chunk of allocation of many disk blocks as a single entity, +which the operating system treats somewhat atomically; this concept is +only barely used in GNU `tar'. + + The term "physical record" is another way to speak of a physical +block, those two terms are somewhat interchangeable. In this manual, +the term "record" usually refers to a tape physical block, _assuming_ +that the `tar' archive is kept on magnetic tape. It is true that +archives may be put on disk or used with pipes, but nevertheless, `tar' +tries to read and write the archive one "record" at a time, whatever +the medium in use. One record is made up of an integral number of +blocks, and this operation of putting many disk blocks into a single +tape block is called "reblocking", or more simply, "blocking". The +term "logical record" refers to the logical organization of many +characters into something meaningful to the application. The term +"unit record" describes a small set of characters which are transmitted +whole to or by the application, and often refers to a line of text. +Those two last terms are unrelated to what we call a "record" in GNU +`tar'. + + When writing to tapes, `tar' writes the contents of the archive in +chunks known as "records". To change the default blocking factor, use +the `--blocking-factor=512-SIZE' (`-b 512-SIZE') option. Each record +will then be composed of 512-SIZE blocks. (Each `tar' block is 512 +bytes. *Note Standard::.) Each file written to the archive uses at +least one full record. As a result, using a larger record size can +result in more wasted space for small files. On the other hand, a +larger record size can often be read and written much more efficiently. + + Further complicating the problem is that some tape drives ignore the +blocking entirely. For these, a larger record size can still improve +performance (because the software layers above the tape drive still +honor the blocking), but not as dramatically as on tape drives that +honor blocking. + + When reading an archive, `tar' can usually figure out the record +size on itself. When this is the case, and a non-standard record size +was used when the archive was created, `tar' will print a message about +a non-standard blocking factor, and then operate normally. On some +tape devices, however, `tar' cannot figure out the record size itself. +On most of those, you can specify a blocking factor (with +`--blocking-factor') larger than the actual blocking factor, and then +use the `--read-full-records' (`-B') option. (If you specify a +blocking factor with `--blocking-factor' and don't use the +`--read-full-records' option, then `tar' will not attempt to figure out +the recording size itself.) On some devices, you must always specify +the record size exactly with `--blocking-factor' when reading, because +`tar' cannot figure it out. In any case, use `--list' (`-t') before +doing any extractions to see whether `tar' is reading the archive +correctly. + + `tar' blocks are all fixed size (512 bytes), and its scheme for +putting them into records is to put a whole number of them (one or +more) into each record. `tar' records are all the same size; at the +end of the file there's a block containing all zeros, which is how you +tell that the remainder of the last record(s) are garbage. + + In a standard `tar' file (no options), the block size is 512 and the +record size is 10240, for a blocking factor of 20. What the +`--blocking-factor' option does is sets the blocking factor, changing +the record size while leaving the block size at 512 bytes. 20 was fine +for ancient 800 or 1600 bpi reel-to-reel tape drives; most tape drives +these days prefer much bigger records in order to stream and not waste +tape. When writing tapes for myself, some tend to use a factor of the +order of 2048, say, giving a record size of around one megabyte. + + If you use a blocking factor larger than 20, older `tar' programs +might not be able to read the archive, so we recommend this as a limit +to use in practice. GNU `tar', however, will support arbitrarily large +record sizes, limited only by the amount of virtual memory or the +physical characteristics of the tape device. + +* Menu: + +* Format Variations:: Format Variations +* Blocking Factor:: The Blocking Factor of an Archive + + +File: tar.info, Node: Format Variations, Next: Blocking Factor, Up: Blocking + +9.4.1 Format Variations +----------------------- + + _(This message will disappear, once this node revised.)_ + +Format parameters specify how an archive is written on the archive +media. The best choice of format parameters will vary depending on the +type and number of files being archived, and on the media used to store +the archive. + + To specify format parameters when accessing or creating an archive, +you can use the options described in the following sections. If you do +not specify any format parameters, `tar' uses default parameters. You +cannot modify a compressed archive. If you create an archive with the +`--blocking-factor' option specified (*note Blocking Factor::), you +must specify that blocking-factor when operating on the archive. *Note +Formats::, for other examples of format parameter considerations. + + +File: tar.info, Node: Blocking Factor, Prev: Format Variations, Up: Blocking + +9.4.2 The Blocking Factor of an Archive +--------------------------------------- + + _(This message will disappear, once this node revised.)_ + +The data in an archive is grouped into blocks, which are 512 bytes. +Blocks are read and written in whole number multiples called "records". +The number of blocks in a record (i.e., the size of a record in units +of 512 bytes) is called the "blocking factor". The +`--blocking-factor=512-SIZE' (`-b 512-SIZE') option specifies the +blocking factor of an archive. The default blocking factor is +typically 20 (i.e., 10240 bytes), but can be specified at installation. +To find out the blocking factor of an existing archive, use `tar +--list --file=ARCHIVE-NAME'. This may not work on some devices. + + Records are separated by gaps, which waste space on the archive +media. If you are archiving on magnetic tape, using a larger blocking +factor (and therefore larger records) provides faster throughput and +allows you to fit more data on a tape (because there are fewer gaps). +If you are archiving on cartridge, a very large blocking factor (say +126 or more) greatly increases performance. A smaller blocking factor, +on the other hand, may be useful when archiving small files, to avoid +archiving lots of nulls as `tar' fills out the archive to the end of +the record. In general, the ideal record size depends on the size of +the inter-record gaps on the tape you are using, and the average size +of the files you are archiving. *Note create::, for information on +writing archives. + + Archives with blocking factors larger than 20 cannot be read by very +old versions of `tar', or by some newer versions of `tar' running on +old machines with small address spaces. With GNU `tar', the blocking +factor of an archive is limited only by the maximum record size of the +device containing the archive, or by the amount of available virtual +memory. + + Also, on some systems, not using adequate blocking factors, as +sometimes imposed by the device drivers, may yield unexpected +diagnostics. For example, this has been reported: + + Cannot write to /dev/dlt: Invalid argument + +In such cases, it sometimes happen that the `tar' bundled by the system +is aware of block size idiosyncrasies, while GNU `tar' requires an +explicit specification for the block size, which it cannot guess. This +yields some people to consider GNU `tar' is misbehaving, because by +comparison, `the bundle `tar' works OK'. Adding `-b 256', for example, +might resolve the problem. + + If you use a non-default blocking factor when you create an archive, +you must specify the same blocking factor when you modify that archive. +Some archive devices will also require you to specify the blocking +factor when reading that archive, however this is not typically the +case. Usually, you can use `--list' (`-t') without specifying a +blocking factor--`tar' reports a non-default record size and then lists +the archive members as it would normally. To extract files from an +archive with a non-standard blocking factor (particularly if you're not +sure what the blocking factor is), you can usually use the +`--read-full-records' (`-B') option while specifying a blocking factor +larger then the blocking factor of the archive (i.e., `tar --extract +--read-full-records --blocking-factor=300'. *Note list::, for more +information on the `--list' (`-t') operation. *Note Reading::, for a +more detailed explanation of that option. + +`--blocking-factor=NUMBER' +`-b NUMBER' + Specifies the blocking factor of an archive. Can be used with any + operation, but is usually not necessary with `--list' (`-t'). + + Device blocking + +`-b BLOCKS' +`--blocking-factor=BLOCKS' + Set record size to BLOCKS * 512 bytes. + + This option is used to specify a "blocking factor" for the archive. + When reading or writing the archive, `tar', will do reads and + writes of the archive in records of BLOCK*512 bytes. This is true + even when the archive is compressed. Some devices requires that + all write operations be a multiple of a certain size, and so, `tar' + pads the archive out to the next record boundary. + + The default blocking factor is set when `tar' is compiled, and is + typically 20. Blocking factors larger than 20 cannot be read by + very old versions of `tar', or by some newer versions of `tar' + running on old machines with small address spaces. + + With a magnetic tape, larger records give faster throughput and fit + more data on a tape (because there are fewer inter-record gaps). + If the archive is in a disk file or a pipe, you may want to specify + a smaller blocking factor, since a large one will result in a large + number of null bytes at the end of the archive. + + When writing cartridge or other streaming tapes, a much larger + blocking factor (say 126 or more) will greatly increase + performance. However, you must specify the same blocking factor + when reading or updating the archive. + + Apparently, Exabyte drives have a physical block size of 8K bytes. + If we choose our blocksize as a multiple of 8k bytes, then the + problem seems to disappear. Id est, we are using block size of + 112 right now, and we haven't had the problem since we switched... + + With GNU `tar' the blocking factor is limited only by the maximum + record size of the device containing the archive, or by the amount + of available virtual memory. + + However, deblocking or reblocking is virtually avoided in a special + case which often occurs in practice, but which requires all the + following conditions to be simultaneously true: + * the archive is subject to a compression option, + + * the archive is not handled through standard input or output, + nor redirected nor piped, + + * the archive is directly handled to a local disk, instead of + any special device, + + * `--blocking-factor' is not explicitly specified on the `tar' + invocation. + + If the output goes directly to a local disk, and not through + stdout, then the last write is not extended to a full record size. + Otherwise, reblocking occurs. Here are a few other remarks on this + topic: + + * `gzip' will complain about trailing garbage if asked to + uncompress a compressed archive on tape, there is an option + to turn the message off, but it breaks the regularity of + simply having to use `PROG -d' for decompression. It would + be nice if gzip was silently ignoring any number of trailing + zeros. I'll ask Jean-loup Gailly, by sending a copy of this + message to him. + + * `compress' does not show this problem, but as Jean-loup + pointed out to Michael, `compress -d' silently adds garbage + after the result of decompression, which tar ignores because + it already recognized its end-of-file indicator. So this bug + may be safely ignored. + + * `gzip -d -q' will be silent about the trailing zeros indeed, + but will still return an exit status of 2 which tar reports + in turn. `tar' might ignore the exit status returned, but I + hate doing that, as it weakens the protection `tar' offers + users against other possible problems at decompression time. + If `gzip' was silently skipping trailing zeros _and_ also + avoiding setting the exit status in this innocuous case, that + would solve this situation. + + * `tar' should become more solid at not stopping to read a pipe + at the first null block encountered. This inelegantly breaks + the pipe. `tar' should rather drain the pipe out before + exiting itself. + +`-i' +`--ignore-zeros' + Ignore blocks of zeros in archive (means EOF). + + The `--ignore-zeros' (`-i') option causes `tar' to ignore blocks + of zeros in the archive. Normally a block of zeros indicates the + end of the archive, but when reading a damaged archive, or one + which was created by concatenating several archives together, this + option allows `tar' to read the entire archive. This option is + not on by default because many versions of `tar' write garbage + after the zeroed blocks. + + Note that this option causes `tar' to read to the end of the + archive file, which may sometimes avoid problems when multiple + files are stored on a single physical tape. + +`-B' +`--read-full-records' + Reblock as we read (for reading 4.2BSD pipes). + + If `--read-full-records' is used, `tar' will not panic if an + attempt to read a record from the archive does not return a full + record. Instead, `tar' will keep reading until it has obtained a + full record. + + This option is turned on by default when `tar' is reading an + archive from standard input, or from a remote machine. This is + because on BSD Unix systems, a read of a pipe will return however + much happens to be in the pipe, even if it is less than `tar' + requested. If this option was not used, `tar' would fail as soon + as it read an incomplete record from the pipe. + + This option is also useful with the commands for updating an + archive. + + + Tape blocking + + When handling various tapes or cartridges, you have to take care of +selecting a proper blocking, that is, the number of disk blocks you put +together as a single tape block on the tape, without intervening tape +gaps. A "tape gap" is a small landing area on the tape with no +information on it, used for decelerating the tape to a full stop, and +for later regaining the reading or writing speed. When the tape driver +starts reading a record, the record has to be read whole without +stopping, as a tape gap is needed to stop the tape motion without +loosing information. + + Using higher blocking (putting more disk blocks per tape block) will +use the tape more efficiently as there will be less tape gaps. But +reading such tapes may be more difficult for the system, as more memory +will be required to receive at once the whole record. Further, if +there is a reading error on a huge record, this is less likely that the +system will succeed in recovering the information. So, blocking should +not be too low, nor it should be too high. `tar' uses by default a +blocking of 20 for historical reasons, and it does not really matter +when reading or writing to disk. Current tape technology would easily +accommodate higher blockings. Sun recommends a blocking of 126 for +Exabytes and 96 for DATs. We were told that for some DLT drives, the +blocking should be a multiple of 4Kb, preferably 64Kb (`-b 128') or 256 +for decent performance. Other manufacturers may use different +recommendations for the same tapes. This might also depends of the +buffering techniques used inside modern tape controllers. Some imposes +a minimum blocking, or a maximum blocking. Others request blocking to +be some exponent of two. + + So, there is no fixed rule for blocking. But blocking at read time +should ideally be the same as blocking used at write time. At one place +I know, with a wide variety of equipment, they found it best to use a +blocking of 32 to guarantee that their tapes are fully interchangeable. + + I was also told that, for recycled tapes, prior erasure (by the same +drive unit that will be used to create the archives) sometimes lowers +the error rates observed at rewriting time. + + I might also use `--number-blocks' instead of `--block-number', so +`--block' will then expand to `--blocking-factor' unambiguously. + + +File: tar.info, Node: Many, Next: Using Multiple Tapes, Prev: Blocking, Up: Media + +9.5 Many Archives on One Tape +============================= + +Most tape devices have two entries in the `/dev' directory, or entries +that come in pairs, which differ only in the minor number for this +device. Let's take for example `/dev/tape', which often points to the +only or usual tape device of a given system. There might be a +corresponding `/dev/nrtape' or `/dev/ntape'. The simpler name is the +_rewinding_ version of the device, while the name having `nr' in it is +the _no rewinding_ version of the same device. + + A rewinding tape device will bring back the tape to its beginning +point automatically when this device is opened or closed. Since `tar' +opens the archive file before using it and closes it afterwards, this +means that a simple: + + $ tar cf /dev/tape DIRECTORY + +will reposition the tape to its beginning both prior and after saving +DIRECTORY contents to it, thus erasing prior tape contents and making +it so that any subsequent write operation will destroy what has just +been saved. + + So, a rewinding device is normally meant to hold one and only one +file. If you want to put more than one `tar' archive on a given tape, +you will need to avoid using the rewinding version of the tape device. +You will also have to pay special attention to tape positioning. +Errors in positioning may overwrite the valuable data already on your +tape. Many people, burnt by past experiences, will only use rewinding +devices and limit themselves to one file per tape, precisely to avoid +the risk of such errors. Be fully aware that writing at the wrong +position on a tape loses all information past this point and most +probably until the end of the tape, and this destroyed information +_cannot_ be recovered. + + To save DIRECTORY-1 as a first archive at the beginning of a tape, +and leave that tape ready for a second archive, you should use: + + $ mt -f /dev/nrtape rewind + $ tar cf /dev/nrtape DIRECTORY-1 + + "Tape marks" are special magnetic patterns written on the tape +media, which are later recognizable by the reading hardware. These +marks are used after each file, when there are many on a single tape. +An empty file (that is to say, two tape marks in a row) signal the +logical end of the tape, after which no file exist. Usually, +non-rewinding tape device drivers will react to the close request issued +by `tar' by first writing two tape marks after your archive, and by +backspacing over one of these. So, if you remove the tape at that time +from the tape drive, it is properly terminated. But if you write +another file at the current position, the second tape mark will be +erased by the new information, leaving only one tape mark between files. + + So, you may now save DIRECTORY-2 as a second archive after the first +on the same tape by issuing the command: + + $ tar cf /dev/nrtape DIRECTORY-2 + +and so on for all the archives you want to put on the same tape. + + Another usual case is that you do not write all the archives the same +day, and you need to remove and store the tape between two archive +sessions. In general, you must remember how many files are already +saved on your tape. Suppose your tape already has 16 files on it, and +that you are ready to write the 17th. You have to take care of skipping +the first 16 tape marks before saving DIRECTORY-17, say, by using these +commands: + + $ mt -f /dev/nrtape rewind + $ mt -f /dev/nrtape fsf 16 + $ tar cf /dev/nrtape DIRECTORY-17 + + In all the previous examples, we put aside blocking considerations, +but you should do the proper things for that as well. *Note Blocking::. + +* Menu: + +* Tape Positioning:: Tape Positions and Tape Marks +* mt:: The `mt' Utility + + +File: tar.info, Node: Tape Positioning, Next: mt, Up: Many + +9.5.1 Tape Positions and Tape Marks +----------------------------------- + + _(This message will disappear, once this node revised.)_ + +Just as archives can store more than one file from the file system, +tapes can store more than one archive file. To keep track of where +archive files (or any other type of file stored on tape) begin and end, +tape archive devices write magnetic "tape marks" on the archive media. +Tape drives write one tape mark between files, two at the end of all +the file entries. + + If you think of data as a series of records "rrrr"'s, and tape marks +as "*"'s, a tape might look like the following: + + rrrr*rrrrrr*rrrrr*rr*rrrrr**------------------------- + + Tape devices read and write tapes using a read/write "tape head"--a +physical part of the device which can only access one point on the tape +at a time. When you use `tar' to read or write archive data from a +tape device, the device will begin reading or writing from wherever on +the tape the tape head happens to be, regardless of which archive or +what part of the archive the tape head is on. Before writing an +archive, you should make sure that no data on the tape will be +overwritten (unless it is no longer needed). Before reading an +archive, you should make sure the tape head is at the beginning of the +archive you want to read. You can do it manually via `mt' utility +(*note mt::). The `restore' script does that automatically (*note +Scripted Restoration::). + + If you want to add new archive file entries to a tape, you should +advance the tape to the end of the existing file entries, backspace +over the last tape mark, and write the new archive file. If you were +to add two archives to the example above, the tape might look like the +following: + + rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- + + +File: tar.info, Node: mt, Prev: Tape Positioning, Up: Many + +9.5.2 The `mt' Utility +---------------------- + + _(This message will disappear, once this node revised.)_ + +*Note Blocking Factor::. + + You can use the `mt' utility to advance or rewind a tape past a +specified number of archive files on the tape. This will allow you to +move to the beginning of an archive before extracting or reading it, or +to the end of all the archives before writing a new one. + + The syntax of the `mt' command is: + + mt [-f TAPENAME] OPERATION [NUMBER] + + where TAPENAME is the name of the tape device, NUMBER is the number +of times an operation is performed (with a default of one), and +OPERATION is one of the following: + +`eof' +`weof' + Writes NUMBER tape marks at the current position on the tape. + +`fsf' + Moves tape position forward NUMBER files. + +`bsf' + Moves tape position back NUMBER files. + +`rewind' + Rewinds the tape. (Ignores NUMBER). + +`offline' +`rewoff1' + Rewinds the tape and takes the tape device off-line. (Ignores + NUMBER). + +`status' + Prints status information about the tape unit. + + + If you don't specify a TAPENAME, `mt' uses the environment variable +`TAPE'; if `TAPE' is not set, `mt' will use the default device +specified in your `sys/mtio.h' file (`DEFTAPE' variable). If this is +not defined, the program will display a descriptive error message and +exit with code 1. + + `mt' returns a 0 exit status when the operation(s) were successful, +1 if the command was unrecognized, and 2 if an operation failed. + + +File: tar.info, Node: Using Multiple Tapes, Next: label, Prev: Many, Up: Media + +9.6 Using Multiple Tapes +======================== + +Often you might want to write a large archive, one larger than will fit +on the actual tape you are using. In such a case, you can run multiple +`tar' commands, but this can be inconvenient, particularly if you are +using options like `--exclude=PATTERN' or dumping entire file systems. +Therefore, `tar' provides a special mode for creating multi-volume +archives. + + "Multi-volume" archive is a single `tar' archive, stored on several +media volumes of fixed size. Although in this section we will often +call `volume' a "tape", there is absolutely no requirement for +multi-volume archives to be stored on tapes. Instead, they can use +whatever media type the user finds convenient, they can even be located +on files. + + When creating a multi-volume archive, GNU `tar' continues to fill +current volume until it runs out of space, then it switches to next +volume (usually the operator is queried to replace the tape on this +point), and continues working on the new volume. This operation +continues until all requested files are dumped. If GNU `tar' detects +end of media while dumping a file, such a file is archived in split +form. Some very big files can even be split across several volumes. + + Each volume is itself a valid GNU `tar' archive, so it can be read +without any special options. Consequently any file member residing +entirely on one volume can be extracted or otherwise operated upon +without needing the other volume. Sure enough, to extract a split +member you would need all volumes its parts reside on. + + Multi-volume archives suffer from several limitations. In +particular, they cannot be compressed. + + GNU `tar' is able to create multi-volume archives of two formats +(*note Formats::): `GNU' and `POSIX'. + +* Menu: + +* Multi-Volume Archives:: Archives Longer than One Tape or Disk +* Tape Files:: Tape Files +* Tarcat:: Concatenate Volumes into a Single Archive + + +File: tar.info, Node: Multi-Volume Archives, Next: Tape Files, Up: Using Multiple Tapes + +9.6.1 Archives Longer than One Tape or Disk +------------------------------------------- + +To create an archive that is larger than will fit on a single unit of +the media, use the `--multi-volume' (`-M') option in conjunction with +the `--create' option (*note create::). A "multi-volume" archive can +be manipulated like any other archive (provided the `--multi-volume' +option is specified), but is stored on more than one tape or disk. + + When you specify `--multi-volume', `tar' does not report an error +when it comes to the end of an archive volume (when reading), or the +end of the media (when writing). Instead, it prompts you to load a new +storage volume. If the archive is on a magnetic tape, you should +change tapes when you see the prompt; if the archive is on a floppy +disk, you should change disks; etc. + +`--multi-volume' +`-M' + Creates a multi-volume archive, when used in conjunction with + `--create' (`-c'). To perform any other operation on a + multi-volume archive, specify `--multi-volume' in conjunction with + that operation. For example: + + $ tar --create --multi-volume --file=/dev/tape FILES + + The method `tar' uses to detect end of tape is not perfect, and +fails on some operating systems or on some devices. If `tar' cannot +detect the end of the tape itself, you can use `--tape-length' option +to inform it about the capacity of the tape: + +`--tape-length=SIZE' +`-L SIZE' + Set maximum length of a volume. The SIZE argument should then be + the usable size of the tape in units of 1024 bytes. This option + selects `--multi-volume' automatically. For example: + + $ tar --create --tape-length=41943040 --file=/dev/tape FILES + + When GNU `tar' comes to the end of a storage media, it asks you to +change the volume. The built-in prompt for POSIX locale is(1): + + Prepare volume #N for `ARCHIVE' and hit return: + +where N is the ordinal number of the volume to be created and ARCHIVE +is archive file or device name. + + When prompting for a new tape, `tar' accepts any of the following +responses: + +`?' + Request `tar' to explain possible responses + +`q' + Request `tar' to exit immediately. + +`n FILE-NAME' + Request `tar' to write the next volume on the file FILE-NAME. + +`!' + Request `tar' to run a subshell. This option can be disabled by + giving `--restrict' command line option to `tar'(2). + +`y' + Request `tar' to begin writing the next volume. + + (You should only type `y' after you have changed the tape; otherwise +`tar' will write over the volume it just finished.) + + The volume number used by `tar' in its tape-changing prompt can be +changed; if you give the `--volno-file=FILE-OF-NUMBER' option, then +FILE-OF-NUMBER should be an non-existing file to be created, or else, a +file already containing a decimal number. That number will be used as +the volume number of the first volume written. When `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, as per *note +label::, it _only_ affects the number used in the prompt.) + + If you want more elaborate behavior than this, you can write a +special "new volume script", that will be responsible for changing the +volume, and instruct `tar' to use it instead of its normal prompting +procedure: + +`--info-script=SCRIPT-NAME' +`--new-volume-script=SCRIPT-NAME' +`-F SCRIPT-NAME' + Specify the full name of the volume script to use. The script can + be used to eject cassettes, or to broadcast messages such as + `Someone please come change my tape' when performing unattended + backups. + + The SCRIPT-NAME is executed without any command line arguments. It +inherits `tar''s shell environment. Additional data is passed to it +via the following environment variables: + +`TAR_VERSION' + GNU `tar' version number. + +`TAR_ARCHIVE' + The name of the archive `tar' is processing. + +`TAR_VOLUME' + Ordinal number of the volume `tar' is about to start. + +`TAR_SUBCOMMAND' + Short option describing the operation `tar' is executing *Note + Operations::, for a complete list of subcommand options. + +`TAR_FORMAT' + Format of the archive being processed. *Note Formats::, for a + complete list of archive format names. + +`TAR_FD' + File descriptor which can be used to communicate the new volume + name to `tar'. + + The volume script can instruct `tar' to use new archive name, by +writing in to file descriptor `$TAR_FD' (see below for an example). + + If the info script fails, `tar' exits; otherwise, it begins writing +the next volume. + + If you want `tar' to cycle through a series of files or tape drives, +there are three approaches to choose from. First of all, you can give +`tar' multiple `--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 `tar' +prompt for a tape change (or run the info script). For example, +suppose someone has two tape drives on a system named `/dev/tape0' and +`/dev/tape1'. For having GNU `tar' to switch to the second drive when +it needs to write the second tape, and then back to the first tape, +etc., just do either of: + + $ tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 FILES + $ tar cMff /dev/tape0 /dev/tape1 FILES + + The second method is to use the `n' response to the tape-change +prompt. + + Finally, the most flexible approach is to use a volume script, that +writes new archive name to the file descriptor `$TAR_FD'. For example, +the following volume script will create a series of archive files, named +`ARCHIVE-VOL', where ARCHIVE is the name of the archive being created +(as given by `--file' option) and VOL is the ordinal number of the +archive being created: + + #! /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 >&$TAR_FD + + The same script cant be used while listing, comparing or extracting +from the created archive. For example: + + # Create a multi-volume archive: + $ tar -c -L1024 -f archive.tar -F new-volume . + # Extract from the created archive: + $ tar -x -f archive.tar -F new-volume . + +Notice, that the first command had to use `-L' option, since otherwise +GNU `tar' will end up writing everything to file `archive.tar'. + + You can read each individual volume of a multi-volume archive as if +it were an archive by itself. For example, to list the contents of one +volume, use `--list', without `--multi-volume' specified. To extract +an archive member from one volume (assuming it is described that +volume), use `--extract', again without `--multi-volume'. + + If an archive member is split across volumes (i.e., its entry begins +on one volume of the media and ends on another), you need to specify +`--multi-volume' to extract it successfully. In this case, you should +load the volume where the archive member starts, and use `tar --extract +--multi-volume'--`tar' will prompt for later volumes as it needs them. +*Note extracting archives::, for more information about extracting +archives. + + 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 volume +of the archive media (and new volumes, if needed). For all other +operations, you need to use the entire archive. + + If a multi-volume archive was labeled using `--label=ARCHIVE-LABEL' +(*note label::) when it was created, `tar' will not automatically label +volumes which are added later. To label subsequent volumes, specify +`--label=ARCHIVE-LABEL' again in conjunction with the `--append', +`--update' or `--concatenate' operation. + + Notice that multi-volume support is a GNU extension and the archives +created in this mode should be read only using GNU `tar'. If you +absolutely have to process such archives using a third-party `tar' +implementation, read *note Split Recovery::. + + ---------- Footnotes ---------- + + (1) If you run GNU `tar' under a different locale, the translation +to the locale's language will be used. + + (2) *Note --restrict::, for more information about this option + + +File: tar.info, Node: Tape Files, Next: Tarcat, Prev: Multi-Volume Archives, Up: Using Multiple Tapes + +9.6.2 Tape Files +---------------- + + _(This message will disappear, once this node revised.)_ + +To give the archive a name which will be recorded in it, use the +`--label=VOLUME-LABEL' (`-V VOLUME-LABEL') option. This will write a +special block identifying VOLUME-LABEL as the name of the archive to +the front of the archive which will be displayed when the archive is +listed with `--list'. If you are creating a multi-volume archive with +`--multi-volume' (*note Using Multiple Tapes::), then the volume label +will have `Volume NNN' appended to the name you give, where NNN is the +number of the volume of the archive. (If you use the +`--label=VOLUME-LABEL') option when reading an archive, it checks to +make sure the label on the tape matches the one you give. *Note label::. + + When `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 +`tar'. To do this, use the `mt' command. For more information on the +`mt' command and on the organization of tapes into a sequence of tape +files, see *note mt::. + + People seem to often do: + + --label="SOME-PREFIX `date +SOME-FORMAT`" + + or such, for pushing a common date in all volumes or an archive set. + + +File: tar.info, Node: Tarcat, Prev: Tape Files, Up: Using Multiple Tapes + +9.6.3 Concatenate Volumes into a Single Archive +----------------------------------------------- + +Sometimes it is necessary to convert existing GNU `tar' multi-volume +archive to a single `tar' archive. Simply concatenating all volumes +into one will not work, since each volume carries an additional +information at the beginning. GNU `tar' is shipped with the shell +script `tarcat' designed for this purpose. + + The script takes a list of files comprising a multi-volume archive +and creates the resulting archive at the standard output. For example: + + tarcat vol.1 vol.2 vol.3 | tar tf - + + The script implements a simple heuristics to determine the format of +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 `tar' archives. It uses `dd' +and does not filter its standard error, so you will usually see lots of +spurious messages. + + +File: tar.info, Node: label, Next: verify, Prev: Using Multiple Tapes, Up: Media + +9.7 Including a Label in the Archive +==================================== + + _(This message will disappear, once this node revised.)_ + +To avoid problems caused by misplaced paper labels on the archive +media, you can include a "label" entry--an archive member which +contains the name of the archive--in the archive itself. Use the +`--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') option in conjunction with +the `--create' operation to include a label entry in the archive as it +is being created. + +`--label=ARCHIVE-LABEL' +`-V ARCHIVE-LABEL' + Includes an "archive-label" at the beginning of the archive when + the archive is being created, when used in conjunction with the + `--create' operation. Checks to make sure the archive label + matches the one specified (when used in conjunction with any other + operation. + + If you create an archive using both `--label=ARCHIVE-LABEL' (`-V +ARCHIVE-LABEL') and `--multi-volume' (`-M'), each volume of the archive +will have an archive label of the form `ARCHIVE-LABEL Volume N', where +N is 1 for the first volume, 2 for the next, and so on. *Note Using +Multiple Tapes::, for information on creating multiple volume archives. + + The volume label will be displayed by `--list' along with the file +contents. If verbose display is requested, it will also be explicitly +marked as in the example below: + + $ tar --verbose --list --file=iamanarchive + V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header-- + -rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename + + However, `--list' option will cause listing entire contents of the +archive, which may be undesirable (for example, if the archive is +stored on a tape). You can request checking only the volume by +specifying `--test-label' option. This option reads only the first +block of an archive, so it can be used with slow storage devices. For +example: + + $ tar --test-label --file=iamanarchive + iamalabel + + If `--test-label' is used with a single command line argument, `tar' +compares the volume label with the argument. It exits with code 0 if +the two strings match, and with code 2 otherwise. In this case no +output is displayed. For example: + + $ tar --test-label --file=iamanarchive 'iamalable' + => 0 + $ tar --test-label --file=iamanarchive 'iamalable' alabel + => 1 + + If you request any operation, other than `--create', along with +using `--label' option, `tar' will first check if the archive label +matches the one specified and will refuse to proceed if it does not. +Use this as a safety precaution to avoid accidentally overwriting +existing archives. For example, if you wish to add files to `archive', +presumably labeled with string `My volume', you will get: + + $ tar -rf archive --label 'My volume' . + tar: Archive not labeled to match `My volume' + +in case its label does not match. This will work even if `archive' is +not labeled at all. + + Similarly, `tar' will refuse to list or extract the archive if its +label doesn't match the ARCHIVE-LABEL specified. In those cases, +ARCHIVE-LABEL argument is interpreted as a globbing-style pattern which +must match the actual magnetic volume label. *Note exclude::, for a +precise description of how match is attempted(1). If the switch +`--multi-volume' (`-M') is being used, the volume label matcher will +also suffix ARCHIVE-LABEL by ` Volume [1-9]*' if the initial match +fails, before giving up. Since the volume numbering is automatically +added in labels at creation time, it sounded logical to equally help +the user taking care of it when the archive is being read. + + The `--label' was once called `--volume', but is not available under +that name anymore. + + You can also use `--label' to get a common information on all tapes +of a series. For having this information different in each series +created through a single script used on a regular basis, just manage to +get some date string as part of the label. For example: + + $ tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`" + $ tar --create --file=/dev/tape --multi-volume \ + --volume="Daily backup for `date +%Y-%m-%d`" + + Also note that each label has its own date and time, which +corresponds to when GNU `tar' initially attempted to write it, often +soon after the operator launches `tar' or types the carriage return +telling that the next tape is ready. Comparing date labels does give +an idea of tape throughput only if the delays for rewinding tapes and +the operator switching them were negligible, which is usually not the +case. + + ---------- Footnotes ---------- + + (1) Previous versions of `tar' used full regular expression +matching, or before that, only exact string matching, instead of +wildcard matchers. We decided for the sake of simplicity to use a +uniform matching device through `tar'. + + +File: tar.info, Node: verify, Next: Write Protection, Prev: label, Up: Media + +9.8 Verifying Data as It is Stored +================================== + +`-W' +`--verify' + Attempt to verify the archive after writing. + + This option causes `tar' to verify the archive after writing it. +Each volume is checked after it is written, and any discrepancies are +recorded on the standard error output. + + Verification requires that the archive be on a back-space-able +medium. This means pipes, some cartridge tape drives, and some other +devices cannot be verified. + + You can insure the accuracy of an archive by comparing files in the +system with archive members. `tar' can compare an archive to the file +system as the archive is being written, to verify a write operation, or +can compare a previously written archive, to insure that it is up to +date. + + To check for discrepancies in an archive immediately after it is +written, use the `--verify' (`-W') option in conjunction with the +`--create' operation. When this option is specified, `tar' checks +archive members against their counterparts in the file system, and +reports discrepancies on the standard error. + + To verify an archive, you must be able to read it from before the end +of the last written entry. This option is useful for detecting data +errors on some tapes. Archives written to pipes, some cartridge tape +drives, and some other devices cannot be verified. + + One can explicitly compare an already made archive with the file +system by using the `--compare' (`--diff', `-d') option, instead of +using the more automatic `--verify' option. *Note compare::. + + Note that these two options have a slightly different intent. The +`--compare' option checks how identical are the logical contents of some +archive with what is on your disks, while the `--verify' option is +really for checking if the physical contents agree and if the recording +media itself is of dependable quality. So, for the `--verify' +operation, `tar' tries to defeat all in-memory cache pertaining to the +archive, while it lets the speed optimization undisturbed for the +`--compare' option. If you nevertheless use `--compare' for media +verification, you may have to defeat the in-memory cache yourself, +maybe by opening and reclosing the door latch of your recording unit, +forcing some doubt in your operating system about the fact this is +really the same volume as the one just written or read. + + The `--verify' option would not be necessary if drivers were indeed +able to detect dependably all write failures. This sometimes require +many magnetic heads, some able to read after the writes occurred. One +would not say that drivers unable to detect all cases are necessarily +flawed, as long as programming is concerned. + + The `--verify' (`-W') option will not work in conjunction with the +`--multi-volume' (`-M') option or the `--append' (`-r'), `--update' +(`-u') and `--delete' operations. *Note Operations::, for more +information on these operations. + + Also, since `tar' normally strips leading `/' from file names (*note +absolute::), a command like `tar --verify -cf /tmp/foo.tar /etc' will +work as desired only if the working directory is `/', as `tar' uses the +archive's relative member names (e.g., `etc/motd') when verifying the +archive. + + +File: tar.info, Node: Write Protection, Prev: verify, Up: Media + +9.9 Write Protection +==================== + +Almost all tapes and diskettes, and in a few rare cases, even disks can +be "write protected", to protect data on them from being changed. Once +an archive is written, you should write protect the media to prevent +the archive from being accidentally overwritten or deleted. (This will +protect the archive from being changed with a tape or floppy drive--it +will not protect it from magnet fields or other physical hazards). + + The write protection device itself is usually an integral part of the +physical media, and can be a two position (write enabled/write +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. + + +File: tar.info, Node: Changes, Next: Configuring Help Summary, Prev: Media, Up: Top + +Appendix A Changes +****************** + +This appendix lists some important user-visible changes between version +GNU `tar' 1.17 and previous versions. An up-to-date version of this +document is available at the GNU `tar' documentation page +(http://www.gnu.org/software/tar/manual/changes.html). + +Use of globbing patterns when listing and extracting. + Previous versions of GNU tar assumed shell-style globbing when + extracting from or listing an archive. For example: + + $ tar xf foo.tar '*.c' + + would extract all files whose names end in `.c'. This behavior + was not documented and was incompatible with traditional tar + implementations. Therefore, starting from version 1.15.91, GNU tar + no longer uses globbing by default. For example, the above + invocation is now interpreted as a request to extract from the + archive the file named `*.c'. + + To facilitate transition to the new behavior for those users who + got used to the previous incorrect one, `tar' will print a warning + if it finds out that a requested member was not found in the + archive and its name looks like a globbing pattern. For example: + + $ tar xf foo.tar '*.c' + tar: Pattern matching characters used in file names. Please, + tar: use --wildcards to enable pattern matching, or --no-wildcards to + tar: suppress this warning. + tar: *.c: Not found in archive + tar: Error exit delayed from previous errors + + To treat member names as globbing patterns, use -wildcards option. + If you want to tar to mimic the behavior of versions prior to + 1.15.91, add this option to your `TAR_OPTIONS' variable. + + *Note wildcards::, for the detailed discussion of the use of + globbing patterns by GNU `tar'. + +Use of short option `-o'. + Earlier versions of GNU `tar' understood `-o' command line option + as a synonym for `--old-archive'. + + GNU `tar' starting from version 1.13.90 understands this option as + a synonym for `--no-same-owner'. This is compatible with UNIX98 + `tar' implementations. + + However, to facilitate transition, `-o' option retains its old + semantics when it is used with one of archive-creation commands. + Users are encouraged to use `--format=oldgnu' instead. + + It is especially important, since versions of GNU Automake up to + and including 1.8.4 invoke tar with this option to produce + distribution tarballs. *Note v7: Formats, for the detailed + discussion of this issue and its implications. + + . *Note tar-v7: (automake)Options, for a description on how to + use various archive formats with `automake'. + + Future versions of GNU `tar' will understand `-o' only as a + synonym for `--no-same-owner'. + +Use of short option `-l' + Earlier versions of GNU `tar' understood `-l' option as a synonym + for `--one-file-system'. Since such usage contradicted to UNIX98 + specification and harmed compatibility with other implementation, + it was declared deprecated in version 1.14. However, to + facilitate transition to its new semantics, it was supported by + versions 1.15 and 1.15.90. The present use of `-l' as a short + variant of `--check-links' was introduced in version 1.15.91. + +Use of options `--portability' and `--old-archive' + These options are deprecated. Please use `--format=v7' instead. + +Use of option `--posix' + This option is deprecated. Please use `--format=posix' instead. + + +File: tar.info, Node: Configuring Help Summary, Next: Tar Internals, Prev: Changes, Up: Top + +Appendix B Configuring Help Summary +*********************************** + +Running `tar --help' displays the short `tar' option summary (*note +help::). This summary is organized by "groups" of semantically close +options. The options within each group are printed in the following +order: a short option, eventually followed by a list of corresponding +long option names, followed by a short description of the option. For +example, here is an excerpt from the actual `tar --help' output: + + + Main operation mode: + + -A, --catenate, --concatenate append tar files to an archive + -c, --create create a new archive + -d, --diff, --compare find differences between archive and + file system + --delete delete from the archive + + The exact visual representation of the help output is configurable +via `ARGP_HELP_FMT' environment variable. The value of this variable is +a comma-separated list of "format variable" assignments. There are two +kinds of format variables. An "offset variable" keeps the offset of +some part of help output text from the leftmost column on the screen. A +"boolean" variable is a flag that toggles some output feature on or +off. Depending on the type of the corresponding variable, there are two +kinds of assignments: + +Offset assignment + The assignment to an offset variable has the following syntax: + + VARIABLE=VALUE + + where VARIABLE is the variable name, and VALUE is a numeric value + to be assigned to the variable. + +Boolean assignment + To assign `true' value to a variable, simply put this variable + name. To assign `false' value, prefix the variable name with + `no-'. For example: + + # Assign `true' value: + dup-args + # Assign `false' value: + no-dup-args + + Following variables are declared: + + -- Help Output: boolean dup-args + If true, arguments for an option are shown with both short and long + options, even when a given option has both forms, for example: + + -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE + + If false, then if an option has both short and long forms, the + argument is only shown with the long one, for example: + + -f, --file=ARCHIVE use archive file or device ARCHIVE + + and a message indicating that the argument is applicable to both + forms is printed below the options. This message can be disabled + using `dup-args-note' (see below). + + The default is false. + + -- Help Output: boolean dup-args-note + If this variable is true, which is the default, the following + notice is displayed at the end of the help output: + + Mandatory or optional arguments to long options are also + mandatory or optional for any corresponding short options. + + Setting `no-dup-args-note' inhibits this message. Normally, only + one of variables `dup-args' or `dup-args-note' should be set. + + -- Help Output: offset short-opt-col + Column in which short options start. Default is 2. + + $ tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + $ ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + + -- Help Output: offset long-opt-col + Column in which long options start. Default is 6. For example: + + $ tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + $ ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + + -- Help Output: offset doc-opt-col + Column in which "doc options" start. A doc option isn't actually + an option, but rather an arbitrary piece of documentation that is + displayed in much the same manner as the options. For example, in + the description of `--format' option: + + -H, --format=FORMAT create archive of the given format. + + FORMAT is one of the following: + + gnu GNU tar 1.13.x format + oldgnu GNU format as per tar <= 1.12 + pax POSIX 1003.1-2001 (pax) format + posix same as pax + ustar POSIX 1003.1-1988 (ustar) format + v7 old V7 tar format + + the format names are doc options. Thus, if you set + `ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output + will look as follows: + + -H, --format=FORMAT create archive of the given format. + + FORMAT is one of the following: + + gnu GNU tar 1.13.x format + oldgnu GNU format as per tar <= 1.12 + pax POSIX 1003.1-2001 (pax) format + posix same as pax + ustar POSIX 1003.1-1988 (ustar) format + v7 old V7 tar format + + -- Help Output: offset opt-doc-col + Column in which option description starts. Default is 29. + + $ tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + $ ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + $ ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE + -f, --file=ARCHIVE + use archive file or device ARCHIVE + + Notice, that the description starts on a separate line if + `opt-doc-col' value is too small. + + -- Help Output: offset header-col + Column in which "group headers" are printed. A group header is a + descriptive text preceding an option group. For example, in the + following text: + + + Main operation mode: + + -A, --catenate, --concatenate append tar files to + an archive + -c, --create create a new archive + `Main operation mode:' is the group header. + + The default value is 1. + + -- Help Output: offset usage-indent + Indentation of wrapped usage lines. Affects `--usage' output. + Default is 12. + + -- Help Output: offset rmargin + Right margin of the text output. Used for wrapping. + + +File: tar.info, Node: Tar Internals, Next: Genfile, Prev: Configuring Help Summary, Up: Top + +Appendix C Tar Internals +************************ + +* Menu: + +* Standard:: Basic Tar Format +* Extensions:: GNU Extensions to the Archive Format +* Sparse Formats:: Storing Sparse Files +* Snapshot Files:: +* Dumpdir:: + + +File: tar.info, Node: Standard, Next: Extensions, Up: Tar Internals + +Basic Tar Format +================ + + _(This message will disappear, once this node revised.)_ + +While an archive may contain many files, the archive itself is a single +ordinary file. Like any other file, an archive file can be written to +a storage device such as a tape or disk, sent through a pipe or over a +network, saved on the active file system, or even stored in another +archive. An archive file is not easy to read or manipulate without +using the `tar' utility or Tar mode in GNU Emacs. + + Physically, an archive consists of a series of file entries +terminated by an end-of-archive entry, which consists of two 512 blocks +of zero bytes. A file entry usually describes one of the files in the +archive (an "archive member"), and consists of a file header and the +contents of the file. File headers contain file names and statistics, +checksum information which `tar' uses to detect file corruption, and +information about file types. + + Archives are permitted to have more than one member with the same +member name. One way this situation can occur is if more than one +version of a file has been stored in the archive. For information +about adding new versions of a file to an archive, see *note update::. + + In addition to entries describing archive members, an archive may +contain entries which `tar' itself uses to store information. *Note +label::, for an example of such an archive entry. + + A `tar' archive file contains a series of blocks. Each block +contains `BLOCKSIZE' bytes. Although this format may be thought of as +being on magnetic tape, other media are often used. + + Each file archived is represented by a header block which describes +the file, followed by zero or more blocks which give the contents of +the file. At the end of the archive file there are two 512-byte blocks +filled with binary zeros as an end-of-file marker. A reasonable system +should write such end-of-file marker at the end of an archive, but must +not assume that such a block exists when reading an archive. In +particular GNU `tar' always issues a warning if it does not encounter +it. + + The blocks may be "blocked" for physical I/O operations. Each +record of N blocks (where N is set by the `--blocking-factor=512-SIZE' +(`-b 512-SIZE') option to `tar') is written with a single `write ()' +operation. On magnetic tapes, the result of such a write is a single +record. When writing an archive, the last record of blocks should be +written at the full size, with blocks after the zero block containing +all zeros. When reading an archive, a reasonable system should +properly handle an archive whose last record is shorter than the rest, +or which contains garbage records after a zero block. + + The header block is defined in C as follows. In the GNU `tar' +distribution, this is part of file `src/tar.h': + + + /* tar Header Block, from POSIX 1003.1-1990. */ + + /* POSIX header. */ + + struct posix_header + { /* byte offset */ + char name[100]; /* 0 */ + char mode[8]; /* 100 */ + char uid[8]; /* 108 */ + char gid[8]; /* 116 */ + char size[12]; /* 124 */ + char mtime[12]; /* 136 */ + char chksum[8]; /* 148 */ + char typeflag; /* 156 */ + char linkname[100]; /* 157 */ + char magic[6]; /* 257 */ + char version[2]; /* 263 */ + char uname[32]; /* 265 */ + char gname[32]; /* 297 */ + char devmajor[8]; /* 329 */ + char devminor[8]; /* 337 */ + char prefix[155]; /* 345 */ + /* 500 */ + }; + + #define TMAGIC "ustar" /* ustar and a null */ + #define TMAGLEN 6 + #define TVERSION "00" /* 00 and no null */ + #define TVERSLEN 2 + + /* Values used in typeflag field. */ + #define REGTYPE '0' /* regular file */ + #define AREGTYPE '\0' /* regular file */ + #define LNKTYPE '1' /* link */ + #define SYMTYPE '2' /* reserved */ + #define CHRTYPE '3' /* character special */ + #define BLKTYPE '4' /* block special */ + #define DIRTYPE '5' /* directory */ + #define FIFOTYPE '6' /* FIFO special */ + #define CONTTYPE '7' /* reserved */ + + #define XHDTYPE 'x' /* Extended header referring to the + next file in the archive */ + #define XGLTYPE 'g' /* Global extended header */ + + /* Bits used in the mode field, values in octal. */ + #define TSUID 04000 /* set UID on execution */ + #define TSGID 02000 /* set GID on execution */ + #define TSVTX 01000 /* reserved */ + /* file permissions */ + #define TUREAD 00400 /* read by owner */ + #define TUWRITE 00200 /* write by owner */ + #define TUEXEC 00100 /* execute/search by owner */ + #define TGREAD 00040 /* read by group */ + #define TGWRITE 00020 /* write by group */ + #define TGEXEC 00010 /* execute/search by group */ + #define TOREAD 00004 /* read by other */ + #define TOWRITE 00002 /* write by other */ + #define TOEXEC 00001 /* execute/search by other */ + + /* tar Header Block, GNU extensions. */ + + /* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for + contiguous files, so maybe disobeying the `reserved' comment in POSIX + header description. I suspect these were meant to be used this way, and + should not have really been `reserved' in the published standards. */ + + /* *BEWARE* *BEWARE* *BEWARE* that the following information is still + boiling, and may change. Even if the OLDGNU format description should be + accurate, the so-called GNU format is not yet fully decided. It is + surely meant to use only extensions allowed by POSIX, but the sketch + below repeats some ugliness from the OLDGNU format, which should rather + go away. Sparse files should be saved in such a way that they do *not* + require two passes at archive creation time. Huge files get some POSIX + fields to overflow, alternate solutions have to be sought for this. */ + + /* Descriptor for a single file hole. */ + + struct sparse + { /* byte offset */ + char offset[12]; /* 0 */ + char numbytes[12]; /* 12 */ + /* 24 */ + }; + + /* Sparse files are not supported in POSIX ustar format. For sparse files + with a POSIX header, a GNU extra header is provided which holds overall + sparse information and a few sparse descriptors. When an old GNU header + replaces both the POSIX header and the GNU extra header, it holds some + sparse descriptors too. Whether POSIX or not, if more sparse descriptors + are still needed, they are put into as many successive sparse headers as + necessary. The following constants tell how many sparse descriptors fit + in each kind of header able to hold them. */ + + #define SPARSES_IN_EXTRA_HEADER 16 + #define SPARSES_IN_OLDGNU_HEADER 4 + #define SPARSES_IN_SPARSE_HEADER 21 + + /* Extension header for sparse files, used immediately after the GNU extra + header, and used only if all sparse information cannot fit into that + extra header. There might even be many such extension headers, one after + the other, until all sparse information has been recorded. */ + + struct sparse_header + { /* byte offset */ + struct sparse sp[SPARSES_IN_SPARSE_HEADER]; + /* 0 */ + char isextended; /* 504 */ + /* 505 */ + }; + + /* The old GNU format header conflicts with POSIX format in such a way that + POSIX archives may fool old GNU tar's, and POSIX tar's might well be + fooled by old GNU tar archives. An old GNU format header uses the space + used by the prefix field in a POSIX header, and cumulates information + normally found in a GNU extra header. With an old GNU tar header, we + never see any POSIX header nor GNU extra header. Supplementary sparse + headers are allowed, however. */ + + struct oldgnu_header + { /* byte offset */ + char unused_pad1[345]; /* 0 */ + char atime[12]; /* 345 Incr. archive: atime of the file */ + char ctime[12]; /* 357 Incr. archive: ctime of the file */ + char offset[12]; /* 369 Multivolume archive: the offset of + the start of this volume */ + char longnames[4]; /* 381 Not used */ + char unused_pad2; /* 385 */ + struct sparse sp[SPARSES_IN_OLDGNU_HEADER]; + /* 386 */ + char isextended; /* 482 Sparse file: Extension sparse header + follows */ + char realsize[12]; /* 483 Sparse file: Real size*/ + /* 495 */ + }; + + /* OLDGNU_MAGIC uses both magic and version fields, which are contiguous. + Found in an archive, it indicates an old GNU header format, which will be + hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are + valid, though the header is not truly POSIX conforming. */ + #define OLDGNU_MAGIC "ustar " /* 7 chars and a null */ + + /* The standards committee allows only capital A through capital Z for + user-defined expansion. Other letters in use include: + + 'A' Solaris Access Control List + 'E' Solaris Extended Attribute File + 'I' Inode only, as in 'star' + 'N' Obsolete GNU tar, for file names that do not fit into the main header. + 'X' POSIX 1003.1-2001 eXtended (VU version) */ + + /* This is a dir entry that contains the names of files that were in the + dir at the time the dump was made. */ + #define GNUTYPE_DUMPDIR 'D' + + /* Identifies the *next* file on the tape as having a long linkname. */ + #define GNUTYPE_LONGLINK 'K' + + /* Identifies the *next* file on the tape as having a long name. */ + #define GNUTYPE_LONGNAME 'L' + + /* This is the continuation of a file that began on another volume. */ + #define GNUTYPE_MULTIVOL 'M' + + /* This is for sparse files. */ + #define GNUTYPE_SPARSE 'S' + + /* This file is a tape/volume header. Ignore it on extraction. */ + #define GNUTYPE_VOLHDR 'V' + + /* Solaris extended header */ + #define SOLARIS_XHDTYPE 'X' + + /* Jo"rg Schilling star header */ + + struct star_header + { /* byte offset */ + char name[100]; /* 0 */ + char mode[8]; /* 100 */ + char uid[8]; /* 108 */ + char gid[8]; /* 116 */ + char size[12]; /* 124 */ + char mtime[12]; /* 136 */ + char chksum[8]; /* 148 */ + char typeflag; /* 156 */ + char linkname[100]; /* 157 */ + char magic[6]; /* 257 */ + char version[2]; /* 263 */ + char uname[32]; /* 265 */ + char gname[32]; /* 297 */ + char devmajor[8]; /* 329 */ + char devminor[8]; /* 337 */ + char prefix[131]; /* 345 */ + char atime[12]; /* 476 */ + char ctime[12]; /* 488 */ + /* 500 */ + }; + + #define SPARSES_IN_STAR_HEADER 4 + #define SPARSES_IN_STAR_EXT_HEADER 21 + + struct star_in_header + { + char fill[345]; /* 0 Everything that is before t_prefix */ + char prefix[1]; /* 345 t_name prefix */ + char fill2; /* 346 */ + char fill3[8]; /* 347 */ + char isextended; /* 355 */ + struct sparse sp[SPARSES_IN_STAR_HEADER]; /* 356 */ + char realsize[12]; /* 452 Actual size of the file */ + char offset[12]; /* 464 Offset of multivolume contents */ + char atime[12]; /* 476 */ + char ctime[12]; /* 488 */ + char mfill[8]; /* 500 */ + char xmagic[4]; /* 508 "tar" */ + }; + + struct star_ext_header + { + struct sparse sp[SPARSES_IN_STAR_EXT_HEADER]; + char isextended; + }; + + All characters in header blocks are represented by using 8-bit +characters in the local variant of ASCII. Each field within the +structure is contiguous; that is, there is no padding used within the +structure. Each character on the archive medium is stored contiguously. + + Bytes representing the contents of files (after the header block of +each file) are not translated in any way and are not constrained to +represent characters in any character set. The `tar' format does not +distinguish text files from binary files, and no translation of file +contents is performed. + + The `name', `linkname', `magic', `uname', and `gname' are +null-terminated character strings. All other fields are zero-filled +octal numbers in ASCII. Each numeric field of width W contains W minus +1 digits, and a null. + + The `name' field is the file name of the file, with directory names +(if any) preceding the file name, separated by slashes. + + The `mode' field provides nine bits specifying file permissions and +three bits to specify the Set UID, Set GID, and Save Text ("sticky") +modes. Values for these bits are defined above. When special +permissions are required to create a file with a given mode, and the +user restoring files from the archive does not hold such permissions, +the mode bit(s) specifying those special permissions are ignored. +Modes which are not supported by the operating system restoring files +from the archive will be ignored. Unsupported modes should be faked up +when creating or updating an archive; e.g., the group permission could +be copied from the _other_ permission. + + The `uid' and `gid' fields are the numeric user and group ID of the +file owners, respectively. If the operating system does not support +numeric user or group IDs, these fields should be ignored. + + The `size' field is the size of the file in bytes; linked files are +archived with this field specified as zero. + + The `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 `chksum' field is the ASCII representation of the octal value of +the simple sum of all bytes in the header block. Each 8-bit byte in +the header is added to an unsigned integer, initialized to zero, the +precision of which shall be no less than seventeen bits. When +calculating the checksum, the `chksum' field is treated as if it were +all blanks. + + The `typeflag' field specifies the type of file archived. If a +particular implementation does not recognize or permit the specified +type, the file will be extracted as if it were a regular file. As this +action occurs, `tar' issues a warning to the standard error. + + The `atime' and `ctime' fields are used in making incremental +backups; they store, respectively, the particular file's access and +status change times. + + The `offset' is used by the `--multi-volume' (`-M') option, when +making a multi-volume archive. The offset is number of bytes into the +file that we need to restart at to continue the file on the next tape, +i.e., where we store the location that a continued file is continued at. + + The following fields were added to deal with sparse files. A file +is "sparse" if it takes in unallocated blocks which end up being +represented as zeros, i.e., no useful data. A test to see if a file is +sparse is to look at the number blocks allocated for it versus the +number of characters in the file; if there are fewer blocks allocated +for the file than would normally be allocated for a file of that size, +then the file is sparse. This is the method `tar' uses to detect a +sparse file, and once such a file is detected, it is treated +differently from non-sparse files. + + Sparse files are often `dbm' files, or other database-type files +which have data at some points and emptiness in the greater part of the +file. Such files can appear to be very large when an `ls -l' is done +on them, when in truth, there may be a very small amount of important +data contained in the file. It is thus undesirable to have `tar' think +that it must back up this entire file, as great quantities of room are +wasted on empty blocks, which can lead to running out of room on a tape +far earlier than is necessary. Thus, sparse files are dealt with so +that these empty blocks are not written to the tape. Instead, what is +written to the tape is a description, of sorts, of the sparse file: +where the holes are, how big the holes are, and how much data is found +at the end of the hole. This way, the file takes up potentially far +less room on the tape, and when the file is extracted later on, it will +look exactly the way it looked beforehand. The following is a +description of the fields used to handle a sparse file: + + The `sp' is an array of `struct sparse'. Each `struct sparse' +contains two 12-character strings which represent an offset into the +file and a number of bytes to be written at that offset. The offset is +absolute, and not relative to the offset in preceding array element. + + The header can hold four of these `struct sparse' at the moment; if +more are needed, they are not stored in the header. + + The `isextended' flag is set when an `extended_header' is needed to +deal with a file. Note that this means that this flag can only be set +when dealing with a sparse file, and it is only set in the event that +the description of the file will not fit in the allotted room for +sparse structures in the header. In other words, an extended_header is +needed. + + The `extended_header' structure is used for sparse files which need +more sparse structures than can fit in the header. The header can fit +4 such structures; if more are needed, the flag `isextended' gets set +and the next block is an `extended_header'. + + Each `extended_header' structure contains an array of 21 sparse +structures, along with a similar `isextended' flag that the header had. +There can be an indeterminate number of such `extended_header's to +describe a sparse file. + +`REGTYPE' +`AREGTYPE' + These flags represent a regular file. In order to be compatible + with older versions of `tar', a `typeflag' value of `AREGTYPE' + should be silently recognized as a regular file. New archives + should be created using `REGTYPE'. Also, for backward + compatibility, `tar' treats a regular file whose name ends with a + slash as a directory. + +`LNKTYPE' + This flag represents a file linked to another file, of any type, + previously archived. Such files are identified in Unix by each + file having the same device and inode number. The linked-to name + is specified in the `linkname' field with a trailing null. + +`SYMTYPE' + This represents a symbolic link to another file. The linked-to + name is specified in the `linkname' field with a trailing null. + +`CHRTYPE' +`BLKTYPE' + These represent character special files and block special files + respectively. In this case the `devmajor' and `devminor' fields + will contain the major and minor device numbers respectively. + Operating systems may map the device specifications to their own + local specification, or may ignore the entry. + +`DIRTYPE' + This flag specifies a directory or sub-directory. The directory + name in the `name' field should end with a slash. On systems where + disk allocation is performed on a directory basis, the `size' field + will contain the maximum number of bytes (which may be rounded to + the nearest disk block allocation unit) which the directory may + hold. A `size' field of zero indicates no such limiting. Systems + which do not support limiting in this manner should ignore the + `size' field. + +`FIFOTYPE' + This specifies a FIFO special file. Note that the archiving of a + FIFO file archives the existence of this file and not its contents. + +`CONTTYPE' + This specifies a contiguous file, which is the same as a normal + file except that, in operating systems which support it, all its + space is allocated contiguously on the disk. Operating systems + which do not allow contiguous allocation should silently treat this + type as a normal file. + +`A' ... `Z' + These are reserved for custom implementations. Some of these are + used in the GNU modified format, as described below. + + + Other values are reserved for specification in future revisions of +the P1003 standard, and should not be used by any `tar' program. + + The `magic' field indicates that this archive was output in the +P1003 archive format. If this field contains `TMAGIC', the `uname' and +`gname' fields will contain the ASCII representation of the owner and +group of the file respectively. If found, the user and group IDs are +used rather than the values in the `uid' and `gid' fields. + + For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, +pages 169-173 (section 10.1) for `Archive/Interchange File Format'; and +IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940 +(section E.4.48) for `pax - Portable archive interchange'. + + +File: tar.info, Node: Extensions, Next: Sparse Formats, Prev: Standard, Up: Tar Internals + +GNU Extensions to the Archive Format +==================================== + + _(This message will disappear, once this node revised.)_ + +The GNU format uses additional file types to describe new types of +files in an archive. These are listed below. + +`GNUTYPE_DUMPDIR' +`'D'' + This represents a directory and a list of files created by the + `--incremental' (`-G') option. The `size' field gives the total + size of the associated list of files. Each file name is preceded + by either a `Y' (the file should be in this archive) or an `N'. + (The file is a directory, or is not stored in the archive.) Each + file name is terminated by a null. There is an additional null + after the last file name. + +`GNUTYPE_MULTIVOL' +`'M'' + This represents a file continued from another volume of a + multi-volume archive created with the `--multi-volume' (`-M') + option. The original type of the file is not given here. The + `size' field gives the maximum size of this piece of the file + (assuming the volume does not end before the file is written out). + The `offset' field gives the offset from the beginning of the + file where this part of the file begins. Thus `size' plus + `offset' should equal the original size of the file. + +`GNUTYPE_SPARSE' +`'S'' + This flag indicates that we are dealing with a sparse file. Note + that archiving a sparse file requires special operations to find + holes in the file, which mark the positions of these holes, along + with the number of bytes of data to be found after the hole. + +`GNUTYPE_VOLHDR' +`'V'' + This file type is used to mark the volume header that was given + with the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') option when + the archive was created. The `name' field contains the `name' + given after the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') + option. The `size' field is zero. Only the first file in each + volume of an archive should have this type. + + + You may have trouble reading a GNU format archive on a non-GNU +system if the options `--incremental' (`-G'), `--multi-volume' (`-M'), +`--sparse' (`-S'), or `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') were +used when writing the archive. In general, if `tar' does not use the +GNU-added fields of the header, other versions of `tar' should be able +to read the archive. Otherwise, the `tar' program will give an error, +the most likely one being a checksum error. + + +File: tar.info, Node: Sparse Formats, Next: Snapshot Files, Prev: Extensions, Up: Tar Internals + +Storing Sparse Files +==================== + +The notion of sparse file, and the ways of handling it from the point +of view of GNU `tar' user have been described in detail in *note +sparse::. This chapter describes the internal format GNU `tar' uses to +store such files. + + The support for sparse files in GNU `tar' has a long history. The +earliest version featuring this support that I was able to find was +1.09, released in November, 1990. The format introduced back then is +called "old GNU" sparse format and in spite of the fact that its design +contained many flaws, it was the only format GNU `tar' supported until +version 1.14 (May, 2004), which introduced initial support for sparse +archives in PAX archives (*note posix::). This format was not free +from design flows, either and it was subsequently improved in versions +1.15.2 (November, 2005) and 1.15.92 (June, 2006). + + In addition to GNU sparse format, GNU `tar' is able to read and +extract sparse files archived by `star'. + + The following subsections describe each format in detail. + +* Menu: + +* Old GNU Format:: +* PAX 0:: PAX Format, Versions 0.0 and 0.1 +* PAX 1:: PAX Format, Version 1.0 + + +File: tar.info, Node: Old GNU Format, Next: PAX 0, Up: Sparse Formats + +C.0.1 Old GNU Format +-------------------- + +The format introduced some time around 1990 (v. 1.09). It was designed +on top of standard `ustar' headers in such an unfortunate way that some +of its fields overwrote fields required by POSIX. + + An old GNU sparse header is designated by type `S' +(`GNUTYPE_SPARSE') and has the following layout: + +Offset Size Name Data type Contents +---------------------------------------------------------------------------- +0 345 N/A Not used. +345 12 atime Number `atime' of the file. +357 12 ctime Number `ctime' of the file . +369 12 offset Number For multivolume archives: + the offset of the start of + this volume. +381 4 N/A Not used. +385 1 N/A Not used. +386 96 sp `sparse_header'(4 entries) File map. +482 1 isextended Bool `1' if an extension sparse + header follows, `0' + otherwise. +483 12 realsize Number Real size of the file. + + Each of `sparse_header' object at offset 386 describes a single data +chunk. It has the following structure: + +Offset Size Data type Contents +--------------------------------------------------------------------------- +0 12 Number Offset of the beginning of the chunk. +12 12 Number Size of the chunk. + + If the member contains more than four chunks, the `isextended' field +of the header has the value `1' and the main header is followed by one +or more "extension headers". Each such header has the following +structure: + +Offset Size Name Data type Contents +---------------------------------------------------------------------------- +0 21 sp `sparse_header' (21 entires) File map. +504 1 isextended Bool `1' if an extension sparse + header follows, or `0' + otherwise. + + A header with `isextended=0' ends the map. + + +File: tar.info, Node: PAX 0, Next: PAX 1, Prev: Old GNU Format, Up: Sparse Formats + +C.0.2 PAX Format, Versions 0.0 and 0.1 +-------------------------------------- + +There are two formats available in this branch. The version `0.0' is +the initial version of sparse format used by `tar' versions +1.14-1.15.1. The sparse file map is kept in extended (`x') PAX header +variables: + +`GNU.sparse.size' + Real size of the stored file + +`GNU.sparse.numblocks' + Number of blocks in the sparse map + +`GNU.sparse.offset' + Offset of the data block + +`GNU.sparse.numbytes' + Size of the data block + + The latter two variables repeat for each data block, so the overall +structure is like this: + + GNU.sparse.size=SIZE + GNU.sparse.numblocks=NUMBLOCKS + repeat NUMBLOCKS times + GNU.sparse.offset=OFFSET + GNU.sparse.numbytes=NUMBYTES + end repeat + + This format presented the following two problems: + + 1. Whereas the POSIX specification allows a variable to appear + multiple times in a header, it requires that only the last + occurrence be meaningful. Thus, multiple occurrences of + `GNU.sparse.offset' and `GNU.sparse.numbytes' are conflicting with + the POSIX specs. + + 2. Attempting to extract such archives using a third-party `tar's + results in extraction of sparse files in _compressed form_. If + the `tar' implementation in question does not support POSIX + format, it will also extract a file containing extension header + attributes. This file can be used to expand the file to its + original state. However, posix-aware `tar's will usually ignore + the unknown variables, which makes restoring the file more + difficult. *Note Extraction of sparse members in v.0.0 format: + extracting sparse v.0.x, for the detailed description of how to + restore such members using non-GNU `tar's. + + GNU `tar' 1.15.2 introduced sparse format version `0.1', which +attempted to solve these problems. As its predecessor, this format +stores sparse map in the extended POSIX header. It retains +`GNU.sparse.size' and `GNU.sparse.numblocks' variables, but instead of +`GNU.sparse.offset'/`GNU.sparse.numbytes' pairs it uses a single +variable: + +`GNU.sparse.map' + Map of non-null data chunks. It is a string consisting of + comma-separated values "OFFSET,SIZE[,OFFSET-1,SIZE-1...]" + + To address the 2nd problem, the `name' field in `ustar' is replaced +with a special name, constructed using the following pattern: + + %d/GNUSparseFile.%p/%f + + The real name of the sparse file is stored in the variable +`GNU.sparse.name'. Thus, those `tar' implementations that are not +aware of GNU extensions will at least extract the files into separate +directories, giving the user a possibility to expand it afterwards. +*Note Extraction of sparse members in v.0.1 format: extracting sparse +v.0.x, for the detailed description of how to restore such members +using non-GNU `tar's. + + The resulting `GNU.sparse.map' string can be _very_ long. Although +POSIX does not impose any limit on the length of a `x' header variable, +this possibly can confuse some tars. + + +File: tar.info, Node: PAX 1, Prev: PAX 0, Up: Sparse Formats + +C.0.3 PAX Format, Version 1.0 +----------------------------- + +The version `1.0' of sparse format was introduced with GNU `tar' +1.15.92. Its main objective was to make the resulting file extractable +with little effort even by non-posix aware `tar' implementations. +Starting from this version, the extended header preceding a sparse +member always contains the following variables that identify the format +being used: + +`GNU.sparse.major' + Major version + +`GNU.sparse.minor' + Minor version + + The `name' field in `ustar' header contains a special name, +constructed using the following pattern: + + %d/GNUSparseFile.%p/%f + + The real name of the sparse file is stored in the variable +`GNU.sparse.name'. The real size of the file is stored in the variable +`GNU.sparse.realsize'. + + The sparse map itself is stored in the file data block, preceding +the actual file data. It consists of a series of octal numbers of +arbitrary length, delimited by newlines. The map is padded with nulls +to the nearest block boundary. + + The first number gives the number of entries in the map. Following +are map entries, each one consisting of two numbers giving the offset +and size of the data block it describes. + + The format is designed in such a way that non-posix aware tars and +tars not supporting `GNU.sparse.*' keywords will extract each sparse +file in its condensed form with the file map prepended and will place it +into a separate directory. Then, using a simple program it would be +possible to expand the file to its original form even without GNU `tar'. +*Note Sparse Recovery::, for the detailed information on how to extract +sparse members without GNU `tar'. + + +File: tar.info, Node: Snapshot Files, Next: Dumpdir, Prev: Sparse Formats, Up: Tar Internals + +Format of the Incremental Snapshot Files +======================================== + +A "snapshot file" (or "directory file") is created during incremental +backups (*note Incremental Dumps::). It contains the status of the +file system at the time of the dump and is used to determine which +files were modified since the last backup. + + GNU `tar' version 1.17 supports two snapshot file formats. The +first format, called "format 0", is the one used by GNU `tar' versions +up to 1.15.1. The second format, called "format 1" is an extended +version of this format, that contains more metadata and allows for +further extensions. + + `Format 0' snapshot file begins with a line containing a decimal +number that represents the UNIX timestamp of the beginning of the last +archivation. This line is followed by directory metadata descriptions, +one per line. Each description has the following format: + + [NFS]DEV INODE NAME + +where optional NFS is a single plus character (`+') if this directory +is located on an NFS-mounted partition, DEV and INODE are the device +and inode numbers of the directory, and NAME is the directory name. + + `Format 1' snapshot file begins with a line specifying the format of +the file. This line has the following structure: + + `GNU tar-'TAR-VERSION`-'INCR-FORMAT-VERSION + +where TAR-VERSION is the version of GNU `tar' implementation that +created this snapshot, and INCR-FORMAT-VERSION is the version number of +the snapshot format (in this case `1'). + + The following line contains two decimal numbers, representing the +time of the last backup. First number is the number of seconds, the +second one is the number of nanoseconds, since the beginning of the +epoch. + + Following lines contain directory metadata, one line per directory. +The line format is: + + [NFS]MTIME-SEC MTIME-NSEC DEV INODE NAME + +where MTIME-SEC and MTIME-NSEC represent the last modification time of +this directory with nanosecond precision; NFS, DEV, INODE and NAME have +the same meaning as with `format 0'. + + +File: tar.info, Node: Dumpdir, Prev: Snapshot Files, Up: Tar Internals + +Dumpdir +======= + +Incremental archives keep information about contents of each dumped +directory in special data blocks called "dumpdirs". + + Dumpdir is a sequence of entries of the following form: + + C FILENAME \0 + +where C is one of the "control codes" described below, FILENAME is the +name of the file C operates upon, and `\0' represents a nul character +(ASCII 0). The white space characters were added for readability, real +dumpdirs do not contain them. + + Each dumpdir ends with a single nul character. + + The following table describes control codes and their meanings: + +`Y' + FILENAME is contained in the archive. + +`N' + FILENAME was present in the directory at the time the archive was + made, yet it was not dumped to the archive, because it had not + changed since the last backup. + +`D' + FILENAME is a directory. + +`R' + This code requests renaming of the FILENAME to the name specified + with the following `T' command. + +`T' + Specify target file name for `R' command (see below). + +`X' + Specify "temporary directory" name for a rename operation (see + below). + + Codes `Y', `N' and `D' require FILENAME argument to be a relative +file name to the directory this dumpdir describes, whereas codes `R', +`T' and `X' require their argument to be an absolute file name. + + The three codes `R', `T' and `X' specify a "renaming operation". In +the simplest case it is: + + R`source'\0T`dest'\0 + +which means "rename file `source' to file `dest'". + + However, there are cases that require using a "temporary directory". +For example, consider the following scenario: + + 1. Previous run dumped a directory `foo' which contained the + following three directories: + + a + b + c + + 2. They were renamed _cyclically_, so that: + + `a' became `b' + `b' became `c' + `c' became `a' + + 3. New incremental dump was made. + + This case cannot be handled by three successive renames, since +renaming `a' to `b' will destroy existing directory. To handle such +case a temporary directory is required. GNU `tar' will create the +following dumpdir (newlines have been added for readability): + + Xfoo\0 + Rfoo/a\0T\0 + Rfoo/b\0Tfoo/c\0 + Rfoo/c\0Tfoo/a\0 + R\0Tfoo/a\0 + + The first command, `Xfoo\0', instructs the extractor to create a +temporary directory in the directory `foo'. Second command, +`Rfoo/aT\0', says "rename file `foo/a' to the temporary directory that +has just been created" (empty file name after a command means use +temporary directory). Third and fourth commands work as usual, and, +finally, the last command, `R\0Tfoo/a\0' tells tar to rename the +temporary directory to `foo/a'. + + The exact placement of a dumpdir in the archive depends on the +archive format (*note Formats::): + + * PAX archives + + In PAX archives, dumpdir is stored in the extended header of the + corresponding directory, in variable `GNU.dumpdir'. + + * GNU and old GNU archives + + These formats implement special header type `D', which is similar + to ustar header `5' (directory), except that it precedes a data + block containing the dumpdir. + + +File: tar.info, Node: Genfile, Next: Free Software Needs Free Documentation, Prev: Tar Internals, Up: Top + +Appendix D Genfile +****************** + +This appendix describes `genfile', an auxiliary program used in the GNU +tar testsuite. If you are not interested in developing GNU tar, skip +this appendix. + + Initially, `genfile' was used to generate data files for the +testsuite, hence its name. However, new operation modes were being +implemented as the testsuite grew more sophisticated, and now `genfile' +is a multi-purpose instrument. + + There are three basic operation modes: + +File Generation + This is the default mode. In this mode, `genfile' generates data + files. + +File Status + In this mode `genfile' displays status of specified files. + +Synchronous Execution. + In this mode `genfile' executes the given program with + `--checkpoint' option and executes a set of actions when specified + checkpoints are reached. + +* Menu: + +* Generate Mode:: File Generation Mode. +* Status Mode:: File Status Mode. +* Exec Mode:: Synchronous Execution mode. + + +File: tar.info, Node: Generate Mode, Next: Status Mode, Up: Genfile + +D.1 Generate Mode +================= + +In this mode `genfile' creates a data file for the test suite. The size +of the file is given with the `--length' (`-l') option. By default the +file contents is written to the standard output, this can be changed +using `--file' (`-f') command line option. Thus, the following two +commands are equivalent: + + genfile --length 100 > outfile + genfile --length 100 --file outfile + + If `--length' is not given, `genfile' will generate an empty +(zero-length) file. + + The command line option `--seek=N' istructs `genfile' to skip the +given number of bytes (N) in the output file before writing to it. It +is similar to the `seek=N' of the `dd' utility. + + You can instruct `genfile' to create several files at one go, by +giving it `--files-from' (`-T') option followed by a name of file +containing a list of file names. Using dash (`-') instead of the file +name causes `genfile' to read file list from the standard input. For +example: + + # Read file names from file `file.list' + genfile --files-from file.list + # Read file names from standard input + genfile --files-from - + + The list file is supposed to contain one file name per line. To use +file lists separated by ASCII NUL character, use `--null' (`-0') +command line option: + + genfile --null --files-from file.list + + The default data pattern for filling the generated file consists of +first 256 letters of ASCII code, repeated enough times to fill the +entire file. This behavior can be changed with `--pattern' option. This +option takes a mandatory argument, specifying pattern name to use. +Currently two patterns are implemented: + +`--pattern=default' + The default pattern as described above. + +`--pattern=zero' + Fills the file with zeroes. + + If no file name was given, the program exits with the code `0'. +Otherwise, it exits with `0' only if it was able to create a file of +the specified length. + + Special option `--sparse' (`-s') instructs `genfile' to create a +sparse file. Sparse files consist of "data fragments", separated by +"holes" or blocks of zeros. On many operating systems, actual disk +storage is not allocated for holes, but they are counted in the length +of the file. To create a sparse file, `genfile' should know where to +put data fragments, and what data to use to fill them. So, when +`--sparse' is given the rest of the command line specifies a so-called +"file map". + + The file map consists of any number of "fragment descriptors". Each +descriptor is composed of two values: a number, specifying fragment +offset from the end of the previous fragment or, for the very first +fragment, from the beginning of the file, and "contents string", i.e., +a string of characters, specifying the pattern to fill the fragment +with. File offset can be suffixed with the following quantifiers: + +`k' +`K' + The number is expressed in kilobytes. + +`m' +`M' + The number is expressed in megabytes. + +`g' +`G' + The number is expressed in gigabytes. + + For each letter in contents string `genfile' will generate a "block" +of data, filled with this letter and will write it to the fragment. The +size of block is given by `--block-size' option. It defaults to 512. +Thus, if the string consists of N characters, the resulting file +fragment will contain `N*BLOCK-SIZE' of data. + + Last fragment descriptor can have only file offset part. In this +case `genfile' will create a hole at the end of the file up to the +given offset. + + For example, consider the following invocation: + + genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K + +It will create 3101184-bytes long file of the following structure: + +Offset Length Contents +0 4*512=2048 Four 512-byte blocks, filled + with letters `A', `B', `C' and + `D'. +2048 1046528 Zero bytes +1050624 5*512=2560 Five blocks, filled with letters + `E', `F', `G', `H', `I'. +1053184 2048000 Zero bytes + + The exit code of `genfile --status' command is `0' only if created +file is actually sparse. + + +File: tar.info, Node: Status Mode, Next: Exec Mode, Prev: Generate Mode, Up: Genfile + +D.2 Status Mode +=============== + +In status mode, `genfile' prints file system status for each file +specified in the command line. This mode is toggled by `--stat' (`-S') +command line option. An optional argument to this option specifies +output "format": a comma-separated list of `struct stat' fields to be +displayed. This list can contain following identifiers : + +name + The file name. + +dev +st_dev + Device number in decimal. + +ino +st_ino + Inode number. + +mode[.NUMBER] +st_mode[.NUMBER] + File mode in octal. Optional NUMBER specifies octal mask to be + applied to the mode before outputting. For example, `--stat + mode.777' will preserve lower nine bits of it. Notice, that you + can use any punctuation character in place of `.'. + +nlink +st_nlink + Number of hard links. + +uid +st_uid + User ID of owner. + +gid +st_gid + Group ID of owner. + +size +st_size + File size in decimal. + +blksize +st_blksize + The size in bytes of each file block. + +blocks +st_blocks + Number of blocks allocated. + +atime +st_atime + Time of last access. + +mtime +st_mtime + Time of last modification + +ctime +st_ctime + Time of last status change + +sparse + A boolean value indicating whether the file is `sparse'. + + Modification times are displayed in UTC as UNIX timestamps, unless +suffixed with `H' (for "human-readable"), as in `ctimeH', in which case +usual `tar tv' output format is used. + + The default output format is: `name,dev,ino,mode, +nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime'. + + For example, the following command will display file names and +corresponding times of last access for each file in the current working +directory: + + genfile --stat=name,atime * + + +File: tar.info, Node: Exec Mode, Prev: Status Mode, Up: Genfile + +D.3 Exec Mode +============= + +This mode is designed for testing the behavior of `paxutils' commands +when some of the files change during archiving. It is an experimental +mode. + + The `Exec Mode' is toggled by `--run' command line option (or its +alias `-r'). The argument to this option gives the command line to be +executed. The actual command line is constructed by inserting +`--checkpoint' option between the command name and its first argument +(if any). Due to this, the argument to `--run' may not use traditional +`tar' option syntax, i.e., the following is wrong: + + # Wrong! + genfile --run 'tar cf foo bar' + +Use the following syntax instead: + + genfile --run 'tar -cf foo bar' + + The rest of command line after `--run' or its equivalent specifies +checkpoint values and actions to be executed upon reaching them. +Checkpoint values are introduced with `--checkpoint' command line +option. Argument to this option is the number of checkpoint in decimal. + + Any number of "actions" may be specified after a checkpoint. +Available actions are + +`--cut FILE' +`--truncate FILE' + Truncate FILE to the size specified by previous `--length' option + (or 0, if it is not given). + +`--append FILE' + Append data to FILE. The size of data and its pattern are given by + previous `--length' and `pattern' options. + +`--touch FILE' + Update the access and modification times of FILE. These timestamps + are changed to the current time, unless `--date' option was given, + in which case they are changed to the specified time. Argument to + `--date' option is a date specification in an almost arbitrary + format (*note Date input formats::). + +`--exec COMMAND' + Execute given shell command. + + + Option `--verbose' instructs `genfile' to print on standard output +notifications about checkpoints being executed and to verbosely +describe exit status of the command. + + While the command is being executed its standard output remains +connected to descriptor 1. All messages it prints to file descriptor 2, +except checkpoint notifications, are forwarded to standard error. + + `Genfile' exits with the exit status of the executed command. + + +File: tar.info, Node: Free Software Needs Free Documentation, Next: Copying This Manual, Prev: Genfile, Up: Top + +Appendix E Free Software Needs Free Documentation +************************************************* + +The biggest deficiency in the free software community today is not in +the software--it is the lack of good free documentation that we can +include with the free software. Many of our most important programs do +not come with free reference manuals and free introductory texts. +Documentation is an essential part of any software package; when an +important free software package does not come with a free manual and a +free tutorial, that is a major gap. We have many such gaps today. + + Consider Perl, for instance. The tutorial manuals that people +normally use are non-free. How did this come about? Because the +authors of those manuals published them with restrictive terms--no +copying, no modification, source files not available--which exclude +them from the free software world. + + That wasn't the first time this sort of thing happened, and it was +far from the last. Many times we have heard a GNU user eagerly +describe a manual that he is writing, his intended contribution to the +community, only to learn that he had ruined everything by signing a +publication contract to make it non-free. + + Free documentation, like free software, is a matter of freedom, not +price. The problem with the non-free manual is not that publishers +charge a price for printed copies--that in itself is fine. (The Free +Software Foundation sells printed copies of manuals, too.) The problem +is the restrictions on the use of the manual. Free manuals are +available in source code form, and give you permission to copy and +modify. Non-free manuals do not allow this. + + The criteria of freedom for a free manual are roughly the same as for +free software. Redistribution (including the normal kinds of +commercial redistribution) must be permitted, so that the manual can +accompany every copy of the program, both on-line and on paper. + + Permission for modification of the technical content is crucial too. +When people modify the software, adding or changing features, if they +are conscientious they will change the manual too--so they can provide +accurate and clear documentation for the modified program. A manual +that leaves you no choice but to write a new manual to document a +changed version of the program is not really available to our community. + + Some kinds of limits on the way modification is handled are +acceptable. For example, requirements to preserve the original +author's copyright notice, the distribution terms, or the list of +authors, are ok. It is also no problem to require modified versions to +include notice that they were modified. Even entire sections that may +not be deleted or changed are acceptable, as long as they deal with +nontechnical topics (like this one). These kinds of restrictions are +acceptable because they don't obstruct the community's normal use of +the manual. + + However, it must be possible to modify all the _technical_ content +of the manual, and then distribute the result in all the usual media, +through all the usual channels. Otherwise, the restrictions obstruct +the use of the manual, it is not free, and we need another manual to +replace it. + + Please spread the word about this issue. Our community continues to +lose manuals to proprietary publishing. If we spread the word that +free software needs free reference manuals and free tutorials, perhaps +the next person who wants to contribute by writing documentation will +realize, before it is too late, that only free manuals contribute to +the free software community. + + If you are writing documentation, please insist on publishing it +under the GNU Free Documentation License or another free documentation +license. Remember that this decision requires your approval--you don't +have to let the publisher decide. Some commercial publishers will use +a free license if you insist, but they will not propose the option; it +is up to you to raise the issue and say firmly that this is what you +want. If the publisher you are dealing with refuses, please try other +publishers. If you're not sure whether a proposed license is free, +write to <licensing@gnu.org>. + + You can encourage commercial publishers to sell more free, copylefted +manuals and tutorials by buying them, and particularly by buying copies +from the publishers that paid for their writing or for major +improvements. Meanwhile, try to avoid buying non-free documentation at +all. Check the distribution terms of a manual before you buy it, and +insist that whoever seeks your business must respect your freedom. +Check the history of the book, and try reward the publishers that have +paid or pay the authors to work on it. + + The Free Software Foundation maintains a list of free documentation +published by other publishers, at +`http://www.fsf.org/doc/other-free-books.html'. + + +File: tar.info, Node: Copying This Manual, Next: Index of Command Line Options, Prev: Free Software Needs Free Documentation, Up: Top + +Appendix F Copying This Manual +****************************** + +* Menu: + +* GNU Free Documentation License:: License for copying this manual + + +File: tar.info, Node: GNU Free Documentation License, Up: Copying This Manual + +F.1 GNU Free Documentation License +================================== + + Version 1.2, November 2002 + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. + We recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it + can be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You + accept the license if you copy, modify or distribute the work in a + way requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in + the notice that says that the Document is released under this + License. If a section does not fit the above definition of + Secondary then it is not allowed to be designated as Invariant. + The Document may contain zero Invariant Sections. If the Document + does not identify any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup, or absence of + markup, has been arranged to thwart or discourage subsequent + modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A + copy that is not "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and + standard-conforming simple HTML, PostScript or PDF designed for + human modification. Examples of transparent image formats include + PNG, XCF and JPG. Opaque formats include proprietary formats that + can be read and edited only by proprietary word processors, SGML or + XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF + produced by some word processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow + the conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the + title equally prominent and visible. You may add other material + on the covers in addition. Copying with changes limited to the + covers, as long as they preserve the title of the Document and + satisfy these conditions, can be treated as verbatim copying in + other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a computer-network location from + which the general network-using public has access to download + using public-standard network protocols a complete Transparent + copy of the Document, free of added material. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of + copies, to give them a chance to provide you with an updated + version of the Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with + the Modified Version filling the role of the Document, thus + licensing distribution and modification of the Modified Version to + whoever possesses a copy of it. In addition, you must do these + things in the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of + previous versions (which should, if there were any, be listed + in the History section of the Document). You may use the + same title as a previous version if the original publisher of + that version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on + the Title Page. If there is no section Entitled "History" in + the Document, create one stating the title, year, authors, + and publisher of the Document as given on its Title Page, + then add an item describing the Modified Version as stated in + the previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in + the "History" section. You may omit a network location for a + work that was published at least four years before the + Document itself, or if the original publisher of the version + it refers to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section + titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end + of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow + this License in all other respects regarding verbatim copying of + that document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + `http://www.gnu.org/copyleft/'. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. + +F.1.1 ADDENDUM: How to use this License for your documents +---------------------------------------------------------- + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, to +permit their use in free software. + + +File: tar.info, Node: Index of Command Line Options, Next: Index, Prev: Copying This Manual, Up: Top + +Appendix G Index of Command Line Options +**************************************** + +This appendix contains an index of all GNU `tar' long command line +options. The options are listed without the preceding double-dash. For +a cross-reference of short command line options, *note Short Option +Summary::. + + +* Menu: + +* absolute-names: absolute. (line 8) +* absolute-names, summary: Option Summary. (line 6) +* add-file: files. (line 84) +* after-date: after. (line 26) +* after-date, summary: Option Summary. (line 12) +* anchored: controlling pattern-matching. + (line 79) +* anchored, summary: Option Summary. (line 15) +* append: append. (line 8) +* append, summary: Operation Summary. (line 6) +* atime-preserve: Attributes. (line 14) +* atime-preserve, summary: Option Summary. (line 19) +* backup: backup. (line 41) +* backup, summary: Option Summary. (line 65) +* block-number: verbose. (line 111) +* block-number, summary: Option Summary. (line 70) +* blocking-factor: Blocking Factor. (line 8) +* blocking-factor, summary: Option Summary. (line 76) +* bzip2: gzip. (line 88) +* bzip2, summary: Option Summary. (line 81) +* catenate: concatenate. (line 6) +* catenate, summary: Operation Summary. (line 10) +* check-links, summary: Option Summary. (line 93) +* checkpoint: verbose. (line 83) +* checkpoint, summary: Option Summary. (line 86) +* compare: compare. (line 8) +* compare, summary: Operation Summary. (line 14) +* compress: gzip. (line 92) +* compress, summary: Option Summary. (line 100) +* concatenate: concatenate. (line 6) +* concatenate, summary: Operation Summary. (line 20) +* confirmation, summary: Option Summary. (line 107) +* create, additional options: create options. (line 6) +* create, complementary notes: Basic tar. (line 11) +* create, introduced: Creating the archive. + (line 6) +* create, summary: Operation Summary. (line 25) +* create, using with --verbose: create verbose. (line 6) +* create, using with --verify: verify. (line 24) +* delay-directory-restore: Directory Modification Times and Permissions. + (line 62) +* delay-directory-restore, summary: Option Summary. (line 110) +* delete: delete. (line 8) +* delete, summary: Operation Summary. (line 29) +* dereference: dereference. (line 6) +* dereference, summary: Option Summary. (line 115) +* diff, summary: Operation Summary. (line 33) +* directory: directory. (line 11) +* directory, summary: Option Summary. (line 121) +* directory, using in --files-from argument: files. (line 60) +* exclude: exclude. (line 11) +* exclude, potential problems with: problems with exclude. + (line 6) +* exclude, summary: Option Summary. (line 128) +* exclude-caches: exclude. (line 45) +* exclude-caches, summary: Option Summary. (line 137) +* exclude-caches-all: exclude. (line 53) +* exclude-caches-all, summary: Option Summary. (line 150) +* exclude-caches-under: exclude. (line 49) +* exclude-caches-under, summary: Option Summary. (line 144) +* exclude-from: exclude. (line 22) +* exclude-from, summary: Option Summary. (line 132) +* exclude-tag: exclude. (line 62) +* exclude-tag, summary: Option Summary. (line 154) +* exclude-tag-all: exclude. (line 70) +* exclude-tag-all, summary: Option Summary. (line 162) +* exclude-tag-under: exclude. (line 66) +* exclude-tag-under, summary: Option Summary. (line 158) +* extract: extract. (line 8) +* extract, additional options: extract options. (line 8) +* extract, complementary notes: Basic tar. (line 48) +* extract, summary: Operation Summary. (line 37) +* extract, using with --listed-incremental: Incremental Dumps. + (line 93) +* file, short description: file. (line 17) +* file, summary: Option Summary. (line 166) +* file, tutorial: file tutorial. (line 6) +* files-from: files. (line 14) +* files-from, summary: Option Summary. (line 172) +* force-local, short description: Device. (line 70) +* force-local, summary: Option Summary. (line 178) +* format, summary: Option Summary. (line 183) +* get, summary: Operation Summary. (line 42) +* group: override. (line 73) +* group, summary: Option Summary. (line 208) +* gunzip, summary: Option Summary. (line 216) +* gzip: gzip. (line 54) +* gzip, summary: Option Summary. (line 216) +* help: help tutorial. (line 6) +* help, introduction: help. (line 26) +* help, summary: Option Summary. (line 224) +* ignore-case: controlling pattern-matching. + (line 86) +* ignore-case, summary: Option Summary. (line 229) +* ignore-command-error: Writing to an External Program. + (line 82) +* ignore-command-error, summary: Option Summary. (line 233) +* ignore-failed-read: Ignore Failed Read. (line 7) +* ignore-failed-read, summary: Option Summary. (line 237) +* ignore-zeros: Ignore Zeros. (line 6) +* ignore-zeros, short description: Blocking Factor. (line 156) +* ignore-zeros, summary: Option Summary. (line 241) +* incremental, summary: Option Summary. (line 246) +* incremental, using with --list: Incremental Dumps. (line 158) +* index-file, summary: Option Summary. (line 253) +* info-script: Multi-Volume Archives. + (line 80) +* info-script, short description: Device. (line 104) +* info-script, summary: Option Summary. (line 256) +* interactive: interactive. (line 14) +* interactive, summary: Option Summary. (line 264) +* keep-newer-files: Keep Newer Files. (line 6) +* keep-newer-files, summary: Option Summary. (line 271) +* keep-old-files: Keep Old Files. (line 6) +* keep-old-files, introduced: Dealing with Old Files. + (line 16) +* keep-old-files, summary: Option Summary. (line 275) +* label: label. (line 8) +* label, summary: Option Summary. (line 280) +* list: list. (line 6) +* list, summary: Operation Summary. (line 46) +* list, using with --incremental: Incremental Dumps. (line 158) +* list, using with --listed-incremental: Incremental Dumps. (line 158) +* list, using with --verbose: list. (line 30) +* list, using with file name arguments: list. (line 68) +* listed-incremental: Incremental Dumps. (line 14) +* listed-incremental, summary: Option Summary. (line 287) +* listed-incremental, using with --extract: Incremental Dumps. + (line 93) +* listed-incremental, using with --list: Incremental Dumps. (line 158) +* mode: override. (line 14) +* mode, summary: Option Summary. (line 295) +* mtime: override. (line 29) +* mtime, summary: Option Summary. (line 301) +* multi-volume: Multi-Volume Archives. + (line 6) +* multi-volume, short description: Device. (line 88) +* multi-volume, summary: Option Summary. (line 310) +* new-volume-script: Multi-Volume Archives. + (line 80) +* new-volume-script, short description: Device. (line 104) +* new-volume-script, summary: Option Summary. (line 256) +* newer: after. (line 26) +* newer, summary: Option Summary. (line 318) +* newer-mtime: after. (line 37) +* newer-mtime, summary: Option Summary. (line 326) +* no-anchored: controlling pattern-matching. + (line 79) +* no-anchored, summary: Option Summary. (line 331) +* no-delay-directory-restore: Directory Modification Times and Permissions. + (line 68) +* no-delay-directory-restore, summary: Option Summary. (line 335) +* no-ignore-case: controlling pattern-matching. + (line 86) +* no-ignore-case, summary: Option Summary. (line 341) +* no-ignore-command-error: Writing to an External Program. + (line 87) +* no-ignore-command-error, summary: Option Summary. (line 344) +* no-overwrite-dir, summary: Option Summary. (line 348) +* no-quote-chars, summary: Option Summary. (line 352) +* no-recursion: recurse. (line 13) +* no-recursion, summary: Option Summary. (line 357) +* no-same-owner: Attributes. (line 67) +* no-same-owner, summary: Option Summary. (line 361) +* no-same-permissions, summary: Option Summary. (line 367) +* no-unquote: Selecting Archive Members. + (line 42) +* no-unquote, summary: Option Summary. (line 372) +* no-wildcards: controlling pattern-matching. + (line 41) +* no-wildcards, summary: Option Summary. (line 376) +* no-wildcards-match-slash: controlling pattern-matching. + (line 92) +* no-wildcards-match-slash, summary: Option Summary. (line 379) +* null: nul. (line 11) +* null, summary: Option Summary. (line 382) +* numeric-owner: Attributes. (line 73) +* numeric-owner, summary: Option Summary. (line 388) +* occurrence, summary: Option Summary. (line 405) +* old-archive, summary: Option Summary. (line 419) +* one-file-system: one. (line 16) +* one-file-system, summary: Option Summary. (line 422) +* overwrite: Overwrite Old Files. (line 6) +* overwrite, introduced: Dealing with Old Files. + (line 22) +* overwrite, summary: Option Summary. (line 427) +* overwrite-dir: Overwrite Old Files. (line 28) +* overwrite-dir, introduced: Dealing with Old Files. + (line 6) +* overwrite-dir, summary: Option Summary. (line 431) +* owner: override. (line 57) +* owner, summary: Option Summary. (line 435) +* pax-option: PAX keywords. (line 6) +* pax-option, summary: Option Summary. (line 444) +* portability, summary: Option Summary. (line 450) +* posix, summary: Option Summary. (line 454) +* preserve: Attributes. (line 126) +* preserve, summary: Option Summary. (line 457) +* preserve-order: Same Order. (line 6) +* preserve-order, summary: Option Summary. (line 461) +* preserve-permissions: Setting Access Permissions. + (line 10) +* preserve-permissions, short description: Attributes. (line 113) +* preserve-permissions, summary: Option Summary. (line 464) +* quote-chars, summary: Option Summary. (line 474) +* quoting-style: quoting styles. (line 39) +* quoting-style, summary: Option Summary. (line 478) +* read-full-records <1>: read full records. (line 6) +* read-full-records: Reading. (line 8) +* read-full-records, short description: Blocking Factor. (line 172) +* read-full-records, summary: Option Summary. (line 485) +* record-size, summary: Option Summary. (line 490) +* recursion: recurse. (line 24) +* recursion, summary: Option Summary. (line 494) +* recursive-unlink: Recursive Unlink. (line 6) +* recursive-unlink, summary: Option Summary. (line 498) +* remove-files: remove files. (line 6) +* remove-files, summary: Option Summary. (line 503) +* restrict, summary: Option Summary. (line 507) +* rmt-command, summary: Option Summary. (line 512) +* rsh-command: Device. (line 73) +* rsh-command, summary: Option Summary. (line 516) +* same-order: Same Order. (line 6) +* same-order, summary: Option Summary. (line 520) +* same-owner: Attributes. (line 48) +* same-owner, summary: Option Summary. (line 528) +* same-permissions: Setting Access Permissions. + (line 10) +* same-permissions, short description: Attributes. (line 113) +* same-permissions, summary: Option Summary. (line 464) +* seek, summary: Option Summary. (line 537) +* show-defaults: defaults. (line 6) +* show-defaults, summary: Option Summary. (line 544) +* show-omitted-dirs: verbose. (line 103) +* show-omitted-dirs, summary: Option Summary. (line 553) +* show-stored-names: list. (line 60) +* show-stored-names, summary: Option Summary. (line 557) +* show-transformed-names: transform. (line 45) +* show-transformed-names, summary: Option Summary. (line 557) +* sparse: sparse. (line 22) +* sparse, summary: Option Summary. (line 565) +* sparse-version: sparse. (line 57) +* sparse-version, summary: Option Summary. (line 570) +* starting-file: Starting File. (line 6) +* starting-file, summary: Option Summary. (line 575) +* strip-components: transform. (line 25) +* strip-components, summary: Option Summary. (line 581) +* suffix: backup. (line 68) +* suffix, summary: Option Summary. (line 590) +* tape-length: Multi-Volume Archives. + (line 33) +* tape-length, short description: Device. (line 96) +* tape-length, summary: Option Summary. (line 596) +* test-label: label. (line 37) +* test-label, summary: Option Summary. (line 601) +* to-command: Writing to an External Program. + (line 9) +* to-command, summary: Option Summary. (line 605) +* to-stdout: Writing to Standard Output. + (line 14) +* to-stdout, summary: Option Summary. (line 609) +* totals: verbose. (line 46) +* totals, summary: Option Summary. (line 614) +* touch <1>: Attributes. (line 37) +* touch: Data Modification Times. + (line 15) +* touch, summary: Option Summary. (line 619) +* transform: transform. (line 74) +* transform, summary: Option Summary. (line 625) +* uncompress: gzip. (line 92) +* uncompress, summary: Option Summary. (line 100) +* ungzip: gzip. (line 54) +* ungzip, summary: Option Summary. (line 216) +* unlink-first: Unlink First. (line 6) +* unlink-first, introduced: Dealing with Old Files. + (line 42) +* unlink-first, summary: Option Summary. (line 644) +* unquote: Selecting Archive Members. + (line 39) +* unquote, summary: Option Summary. (line 650) +* update: update. (line 8) +* update, summary: Operation Summary. (line 50) +* usage: help. (line 53) +* use-compress-program: gzip. (line 101) +* use-compress-program, summary: Option Summary. (line 654) +* utc, summary: Option Summary. (line 658) +* verbose: verbose. (line 18) +* verbose, introduced: verbose tutorial. (line 6) +* verbose, summary: Option Summary. (line 662) +* verbose, using with --create: create verbose. (line 6) +* verbose, using with --list: list. (line 30) +* verify, short description: verify. (line 8) +* verify, summary: Option Summary. (line 669) +* verify, using with --create: verify. (line 24) +* version: help. (line 6) +* version, summary: Option Summary. (line 674) +* volno-file: Multi-Volume Archives. + (line 71) +* volno-file, summary: Option Summary. (line 679) +* wildcards: controlling pattern-matching. + (line 38) +* wildcards, summary: Option Summary. (line 684) +* wildcards-match-slash: controlling pattern-matching. + (line 92) +* wildcards-match-slash, summary: Option Summary. (line 688) + + +File: tar.info, Node: Index, Prev: Index of Command Line Options, Up: Top + +Appendix H Index +**************** + + +* Menu: + +* abbreviations for months: Calendar date items. (line 38) +* absolute file names: Remote Tape Server. (line 17) +* Adding archives to an archive: concatenate. (line 6) +* Adding files to an Archive: appending files. (line 8) +* ADMINISTRATOR: General-Purpose Variables. + (line 7) +* Age, excluding files by: after. (line 8) +* ago in date strings: Relative items in date strings. + (line 23) +* am in date strings: Time of day items. (line 22) +* Appending files to an Archive: appending files. (line 8) +* archive: Definitions. (line 6) +* Archive creation: file. (line 36) +* archive member: Definitions. (line 15) +* Archive Name: file. (line 8) +* Archive, creation of: create. (line 8) +* Archives, Appending files to: appending files. (line 8) +* Archiving Directories: create dir. (line 6) +* archiving files: Top. (line 24) +* ARGP_HELP_FMT, environment variable: Configuring Help Summary. + (line 22) +* authors of get_date: Authors of get_date. (line 6) +* Avoiding recursion in directories: recurse. (line 8) +* backup options: backup. (line 6) +* backup suffix: backup. (line 68) +* BACKUP_DIRS: General-Purpose Variables. + (line 29) +* BACKUP_FILES: General-Purpose Variables. + (line 55) +* BACKUP_HOUR: General-Purpose Variables. + (line 11) +* backups: backup. (line 41) +* beginning of time, for POSIX: Seconds since the Epoch. + (line 13) +* Bellovin, Steven M.: Authors of get_date. (line 6) +* Berets, Jim: Authors of get_date. (line 6) +* Berry, K.: Authors of get_date. (line 14) +* Block number where error occurred: verbose. (line 111) +* BLOCKING: General-Purpose Variables. + (line 25) +* blocking factor: Blocking Factor. (line 194) +* Blocking Factor: Blocking Factor. (line 6) +* Blocks per record: Blocking Factor. (line 6) +* bug reports: Reports. (line 6) +* Bytes per record: Blocking Factor. (line 6) +* calendar date item: Calendar date items. (line 6) +* case, ignored in dates: General date syntax. (line 64) +* cat vs concatenate: concatenate. (line 63) +* Changing directory mid-stream: directory. (line 6) +* Character class, excluding characters from: wildcards. (line 34) +* Choosing an archive file: file. (line 8) +* comments, in dates: General date syntax. (line 64) +* Compressed archives: gzip. (line 6) +* concatenate vs cat: concatenate. (line 63) +* Concatenating Archives: concatenate. (line 6) +* corrupted archives <1>: gzip. (line 73) +* corrupted archives: Full Dumps. (line 8) +* Creation of the archive: create. (line 8) +* DAT blocking: Blocking Factor. (line 204) +* Data Modification time, excluding files by: after. (line 8) +* Data modification times of extracted files: Data Modification Times. + (line 6) +* date format, ISO 8601: Calendar date items. (line 30) +* date input formats: Date input formats. (line 6) +* day in date strings: Relative items in date strings. + (line 15) +* day of week item: Day of week items. (line 6) +* Deleting files from an archive: delete. (line 8) +* Deleting from tape archives: delete. (line 19) +* Descending directories, avoiding: recurse. (line 8) +* Directories, Archiving: create dir. (line 6) +* Directories, avoiding recursion: recurse. (line 8) +* Directory, changing mid-stream: directory. (line 6) +* DIRLIST: General-Purpose Variables. + (line 51) +* displacement of dates: Relative items in date strings. + (line 6) +* doc-opt-col: Configuring Help Summary. + (line 95) +* Double-checking a write operation: verify. (line 6) +* DUMP_BEGIN: User Hooks. (line 32) +* DUMP_END: User Hooks. (line 36) +* DUMP_REMIND_SCRIPT: General-Purpose Variables. + (line 102) +* dumps, full: Full Dumps. (line 8) +* dup-args: Configuring Help Summary. + (line 52) +* dup-args-note: Configuring Help Summary. + (line 69) +* Eggert, Paul: Authors of get_date. (line 6) +* End-of-archive blocks, ignoring: Ignore Zeros. (line 6) +* End-of-archive info script: Multi-Volume Archives. + (line 80) +* entry: Naming tar Archives. (line 11) +* epoch, for POSIX: Seconds since the Epoch. + (line 13) +* Error message, block number of: verbose. (line 121) +* Exabyte blocking: Blocking Factor. (line 204) +* exclude: exclude. (line 14) +* exclude-caches: exclude. (line 33) +* exclude-from: exclude. (line 27) +* exclude-tag: exclude. (line 56) +* Excluding characters from a character class: wildcards. (line 34) +* Excluding file by age: after. (line 8) +* Excluding files by file system: exclude. (line 8) +* Excluding files by name and pattern: exclude. (line 8) +* Exec Mode, genfile: Exec Mode. (line 6) +* existing backup method: backup. (line 59) +* exit status: Synopsis. (line 67) +* Extraction: extract. (line 8) +* extraction: Definitions. (line 22) +* FDL, GNU Free Documentation License: GNU Free Documentation License. + (line 6) +* file archival: Top. (line 24) +* File lists separated by NUL characters: Generate Mode. (line 33) +* file name: Definitions. (line 15) +* File Name arguments, alternatives: files. (line 6) +* File name arguments, using --list with: list. (line 68) +* File names, excluding files by: exclude. (line 8) +* File names, terminated by NUL: nul. (line 6) +* File names, using symbolic links: dereference. (line 6) +* File system boundaries, not crossing: one. (line 6) +* FILELIST: General-Purpose Variables. + (line 65) +* first in date strings: General date syntax. (line 26) +* Format Options: Format Variations. (line 6) +* Format Parameters: Format Variations. (line 6) +* Format, old style: old. (line 6) +* fortnight in date strings: Relative items in date strings. + (line 15) +* free documentation: Free Software Needs Free Documentation. + (line 6) +* full dumps: Full Dumps. (line 8) +* future time stamps: Large or Negative Values. + (line 6) +* general date syntax: General date syntax. (line 6) +* Generate Mode, genfile: Generate Mode. (line 6) +* genfile: Genfile. (line 6) +* genfile, create file: Generate Mode. (line 6) +* genfile, creating sparse files: Generate Mode. (line 55) +* genfile, generate mode: Generate Mode. (line 6) +* genfile, reading a list of file names: Generate Mode. (line 22) +* genfile, seeking to a given offset: Generate Mode. (line 18) +* get_date: Date input formats. (line 6) +* Getting program version number: help. (line 6) +* GNU archive format: gnu. (line 6) +* GNU.sparse.major, extended header variable: PAX 1. (line 14) +* GNU.sparse.map, extended header variable: PAX 0. (line 60) +* GNU.sparse.minor, extended header variable: PAX 1. (line 17) +* GNU.sparse.name, extended header variable: PAX 0. (line 68) +* GNU.sparse.name, extended header variable, in v.1.0: PAX 1. (line 24) +* GNU.sparse.numblocks, extended header variable: PAX 0. (line 15) +* GNU.sparse.numbytes, extended header variable: PAX 0. (line 21) +* GNU.sparse.offset, extended header variable: PAX 0. (line 18) +* GNU.sparse.realsize, extended header variable: PAX 1. (line 24) +* GNU.sparse.size, extended header variable: PAX 0. (line 11) +* gnupg, using with tar: gzip. (line 113) +* gpg, using with tar: gzip. (line 113) +* header-col: Configuring Help Summary. + (line 141) +* hook: User Hooks. (line 13) +* hour in date strings: Relative items in date strings. + (line 15) +* Ignoring end-of-archive blocks: Ignore Zeros. (line 6) +* Info script: Multi-Volume Archives. + (line 80) +* Interactive operation: interactive. (line 6) +* ISO 8601 date format: Calendar date items. (line 30) +* items in date strings: General date syntax. (line 6) +* Labeling an archive: label. (line 6) +* Labeling multi-volume archives: label. (line 6) +* Labels on the archive media: label. (line 6) +* language, in dates: General date syntax. (line 40) +* Large lists of file names on small machines: Same Order. (line 6) +* large values: Large or Negative Values. + (line 6) +* last DAY: Day of week items. (line 15) +* last in date strings: General date syntax. (line 26) +* Listing all tar options: help. (line 26) +* listing member and file names: list. (line 41) +* Listing volume label: label. (line 29) +* Lists of file names: files. (line 6) +* Local and remote archives: file. (line 73) +* long-opt-col: Configuring Help Summary. + (line 87) +* MacKenzie, David: Authors of get_date. (line 6) +* member: Definitions. (line 15) +* member name: Definitions. (line 15) +* Members, replacing with other members: append. (line 49) +* Meyering, Jim: Authors of get_date. (line 6) +* Middle of the archive, starting in the: Starting File. (line 11) +* midnight in date strings: Time of day items. (line 22) +* minute in date strings: Relative items in date strings. + (line 15) +* minutes, time zone correction by: Time of day items. (line 30) +* Modes of extracted files: Setting Access Permissions. + (line 6) +* Modification time, excluding files by: after. (line 8) +* Modification times of extracted files: Data Modification Times. + (line 6) +* month in date strings: Relative items in date strings. + (line 15) +* month names in date strings: Calendar date items. (line 38) +* months, written-out: General date syntax. (line 36) +* MT: General-Purpose Variables. + (line 69) +* MT_BEGIN: Magnetic Tape Control. + (line 11) +* MT_OFFLINE: Magnetic Tape Control. + (line 32) +* MT_REWIND: Magnetic Tape Control. + (line 21) +* MT_STATUS: Magnetic Tape Control. + (line 42) +* Multi-volume archives: Multi-Volume Archives. + (line 6) +* Mutli-volume archives in PAX format, extracting using non-GNU tars: Split Recovery. + (line 17) +* Mutli-volume archives, extracting using non-GNU tars: Split Recovery. + (line 6) +* Naming an archive: file. (line 8) +* negative time stamps: Large or Negative Values. + (line 6) +* next DAY: Day of week items. (line 15) +* next in date strings: General date syntax. (line 26) +* noon in date strings: Time of day items. (line 22) +* now in date strings: Relative items in date strings. + (line 33) +* ntape device: Many. (line 6) +* NUL terminated file names: nul. (line 6) +* Number of blocks per record: Blocking Factor. (line 6) +* Number of bytes per record: Blocking Factor. (line 6) +* numbered backup method: backup. (line 55) +* numbers, written-out: General date syntax. (line 26) +* Obtaining help: help. (line 26) +* Obtaining total status information: verbose. (line 46) +* Old GNU archive format: gnu. (line 6) +* Old GNU sparse format: Old GNU Format. (line 6) +* Old style archives: old. (line 6) +* Old style format: old. (line 6) +* opt-doc-col: Configuring Help Summary. + (line 127) +* option syntax, traditional: Old Options. (line 60) +* Options when reading archives: Reading. (line 6) +* Options, archive format specifying: Format Variations. (line 6) +* Options, format specifying: Format Variations. (line 6) +* ordinal numbers: General date syntax. (line 26) +* Overwriting old files, prevention: Dealing with Old Files. + (line 16) +* pattern, genfile: Generate Mode. (line 39) +* PAX archive format: posix. (line 6) +* Permissions of extracted files: Setting Access Permissions. + (line 6) +* Pinard, F.: Authors of get_date. (line 14) +* pm in date strings: Time of day items. (line 22) +* POSIX archive format: posix. (line 6) +* Progress information: verbose. (line 83) +* Protecting old files: Dealing with Old Files. + (line 26) +* pure numbers in date strings: Pure numbers in date strings. + (line 6) +* Reading file names from a file: files. (line 6) +* Reading incomplete records: Reading. (line 8) +* Record Size: Blocking Factor. (line 6) +* Records, incomplete: Reading. (line 8) +* Recursion in directories, avoiding: recurse. (line 8) +* relative items in date strings: Relative items in date strings. + (line 6) +* Remote devices: file. (line 62) +* remote tape drive: Remote Tape Server. (line 6) +* Removing files from an archive: delete. (line 8) +* Replacing members with other members: append. (line 49) +* reporting bugs: Reports. (line 6) +* RESTORE_BEGIN: User Hooks. (line 39) +* RESTORE_END: User Hooks. (line 42) +* Resurrecting files from an archive: extract. (line 8) +* Retrieving files from an archive: extract. (line 8) +* return status: Synopsis. (line 67) +* rmargin: Configuring Help Summary. + (line 160) +* rmt: Remote Tape Server. (line 6) +* RSH: General-Purpose Variables. + (line 72) +* RSH_COMMAND: General-Purpose Variables. + (line 77) +* Running out of space: Scarce. (line 8) +* Salz, Rich: Authors of get_date. (line 6) +* short-opt-col: Configuring Help Summary. + (line 79) +* simple backup method: backup. (line 64) +* SIMPLE_BACKUP_SUFFIX: backup. (line 68) +* SLEEP_MESSAGE: General-Purpose Variables. + (line 111) +* SLEEP_TIME: General-Purpose Variables. + (line 97) +* Small memory: Scarce. (line 8) +* Sparse Files: sparse. (line 6) +* sparse files v.0.0, extracting with non-GNU tars: Sparse Recovery. + (line 92) +* sparse files v.0.1, extracting with non-GNU tars: Sparse Recovery. + (line 92) +* sparse files v.1.0, extracting with non-GNU tars: Sparse Recovery. + (line 17) +* Sparse files, creating using genfile: Generate Mode. (line 55) +* sparse files, extracting with non-GNU tars: Sparse Recovery. + (line 6) +* sparse formats: Sparse Formats. (line 6) +* sparse formats, defined: sparse. (line 50) +* sparse formats, Old GNU: Old GNU Format. (line 6) +* sparse formats, v.0.0: PAX 0. (line 6) +* sparse formats, v.0.1: PAX 0. (line 52) +* sparse formats, v.1.0: PAX 1. (line 6) +* sparse versions: Sparse Formats. (line 6) +* Specifying archive members: Selecting Archive Members. + (line 6) +* Specifying files to act on: Selecting Archive Members. + (line 6) +* Standard input and output: file. (line 41) +* Standard output, writing extracted files to: Writing to Standard Output. + (line 6) +* Storing archives in compressed format: gzip. (line 6) +* Symbolic link as file name: dereference. (line 6) +* TAPE: file tutorial. (line 14) +* tape blocking: Blocking Factor. (line 194) +* tape marks: Many. (line 44) +* tape positioning: Many. (line 26) +* TAPE_FILE: General-Purpose Variables. + (line 19) +* Tapes, using --delete and: delete. (line 19) +* TAR: General-Purpose Variables. + (line 115) +* tar: What tar Does. (line 6) +* tar archive: Definitions. (line 6) +* Tar archive formats: Formats. (line 6) +* tar entry: Naming tar Archives. (line 11) +* tar file: Naming tar Archives. (line 11) +* tar to a remote device: file. (line 62) +* tar to standard input and output: file. (line 41) +* TAR_ARCHIVE, info script environment variable: Multi-Volume Archives. + (line 100) +* TAR_ATIME, to-command environment: Writing to an External Program. + (line 49) +* TAR_CTIME, to-command environment: Writing to an External Program. + (line 58) +* TAR_FD, info script environment variable: Multi-Volume Archives. + (line 114) +* TAR_FILENAME, to-command environment: Writing to an External Program. + (line 37) +* TAR_FILETYPE, to-command environment: Writing to an External Program. + (line 22) +* TAR_FORMAT, info script environment variable: Multi-Volume Archives. + (line 110) +* TAR_GID, to-command environment: Writing to an External Program. + (line 67) +* TAR_GNAME, to-command environment: Writing to an External Program. + (line 46) +* TAR_MODE, to-command environment: Writing to an External Program. + (line 34) +* TAR_MTIME, to-command environment: Writing to an External Program. + (line 55) +* TAR_OPTIONS, environment variable: using tar options. (line 30) +* TAR_REALNAME, to-command environment: Writing to an External Program. + (line 40) +* TAR_SIZE, to-command environment: Writing to an External Program. + (line 61) +* TAR_SUBCOMMAND, info script environment variable: Multi-Volume Archives. + (line 106) +* TAR_UID, to-command environment: Writing to an External Program. + (line 64) +* TAR_UNAME, to-command environment: Writing to an External Program. + (line 43) +* TAR_VERSION, info script environment variable: Multi-Volume Archives. + (line 97) +* TAR_VOLUME, info script environment variable: Multi-Volume Archives. + (line 103) +* tarcat: Tarcat. (line 6) +* this in date strings: Relative items in date strings. + (line 33) +* time of day item: Time of day items. (line 6) +* time zone correction: Time of day items. (line 30) +* time zone item <1>: Time zone items. (line 6) +* time zone item: General date syntax. (line 44) +* today in date strings: Relative items in date strings. + (line 33) +* tomorrow in date strings: Relative items in date strings. + (line 29) +* TZ: Specifying time zone rules. + (line 6) +* Ultrix 3.1 and write failure: Remote Tape Server. (line 40) +* unpacking: Definitions. (line 22) +* Updating an archive: update. (line 8) +* usage-indent: Configuring Help Summary. + (line 156) +* Using encrypted archives: gzip. (line 113) +* ustar archive format: ustar. (line 6) +* uuencode: Applications. (line 8) +* v7 archive format: old. (line 6) +* Verbose operation: verbose. (line 18) +* Verifying a write operation: verify. (line 6) +* Verifying the currency of an archive: compare. (line 6) +* Version of the tar program: help. (line 6) +* version-control Emacs variable: backup. (line 49) +* VERSION_CONTROL: backup. (line 41) +* volno file: Multi-Volume Archives. + (line 71) +* VOLNO_FILE: General-Purpose Variables. + (line 82) +* Volume label, listing: label. (line 29) +* Volume number file: Multi-Volume Archives. + (line 71) +* week in date strings: Relative items in date strings. + (line 15) +* Where is the archive?: file. (line 8) +* Working directory, specifying: directory. (line 6) +* Writing extracted files to standard output: Writing to Standard Output. + (line 6) +* Writing new archives: file. (line 36) +* XLIST: General-Purpose Variables. + (line 87) +* xsparse: Sparse Recovery. (line 13) +* year in date strings: Relative items in date strings. + (line 15) +* yesterday in date strings: Relative items in date strings. + (line 29) + + |