X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=doc%2Ftar.info-2;fp=doc%2Ftar.info-2;h=0000000000000000000000000000000000000000;hb=5c46f61cabb7912f25347b9300d1d585d7a635cb;hp=bd7e2b377081f2160dfe8a46aa414a60e093c59f;hpb=138fc7e67e3d9845cd7d81aad0e9c7724784f9b9;p=tar diff --git a/doc/tar.info-2 b/doc/tar.info-2 deleted file mode 100644 index bd7e2b3..0000000 --- a/doc/tar.info-2 +++ /dev/null @@ -1,5226 +0,0 @@ -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 - - -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'. - - -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'. - - - -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 - - -File: tar.info, Node: Portable Names, Next: dereference, Up: Portability - -8.3.1 Portable Names --------------------- - -Use portable file and member names. A name is portable if it contains -only ASCII letters and digits, `/', `.', `_', and `-'; it cannot be -empty, start with `-' or `//', or contain `/-'. Avoid deep directory -nesting. For portability to old Unix hosts, limit your file name -components to 14 characters or less. - - If you intend to have your `tar' archives to be read under MSDOS, -you should not rely on case distinction for file names, and you might -use the GNU `doschk' program for helping you further diagnosing illegal -MSDOS names, which are even more limited than System V's. - - -File: tar.info, Node: dereference, Next: 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. - - -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. - - -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. - - -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'). - - -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'. - - -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. - - -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. - - -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. - - -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. - - -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 - - -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. - - -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::). - - -File: tar.info, Node: cpio, Prev: Portability, Up: Formats - -8.4 Comparison of `tar' and `cpio' -================================== - - _(This message will disappear, once this node revised.)_ - -The `cpio' archive formats, like `tar', do have maximum file name -lengths. The binary and old ASCII formats have a maximum file length -of 256, and the new ASCII and CRC ASCII formats have a max file length -of 1024. GNU `cpio' can read and write archives with arbitrary file -name lengths, but other `cpio' implementations may crash unexplainedly -trying to read them. - - `tar' handles symbolic links in the form in which it comes in BSD; -`cpio' doesn't handle symbolic links in the form in which it comes in -System V prior to SVR4, and some vendors may have added symlinks to -their system without enhancing `cpio' to know about them. Others may -have enhanced it in a way other than the way I did it at Sun, and which -was adopted by AT&T (and which is, I think, also present in the `cpio' -that Berkeley picked up from AT&T and put into a later BSD release--I -think I gave them my changes). - - (SVR4 does some funny stuff with `tar'; basically, its `cpio' can -handle `tar' format input, and write it on output, and it probably -handles symbolic links. They may not have bothered doing anything to -enhance `tar' as a result.) - - `cpio' handles special files; traditional `tar' doesn't. - - `tar' comes with V7, System III, System V, and BSD source; `cpio' -comes only with System III, System V, and later BSD (4.3-tahoe and -later). - - `tar''s way of handling multiple hard links to a file can handle -file systems that support 32-bit inumbers (e.g., the BSD file system); -`cpio's way requires you to play some games (in its "binary" format, -i-numbers are only 16 bits, and in its "portable ASCII" format, they're -18 bits--it would have to play games with the "file system ID" field of -the header to make sure that the file system ID/i-number pairs of -different files were always different), and I don't know which `cpio's, -if any, play those games. Those that don't might get confused and -think two files are the same file when they're not, and make hard links -between them. - - `tar's way of handling multiple hard links to a file places only one -copy of the link on the tape, but the name attached to that copy is the -_only_ one you can use to retrieve the file; `cpio's way puts one copy -for every link, but you can retrieve it using any of the names. - - What type of check sum (if any) is used, and how is this - calculated. - - See the attached manual pages for `tar' and `cpio' format. `tar' -uses a checksum which is the sum of all the bytes in the `tar' header -for a file; `cpio' uses no checksum. - - If anyone knows why `cpio' was made when `tar' was present at the - unix scene, - - It wasn't. `cpio' first showed up in PWB/UNIX 1.0; no -generally-available version of UNIX had `tar' at the time. I don't -know whether any version that was generally available _within AT&T_ had -`tar', or, if so, whether the people within AT&T who did `cpio' knew -about it. - - On restore, if there is a corruption on a tape `tar' will stop at -that point, while `cpio' will skip over it and try to restore the rest -of the files. - - The main difference is just in the command syntax and header format. - - `tar' is a little more tape-oriented in that everything is blocked -to start on a record boundary. - - Is there any differences between the ability to recover crashed - archives between the two of them. (Is there any chance of - recovering crashed archives at all.) - - Theoretically it should be easier under `tar' since the blocking -lets you find a header with some variation of `dd skip=NN'. However, -modern `cpio''s and variations have an option to just search for the -next file header after an error with a reasonable chance of resyncing. -However, lots of tape driver software won't allow you to continue past -a media error which should be the only reason for getting out of sync -unless a file changed sizes while you were writing the archive. - - If anyone knows why `cpio' was made when `tar' was present at the - unix scene, please tell me about this too. - - Probably because it is more media efficient (by not blocking -everything and using only the space needed for the headers where `tar' -always uses 512 bytes per file header) and it knows how to archive -special files. - - You might want to look at the freely available alternatives. The -major ones are `afio', GNU `tar', and `pax', each of which have their -own extensions with some backwards compatibility. - - Sparse files were `tar'red as sparse files (which you can easily -test, because the resulting archive gets smaller, and GNU `cpio' can no -longer read it). - - -File: tar.info, Node: Media, Next: Changes, Prev: Formats, Up: Top - -9 Tapes and Other Archive Media -******************************* - - _(This message will disappear, once this node revised.)_ - -A few special cases about tape handling warrant more detailed -description. These special cases are discussed below. - - Many complexities surround the use of `tar' on tape drives. Since -the creation and manipulation of archives located on magnetic tape was -the original purpose of `tar', it contains many features making such -manipulation easier. - - Archives are usually written on dismountable media--tape cartridges, -mag tapes, or floppy disks. - - The amount of data a tape or disk holds depends not only on its size, -but also on how it is formatted. A 2400 foot long reel of mag tape -holds 40 megabytes of data when formatted at 1600 bits per inch. The -physically smaller EXABYTE tape cartridge holds 2.3 gigabytes. - - Magnetic media are re-usable--once the archive on a tape is no longer -needed, the archive can be erased and the tape or disk used over. -Media quality does deteriorate with use, however. Most tapes or disks -should be discarded when they begin to produce data errors. EXABYTE -tape cartridges should be discarded when they generate an "error count" -(number of non-usable bits) of more than 10k. - - Magnetic media are written and erased using magnetic fields, and -should be protected from such fields to avoid damage to stored data. -Sticking a floppy disk to a filing cabinet using a magnet is probably -not a good idea. - -* Menu: - -* Device:: Device selection and switching -* Remote Tape Server:: -* Common Problems and Solutions:: -* Blocking:: Blocking -* Many:: Many archives on one tape -* Using Multiple Tapes:: Using Multiple Tapes -* label:: Including a Label in the Archive -* verify:: -* Write Protection:: - - -File: tar.info, Node: Device, Next: Remote Tape Server, Up: Media - -9.1 Device Selection and Switching -================================== - - _(This message will disappear, once this node revised.)_ - -`-f [HOSTNAME:]FILE' -`--file=[HOSTNAME:]FILE' - Use archive file or device FILE on HOSTNAME. - - This option is used to specify the file name of the archive `tar' -works on. - - If the file name is `-', `tar' reads the archive from standard input -(when listing or extracting), or writes it to standard output (when -creating). If the `-' file name is given when updating an archive, -`tar' will read the original archive from its standard input, and will -write the entire new archive to its standard output. - - If the file name contains a `:', it is interpreted as `hostname:file -name'. If the HOSTNAME contains an "at" sign (`@'), it is treated as -`user@hostname:file name'. In either case, `tar' will invoke the -command `rsh' (or `remsh') to start up an `/usr/libexec/rmt' on the -remote machine. If you give an alternate login name, it will be given -to the `rsh'. Naturally, the remote machine must have an executable -`/usr/libexec/rmt'. This program is free software from the University -of California, and a copy of the source code can be found with the -sources for `tar'; it's compiled and installed by default. The exact -path to this utility is determined when configuring the package. It is -`PREFIX/libexec/rmt', where PREFIX stands for your installation prefix. -This location may also be overridden at runtime by using -`rmt-command=COMMAND' option (*Note --rmt-command: Option Summary, for -detailed description of this option. *Note Remote Tape Server::, for -the description of `rmt' command). - - If this option is not given, but the environment variable `TAPE' is -set, its value is used; otherwise, old versions of `tar' used a default -archive name (which was picked when `tar' was compiled). The default -is normally set up to be the "first" tape drive or other transportable -I/O medium on the system. - - Starting with version 1.11.5, GNU `tar' uses standard input and -standard output as the default device, and I will not try anymore -supporting automatic device detection at installation time. This was -failing really in too many cases, it was hopeless. This is now -completely left to the installer to override standard input and -standard output for default device, if this seems preferable. Further, -I think _most_ actual usages of `tar' are done with pipes or disks, not -really tapes, cartridges or diskettes. - - Some users think that using standard input and output is running -after trouble. This could lead to a nasty surprise on your screen if -you forget to specify an output file name--especially if you are going -through a network or terminal server capable of buffering large amounts -of output. We had so many bug reports in that area of configuring -default tapes automatically, and so many contradicting requests, that -we finally consider the problem to be portably intractable. We could -of course use something like `/dev/tape' as a default, but this is -_also_ running after various kind of trouble, going from hung processes -to accidental destruction of real tapes. After having seen all this -mess, using standard input and output as a default really sounds like -the only clean choice left, and a very useful one too. - - GNU `tar' reads and writes archive in records, I suspect this is the -main reason why block devices are preferred over character devices. -Most probably, block devices are more efficient too. The installer -could also check for `DEFTAPE' in `'. - -`--force-local' - Archive file is local even if it contains a colon. - -`--rsh-command=COMMAND' - Use remote COMMAND instead of `rsh'. This option exists so that - people who use something other than the standard `rsh' (e.g., a - Kerberized `rsh') can access a remote device. - - When this command is not used, the shell command found when the - `tar' program was installed is used instead. This is the first - found of `/usr/ucb/rsh', `/usr/bin/remsh', `/usr/bin/rsh', - `/usr/bsd/rsh' or `/usr/bin/nsh'. The installer may have - overridden this by defining the environment variable `RSH' _at - installation time_. - -`-[0-7][lmh]' - Specify drive and density. - -`-M' -`--multi-volume' - Create/list/extract multi-volume archive. - - This option causes `tar' to write a "multi-volume" archive--one - that may be larger than will fit on the medium used to hold it. - *Note Multi-Volume Archives::. - -`-L NUM' -`--tape-length=NUM' - Change tape after writing NUM x 1024 bytes. - - This option might be useful when your tape drivers do not properly - detect end of physical tapes. By being slightly conservative on - the maximum tape length, you might avoid the problem entirely. - -`-F FILE' -`--info-script=FILE' -`--new-volume-script=FILE' - Execute `file' at end of each tape. This implies `--multi-volume' - (`-M'). *Note info-script::, for a detailed description of this - option. - - -File: tar.info, Node: Remote Tape Server, Next: Common Problems and Solutions, Prev: Device, Up: Media - -9.2 The Remote Tape Server -========================== - -In order to access the tape drive on a remote machine, `tar' uses the -remote tape server written at the University of California at Berkeley. -The remote tape server must be installed as `PREFIX/libexec/rmt' on -any machine whose tape drive you want to use. `tar' calls `rmt' by -running an `rsh' or `remsh' to the remote machine, optionally using a -different login name if one is supplied. - - A copy of the source for the remote tape server is provided. It is -Copyright (C) 1983 by the Regents of the University of California, but -can be freely distributed. It is compiled and installed by default. - - Unless you use the `--absolute-names' (`-P') option, GNU `tar' will -not allow you to create an archive that contains absolute file names (a -file name beginning with `/'.) If you try, `tar' will automatically -remove the leading `/' from the file names it stores in the archive. -It will also type a warning message telling you what it is doing. - - When reading an archive that was created with a different `tar' -program, GNU `tar' automatically extracts entries in the archive which -have absolute file names as if the file names were not absolute. This -is an important feature. A visitor here once gave a `tar' tape to an -operator to restore; the operator used Sun `tar' instead of GNU `tar', -and the result was that it replaced large portions of our `/bin' and -friends with versions from the tape; needless to say, we were unhappy -about having to recover the file system from backup tapes. - - For example, if the archive contained a file `/usr/bin/computoy', -GNU `tar' would extract the file to `usr/bin/computoy', relative to the -current directory. If you want to extract the files in an archive to -the same absolute names that they had when the archive was created, you -should do a `cd /' before extracting the files from the archive, or you -should either use the `--absolute-names' option, or use the command -`tar -C / ...'. - - Some versions of Unix (Ultrix 3.1 is known to have this problem), -can claim that a short write near the end of a tape succeeded, when it -actually failed. This will result in the -M option not working -correctly. The best workaround at the moment is to use a significantly -larger blocking factor than the default 20. - - In order to update an archive, `tar' must be able to backspace the -archive in order to reread or rewrite a record that was just read (or -written). This is currently possible only on two kinds of files: normal -disk files (or any other file that can be backspaced with `lseek'), and -industry-standard 9-track magnetic tape (or any other kind of tape that -can be backspaced with the `MTIOCTOP' `ioctl'. - - This means that the `--append', `--concatenate', and `--delete' -commands will not work on any other kind of file. Some media simply -cannot be backspaced, which means these commands and options will never -be able to work on them. These non-backspacing media include pipes and -cartridge tape drives. - - Some other media can be backspaced, and `tar' will work on them once -`tar' is modified to do so. - - Archives created with the `--multi-volume', `--label', and -`--incremental' (`-G') options may not be readable by other version of -`tar'. In particular, restoring a file that was split over a volume -boundary will require some careful work with `dd', if it can be done at -all. Other versions of `tar' may also create an empty file whose name -is that of the volume header. Some versions of `tar' may create normal -files instead of directories archived with the `--incremental' (`-G') -option. - - -File: tar.info, Node: Common Problems and Solutions, Next: Blocking, Prev: Remote Tape Server, Up: Media - -9.3 Some Common Problems and their Solutions -============================================ - -errors from system: -permission denied -no such file or directory -not owner - -errors from `tar': -directory checksum error -header format error - -errors from media/system: -i/o error -device busy - - -File: tar.info, Node: Blocking, Next: Many, Prev: Common Problems and Solutions, Up: Media - -9.4 Blocking -============ - - _(This message will disappear, once this node revised.)_ - -"Block" and "record" terminology is rather confused, and it is also -confusing to the expert reader. On the other hand, readers who are new -to the field have a fresh mind, and they may safely skip the next two -paragraphs, as the remainder of this manual uses those two terms in a -quite consistent way. - - John Gilmore, the writer of the public domain `tar' from which GNU -`tar' was originally derived, wrote (June 1995): - - The nomenclature of tape drives comes from IBM, where I believe - they were invented for the IBM 650 or so. On IBM mainframes, what - is recorded on tape are tape blocks. The logical organization of - data is into records. There are various ways of putting records - into blocks, including `F' (fixed sized records), `V' (variable - sized records), `FB' (fixed blocked: fixed size records, N to a - block), `VB' (variable size records, N to a block), `VSB' - (variable spanned blocked: variable sized records that can occupy - more than one block), etc. The `JCL' `DD RECFORM=' parameter - specified this to the operating system. - - The Unix man page on `tar' was totally confused about this. When - I wrote `PD TAR', I used the historically correct terminology - (`tar' writes data records, which are grouped into blocks). It - appears that the bogus terminology made it into POSIX (no surprise - here), and now Franc,ois has migrated that terminology back into - the source code too. - - The term "physical block" means the basic transfer chunk from or to -a device, after which reading or writing may stop without anything -being lost. In this manual, the term "block" usually refers to a disk -physical block, _assuming_ that each disk block is 512 bytes in length. -It is true that some disk devices have different physical blocks, but -`tar' ignore these differences in its own format, which is meant to be -portable, so a `tar' block is always 512 bytes in length, and "block" -always mean a `tar' block. The term "logical block" often represents -the basic chunk of allocation of many disk blocks as a single entity, -which the operating system treats somewhat atomically; this concept is -only barely used in GNU `tar'. - - The term "physical record" is another way to speak of a physical -block, those two terms are somewhat interchangeable. In this manual, -the term "record" usually refers to a tape physical block, _assuming_ -that the `tar' archive is kept on magnetic tape. It is true that -archives may be put on disk or used with pipes, but nevertheless, `tar' -tries to read and write the archive one "record" at a time, whatever -the medium in use. One record is made up of an integral number of -blocks, and this operation of putting many disk blocks into a single -tape block is called "reblocking", or more simply, "blocking". The -term "logical record" refers to the logical organization of many -characters into something meaningful to the application. The term -"unit record" describes a small set of characters which are transmitted -whole to or by the application, and often refers to a line of text. -Those two last terms are unrelated to what we call a "record" in GNU -`tar'. - - When writing to tapes, `tar' writes the contents of the archive in -chunks known as "records". To change the default blocking factor, use -the `--blocking-factor=512-SIZE' (`-b 512-SIZE') option. Each record -will then be composed of 512-SIZE blocks. (Each `tar' block is 512 -bytes. *Note Standard::.) Each file written to the archive uses at -least one full record. As a result, using a larger record size can -result in more wasted space for small files. On the other hand, a -larger record size can often be read and written much more efficiently. - - Further complicating the problem is that some tape drives ignore the -blocking entirely. For these, a larger record size can still improve -performance (because the software layers above the tape drive still -honor the blocking), but not as dramatically as on tape drives that -honor blocking. - - When reading an archive, `tar' can usually figure out the record -size on itself. When this is the case, and a non-standard record size -was used when the archive was created, `tar' will print a message about -a non-standard blocking factor, and then operate normally. On some -tape devices, however, `tar' cannot figure out the record size itself. -On most of those, you can specify a blocking factor (with -`--blocking-factor') larger than the actual blocking factor, and then -use the `--read-full-records' (`-B') option. (If you specify a -blocking factor with `--blocking-factor' and don't use the -`--read-full-records' option, then `tar' will not attempt to figure out -the recording size itself.) On some devices, you must always specify -the record size exactly with `--blocking-factor' when reading, because -`tar' cannot figure it out. In any case, use `--list' (`-t') before -doing any extractions to see whether `tar' is reading the archive -correctly. - - `tar' blocks are all fixed size (512 bytes), and its scheme for -putting them into records is to put a whole number of them (one or -more) into each record. `tar' records are all the same size; at the -end of the file there's a block containing all zeros, which is how you -tell that the remainder of the last record(s) are garbage. - - In a standard `tar' file (no options), the block size is 512 and the -record size is 10240, for a blocking factor of 20. What the -`--blocking-factor' option does is sets the blocking factor, changing -the record size while leaving the block size at 512 bytes. 20 was fine -for ancient 800 or 1600 bpi reel-to-reel tape drives; most tape drives -these days prefer much bigger records in order to stream and not waste -tape. When writing tapes for myself, some tend to use a factor of the -order of 2048, say, giving a record size of around one megabyte. - - If you use a blocking factor larger than 20, older `tar' programs -might not be able to read the archive, so we recommend this as a limit -to use in practice. GNU `tar', however, will support arbitrarily large -record sizes, limited only by the amount of virtual memory or the -physical characteristics of the tape device. - -* Menu: - -* Format Variations:: Format Variations -* Blocking Factor:: The Blocking Factor of an Archive - - -File: tar.info, Node: Format Variations, Next: Blocking Factor, Up: Blocking - -9.4.1 Format Variations ------------------------ - - _(This message will disappear, once this node revised.)_ - -Format parameters specify how an archive is written on the archive -media. The best choice of format parameters will vary depending on the -type and number of files being archived, and on the media used to store -the archive. - - To specify format parameters when accessing or creating an archive, -you can use the options described in the following sections. If you do -not specify any format parameters, `tar' uses default parameters. You -cannot modify a compressed archive. If you create an archive with the -`--blocking-factor' option specified (*note Blocking Factor::), you -must specify that blocking-factor when operating on the archive. *Note -Formats::, for other examples of format parameter considerations. - - -File: tar.info, Node: Blocking Factor, Prev: Format Variations, Up: Blocking - -9.4.2 The Blocking Factor of an Archive ---------------------------------------- - - _(This message will disappear, once this node revised.)_ - -The data in an archive is grouped into blocks, which are 512 bytes. -Blocks are read and written in whole number multiples called "records". -The number of blocks in a record (i.e., the size of a record in units -of 512 bytes) is called the "blocking factor". The -`--blocking-factor=512-SIZE' (`-b 512-SIZE') option specifies the -blocking factor of an archive. The default blocking factor is -typically 20 (i.e., 10240 bytes), but can be specified at installation. -To find out the blocking factor of an existing archive, use `tar ---list --file=ARCHIVE-NAME'. This may not work on some devices. - - Records are separated by gaps, which waste space on the archive -media. If you are archiving on magnetic tape, using a larger blocking -factor (and therefore larger records) provides faster throughput and -allows you to fit more data on a tape (because there are fewer gaps). -If you are archiving on cartridge, a very large blocking factor (say -126 or more) greatly increases performance. A smaller blocking factor, -on the other hand, may be useful when archiving small files, to avoid -archiving lots of nulls as `tar' fills out the archive to the end of -the record. In general, the ideal record size depends on the size of -the inter-record gaps on the tape you are using, and the average size -of the files you are archiving. *Note create::, for information on -writing archives. - - Archives with blocking factors larger than 20 cannot be read by very -old versions of `tar', or by some newer versions of `tar' running on -old machines with small address spaces. With GNU `tar', the blocking -factor of an archive is limited only by the maximum record size of the -device containing the archive, or by the amount of available virtual -memory. - - Also, on some systems, not using adequate blocking factors, as -sometimes imposed by the device drivers, may yield unexpected -diagnostics. For example, this has been reported: - - Cannot write to /dev/dlt: Invalid argument - -In such cases, it sometimes happen that the `tar' bundled by the system -is aware of block size idiosyncrasies, while GNU `tar' requires an -explicit specification for the block size, which it cannot guess. This -yields some people to consider GNU `tar' is misbehaving, because by -comparison, `the bundle `tar' works OK'. Adding `-b 256', for example, -might resolve the problem. - - If you use a non-default blocking factor when you create an archive, -you must specify the same blocking factor when you modify that archive. -Some archive devices will also require you to specify the blocking -factor when reading that archive, however this is not typically the -case. Usually, you can use `--list' (`-t') without specifying a -blocking factor--`tar' reports a non-default record size and then lists -the archive members as it would normally. To extract files from an -archive with a non-standard blocking factor (particularly if you're not -sure what the blocking factor is), you can usually use the -`--read-full-records' (`-B') option while specifying a blocking factor -larger then the blocking factor of the archive (i.e., `tar --extract ---read-full-records --blocking-factor=300'. *Note list::, for more -information on the `--list' (`-t') operation. *Note Reading::, for a -more detailed explanation of that option. - -`--blocking-factor=NUMBER' -`-b NUMBER' - Specifies the blocking factor of an archive. Can be used with any - operation, but is usually not necessary with `--list' (`-t'). - - Device blocking - -`-b BLOCKS' -`--blocking-factor=BLOCKS' - Set record size to BLOCKS * 512 bytes. - - This option is used to specify a "blocking factor" for the archive. - When reading or writing the archive, `tar', will do reads and - writes of the archive in records of BLOCK*512 bytes. This is true - even when the archive is compressed. Some devices requires that - all write operations be a multiple of a certain size, and so, `tar' - pads the archive out to the next record boundary. - - The default blocking factor is set when `tar' is compiled, and is - typically 20. Blocking factors larger than 20 cannot be read by - very old versions of `tar', or by some newer versions of `tar' - running on old machines with small address spaces. - - With a magnetic tape, larger records give faster throughput and fit - more data on a tape (because there are fewer inter-record gaps). - If the archive is in a disk file or a pipe, you may want to specify - a smaller blocking factor, since a large one will result in a large - number of null bytes at the end of the archive. - - When writing cartridge or other streaming tapes, a much larger - blocking factor (say 126 or more) will greatly increase - performance. However, you must specify the same blocking factor - when reading or updating the archive. - - Apparently, Exabyte drives have a physical block size of 8K bytes. - If we choose our blocksize as a multiple of 8k bytes, then the - problem seems to disappear. Id est, we are using block size of - 112 right now, and we haven't had the problem since we switched... - - With GNU `tar' the blocking factor is limited only by the maximum - record size of the device containing the archive, or by the amount - of available virtual memory. - - However, deblocking or reblocking is virtually avoided in a special - case which often occurs in practice, but which requires all the - following conditions to be simultaneously true: - * the archive is subject to a compression option, - - * the archive is not handled through standard input or output, - nor redirected nor piped, - - * the archive is directly handled to a local disk, instead of - any special device, - - * `--blocking-factor' is not explicitly specified on the `tar' - invocation. - - If the output goes directly to a local disk, and not through - stdout, then the last write is not extended to a full record size. - Otherwise, reblocking occurs. Here are a few other remarks on this - topic: - - * `gzip' will complain about trailing garbage if asked to - uncompress a compressed archive on tape, there is an option - to turn the message off, but it breaks the regularity of - simply having to use `PROG -d' for decompression. It would - be nice if gzip was silently ignoring any number of trailing - zeros. I'll ask Jean-loup Gailly, by sending a copy of this - message to him. - - * `compress' does not show this problem, but as Jean-loup - pointed out to Michael, `compress -d' silently adds garbage - after the result of decompression, which tar ignores because - it already recognized its end-of-file indicator. So this bug - may be safely ignored. - - * `gzip -d -q' will be silent about the trailing zeros indeed, - but will still return an exit status of 2 which tar reports - in turn. `tar' might ignore the exit status returned, but I - hate doing that, as it weakens the protection `tar' offers - users against other possible problems at decompression time. - If `gzip' was silently skipping trailing zeros _and_ also - avoiding setting the exit status in this innocuous case, that - would solve this situation. - - * `tar' should become more solid at not stopping to read a pipe - at the first null block encountered. This inelegantly breaks - the pipe. `tar' should rather drain the pipe out before - exiting itself. - -`-i' -`--ignore-zeros' - Ignore blocks of zeros in archive (means EOF). - - The `--ignore-zeros' (`-i') option causes `tar' to ignore blocks - of zeros in the archive. Normally a block of zeros indicates the - end of the archive, but when reading a damaged archive, or one - which was created by concatenating several archives together, this - option allows `tar' to read the entire archive. This option is - not on by default because many versions of `tar' write garbage - after the zeroed blocks. - - Note that this option causes `tar' to read to the end of the - archive file, which may sometimes avoid problems when multiple - files are stored on a single physical tape. - -`-B' -`--read-full-records' - Reblock as we read (for reading 4.2BSD pipes). - - If `--read-full-records' is used, `tar' will not panic if an - attempt to read a record from the archive does not return a full - record. Instead, `tar' will keep reading until it has obtained a - full record. - - This option is turned on by default when `tar' is reading an - archive from standard input, or from a remote machine. This is - because on BSD Unix systems, a read of a pipe will return however - much happens to be in the pipe, even if it is less than `tar' - requested. If this option was not used, `tar' would fail as soon - as it read an incomplete record from the pipe. - - This option is also useful with the commands for updating an - archive. - - - Tape blocking - - When handling various tapes or cartridges, you have to take care of -selecting a proper blocking, that is, the number of disk blocks you put -together as a single tape block on the tape, without intervening tape -gaps. A "tape gap" is a small landing area on the tape with no -information on it, used for decelerating the tape to a full stop, and -for later regaining the reading or writing speed. When the tape driver -starts reading a record, the record has to be read whole without -stopping, as a tape gap is needed to stop the tape motion without -loosing information. - - Using higher blocking (putting more disk blocks per tape block) will -use the tape more efficiently as there will be less tape gaps. But -reading such tapes may be more difficult for the system, as more memory -will be required to receive at once the whole record. Further, if -there is a reading error on a huge record, this is less likely that the -system will succeed in recovering the information. So, blocking should -not be too low, nor it should be too high. `tar' uses by default a -blocking of 20 for historical reasons, and it does not really matter -when reading or writing to disk. Current tape technology would easily -accommodate higher blockings. Sun recommends a blocking of 126 for -Exabytes and 96 for DATs. We were told that for some DLT drives, the -blocking should be a multiple of 4Kb, preferably 64Kb (`-b 128') or 256 -for decent performance. Other manufacturers may use different -recommendations for the same tapes. This might also depends of the -buffering techniques used inside modern tape controllers. Some imposes -a minimum blocking, or a maximum blocking. Others request blocking to -be some exponent of two. - - So, there is no fixed rule for blocking. But blocking at read time -should ideally be the same as blocking used at write time. At one place -I know, with a wide variety of equipment, they found it best to use a -blocking of 32 to guarantee that their tapes are fully interchangeable. - - I was also told that, for recycled tapes, prior erasure (by the same -drive unit that will be used to create the archives) sometimes lowers -the error rates observed at rewriting time. - - I might also use `--number-blocks' instead of `--block-number', so -`--block' will then expand to `--blocking-factor' unambiguously. - - -File: tar.info, Node: Many, Next: Using Multiple Tapes, Prev: Blocking, Up: Media - -9.5 Many Archives on One Tape -============================= - -Most tape devices have two entries in the `/dev' directory, or entries -that come in pairs, which differ only in the minor number for this -device. Let's take for example `/dev/tape', which often points to the -only or usual tape device of a given system. There might be a -corresponding `/dev/nrtape' or `/dev/ntape'. The simpler name is the -_rewinding_ version of the device, while the name having `nr' in it is -the _no rewinding_ version of the same device. - - A rewinding tape device will bring back the tape to its beginning -point automatically when this device is opened or closed. Since `tar' -opens the archive file before using it and closes it afterwards, this -means that a simple: - - $ tar cf /dev/tape DIRECTORY - -will reposition the tape to its beginning both prior and after saving -DIRECTORY contents to it, thus erasing prior tape contents and making -it so that any subsequent write operation will destroy what has just -been saved. - - So, a rewinding device is normally meant to hold one and only one -file. If you want to put more than one `tar' archive on a given tape, -you will need to avoid using the rewinding version of the tape device. -You will also have to pay special attention to tape positioning. -Errors in positioning may overwrite the valuable data already on your -tape. Many people, burnt by past experiences, will only use rewinding -devices and limit themselves to one file per tape, precisely to avoid -the risk of such errors. Be fully aware that writing at the wrong -position on a tape loses all information past this point and most -probably until the end of the tape, and this destroyed information -_cannot_ be recovered. - - To save DIRECTORY-1 as a first archive at the beginning of a tape, -and leave that tape ready for a second archive, you should use: - - $ mt -f /dev/nrtape rewind - $ tar cf /dev/nrtape DIRECTORY-1 - - "Tape marks" are special magnetic patterns written on the tape -media, which are later recognizable by the reading hardware. These -marks are used after each file, when there are many on a single tape. -An empty file (that is to say, two tape marks in a row) signal the -logical end of the tape, after which no file exist. Usually, -non-rewinding tape device drivers will react to the close request issued -by `tar' by first writing two tape marks after your archive, and by -backspacing over one of these. So, if you remove the tape at that time -from the tape drive, it is properly terminated. But if you write -another file at the current position, the second tape mark will be -erased by the new information, leaving only one tape mark between files. - - So, you may now save DIRECTORY-2 as a second archive after the first -on the same tape by issuing the command: - - $ tar cf /dev/nrtape DIRECTORY-2 - -and so on for all the archives you want to put on the same tape. - - Another usual case is that you do not write all the archives the same -day, and you need to remove and store the tape between two archive -sessions. In general, you must remember how many files are already -saved on your tape. Suppose your tape already has 16 files on it, and -that you are ready to write the 17th. You have to take care of skipping -the first 16 tape marks before saving DIRECTORY-17, say, by using these -commands: - - $ mt -f /dev/nrtape rewind - $ mt -f /dev/nrtape fsf 16 - $ tar cf /dev/nrtape DIRECTORY-17 - - In all the previous examples, we put aside blocking considerations, -but you should do the proper things for that as well. *Note Blocking::. - -* Menu: - -* Tape Positioning:: Tape Positions and Tape Marks -* mt:: The `mt' Utility - - -File: tar.info, Node: Tape Positioning, Next: mt, Up: Many - -9.5.1 Tape Positions and Tape Marks ------------------------------------ - - _(This message will disappear, once this node revised.)_ - -Just as archives can store more than one file from the file system, -tapes can store more than one archive file. To keep track of where -archive files (or any other type of file stored on tape) begin and end, -tape archive devices write magnetic "tape marks" on the archive media. -Tape drives write one tape mark between files, two at the end of all -the file entries. - - If you think of data as a series of records "rrrr"'s, and tape marks -as "*"'s, a tape might look like the following: - - rrrr*rrrrrr*rrrrr*rr*rrrrr**------------------------- - - Tape devices read and write tapes using a read/write "tape head"--a -physical part of the device which can only access one point on the tape -at a time. When you use `tar' to read or write archive data from a -tape device, the device will begin reading or writing from wherever on -the tape the tape head happens to be, regardless of which archive or -what part of the archive the tape head is on. Before writing an -archive, you should make sure that no data on the tape will be -overwritten (unless it is no longer needed). Before reading an -archive, you should make sure the tape head is at the beginning of the -archive you want to read. You can do it manually via `mt' utility -(*note mt::). The `restore' script does that automatically (*note -Scripted Restoration::). - - If you want to add new archive file entries to a tape, you should -advance the tape to the end of the existing file entries, backspace -over the last tape mark, and write the new archive file. If you were -to add two archives to the example above, the tape might look like the -following: - - rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- - - -File: tar.info, Node: mt, Prev: Tape Positioning, Up: Many - -9.5.2 The `mt' Utility ----------------------- - - _(This message will disappear, once this node revised.)_ - -*Note Blocking Factor::. - - You can use the `mt' utility to advance or rewind a tape past a -specified number of archive files on the tape. This will allow you to -move to the beginning of an archive before extracting or reading it, or -to the end of all the archives before writing a new one. - - The syntax of the `mt' command is: - - mt [-f TAPENAME] OPERATION [NUMBER] - - where TAPENAME is the name of the tape device, NUMBER is the number -of times an operation is performed (with a default of one), and -OPERATION is one of the following: - -`eof' -`weof' - Writes NUMBER tape marks at the current position on the tape. - -`fsf' - Moves tape position forward NUMBER files. - -`bsf' - Moves tape position back NUMBER files. - -`rewind' - Rewinds the tape. (Ignores NUMBER). - -`offline' -`rewoff1' - Rewinds the tape and takes the tape device off-line. (Ignores - NUMBER). - -`status' - Prints status information about the tape unit. - - - If you don't specify a TAPENAME, `mt' uses the environment variable -`TAPE'; if `TAPE' is not set, `mt' will use the default device -specified in your `sys/mtio.h' file (`DEFTAPE' variable). If this is -not defined, the program will display a descriptive error message and -exit with code 1. - - `mt' returns a 0 exit status when the operation(s) were successful, -1 if the command was unrecognized, and 2 if an operation failed. - - -File: tar.info, Node: Using Multiple Tapes, Next: label, Prev: Many, Up: Media - -9.6 Using Multiple Tapes -======================== - -Often you might want to write a large archive, one larger than will fit -on the actual tape you are using. In such a case, you can run multiple -`tar' commands, but this can be inconvenient, particularly if you are -using options like `--exclude=PATTERN' or dumping entire file systems. -Therefore, `tar' provides a special mode for creating multi-volume -archives. - - "Multi-volume" archive is a single `tar' archive, stored on several -media volumes of fixed size. Although in this section we will often -call `volume' a "tape", there is absolutely no requirement for -multi-volume archives to be stored on tapes. Instead, they can use -whatever media type the user finds convenient, they can even be located -on files. - - When creating a multi-volume archive, GNU `tar' continues to fill -current volume until it runs out of space, then it switches to next -volume (usually the operator is queried to replace the tape on this -point), and continues working on the new volume. This operation -continues until all requested files are dumped. If GNU `tar' detects -end of media while dumping a file, such a file is archived in split -form. Some very big files can even be split across several volumes. - - Each volume is itself a valid GNU `tar' archive, so it can be read -without any special options. Consequently any file member residing -entirely on one volume can be extracted or otherwise operated upon -without needing the other volume. Sure enough, to extract a split -member you would need all volumes its parts reside on. - - Multi-volume archives suffer from several limitations. In -particular, they cannot be compressed. - - GNU `tar' is able to create multi-volume archives of two formats -(*note Formats::): `GNU' and `POSIX'. - -* Menu: - -* Multi-Volume Archives:: Archives Longer than One Tape or Disk -* Tape Files:: Tape Files -* Tarcat:: Concatenate Volumes into a Single Archive - - -File: tar.info, Node: Multi-Volume Archives, Next: Tape Files, Up: Using Multiple Tapes - -9.6.1 Archives Longer than One Tape or Disk -------------------------------------------- - -To create an archive that is larger than will fit on a single unit of -the media, use the `--multi-volume' (`-M') option in conjunction with -the `--create' option (*note create::). A "multi-volume" archive can -be manipulated like any other archive (provided the `--multi-volume' -option is specified), but is stored on more than one tape or disk. - - When you specify `--multi-volume', `tar' does not report an error -when it comes to the end of an archive volume (when reading), or the -end of the media (when writing). Instead, it prompts you to load a new -storage volume. If the archive is on a magnetic tape, you should -change tapes when you see the prompt; if the archive is on a floppy -disk, you should change disks; etc. - -`--multi-volume' -`-M' - Creates a multi-volume archive, when used in conjunction with - `--create' (`-c'). To perform any other operation on a - multi-volume archive, specify `--multi-volume' in conjunction with - that operation. For example: - - $ tar --create --multi-volume --file=/dev/tape FILES - - The method `tar' uses to detect end of tape is not perfect, and -fails on some operating systems or on some devices. If `tar' cannot -detect the end of the tape itself, you can use `--tape-length' option -to inform it about the capacity of the tape: - -`--tape-length=SIZE' -`-L SIZE' - Set maximum length of a volume. The SIZE argument should then be - the usable size of the tape in units of 1024 bytes. This option - selects `--multi-volume' automatically. For example: - - $ tar --create --tape-length=41943040 --file=/dev/tape FILES - - When GNU `tar' comes to the end of a storage media, it asks you to -change the volume. The built-in prompt for POSIX locale is(1): - - Prepare volume #N for `ARCHIVE' and hit return: - -where N is the ordinal number of the volume to be created and ARCHIVE -is archive file or device name. - - When prompting for a new tape, `tar' accepts any of the following -responses: - -`?' - Request `tar' to explain possible responses - -`q' - Request `tar' to exit immediately. - -`n FILE-NAME' - Request `tar' to write the next volume on the file FILE-NAME. - -`!' - Request `tar' to run a subshell. This option can be disabled by - giving `--restrict' command line option to `tar'(2). - -`y' - Request `tar' to begin writing the next volume. - - (You should only type `y' after you have changed the tape; otherwise -`tar' will write over the volume it just finished.) - - The volume number used by `tar' in its tape-changing prompt can be -changed; if you give the `--volno-file=FILE-OF-NUMBER' option, then -FILE-OF-NUMBER should be an non-existing file to be created, or else, a -file already containing a decimal number. That number will be used as -the volume number of the first volume written. When `tar' is finished, -it will rewrite the file with the now-current volume number. (This does -not change the volume number written on a tape label, as per *note -label::, it _only_ affects the number used in the prompt.) - - If you want more elaborate behavior than this, you can write a -special "new volume script", that will be responsible for changing the -volume, and instruct `tar' to use it instead of its normal prompting -procedure: - -`--info-script=SCRIPT-NAME' -`--new-volume-script=SCRIPT-NAME' -`-F SCRIPT-NAME' - Specify the full name of the volume script to use. The script can - be used to eject cassettes, or to broadcast messages such as - `Someone please come change my tape' when performing unattended - backups. - - The SCRIPT-NAME is executed without any command line arguments. It -inherits `tar''s shell environment. Additional data is passed to it -via the following environment variables: - -`TAR_VERSION' - GNU `tar' version number. - -`TAR_ARCHIVE' - The name of the archive `tar' is processing. - -`TAR_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 - - -File: tar.info, Node: Tape Files, Next: Tarcat, Prev: Multi-Volume Archives, Up: Using Multiple Tapes - -9.6.2 Tape Files ----------------- - - _(This message will disappear, once this node revised.)_ - -To give the archive a name which will be recorded in it, use the -`--label=VOLUME-LABEL' (`-V VOLUME-LABEL') option. This will write a -special block identifying VOLUME-LABEL as the name of the archive to -the front of the archive which will be displayed when the archive is -listed with `--list'. If you are creating a multi-volume archive with -`--multi-volume' (*note Using Multiple Tapes::), then the volume label -will have `Volume NNN' appended to the name you give, where NNN is the -number of the volume of the archive. (If you use the -`--label=VOLUME-LABEL') option when reading an archive, it checks to -make sure the label on the tape matches the one you give. *Note label::. - - When `tar' writes an archive to tape, it creates a single tape file. -If multiple archives are written to the same tape, one after the -other, they each get written as separate tape files. When extracting, -it is necessary to position the tape at the right place before running -`tar'. To do this, use the `mt' command. For more information on the -`mt' command and on the organization of tapes into a sequence of tape -files, see *note mt::. - - People seem to often do: - - --label="SOME-PREFIX `date +SOME-FORMAT`" - - or such, for pushing a common date in all volumes or an archive set. - - -File: tar.info, Node: Tarcat, Prev: Tape Files, Up: Using Multiple Tapes - -9.6.3 Concatenate Volumes into a Single Archive ------------------------------------------------ - -Sometimes it is necessary to convert existing GNU `tar' multi-volume -archive to a single `tar' archive. Simply concatenating all volumes -into one will not work, since each volume carries an additional -information at the beginning. GNU `tar' is shipped with the shell -script `tarcat' designed for this purpose. - - The script takes a list of files comprising a multi-volume archive -and creates the resulting archive at the standard output. For example: - - tarcat vol.1 vol.2 vol.3 | tar tf - - - The script implements a simple heuristics to determine the format of -the first volume file and to decide how to process the rest of the -files. However, it makes no attempt to verify whether the files are -given in order or even if they are valid `tar' archives. It uses `dd' -and does not filter its standard error, so you will usually see lots of -spurious messages. - - -File: tar.info, Node: label, Next: verify, Prev: Using Multiple Tapes, Up: Media - -9.7 Including a Label in the Archive -==================================== - - _(This message will disappear, once this node revised.)_ - -To avoid problems caused by misplaced paper labels on the archive -media, you can include a "label" entry--an archive member which -contains the name of the archive--in the archive itself. Use the -`--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') option in conjunction with -the `--create' operation to include a label entry in the archive as it -is being created. - -`--label=ARCHIVE-LABEL' -`-V ARCHIVE-LABEL' - Includes an "archive-label" at the beginning of the archive when - the archive is being created, when used in conjunction with the - `--create' operation. Checks to make sure the archive label - matches the one specified (when used in conjunction with any other - operation. - - If you create an archive using both `--label=ARCHIVE-LABEL' (`-V -ARCHIVE-LABEL') and `--multi-volume' (`-M'), each volume of the archive -will have an archive label of the form `ARCHIVE-LABEL Volume N', where -N is 1 for the first volume, 2 for the next, and so on. *Note Using -Multiple Tapes::, for information on creating multiple volume archives. - - The volume label will be displayed by `--list' along with the file -contents. If verbose display is requested, it will also be explicitly -marked as in the example below: - - $ tar --verbose --list --file=iamanarchive - V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header-- - -rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename - - However, `--list' option will cause listing entire contents of the -archive, which may be undesirable (for example, if the archive is -stored on a tape). You can request checking only the volume by -specifying `--test-label' option. This option reads only the first -block of an archive, so it can be used with slow storage devices. For -example: - - $ tar --test-label --file=iamanarchive - iamalabel - - If `--test-label' is used with a single command line argument, `tar' -compares the volume label with the argument. It exits with code 0 if -the two strings match, and with code 2 otherwise. In this case no -output is displayed. For example: - - $ tar --test-label --file=iamanarchive 'iamalable' - => 0 - $ tar --test-label --file=iamanarchive 'iamalable' alabel - => 1 - - If you request any operation, other than `--create', along with -using `--label' option, `tar' will first check if the archive label -matches the one specified and will refuse to proceed if it does not. -Use this as a safety precaution to avoid accidentally overwriting -existing archives. For example, if you wish to add files to `archive', -presumably labeled with string `My volume', you will get: - - $ tar -rf archive --label 'My volume' . - tar: Archive not labeled to match `My volume' - -in case its label does not match. This will work even if `archive' is -not labeled at all. - - Similarly, `tar' will refuse to list or extract the archive if its -label doesn't match the ARCHIVE-LABEL specified. In those cases, -ARCHIVE-LABEL argument is interpreted as a globbing-style pattern which -must match the actual magnetic volume label. *Note exclude::, for a -precise description of how match is attempted(1). If the switch -`--multi-volume' (`-M') is being used, the volume label matcher will -also suffix ARCHIVE-LABEL by ` Volume [1-9]*' if the initial match -fails, before giving up. Since the volume numbering is automatically -added in labels at creation time, it sounded logical to equally help -the user taking care of it when the archive is being read. - - The `--label' was once called `--volume', but is not available under -that name anymore. - - You can also use `--label' to get a common information on all tapes -of a series. For having this information different in each series -created through a single script used on a regular basis, just manage to -get some date string as part of the label. For example: - - $ tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`" - $ tar --create --file=/dev/tape --multi-volume \ - --volume="Daily backup for `date +%Y-%m-%d`" - - Also note that each label has its own date and time, which -corresponds to when GNU `tar' initially attempted to write it, often -soon after the operator launches `tar' or types the carriage return -telling that the next tape is ready. Comparing date labels does give -an idea of tape throughput only if the delays for rewinding tapes and -the operator switching them were negligible, which is usually not the -case. - - ---------- Footnotes ---------- - - (1) Previous versions of `tar' used full regular expression -matching, or before that, only exact string matching, instead of -wildcard matchers. We decided for the sake of simplicity to use a -uniform matching device through `tar'. - - -File: tar.info, Node: verify, Next: Write Protection, Prev: label, Up: Media - -9.8 Verifying Data as It is Stored -================================== - -`-W' -`--verify' - Attempt to verify the archive after writing. - - This option causes `tar' to verify the archive after writing it. -Each volume is checked after it is written, and any discrepancies are -recorded on the standard error output. - - Verification requires that the archive be on a back-space-able -medium. This means pipes, some cartridge tape drives, and some other -devices cannot be verified. - - You can insure the accuracy of an archive by comparing files in the -system with archive members. `tar' can compare an archive to the file -system as the archive is being written, to verify a write operation, or -can compare a previously written archive, to insure that it is up to -date. - - To check for discrepancies in an archive immediately after it is -written, use the `--verify' (`-W') option in conjunction with the -`--create' operation. When this option is specified, `tar' checks -archive members against their counterparts in the file system, and -reports discrepancies on the standard error. - - To verify an archive, you must be able to read it from before the end -of the last written entry. This option is useful for detecting data -errors on some tapes. Archives written to pipes, some cartridge tape -drives, and some other devices cannot be verified. - - One can explicitly compare an already made archive with the file -system by using the `--compare' (`--diff', `-d') option, instead of -using the more automatic `--verify' option. *Note compare::. - - Note that these two options have a slightly different intent. The -`--compare' option checks how identical are the logical contents of some -archive with what is on your disks, while the `--verify' option is -really for checking if the physical contents agree and if the recording -media itself is of dependable quality. So, for the `--verify' -operation, `tar' tries to defeat all in-memory cache pertaining to the -archive, while it lets the speed optimization undisturbed for the -`--compare' option. If you nevertheless use `--compare' for media -verification, you may have to defeat the in-memory cache yourself, -maybe by opening and reclosing the door latch of your recording unit, -forcing some doubt in your operating system about the fact this is -really the same volume as the one just written or read. - - The `--verify' option would not be necessary if drivers were indeed -able to detect dependably all write failures. This sometimes require -many magnetic heads, some able to read after the writes occurred. One -would not say that drivers unable to detect all cases are necessarily -flawed, as long as programming is concerned. - - The `--verify' (`-W') option will not work in conjunction with the -`--multi-volume' (`-M') option or the `--append' (`-r'), `--update' -(`-u') and `--delete' operations. *Note Operations::, for more -information on these operations. - - Also, since `tar' normally strips leading `/' from file names (*note -absolute::), a command like `tar --verify -cf /tmp/foo.tar /etc' will -work as desired only if the working directory is `/', as `tar' uses the -archive's relative member names (e.g., `etc/motd') when verifying the -archive. - - -File: tar.info, Node: Write Protection, Prev: verify, Up: Media - -9.9 Write Protection -==================== - -Almost all tapes and diskettes, and in a few rare cases, even disks can -be "write protected", to protect data on them from being changed. Once -an archive is written, you should write protect the media to prevent -the archive from being accidentally overwritten or deleted. (This will -protect the archive from being changed with a tape or floppy drive--it -will not protect it from magnet fields or other physical hazards). - - The write protection device itself is usually an integral part of the -physical media, and can be a two position (write enabled/write -disabled) switch, a notch which can be popped out or covered, a ring -which can be removed from the center of a tape reel, or some other -changeable feature. - - -File: tar.info, Node: Changes, Next: Configuring Help Summary, Prev: Media, Up: Top - -Appendix A Changes -****************** - -This appendix lists some important user-visible changes between version -GNU `tar' 1.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. - - -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. - - -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 - - -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:: - - -File: tar.info, Node: Standard, Next: Extensions, Up: Tar Internals - -Basic Tar Format -================ - - _(This message will disappear, once this node revised.)_ - -While an archive may contain many files, the archive itself is a single -ordinary file. Like any other file, an archive file can be written to -a storage device such as a tape or disk, sent through a pipe or over a -network, saved on the active file system, or even stored in another -archive. An archive file is not easy to read or manipulate without -using the `tar' utility or Tar mode in GNU Emacs. - - Physically, an archive consists of a series of file entries -terminated by an end-of-archive entry, which consists of two 512 blocks -of zero bytes. A file entry usually describes one of the files in the -archive (an "archive member"), and consists of a file header and the -contents of the file. File headers contain file names and statistics, -checksum information which `tar' uses to detect file corruption, and -information about file types. - - Archives are permitted to have more than one member with the same -member name. One way this situation can occur is if more than one -version of a file has been stored in the archive. For information -about adding new versions of a file to an archive, see *note update::. - - In addition to entries describing archive members, an archive may -contain entries which `tar' itself uses to store information. *Note -label::, for an example of such an archive entry. - - A `tar' archive file contains a series of blocks. Each block -contains `BLOCKSIZE' bytes. Although this format may be thought of as -being on magnetic tape, other media are often used. - - Each file archived is represented by a header block which describes -the file, followed by zero or more blocks which give the contents of -the file. At the end of the archive file there are two 512-byte blocks -filled with binary zeros as an end-of-file marker. A reasonable system -should write such end-of-file marker at the end of an archive, but must -not assume that such a block exists when reading an archive. In -particular GNU `tar' always issues a warning if it does not encounter -it. - - The blocks may be "blocked" for physical I/O operations. Each -record of N blocks (where N is set by the `--blocking-factor=512-SIZE' -(`-b 512-SIZE') option to `tar') is written with a single `write ()' -operation. On magnetic tapes, the result of such a write is a single -record. When writing an archive, the last record of blocks should be -written at the full size, with blocks after the zero block containing -all zeros. When reading an archive, a reasonable system should -properly handle an archive whose last record is shorter than the rest, -or which contains garbage records after a zero block. - - The header block is defined in C as follows. In the GNU `tar' -distribution, this is part of file `src/tar.h': - - - /* tar Header Block, from POSIX 1003.1-1990. */ - - /* POSIX header. */ - - struct posix_header - { /* byte offset */ - char name[100]; /* 0 */ - char mode[8]; /* 100 */ - char uid[8]; /* 108 */ - char gid[8]; /* 116 */ - char size[12]; /* 124 */ - char mtime[12]; /* 136 */ - char chksum[8]; /* 148 */ - char typeflag; /* 156 */ - char linkname[100]; /* 157 */ - char magic[6]; /* 257 */ - char version[2]; /* 263 */ - char uname[32]; /* 265 */ - char gname[32]; /* 297 */ - char devmajor[8]; /* 329 */ - char devminor[8]; /* 337 */ - char prefix[155]; /* 345 */ - /* 500 */ - }; - - #define TMAGIC "ustar" /* ustar and a null */ - #define TMAGLEN 6 - #define TVERSION "00" /* 00 and no null */ - #define TVERSLEN 2 - - /* Values used in typeflag field. */ - #define REGTYPE '0' /* regular file */ - #define AREGTYPE '\0' /* regular file */ - #define LNKTYPE '1' /* link */ - #define SYMTYPE '2' /* reserved */ - #define CHRTYPE '3' /* character special */ - #define BLKTYPE '4' /* block special */ - #define DIRTYPE '5' /* directory */ - #define FIFOTYPE '6' /* FIFO special */ - #define CONTTYPE '7' /* reserved */ - - #define XHDTYPE 'x' /* Extended header referring to the - next file in the archive */ - #define XGLTYPE 'g' /* Global extended header */ - - /* Bits used in the mode field, values in octal. */ - #define TSUID 04000 /* set UID on execution */ - #define TSGID 02000 /* set GID on execution */ - #define TSVTX 01000 /* reserved */ - /* file permissions */ - #define TUREAD 00400 /* read by owner */ - #define TUWRITE 00200 /* write by owner */ - #define TUEXEC 00100 /* execute/search by owner */ - #define TGREAD 00040 /* read by group */ - #define TGWRITE 00020 /* write by group */ - #define TGEXEC 00010 /* execute/search by group */ - #define TOREAD 00004 /* read by other */ - #define TOWRITE 00002 /* write by other */ - #define TOEXEC 00001 /* execute/search by other */ - - /* tar Header Block, GNU extensions. */ - - /* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for - contiguous files, so maybe disobeying the `reserved' comment in POSIX - header description. I suspect these were meant to be used this way, and - should not have really been `reserved' in the published standards. */ - - /* *BEWARE* *BEWARE* *BEWARE* that the following information is still - boiling, and may change. Even if the OLDGNU format description should be - accurate, the so-called GNU format is not yet fully decided. It is - surely meant to use only extensions allowed by POSIX, but the sketch - below repeats some ugliness from the OLDGNU format, which should rather - go away. Sparse files should be saved in such a way that they do *not* - require two passes at archive creation time. Huge files get some POSIX - fields to overflow, alternate solutions have to be sought for this. */ - - /* Descriptor for a single file hole. */ - - struct sparse - { /* byte offset */ - char offset[12]; /* 0 */ - char numbytes[12]; /* 12 */ - /* 24 */ - }; - - /* Sparse files are not supported in POSIX ustar format. For sparse files - with a POSIX header, a GNU extra header is provided which holds overall - sparse information and a few sparse descriptors. When an old GNU header - replaces both the POSIX header and the GNU extra header, it holds some - sparse descriptors too. Whether POSIX or not, if more sparse descriptors - are still needed, they are put into as many successive sparse headers as - necessary. The following constants tell how many sparse descriptors fit - in each kind of header able to hold them. */ - - #define SPARSES_IN_EXTRA_HEADER 16 - #define SPARSES_IN_OLDGNU_HEADER 4 - #define SPARSES_IN_SPARSE_HEADER 21 - - /* Extension header for sparse files, used immediately after the GNU extra - header, and used only if all sparse information cannot fit into that - extra header. There might even be many such extension headers, one after - the other, until all sparse information has been recorded. */ - - struct sparse_header - { /* byte offset */ - struct sparse sp[SPARSES_IN_SPARSE_HEADER]; - /* 0 */ - char isextended; /* 504 */ - /* 505 */ - }; - - /* The old GNU format header conflicts with POSIX format in such a way that - POSIX archives may fool old GNU tar's, and POSIX tar's might well be - fooled by old GNU tar archives. An old GNU format header uses the space - used by the prefix field in a POSIX header, and cumulates information - normally found in a GNU extra header. With an old GNU tar header, we - never see any POSIX header nor GNU extra header. Supplementary sparse - headers are allowed, however. */ - - struct oldgnu_header - { /* byte offset */ - char unused_pad1[345]; /* 0 */ - char atime[12]; /* 345 Incr. archive: atime of the file */ - char ctime[12]; /* 357 Incr. archive: ctime of the file */ - char offset[12]; /* 369 Multivolume archive: the offset of - the start of this volume */ - char longnames[4]; /* 381 Not used */ - char unused_pad2; /* 385 */ - struct sparse sp[SPARSES_IN_OLDGNU_HEADER]; - /* 386 */ - char isextended; /* 482 Sparse file: Extension sparse header - follows */ - char realsize[12]; /* 483 Sparse file: Real size*/ - /* 495 */ - }; - - /* OLDGNU_MAGIC uses both magic and version fields, which are contiguous. - Found in an archive, it indicates an old GNU header format, which will be - hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are - valid, though the header is not truly POSIX conforming. */ - #define OLDGNU_MAGIC "ustar " /* 7 chars and a null */ - - /* The standards committee allows only capital A through capital Z for - user-defined expansion. Other letters in use include: - - 'A' Solaris Access Control List - 'E' Solaris Extended Attribute File - 'I' Inode only, as in 'star' - 'N' Obsolete GNU tar, for file names that do not fit into the main header. - 'X' POSIX 1003.1-2001 eXtended (VU version) */ - - /* This is a dir entry that contains the names of files that were in the - dir at the time the dump was made. */ - #define GNUTYPE_DUMPDIR 'D' - - /* Identifies the *next* file on the tape as having a long linkname. */ - #define GNUTYPE_LONGLINK 'K' - - /* Identifies the *next* file on the tape as having a long name. */ - #define GNUTYPE_LONGNAME 'L' - - /* This is the continuation of a file that began on another volume. */ - #define GNUTYPE_MULTIVOL 'M' - - /* This is for sparse files. */ - #define GNUTYPE_SPARSE 'S' - - /* This file is a tape/volume header. Ignore it on extraction. */ - #define GNUTYPE_VOLHDR 'V' - - /* Solaris extended header */ - #define SOLARIS_XHDTYPE 'X' - - /* Jo"rg Schilling star header */ - - struct star_header - { /* byte offset */ - char name[100]; /* 0 */ - char mode[8]; /* 100 */ - char uid[8]; /* 108 */ - char gid[8]; /* 116 */ - char size[12]; /* 124 */ - char mtime[12]; /* 136 */ - char chksum[8]; /* 148 */ - char typeflag; /* 156 */ - char linkname[100]; /* 157 */ - char magic[6]; /* 257 */ - char version[2]; /* 263 */ - char uname[32]; /* 265 */ - char gname[32]; /* 297 */ - char devmajor[8]; /* 329 */ - char devminor[8]; /* 337 */ - char prefix[131]; /* 345 */ - char atime[12]; /* 476 */ - char ctime[12]; /* 488 */ - /* 500 */ - }; - - #define SPARSES_IN_STAR_HEADER 4 - #define SPARSES_IN_STAR_EXT_HEADER 21 - - struct star_in_header - { - char fill[345]; /* 0 Everything that is before t_prefix */ - char prefix[1]; /* 345 t_name prefix */ - char fill2; /* 346 */ - char fill3[8]; /* 347 */ - char isextended; /* 355 */ - struct sparse sp[SPARSES_IN_STAR_HEADER]; /* 356 */ - char realsize[12]; /* 452 Actual size of the file */ - char offset[12]; /* 464 Offset of multivolume contents */ - char atime[12]; /* 476 */ - char ctime[12]; /* 488 */ - char mfill[8]; /* 500 */ - char xmagic[4]; /* 508 "tar" */ - }; - - struct star_ext_header - { - struct sparse sp[SPARSES_IN_STAR_EXT_HEADER]; - char isextended; - }; - - All characters in header blocks are represented by using 8-bit -characters in the local variant of ASCII. Each field within the -structure is contiguous; that is, there is no padding used within the -structure. Each character on the archive medium is stored contiguously. - - Bytes representing the contents of files (after the header block of -each file) are not translated in any way and are not constrained to -represent characters in any character set. The `tar' format does not -distinguish text files from binary files, and no translation of file -contents is performed. - - The `name', `linkname', `magic', `uname', and `gname' are -null-terminated character strings. All other fields are zero-filled -octal numbers in ASCII. Each numeric field of width W contains W minus -1 digits, and a null. - - The `name' field is the file name of the file, with directory names -(if any) preceding the file name, separated by slashes. - - The `mode' field provides nine bits specifying file permissions and -three bits to specify the Set UID, Set GID, and Save Text ("sticky") -modes. Values for these bits are defined above. When special -permissions are required to create a file with a given mode, and the -user restoring files from the archive does not hold such permissions, -the mode bit(s) specifying those special permissions are ignored. -Modes which are not supported by the operating system restoring files -from the archive will be ignored. Unsupported modes should be faked up -when creating or updating an archive; e.g., the group permission could -be copied from the _other_ permission. - - The `uid' and `gid' fields are the numeric user and group ID of the -file owners, respectively. If the operating system does not support -numeric user or group IDs, these fields should be ignored. - - The `size' field is the size of the file in bytes; linked files are -archived with this field specified as zero. - - The `mtime' field is the data modification time of the file at the -time it was archived. It is the ASCII representation of the octal -value of the last time the file's contents were modified, represented -as an integer number of seconds since January 1, 1970, 00:00 -Coordinated Universal Time. - - The `chksum' field is the ASCII representation of the octal value of -the simple sum of all bytes in the header block. Each 8-bit byte in -the header is added to an unsigned integer, initialized to zero, the -precision of which shall be no less than seventeen bits. When -calculating the checksum, the `chksum' field is treated as if it were -all blanks. - - The `typeflag' field specifies the type of file archived. If a -particular implementation does not recognize or permit the specified -type, the file will be extracted as if it were a regular file. As this -action occurs, `tar' issues a warning to the standard error. - - The `atime' and `ctime' fields are used in making incremental -backups; they store, respectively, the particular file's access and -status change times. - - The `offset' is used by the `--multi-volume' (`-M') option, when -making a multi-volume archive. The offset is number of bytes into the -file that we need to restart at to continue the file on the next tape, -i.e., where we store the location that a continued file is continued at. - - The following fields were added to deal with sparse files. A file -is "sparse" if it takes in unallocated blocks which end up being -represented as zeros, i.e., no useful data. A test to see if a file is -sparse is to look at the number blocks allocated for it versus the -number of characters in the file; if there are fewer blocks allocated -for the file than would normally be allocated for a file of that size, -then the file is sparse. This is the method `tar' uses to detect a -sparse file, and once such a file is detected, it is treated -differently from non-sparse files. - - Sparse files are often `dbm' files, or other database-type files -which have data at some points and emptiness in the greater part of the -file. Such files can appear to be very large when an `ls -l' is done -on them, when in truth, there may be a very small amount of important -data contained in the file. It is thus undesirable to have `tar' think -that it must back up this entire file, as great quantities of room are -wasted on empty blocks, which can lead to running out of room on a tape -far earlier than is necessary. Thus, sparse files are dealt with so -that these empty blocks are not written to the tape. Instead, what is -written to the tape is a description, of sorts, of the sparse file: -where the holes are, how big the holes are, and how much data is found -at the end of the hole. This way, the file takes up potentially far -less room on the tape, and when the file is extracted later on, it will -look exactly the way it looked beforehand. The following is a -description of the fields used to handle a sparse file: - - The `sp' is an array of `struct sparse'. Each `struct sparse' -contains two 12-character strings which represent an offset into the -file and a number of bytes to be written at that offset. The offset is -absolute, and not relative to the offset in preceding array element. - - The header can hold four of these `struct sparse' at the moment; if -more are needed, they are not stored in the header. - - The `isextended' flag is set when an `extended_header' is needed to -deal with a file. Note that this means that this flag can only be set -when dealing with a sparse file, and it is only set in the event that -the description of the file will not fit in the allotted room for -sparse structures in the header. In other words, an extended_header is -needed. - - The `extended_header' structure is used for sparse files which need -more sparse structures than can fit in the header. The header can fit -4 such structures; if more are needed, the flag `isextended' gets set -and the next block is an `extended_header'. - - Each `extended_header' structure contains an array of 21 sparse -structures, along with a similar `isextended' flag that the header had. -There can be an indeterminate number of such `extended_header's to -describe a sparse file. - -`REGTYPE' -`AREGTYPE' - These flags represent a regular file. In order to be compatible - with older versions of `tar', a `typeflag' value of `AREGTYPE' - should be silently recognized as a regular file. New archives - should be created using `REGTYPE'. Also, for backward - compatibility, `tar' treats a regular file whose name ends with a - slash as a directory. - -`LNKTYPE' - This flag represents a file linked to another file, of any type, - previously archived. Such files are identified in Unix by each - file having the same device and inode number. The linked-to name - is specified in the `linkname' field with a trailing null. - -`SYMTYPE' - This represents a symbolic link to another file. The linked-to - name is specified in the `linkname' field with a trailing null. - -`CHRTYPE' -`BLKTYPE' - These represent character special files and block special files - respectively. In this case the `devmajor' and `devminor' fields - will contain the major and minor device numbers respectively. - Operating systems may map the device specifications to their own - local specification, or may ignore the entry. - -`DIRTYPE' - This flag specifies a directory or sub-directory. The directory - name in the `name' field should end with a slash. On systems where - disk allocation is performed on a directory basis, the `size' field - will contain the maximum number of bytes (which may be rounded to - the nearest disk block allocation unit) which the directory may - hold. A `size' field of zero indicates no such limiting. Systems - which do not support limiting in this manner should ignore the - `size' field. - -`FIFOTYPE' - This specifies a FIFO special file. Note that the archiving of a - FIFO file archives the existence of this file and not its contents. - -`CONTTYPE' - This specifies a contiguous file, which is the same as a normal - file except that, in operating systems which support it, all its - space is allocated contiguously on the disk. Operating systems - which do not allow contiguous allocation should silently treat this - type as a normal file. - -`A' ... `Z' - These are reserved for custom implementations. Some of these are - used in the GNU modified format, as described below. - - - Other values are reserved for specification in future revisions of -the P1003 standard, and should not be used by any `tar' program. - - The `magic' field indicates that this archive was output in the -P1003 archive format. If this field contains `TMAGIC', the `uname' and -`gname' fields will contain the ASCII representation of the owner and -group of the file respectively. If found, the user and group IDs are -used rather than the values in the `uid' and `gid' fields. - - For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, -pages 169-173 (section 10.1) for `Archive/Interchange File Format'; and -IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940 -(section E.4.48) for `pax - Portable archive interchange'. - - -File: tar.info, Node: Extensions, Next: Sparse Formats, Prev: Standard, Up: Tar Internals - -GNU Extensions to the Archive Format -==================================== - - _(This message will disappear, once this node revised.)_ - -The GNU format uses additional file types to describe new types of -files in an archive. These are listed below. - -`GNUTYPE_DUMPDIR' -`'D'' - This represents a directory and a list of files created by the - `--incremental' (`-G') option. The `size' field gives the total - size of the associated list of files. Each file name is preceded - by either a `Y' (the file should be in this archive) or an `N'. - (The file is a directory, or is not stored in the archive.) Each - file name is terminated by a null. There is an additional null - after the last file name. - -`GNUTYPE_MULTIVOL' -`'M'' - This represents a file continued from another volume of a - multi-volume archive created with the `--multi-volume' (`-M') - option. The original type of the file is not given here. The - `size' field gives the maximum size of this piece of the file - (assuming the volume does not end before the file is written out). - The `offset' field gives the offset from the beginning of the - file where this part of the file begins. Thus `size' plus - `offset' should equal the original size of the file. - -`GNUTYPE_SPARSE' -`'S'' - This flag indicates that we are dealing with a sparse file. Note - that archiving a sparse file requires special operations to find - holes in the file, which mark the positions of these holes, along - with the number of bytes of data to be found after the hole. - -`GNUTYPE_VOLHDR' -`'V'' - This file type is used to mark the volume header that was given - with the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') option when - the archive was created. The `name' field contains the `name' - given after the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') - option. The `size' field is zero. Only the first file in each - volume of an archive should have this type. - - - You may have trouble reading a GNU format archive on a non-GNU -system if the options `--incremental' (`-G'), `--multi-volume' (`-M'), -`--sparse' (`-S'), or `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') were -used when writing the archive. In general, if `tar' does not use the -GNU-added fields of the header, other versions of `tar' should be able -to read the archive. Otherwise, the `tar' program will give an error, -the most likely one being a checksum error. - - -File: tar.info, Node: Sparse Formats, Next: Snapshot Files, Prev: Extensions, Up: Tar Internals - -Storing Sparse Files -==================== - -The notion of sparse file, and the ways of handling it from the point -of view of GNU `tar' user have been described in detail in *note -sparse::. This chapter describes the internal format GNU `tar' uses to -store such files. - - The support for sparse files in GNU `tar' has a long history. The -earliest version featuring this support that I was able to find was -1.09, released in November, 1990. The format introduced back then is -called "old GNU" sparse format and in spite of the fact that its design -contained many flaws, it was the only format GNU `tar' supported until -version 1.14 (May, 2004), which introduced initial support for sparse -archives in PAX archives (*note posix::). This format was not free -from design flows, either and it was subsequently improved in versions -1.15.2 (November, 2005) and 1.15.92 (June, 2006). - - In addition to GNU sparse format, GNU `tar' is able to read and -extract sparse files archived by `star'. - - The following subsections describe each format in detail. - -* Menu: - -* Old GNU Format:: -* PAX 0:: PAX Format, Versions 0.0 and 0.1 -* PAX 1:: PAX Format, Version 1.0 - - -File: tar.info, Node: Old GNU Format, Next: PAX 0, Up: Sparse Formats - -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. - - -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. - - -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'. - - -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'. - - - -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. - - -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. - - -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. - - -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 * - - -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. - - -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 . - - You can encourage commercial publishers to sell more free, copylefted -manuals and tutorials by buying them, and particularly by buying copies -from the publishers that paid for their writing or for major -improvements. Meanwhile, try to avoid buying non-free documentation at -all. Check the distribution terms of a manual before you buy it, and -insist that whoever seeks your business must respect your freedom. -Check the history of the book, and try reward the publishers that have -paid or pay the authors to work on it. - - The Free Software Foundation maintains a list of free documentation -published by other publishers, at -`http://www.fsf.org/doc/other-free-books.html'. - - -File: tar.info, Node: Copying This Manual, Next: Index of Command Line Options, Prev: Free Software Needs Free Documentation, Up: Top - -Appendix G Copying This Manual -****************************** - -* Menu: - -* GNU Free Documentation License:: License for copying this manual - - -File: tar.info, Node: GNU Free Documentation License, Up: Copying This Manual - -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. - - -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::. - -[index] -* 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) - - -File: tar.info, Node: Index, Prev: Index of Command Line Options, Up: Top - -Appendix I Index -**************** - -[index] -* Menu: - -* abbreviations for months: Calendar date items. (line 38) -* absolute file names: Remote Tape Server. (line 17) -* Adding archives to an archive: concatenate. (line 6) -* Adding files to an Archive: appending files. (line 8) -* ADMINISTRATOR: General-Purpose Variables. - (line 7) -* Age, excluding files by: after. (line 8) -* ago in date strings: Relative items in date strings. - (line 23) -* am in date strings: Time of day items. (line 22) -* Appending files to an Archive: appending files. (line 8) -* archive: Definitions. (line 6) -* Archive creation: file. (line 36) -* archive member: Definitions. (line 15) -* Archive Name: file. (line 8) -* Archive, creation of: create. (line 8) -* Archives, Appending files to: appending files. (line 8) -* Archiving Directories: create dir. (line 6) -* archiving files: Top. (line 24) -* ARGP_HELP_FMT, environment variable: Configuring Help Summary. - (line 22) -* authors of get_date: Authors of get_date. (line 6) -* Avoiding recursion in directories: recurse. (line 8) -* backup options: backup. (line 6) -* backup suffix: backup. (line 68) -* BACKUP_DIRS: General-Purpose Variables. - (line 29) -* BACKUP_FILES: General-Purpose Variables. - (line 55) -* BACKUP_HOUR: General-Purpose Variables. - (line 11) -* backups: backup. (line 41) -* beginning of time, for POSIX: Seconds since the Epoch. - (line 13) -* 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) - -