+++ /dev/null
-This is tar.info, produced by makeinfo version 4.8.90 from tar.texi.
-
- This manual is for GNU `tar' (version 1.20, 14 April 2008), which
-creates and extracts files from archives.
-
- Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
-2004, 2005, 2006, 2007, 2008 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 have the freedom to copy
- and modify this GNU manual. Buying copies from the FSF supports
- it 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
-
-\1f
-File: tar.info, Node: sparse, Prev: gzip, Up: Compression
-
-8.1.2 Archiving Sparse Files
-----------------------------
-
-Files in the file system occasionally have "holes". A "hole" in a file
-is a section of the file's contents which was never written. The
-contents of a hole reads as all zeros. On many operating systems,
-actual disk storage is not allocated for holes, but they are counted in
-the length of the file. If you archive such a file, `tar' could create
-an archive longer than the original. To have `tar' attempt to
-recognize the holes in a file, use `--sparse' (`-S'). When you use
-this option, then, for any file using less disk space than would be
-expected from its length, `tar' searches the file for consecutive
-stretches of zeros. It then records in the archive for the file where
-the consecutive stretches of zeros are, and only archives the "real
-contents" of the file. On extraction (using `--sparse' is not needed
-on extraction) any such files have holes created wherever the
-continuous stretches of zeros were found. Thus, if you use `--sparse',
-`tar' archives won't take more space than the original.
-
-`-S'
-`--sparse'
- This option instructs `tar' to test each file for sparseness
- before attempting to archive it. If the file is found to be
- sparse it is treated specially, thus allowing to decrease the
- amount of space used by its image in the archive.
-
- This option is meaningful only when creating or updating archives.
- It has no effect on extraction.
-
- Consider using `--sparse' when performing file system backups, to
-avoid archiving the expanded forms of files stored sparsely in the
-system.
-
- Even if your system has no sparse files currently, some may be
-created in the future. If you use `--sparse' while making file system
-backups as a matter of course, you can be assured the archive will
-never take more space on the media than the files take on disk
-(otherwise, archiving a disk filled with sparse files might take
-hundreds of tapes). *Note Incremental Dumps::.
-
- However, be aware that `--sparse' option presents a serious
-drawback. Namely, in order to determine if the file is sparse `tar'
-has to read it before trying to archive it, so in total the file is
-read *twice*. So, always bear in mind that the time needed to process
-all files with this option is roughly twice the time needed to archive
-them without it.
-
- When using `POSIX' archive format, GNU `tar' is able to store sparse
-files using in three distinct ways, called "sparse formats". A sparse
-format is identified by its "number", consisting, as usual of two
-decimal numbers, delimited by a dot. By default, format `1.0' is used.
-If, for some reason, you wish to use an earlier format, you can select
-it using `--sparse-version' option.
-
-`--sparse-version=VERSION'
- Select the format to store sparse files in. Valid VERSION values
- are: `0.0', `0.1' and `1.0'. *Note Sparse Formats::, for a
- detailed description of each format.
-
- Using `--sparse-format' option implies `--sparse'.
-
-\1f
-File: tar.info, Node: Attributes, Next: Portability, Prev: Compression, Up: Formats
-
-8.2 Handling File Attributes
-============================
-
- _(This message will disappear, once this node revised.)_
-
-When `tar' reads files, it updates their access times. To avoid this,
-use the `--atime-preserve[=METHOD]' option, which can either reset the
-access time retroactively or avoid changing it in the first place.
-
- Handling of file attributes
-
-`--atime-preserve'
-`--atime-preserve=replace'
-`--atime-preserve=system'
- Preserve the access times of files that are read. This works only
- for files that you own, unless you have superuser privileges.
-
- `--atime-preserve=replace' works on most systems, but it also
- restores the data modification time and updates the status change
- time. Hence it doesn't interact with incremental dumps nicely
- (*note Incremental Dumps::), and it can set access or data
- modification times incorrectly if other programs access the file
- while `tar' is running.
-
- `--atime-preserve=system' avoids changing the access time in the
- first place, if the operating system supports this.
- Unfortunately, this may or may not work on any given operating
- system or file system. If `tar' knows for sure it won't work, it
- complains right away.
-
- Currently `--atime-preserve' with no operand defaults to
- `--atime-preserve=replace', but this is intended to change to
- `--atime-preserve=system' when the latter is better-supported.
-
-`-m'
-`--touch'
- Do not extract data modification time.
-
- When this option is used, `tar' leaves the data modification times
- of the files it extracts as the times when the files were
- extracted, instead of setting it to the times recorded in the
- archive.
-
- This option is meaningless with `--list' (`-t').
-
-`--same-owner'
- Create extracted files with the same ownership they have in the
- archive.
-
- This is the default behavior for the superuser, so this option is
- meaningful only for non-root users, when `tar' is executed on
- those systems able to give files away. This is considered as a
- security flaw by many people, at least because it makes quite
- difficult to correctly account users for the disk space they
- occupy. Also, the `suid' or `sgid' attributes of files are easily
- and silently lost when files are given away.
-
- When writing an archive, `tar' writes the user ID and user name
- separately. If it can't find a user name (because the user ID is
- not in `/etc/passwd'), then it does not write one. When restoring,
- it tries to look the name (if one was written) up in
- `/etc/passwd'. If it fails, then it uses the user ID stored in
- the archive instead.
-
-`--no-same-owner'
-`-o'
- Do not attempt to restore ownership when extracting. This is the
- default behavior for ordinary users, so this option has an effect
- only for the superuser.
-
-`--numeric-owner'
- The `--numeric-owner' option allows (ANSI) archives to be written
- without user/group name information or such information to be
- ignored when extracting. It effectively disables the generation
- and/or use of user/group name information. This option forces
- extraction using the numeric ids from the archive, ignoring the
- names.
-
- This is useful in certain circumstances, when restoring a backup
- from an emergency floppy with different passwd/group files for
- example. It is otherwise impossible to extract files with the
- right ownerships if the password file in use during the extraction
- does not match the one belonging to the file system(s) being
- extracted. This occurs, for example, if you are restoring your
- files after a major crash and had booted from an emergency floppy
- with no password file or put your disk into another machine to do
- the restore.
-
- The numeric ids are _always_ saved into `tar' archives. The
- identifying names are added at create time when provided by the
- system, unless `--old-archive' (`-o') is used. Numeric ids could
- be used when moving archives between a collection of machines using
- a centralized management for attribution of numeric ids to users
- and groups. This is often made through using the NIS capabilities.
-
- When making a `tar' file for distribution to other sites, it is
- sometimes cleaner to use a single owner for all files in the
- distribution, and nicer to specify the write permission bits of the
- files as stored in the archive independently of their actual value
- on the file system. The way to prepare a clean distribution is
- usually to have some Makefile rule creating a directory, copying
- all needed files in that directory, then setting ownership and
- permissions as wanted (there are a lot of possible schemes), and
- only then making a `tar' archive out of this directory, before
- cleaning everything out. Of course, we could add a lot of options
- to GNU `tar' for fine tuning permissions and ownership. This is
- not the good way, I think. GNU `tar' is already crowded with
- options and moreover, the approach just explained gives you a
- great deal of control already.
-
-`-p'
-`--same-permissions'
-`--preserve-permissions'
- Extract all protection information.
-
- This option causes `tar' to set the modes (access permissions) of
- extracted files exactly as recorded in the archive. If this option
- is not used, the current `umask' setting limits the permissions on
- extracted files. This option is by default enabled when `tar' is
- executed by a superuser.
-
- This option is meaningless with `--list' (`-t').
-
-`--preserve'
- Same as both `--same-permissions' and `--same-order'.
-
- The `--preserve' option has no equivalent short option name. It
- is equivalent to `--same-permissions' plus `--same-order'.
-
-
-\1f
-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
-* hard links:: Hard 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
-
-\1f
-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.
-
-\1f
-File: tar.info, Node: dereference, Next: hard links, 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.
-
-\1f
-File: tar.info, Node: hard links, Next: old, Prev: dereference, Up: Portability
-
-8.3.3 Hard Links
-----------------
-
- _(This message will disappear, once this node revised.)_
-
-Normally, when `tar' archives a hard link, it writes a block to the
-archive naming the target of the link (a `1' type block). In that way,
-the actual file contents is stored in file only once. For example,
-consider the following two files:
-
- $ ls
- -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
- -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
-
- Here, `jeden' is a link to `one'. When archiving this directory
-with a verbose level 2, you will get an output similar to the following:
-
- $ tar cfvv ../archive.tar .
- drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
- -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
- hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
-
- The last line shows that, instead of storing two copies of the file,
-`tar' stored it only once, under the name `jeden', and stored file
-`one' as a hard link to this file.
-
- It may be important to know that all hard links to the given file are
-stored in the archive. For example, this may be necessary for exact
-reproduction of the file system. The following option does that:
-
-`--check-links'
-`-l'
- Check the number of links dumped for each processed file. If this
- number does not match the total number of hard links for the file,
- print a warning message.
-
- For example, trying to archive only file `jeden' with this option
-produces the following diagnostics:
-
- $ tar -c -f ../archive.tar jeden
- tar: Missing links to `jeden'.
-
- Although creating special records for hard links helps keep a
-faithful record of the file system contents and makes archives more
-compact, it may present some difficulties when extracting individual
-members from the archive. For example, trying to extract file `one'
-from the archive created in previous examples produces, in the absense
-of file `jeden':
-
- $ tar xf archive.tar ./one
- tar: ./one: Cannot hard link to `./jeden': No such file or directory
- tar: Error exit delayed from previous errors
-
- The reason for this behavior is that `tar' cannot seek back in the
-archive to the previous member (in this case, `one'), to extract it(1).
-If you wish to avoid such problems at the cost of a bigger archive, use
-the following option:
-
-`--hard-dereference'
- Dereference hard links and store the files they refer to.
-
- For example, trying this option on our two sample files, we get two
-copies in the archive, each of which can then be extracted
-independently of the other:
-
- $ tar -c -vv -f ../archive.tar --hard-dereference .
- drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
- -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
- -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one
-
- ---------- Footnotes ----------
-
- (1) There are plans to fix this in future releases.
-
-\1f
-File: tar.info, Node: old, Next: ustar, Prev: hard links, Up: Portability
-
-8.3.4 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.
-
-\1f
-File: tar.info, Node: ustar, Next: gnu, Prev: old, Up: Portability
-
-8.3.5 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').
-
-\1f
-File: tar.info, Node: gnu, Next: posix, Prev: ustar, Up: Portability
-
-8.3.6 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'.
-
-\1f
-File: tar.info, Node: posix, Next: Checksumming, Prev: gnu, Up: Portability
-
-8.3.7 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.
-
-\1f
-File: tar.info, Node: PAX keywords, Up: posix
-
-8.3.7.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.
-
-\1f
-File: tar.info, Node: Checksumming, Next: Large or Negative Values, Prev: posix, Up: Portability
-
-8.3.8 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.
-
-\1f
-File: tar.info, Node: Large or Negative Values, Next: Other Tars, Prev: Checksumming, Up: Portability
-
-8.3.9 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.
-
-\1f
-File: tar.info, Node: Other Tars, Prev: Large or Negative Values, Up: Portability
-
-8.3.10 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
-
-\1f
-File: tar.info, Node: Split Recovery, Next: Sparse Recovery, Up: Other Tars
-
-8.3.10.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.
-
-\1f
-File: tar.info, Node: Sparse Recovery, Prev: Split Recovery, Up: Other Tars
-
-8.3.10.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::).
-
-\1f
-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).
-
-\1f
-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::
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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
-
-\1f
-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
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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
-
-\1f
-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**----------------
-
-\1f
-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.
-
-\1f
-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
-
-\1f
-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_BLOCKING_FACTOR'
- Current blocking factor (*note Blocking::.
-
-`TAR_VOLUME'
- Ordinal number of the volume `tar' is about to start.
-
-`TAR_SUBCOMMAND'
- A 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 can 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
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.20 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.
-
-\1f
-File: tar.info, Node: Configuring Help Summary, Next: Fixing Snapshot Files, 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.
-
-\1f
-File: tar.info, Node: Fixing Snapshot Files, Next: Tar Internals, Prev: Configuring Help Summary, Up: Top
-
-Appendix C Fixing Snapshot Files
-********************************
-
-Sometimes device numbers can change after upgrading your kernel version
-or recofiguring the harvare. Reportedly this is the case with some
-newer Linux kernels, when using LVM. In majority of cases this change
-is unnoticed by the users. However, it influences `tar' incremental
-backups: the device number is stored in tar snapshot files (*note
-Snapshot Files::) and is used to determine whether the file has changed
-since the last backup. If the device numbers change for some reason,
-the next backup you run will be a full backup.
-
- To minimize the impact in these cases, GNU `tar' comes with the
-`tar-snapshot-edit' utility for inspecting and updating device numbers
-in snapshot files. The utility, written by Dustin J. Mitchell, is
-available from GNU `tar' home page
-(http://www.gnu.org/software/tar/utils/tar-snapshot-edit.html).
-
- To obtain the device numbers used in the snapshot file, run
-
- $ tar-snapshot-edit SNAPFILE
-
-where SNAPFILE is the name of the snapshot file (you can supply as many
-files as you wish in a single command line ).
-
- To update all occurrences of the given device number in the file, use
-`-r' option. It takes a single argument of the form `OLDDEV-NEWDEV',
-where OLDDEV is the device number used in the snapshot file, and NEWDEV
-is the corresponding new device number. Both numbers may be specified
-in hex (e.g., `0xfe01'), decimal (e.g., `65025'), or as a major:minor
-number pair (e.g., `254:1'). To change several device numbers at once,
-specify them in a single comma-separated list, as in `-r
-0x3060-0x4500,0x307-0x4600'.
-
- Before updating the snapshot file, it is a good idea to create a
-backup copy of it. This is accomplished by `-b' option. The name of
-the backup file is obtained by appending `~' to the original file name.
-
- An example session:
- $ tar-snapshot-edit /var/backup/snap.a
- file version 2
- /tmp/snap: Device 0x0306 occurs 634 times.
- $ tar-snapshot-edit -b -r 0x0306-0x4500 /var/backup/snap.a
- file version 2
-
-\1f
-File: tar.info, Node: Tar Internals, Next: Genfile, Prev: Fixing Snapshot Files, Up: Top
-
-Appendix D Tar Internals
-************************
-
-* Menu:
-
-* Standard:: Basic Tar Format
-* Extensions:: GNU Extensions to the Archive Format
-* Sparse Formats:: Storing Sparse Files
-* Snapshot Files::
-* Dumpdir::
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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
-
-\1f
-File: tar.info, Node: Old GNU Format, Next: PAX 0, Up: Sparse Formats
-
-D.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.
-
-\1f
-File: tar.info, Node: PAX 0, Next: PAX 1, Prev: Old GNU Format, Up: Sparse Formats
-
-D.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.
-
-\1f
-File: tar.info, Node: PAX 1, Prev: PAX 0, Up: Sparse Formats
-
-D.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'.
-
-\1f
-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.20 supports three 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. It was used by version 1.15.1. Starting from
-version 1.16 and up to 1.20, the "format 2" is used.
-
- GNU `tar' is able to read all three formats, but will create
-snapshots only in format 2.
-
- This appendix describes all three formats in detail.
-
- 0. `Format 0' snapshot file begins with a line containing a decimal
- number that represents a 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:
-
- NFSDEV INODE NAME
-
- where:
-
- NFS
- A single plus character (`+'), if this directory is located on
- an NFS-mounted partition, or a single space otherwise;
-
- DEV
- Device number of the directory;
-
- INODE
- I-node number of the directory;
-
- NAME
- Name of the directory. Any special characters (white-space,
- backslashes, etc.) are quoted.
-
- 1. `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 number of GNU `tar'
- implementation that created this snapshot, and INCR-FORMAT-VERSION
- is the version number of the snapshot format (in this case `1').
-
- Next 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.
-
- Lines that follow contain directory metadata, one line per
- directory. Each line is formatted as follows:
-
- [NFS]MTIME-SEC MTIME-NSEC DEV INODE NAME
-
- where MTIME-SEC and MTIME-NSEC represent last modification time of
- this directory with nanosecond precision; NFS, DEV, INODE and NAME
- have the same meaning as with `format 0'.
-
- 2. A snapshot file begins with a format identifier, as described
- for version 1, e.g.:
-
- GNU tar-1.20-2
-
- This line is followed by newline. Rest of file consists of
- records, separated by null (ASCII 0) characters. Thus, in contrast
- to the previous formats, format 2 snapshot is a binary file.
-
- First two records are 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. These are followed by arbitrary number of directory
- records.
-
- Each "directory record" contains a set of metadata describing a
- particular directory. Parts of a directory record are delimited
- with ASCII 0 characters. The following table describes each part.
- The "Number" type in this table stands for a decimal number in
- ASCII notation.
-
- Field Type Description
- ---------------------------------------------------------------------
- nfs Character `1' if the directory is located on an
- NFS-mounted partition, or `0' otherwise;
- mtime-sec Number Modification time, seconds;
- mtime-nano Number Modification time, nanoseconds;
- dev-no Number Device number;
- i-no Number I-node number;
- name String Directory name; In contrast to the
- previous versions it is not quoted.
- contents Dumpdir Contents of the directory; *Note
- Dumpdir::, for a description of its
- format.
-
-
- Dumpdirs stored in snapshot files contain only records of types
- `Y', `N' and `D'.
-
-
-\1f
-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 `T' command, that immediately follows it.
-
-`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 the existing directory. To correctly
-process it, GNU `tar' needs a temporary directory, so it creates 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.
-
-\1f
-File: tar.info, Node: Genfile, Next: Free Software Needs Free Documentation, Prev: Tar Internals, Up: Top
-
-Appendix E 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.
-
-\1f
-File: tar.info, Node: Generate Mode, Next: Status Mode, Up: Genfile
-
-E.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.
-
-\1f
-File: tar.info, Node: Status Mode, Next: Exec Mode, Prev: Generate Mode, Up: Genfile
-
-E.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 *
-
-\1f
-File: tar.info, Node: Exec Mode, Prev: Status Mode, Up: Genfile
-
-E.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.
-
-\1f
-File: tar.info, Node: Free Software Needs Free Documentation, Next: Copying This Manual, Prev: Genfile, Up: Top
-
-Appendix F 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'.
-
-\1f
-File: tar.info, Node: Copying This Manual, Next: Index of Command Line Options, Prev: Free Software Needs Free Documentation, Up: Top
-
-Appendix G Copying This Manual
-******************************
-
-* Menu:
-
-* GNU Free Documentation License:: License for copying this manual
-
-\1f
-File: tar.info, Node: GNU Free Documentation License, Up: Copying This Manual
-
-G.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.
-
-G.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.
-
-\1f
-File: tar.info, Node: Index of Command Line Options, Next: Index, Prev: Copying This Manual, Up: Top
-
-Appendix H 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::.
-
-\0\b[index\0\b]
-* 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)
-* auto-compress: gzip. (line 69)
-* auto-compress, summary: Option Summary. (line 65)
-* backup: backup. (line 41)
-* backup, summary: Option Summary. (line 70)
-* block-number: verbose. (line 115)
-* block-number, summary: Option Summary. (line 75)
-* blocking-factor: Blocking Factor. (line 8)
-* blocking-factor, summary: Option Summary. (line 81)
-* bzip2: gzip. (line 122)
-* bzip2, summary: Option Summary. (line 86)
-* catenate: concatenate. (line 6)
-* catenate, summary: Operation Summary. (line 10)
-* check-device, described: Incremental Dumps. (line 99)
-* check-device, summary: Option Summary. (line 91)
-* check-links, described: hard links. (line 33)
-* check-links, summary: Option Summary. (line 142)
-* checkpoint: checkpoints. (line 6)
-* checkpoint, defined: checkpoints. (line 13)
-* checkpoint, summary: Option Summary. (line 96)
-* checkpoint-action: checkpoints. (line 6)
-* checkpoint-action, defined: checkpoints. (line 22)
-* checkpoint-action, summary: Option Summary. (line 104)
-* compare: compare. (line 8)
-* compare, summary: Operation Summary. (line 14)
-* compress: gzip. (line 129)
-* compress, summary: Option Summary. (line 151)
-* concatenate: concatenate. (line 6)
-* concatenate, summary: Operation Summary. (line 20)
-* confirmation, summary: Option Summary. (line 158)
-* 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 161)
-* delete: delete. (line 8)
-* delete, summary: Operation Summary. (line 29)
-* dereference: dereference. (line 6)
-* dereference, summary: Option Summary. (line 166)
-* diff, summary: Operation Summary. (line 33)
-* directory: directory. (line 11)
-* directory, summary: Option Summary. (line 172)
-* 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 179)
-* exclude-caches: exclude. (line 80)
-* exclude-caches, summary: Option Summary. (line 188)
-* exclude-caches-all: exclude. (line 88)
-* exclude-caches-all, summary: Option Summary. (line 201)
-* exclude-caches-under: exclude. (line 84)
-* exclude-caches-under, summary: Option Summary. (line 195)
-* exclude-from: exclude. (line 22)
-* exclude-from, summary: Option Summary. (line 183)
-* exclude-tag: exclude. (line 97)
-* exclude-tag, summary: Option Summary. (line 205)
-* exclude-tag-all: exclude. (line 105)
-* exclude-tag-all, summary: Option Summary. (line 213)
-* exclude-tag-under: exclude. (line 101)
-* exclude-tag-under, summary: Option Summary. (line 209)
-* exclude-vcs: exclude. (line 39)
-* exclude-vcs, summary: Option Summary. (line 217)
-* 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 112)
-* file, short description: file. (line 17)
-* file, summary: Option Summary. (line 223)
-* file, tutorial: file tutorial. (line 6)
-* files-from: files. (line 14)
-* files-from, summary: Option Summary. (line 229)
-* force-local, short description: Device. (line 70)
-* force-local, summary: Option Summary. (line 235)
-* format, summary: Option Summary. (line 240)
-* get, summary: Operation Summary. (line 42)
-* group: override. (line 73)
-* group, summary: Option Summary. (line 265)
-* gunzip, summary: Option Summary. (line 273)
-* gzip: gzip. (line 88)
-* gzip, summary: Option Summary. (line 273)
-* hard-dereference, described: hard links. (line 61)
-* hard-dereference, summary: Option Summary. (line 281)
-* help: help tutorial. (line 6)
-* help, introduction: help. (line 26)
-* help, summary: Option Summary. (line 287)
-* ignore-case: controlling pattern-matching.
- (line 86)
-* ignore-case, summary: Option Summary. (line 292)
-* ignore-command-error: Writing to an External Program.
- (line 82)
-* ignore-command-error, summary: Option Summary. (line 296)
-* ignore-failed-read: Ignore Failed Read. (line 7)
-* ignore-failed-read, summary: Option Summary. (line 300)
-* ignore-zeros: Ignore Zeros. (line 6)
-* ignore-zeros, short description: Blocking Factor. (line 156)
-* ignore-zeros, summary: Option Summary. (line 304)
-* incremental, summary: Option Summary. (line 309)
-* incremental, using with --list: Incremental Dumps. (line 177)
-* index-file, summary: Option Summary. (line 316)
-* info-script: Multi-Volume Archives.
- (line 80)
-* info-script, short description: Device. (line 104)
-* info-script, summary: Option Summary. (line 319)
-* interactive: interactive. (line 14)
-* interactive, summary: Option Summary. (line 327)
-* keep-newer-files: Keep Newer Files. (line 6)
-* keep-newer-files, summary: Option Summary. (line 334)
-* 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 338)
-* label: label. (line 8)
-* label, summary: Option Summary. (line 343)
-* list: list. (line 6)
-* list, summary: Operation Summary. (line 46)
-* list, using with --incremental: Incremental Dumps. (line 177)
-* list, using with --listed-incremental: Incremental Dumps. (line 177)
-* 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 350)
-* listed-incremental, using with --extract: Incremental Dumps.
- (line 112)
-* listed-incremental, using with --list: Incremental Dumps. (line 177)
-* lzma: gzip. (line 126)
-* lzma, summary: Option Summary. (line 358)
-* mode: override. (line 14)
-* mode, summary: Option Summary. (line 362)
-* mtime: override. (line 29)
-* mtime, summary: Option Summary. (line 368)
-* multi-volume: Multi-Volume Archives.
- (line 6)
-* multi-volume, short description: Device. (line 88)
-* multi-volume, summary: Option Summary. (line 377)
-* new-volume-script: Multi-Volume Archives.
- (line 80)
-* new-volume-script, short description: Device. (line 104)
-* new-volume-script, summary: Option Summary. (line 319)
-* newer: after. (line 26)
-* newer, summary: Option Summary. (line 385)
-* newer-mtime: after. (line 37)
-* newer-mtime, summary: Option Summary. (line 393)
-* no-anchored: controlling pattern-matching.
- (line 79)
-* no-anchored, summary: Option Summary. (line 398)
-* no-check-device, described: Incremental Dumps. (line 95)
-* no-check-device, summary: Option Summary. (line 402)
-* no-delay-directory-restore: Directory Modification Times and Permissions.
- (line 68)
-* no-delay-directory-restore, summary: Option Summary. (line 407)
-* no-ignore-case: controlling pattern-matching.
- (line 86)
-* no-ignore-case, summary: Option Summary. (line 413)
-* no-ignore-command-error: Writing to an External Program.
- (line 87)
-* no-ignore-command-error, summary: Option Summary. (line 416)
-* no-overwrite-dir, summary: Option Summary. (line 420)
-* no-quote-chars, summary: Option Summary. (line 424)
-* no-recursion: recurse. (line 13)
-* no-recursion, summary: Option Summary. (line 429)
-* no-same-owner: Attributes. (line 67)
-* no-same-owner, summary: Option Summary. (line 433)
-* no-same-permissions, summary: Option Summary. (line 439)
-* no-unquote: Selecting Archive Members.
- (line 42)
-* no-unquote, summary: Option Summary. (line 444)
-* no-wildcards: controlling pattern-matching.
- (line 41)
-* no-wildcards, summary: Option Summary. (line 448)
-* no-wildcards-match-slash: controlling pattern-matching.
- (line 92)
-* no-wildcards-match-slash, summary: Option Summary. (line 451)
-* null: nul. (line 11)
-* null, summary: Option Summary. (line 454)
-* numeric-owner: Attributes. (line 73)
-* numeric-owner, summary: Option Summary. (line 460)
-* occurrence, summary: Option Summary. (line 477)
-* old-archive, summary: Option Summary. (line 491)
-* one-file-system: one. (line 16)
-* one-file-system, summary: Option Summary. (line 494)
-* overwrite: Overwrite Old Files. (line 6)
-* overwrite, introduced: Dealing with Old Files.
- (line 22)
-* overwrite, summary: Option Summary. (line 499)
-* overwrite-dir: Overwrite Old Files. (line 28)
-* overwrite-dir, introduced: Dealing with Old Files.
- (line 6)
-* overwrite-dir, summary: Option Summary. (line 503)
-* owner: override. (line 57)
-* owner, summary: Option Summary. (line 507)
-* pax-option: PAX keywords. (line 6)
-* pax-option, summary: Option Summary. (line 516)
-* portability, summary: Option Summary. (line 522)
-* posix, summary: Option Summary. (line 526)
-* preserve: Attributes. (line 126)
-* preserve, summary: Option Summary. (line 529)
-* preserve-order: Same Order. (line 6)
-* preserve-order, summary: Option Summary. (line 533)
-* preserve-permissions: Setting Access Permissions.
- (line 10)
-* preserve-permissions, short description: Attributes. (line 113)
-* preserve-permissions, summary: Option Summary. (line 536)
-* quote-chars, summary: Option Summary. (line 546)
-* quoting-style: quoting styles. (line 39)
-* quoting-style, summary: Option Summary. (line 550)
-* 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 557)
-* record-size, summary: Option Summary. (line 562)
-* recursion: recurse. (line 24)
-* recursion, summary: Option Summary. (line 566)
-* recursive-unlink: Recursive Unlink. (line 6)
-* recursive-unlink, summary: Option Summary. (line 570)
-* remove-files: remove files. (line 6)
-* remove-files, summary: Option Summary. (line 575)
-* restrict, summary: Option Summary. (line 579)
-* rmt-command, summary: Option Summary. (line 584)
-* rsh-command: Device. (line 73)
-* rsh-command, summary: Option Summary. (line 588)
-* same-order: Same Order. (line 6)
-* same-order, summary: Option Summary. (line 592)
-* same-owner: Attributes. (line 48)
-* same-owner, summary: Option Summary. (line 600)
-* same-permissions: Setting Access Permissions.
- (line 10)
-* same-permissions, short description: Attributes. (line 113)
-* same-permissions, summary: Option Summary. (line 536)
-* seek, summary: Option Summary. (line 609)
-* show-defaults: defaults. (line 6)
-* show-defaults, summary: Option Summary. (line 616)
-* show-omitted-dirs: verbose. (line 107)
-* show-omitted-dirs, summary: Option Summary. (line 625)
-* show-stored-names: list. (line 60)
-* show-stored-names, summary: Option Summary. (line 629)
-* show-transformed-names: transform. (line 45)
-* show-transformed-names, summary: Option Summary. (line 629)
-* sparse: sparse. (line 22)
-* sparse, summary: Option Summary. (line 637)
-* sparse-version: sparse. (line 57)
-* sparse-version, summary: Option Summary. (line 642)
-* starting-file: Starting File. (line 6)
-* starting-file, summary: Option Summary. (line 647)
-* strip-components: transform. (line 25)
-* strip-components, summary: Option Summary. (line 653)
-* suffix: backup. (line 68)
-* suffix, summary: Option Summary. (line 662)
-* tape-length: Multi-Volume Archives.
- (line 33)
-* tape-length, short description: Device. (line 96)
-* tape-length, summary: Option Summary. (line 668)
-* test-label: label. (line 37)
-* test-label, summary: Option Summary. (line 673)
-* to-command: Writing to an External Program.
- (line 9)
-* to-command, summary: Option Summary. (line 677)
-* to-stdout: Writing to Standard Output.
- (line 14)
-* to-stdout, summary: Option Summary. (line 681)
-* totals: verbose. (line 46)
-* totals, summary: Option Summary. (line 686)
-* touch <1>: Attributes. (line 37)
-* touch: Data Modification Times.
- (line 15)
-* touch, summary: Option Summary. (line 691)
-* transform: transform. (line 74)
-* transform, summary: Option Summary. (line 697)
-* uncompress: gzip. (line 129)
-* uncompress, summary: Option Summary. (line 151)
-* ungzip: gzip. (line 88)
-* ungzip, summary: Option Summary. (line 273)
-* unlink-first: Unlink First. (line 6)
-* unlink-first, introduced: Dealing with Old Files.
- (line 42)
-* unlink-first, summary: Option Summary. (line 716)
-* unquote: Selecting Archive Members.
- (line 39)
-* unquote, summary: Option Summary. (line 722)
-* update: update. (line 8)
-* update, summary: Operation Summary. (line 50)
-* usage: help. (line 53)
-* use-compress-program: gzip. (line 134)
-* use-compress-program, summary: Option Summary. (line 726)
-* utc, summary: Option Summary. (line 730)
-* verbose: verbose. (line 18)
-* verbose, introduced: verbose tutorial. (line 6)
-* verbose, summary: Option Summary. (line 734)
-* 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 741)
-* verify, using with --create: verify. (line 24)
-* version: help. (line 6)
-* version, summary: Option Summary. (line 746)
-* volno-file: Multi-Volume Archives.
- (line 71)
-* volno-file, summary: Option Summary. (line 751)
-* wildcards: controlling pattern-matching.
- (line 38)
-* wildcards, summary: Option Summary. (line 756)
-* wildcards-match-slash: controlling pattern-matching.
- (line 92)
-* wildcards-match-slash, summary: Option Summary. (line 760)
-
-\1f
-File: tar.info, Node: Index, Prev: Index of Command Line Options, Up: Top
-
-Appendix I Index
-****************
-
-\0\b[index\0\b]
-* 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)
-* bell, checkpoint action: checkpoints. (line 65)
-* 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 115)
-* 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)
-* checkpoints, defined: checkpoints. (line 6)
-* 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 107)
-* corrupted archives: Full Dumps. (line 8)
-* Creation of the archive: create. (line 8)
-* CVS, excluding files: exclude. (line 39)
-* 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)
-* dereferencing hard links: hard links. (line 8)
-* Descending directories, avoiding: recurse. (line 8)
-* Device numbers, changing: Fixing Snapshot Files.
- (line 6)
-* Device numbers, using in incremental backups: Incremental Dumps.
- (line 81)
-* 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)
-* dot, checkpoint action: checkpoints. (line 80)
-* 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)
-* echo, checkpoint action: checkpoints. (line 25)
-* 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 125)
-* Exabyte blocking: Blocking Factor. (line 204)
-* exclude: exclude. (line 14)
-* exclude-caches: exclude. (line 68)
-* exclude-from: exclude. (line 27)
-* exclude-tag: exclude. (line 91)
-* 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)
-* exec, checkpoint action: checkpoints. (line 96)
-* 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 hard links: hard links. (line 8)
-* 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 0, snapshot file: Snapshot Files. (line 23)
-* format 1, snapshot file: Snapshot Files. (line 47)
-* format 2, snapshot file: Snapshot Files. (line 69)
-* 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)
-* git, excluding files: exclude. (line 39)
-* 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 146)
-* gpg, using with tar: gzip. (line 146)
-* hard links, dereferencing: hard links. (line 8)
-* 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)
-* RCS, excluding files: exclude. (line 39)
-* 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)
-* SCCS, excluding files: exclude. (line 39)
-* short-opt-col: Configuring Help Summary.
- (line 79)
-* simple backup method: backup. (line 64)
-* SIMPLE_BACKUP_SUFFIX: backup. (line 68)
-* sleep, checkpoint action: checkpoints. (line 90)
-* SLEEP_MESSAGE: General-Purpose Variables.
- (line 111)
-* SLEEP_TIME: General-Purpose Variables.
- (line 97)
-* Small memory: Scarce. (line 8)
-* snapshot file, format 0: Snapshot Files. (line 23)
-* snapshot file, format 1: Snapshot Files. (line 47)
-* snapshot file, format 2: Snapshot Files. (line 69)
-* snapshot files, editing: Fixing Snapshot Files.
- (line 6)
-* snapshot files, fixing device numbers: Fixing Snapshot Files.
- (line 6)
-* 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)
-* SVN, excluding files: exclude. (line 39)
-* 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-snapshot-edit: Fixing Snapshot Files.
- (line 15)
-* TAR_ARCHIVE, checkpoint script environment: checkpoints. (line 108)
-* TAR_ARCHIVE, info script environment variable: Multi-Volume Archives.
- (line 100)
-* TAR_ATIME, to-command environment: Writing to an External Program.
- (line 49)
-* TAR_BLOCKING_FACTOR, checkpoint script environment: checkpoints.
- (line 111)
-* TAR_BLOCKING_FACTOR, info script environment variable: Multi-Volume Archives.
- (line 103)
-* TAR_CHECKPOINT, checkpoint script environment: checkpoints. (line 114)
-* TAR_CTIME, to-command environment: Writing to an External Program.
- (line 58)
-* TAR_FD, info script environment variable: Multi-Volume Archives.
- (line 117)
-* 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, checkpoint script environment: checkpoints. (line 121)
-* TAR_FORMAT, info script environment variable: Multi-Volume Archives.
- (line 113)
-* 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, checkpoint script environment: checkpoints. (line 117)
-* TAR_SUBCOMMAND, info script environment variable: Multi-Volume Archives.
- (line 109)
-* 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, checkpoint script environment: checkpoints. (line 105)
-* TAR_VERSION, info script environment variable: Multi-Volume Archives.
- (line 97)
-* TAR_VOLUME, info script environment variable: Multi-Volume Archives.
- (line 106)
-* 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)
-* ttyout, checkpoint action: checkpoints. (line 70)
-* 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 146)
-* ustar archive format: ustar. (line 6)
-* uuencode: Applications. (line 8)
-* v7 archive format: old. (line 6)
-* VCS, excluding files: exclude. (line 39)
-* Verbose operation: verbose. (line 18)
-* Verifying a write operation: verify. (line 6)
-* Verifying the currency of an archive: compare. (line 6)
-* version control system, excluding files: exclude. (line 39)
-* 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)
-
-
projects / tar / blobdiff