1 This is tar.info, produced by makeinfo version 4.13 from tar.texi.
3 This manual is for GNU `tar' (version 1.24, 24 October 2010), which
4 creates and extracts files from archives.
6 Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
7 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
9 Permission is granted to copy, distribute and/or modify this
10 document under the terms of the GNU Free Documentation License,
11 Version 1.3 or any later version published by the Free Software
12 Foundation; with no Invariant Sections, with the Front-Cover Texts
13 being "A GNU Manual", and with the Back-Cover Texts as in (a)
14 below. A copy of the license is included in the section entitled
15 "GNU Free Documentation License".
17 (a) The FSF's Back-Cover Text is: "You have the freedom to copy
18 and modify this GNU manual. Buying copies from the FSF supports
19 it in developing GNU and promoting software freedom."
21 INFO-DIR-SECTION Archiving
23 * Tar: (tar). Making tape (or disk) archives.
26 INFO-DIR-SECTION Individual utilities
28 * tar: (tar)tar invocation. Invoking GNU `tar'.
32 File: tar.info, Node: Formats, Next: Media, Prev: Date input formats, Up: Top
34 8 Controlling the Archive Format
35 ********************************
37 Due to historical reasons, there are several formats of tar archives.
38 All of them are based on the same principles, but have some subtle
39 differences that often make them incompatible with each other.
41 GNU tar is able to create and handle archives in a variety of
42 formats. The most frequently used formats are (in alphabetical order):
45 Format used by GNU `tar' versions up to 1.13.25. This format
46 derived from an early POSIX standard, adding some improvements
47 such as sparse file handling and incremental archives.
48 Unfortunately these features were implemented in a way
49 incompatible with other archive formats.
51 Archives in `gnu' format are able to hold file names of unlimited
55 Format used by GNU `tar' of versions prior to 1.12.
58 Archive format, compatible with the V7 implementation of tar. This
59 format imposes a number of limitations. The most important of them
62 1. The maximum length of a file name is limited to 99 characters.
64 2. The maximum length of a symbolic link is limited to 99
67 3. It is impossible to store special files (block and character
70 4. Maximum value of user or group ID is limited to 2097151
73 5. V7 archives do not contain symbolic ownership information
74 (user and group name of the file owner).
76 This format has traditionally been used by Automake when producing
77 Makefiles. This practice will change in the future, in the
78 meantime, however this means that projects containing file names
79 more than 99 characters long will not be able to use GNU `tar'
80 1.24 and Automake prior to 1.9.
83 Archive format defined by POSIX.1-1988 specification. It stores
84 symbolic ownership information. It is also able to store special
85 files. However, it imposes several restrictions as well:
87 1. The maximum length of a file name is limited to 256
88 characters, provided that the file name can be split at a
89 directory separator in two parts, first of them being at most
90 155 bytes long. So, in most cases the maximum file name
91 length will be shorter than 256 characters.
93 2. The maximum length of a symbolic link name is limited to 100
96 3. Maximum size of a file the archive is able to accommodate is
99 4. Maximum value of UID/GID is 2097151.
101 5. Maximum number of bits in device major and minor numbers is
105 Format used by Jo"rg Schilling `star' implementation. GNU `tar'
106 is able to read `star' archives but currently does not produce
110 Archive format defined by POSIX.1-2001 specification. This is the
111 most flexible and feature-rich format. It does not impose any
112 restrictions on file sizes or file name lengths. This format is
113 quite recent, so not all tar implementations are able to handle it
114 properly. However, this format is designed in such a way that any
115 tar implementation able to read `ustar' archives will be able to
116 read most `posix' archives as well, with the only exception that
117 any additional information (such as long file names etc.) will in
118 such case be extracted as plain text files along with the files it
121 This archive format will be the default format for future versions
125 The following table summarizes the limitations of each of these
128 Format UID File Size File Name Devn
129 --------------------------------------------------------------------
130 gnu 1.8e19 Unlimited Unlimited 63
131 oldgnu 1.8e19 Unlimited Unlimited 63
132 v7 2097151 8GB 99 n/a
133 ustar 2097151 8GB 256 21
134 posix Unlimited Unlimited Unlimited Unlimited
136 The default format for GNU `tar' is defined at compilation time.
137 You may check it by running `tar --help', and examining the last lines
138 of its output. Usually, GNU `tar' is configured to create archives in
139 `gnu' format, however, future version will switch to `posix'.
143 * Compression:: Using Less Space through Compression
144 * Attributes:: Handling File Attributes
145 * Portability:: Making `tar' Archives More Portable
146 * cpio:: Comparison of `tar' and `cpio'
149 File: tar.info, Node: Compression, Next: Attributes, Up: Formats
151 8.1 Using Less Space through Compression
152 ========================================
156 * gzip:: Creating and Reading Compressed Archives
157 * sparse:: Archiving Sparse Files
160 File: tar.info, Node: gzip, Next: sparse, Up: Compression
162 8.1.1 Creating and Reading Compressed Archives
163 ----------------------------------------------
165 GNU `tar' is able to create and read compressed archives. It supports
166 a wide variety of compression programs, namely: `gzip', `bzip2',
167 `lzip', `lzma', `lzop', `xz' and traditional `compress'. The latter is
168 supported mostly for backward compatibility, and we recommend against
169 using it, because it is by far less effective than the other
170 compression programs(1).
172 Creating a compressed archive is simple: you just specify a
173 "compression option" along with the usual archive creation commands.
174 The compression option is `-z' (`--gzip') to create a `gzip' compressed
175 archive, `-j' (`--bzip2') to create a `bzip2' compressed archive,
176 `--lzip' to create an lzip compressed archive, `-J' (`--xz') to create
177 an XZ archive, `--lzma' to create an LZMA compressed archive, `--lzop'
178 to create an LSOP archive, and `-Z' (`--compress') to use `compress'
179 program. For example:
181 $ tar cfz archive.tar.gz .
183 You can also let GNU `tar' select the compression program based on
184 the suffix of the archive file name. This is done using
185 `--auto-compress' (`-a') command line option. For example, the
186 following invocation will use `bzip2' for compression:
188 $ tar cfa archive.tar.bz2 .
190 whereas the following one will use `lzma':
192 $ tar cfa archive.tar.lzma .
194 For a complete list of file name suffixes recognized by GNU `tar',
195 see *note auto-compress::.
197 Reading compressed archive is even simpler: you don't need to specify
198 any additional options as GNU `tar' recognizes its format
199 automatically. Thus, the following commands will list and extract the
200 archive created in previous example:
202 # List the compressed archive
203 $ tar tf archive.tar.gz
204 # Extract the compressed archive
205 $ tar xf archive.tar.gz
207 The format recognition algorithm is based on "signatures", a special
208 byte sequences in the beginning of file, that are specific for certain
209 compression formats. If this approach fails, `tar' falls back to using
210 archive name suffix to determine its format (*note auto-compress::, for
211 a list of recognized suffixes).
213 The only case when you have to specify a decompression option while
214 reading the archive is when reading from a pipe or from a tape drive
215 that does not support random access. However, in this case GNU `tar'
216 will indicate which option you should use. For example:
218 $ cat archive.tar.gz | tar tf -
219 tar: Archive is compressed. Use -z option
220 tar: Error is not recoverable: exiting now
222 If you see such diagnostics, just add the suggested option to the
223 invocation of GNU `tar':
225 $ cat archive.tar.gz | tar tfz -
227 Notice also, that there are several restrictions on operations on
228 compressed archives. First of all, compressed archives cannot be
229 modified, i.e., you cannot update (`--update', alias `-u') them or
230 delete (`--delete') members from them or add (`--append', alias `-r')
231 members to them. Likewise, you cannot append another `tar' archive to
232 a compressed archive using `--concatenate' (`-A'). Secondly,
233 multi-volume archives cannot be compressed.
235 The following options allow to select a particular compressor
241 Filter the archive through `gzip'.
245 Filter the archive through `xz'.
249 Filter the archive through `bzip2'.
252 Filter the archive through `lzip'.
255 Filter the archive through `lzma'.
258 Filter the archive through `lzop'.
263 Filter the archive through `compress'.
265 When any of these options is given, GNU `tar' searches the compressor
266 binary in the current path and invokes it. The name of the compressor
267 program is specified at compilation time using a corresponding
268 `--with-COMPNAME' option to `configure', e.g. `--with-bzip2' to select
269 a specific `bzip2' binary. *Note lbzip2::, for a detailed discussion.
271 The output produced by `tar --help' shows the actual compressor
272 names along with each of these options.
274 You can use any of these options on physical devices (tape drives,
275 etc.) and remote files as well as on normal files; data to or from such
276 devices or remote files is reblocked by another copy of the `tar'
277 program to enforce the specified (or default) record size. The default
278 compression parameters are used. Most compression programs allow to
279 override these by setting a program-specific environment variable. For
280 example, when using `gzip' you can use `GZIP' as in the example below:
282 $ GZIP=--best tar cfz archive.tar.gz subdir
284 Another way would be to use the `-I' option instead (see below), e.g.:
286 $ tar -cf archive.tar.gz -I 'gzip --best' subdir
288 Finally, the third, traditional, way to achieve the same result is to
291 $ tar cf - subdir | gzip --best -c - > archive.tar.gz
293 About corrupted compressed archives: compressed files have no
294 redundancy, for maximum compression. The adaptive nature of the
295 compression scheme means that the compression tables are implicitly
296 spread all over the archive. If you lose a few blocks, the dynamic
297 construction of the compression tables becomes unsynchronized, and there
298 is little chance that you could recover later in the archive.
300 Another compression options provide a better control over creating
301 compressed archives. These are:
305 Select a compression program to use by the archive file name
306 suffix. The following suffixes are recognized:
308 Suffix Compression program
309 --------------------------------------------------------------
325 `--use-compress-program=PROG'
327 Use external compression program PROG. Use this option if you are
328 not happy with the compression program associated with the suffix
329 at compile time or if you have a compression program that GNU `tar'
330 does not support. There are two requirements to which PROG should
333 First, when called without options, it should read data from
334 standard input, compress it and output it on standard output.
336 Secondly, if called with `-d' argument, it should do exactly the
337 opposite, i.e., read the compressed data from the standard input
338 and produce uncompressed data on the standard output.
340 The `--use-compress-program' option, in particular, lets you
341 implement your own filters, not necessarily dealing with
342 compression/decompression. For example, suppose you wish to implement
343 PGP encryption on top of compression, using `gpg' (*note gpg:
344 (gpg)Top.). The following script does that:
348 -d) gpg --decrypt - | gzip -d -c;;
349 '') gzip -c | gpg -s;;
350 *) echo "Unknown option $1">&2; exit 1;;
353 Suppose you name it `gpgz' and save it somewhere in your `PATH'.
354 Then the following command will create a compressed archive signed with
357 $ tar -cf foo.tar.gpgz -Igpgz .
359 Likewise, the command below will list its contents:
361 $ tar -tf foo.tar.gpgz -Igpgz .
365 * lbzip2:: Using lbzip2 with GNU `tar'.
367 ---------- Footnotes ----------
369 (1) It also had patent problems in the past.
372 File: tar.info, Node: lbzip2, Up: gzip
374 8.1.1.1 Using lbzip2 with GNU `tar'.
375 ....................................
377 `Lbzip2' is a multithreaded utility for handling `bzip2' compression,
378 written by Laszlo Ersek. It makes use of multiple processors to speed
379 up its operation and in general works considerably faster than `bzip2'.
380 For a detailed description of `lbzip2' see
381 `http://freshmeat.net/projects/lbzip2' and lbzip2: parallel bzip2
383 (http://www.linuxinsight.com/lbzip2-parallel-bzip2-utility.html).
385 Recent versions of `lbzip2' are mostly command line compatible with
386 `bzip2', which makes it possible to automatically invoke it via the
387 `--bzip2' GNU `tar' command line option. To do so, GNU `tar' must be
388 configured with the `--with-bzip2' command line option, like this:
390 $ ./configure --with-bzip2=lbzip2 [OTHER-OPTIONS]
392 Once configured and compiled this way, `tar --help' will show the
395 $ tar --help | grep -- --bzip2
396 -j, --bzip2 filter the archive through lbzip2
398 which means that running `tar --bzip2' will invoke `lbzip2'.
401 File: tar.info, Node: sparse, Prev: gzip, Up: Compression
403 8.1.2 Archiving Sparse Files
404 ----------------------------
406 Files in the file system occasionally have "holes". A "hole" in a file
407 is a section of the file's contents which was never written. The
408 contents of a hole reads as all zeros. On many operating systems,
409 actual disk storage is not allocated for holes, but they are counted in
410 the length of the file. If you archive such a file, `tar' could create
411 an archive longer than the original. To have `tar' attempt to
412 recognize the holes in a file, use `--sparse' (`-S'). When you use
413 this option, then, for any file using less disk space than would be
414 expected from its length, `tar' searches the file for consecutive
415 stretches of zeros. It then records in the archive for the file where
416 the consecutive stretches of zeros are, and only archives the "real
417 contents" of the file. On extraction (using `--sparse' is not needed
418 on extraction) any such files have holes created wherever the
419 continuous stretches of zeros were found. Thus, if you use `--sparse',
420 `tar' archives won't take more space than the original.
424 This option instructs `tar' to test each file for sparseness
425 before attempting to archive it. If the file is found to be
426 sparse it is treated specially, thus allowing to decrease the
427 amount of space used by its image in the archive.
429 This option is meaningful only when creating or updating archives.
430 It has no effect on extraction.
432 Consider using `--sparse' when performing file system backups, to
433 avoid archiving the expanded forms of files stored sparsely in the
436 Even if your system has no sparse files currently, some may be
437 created in the future. If you use `--sparse' while making file system
438 backups as a matter of course, you can be assured the archive will
439 never take more space on the media than the files take on disk
440 (otherwise, archiving a disk filled with sparse files might take
441 hundreds of tapes). *Note Incremental Dumps::.
443 However, be aware that `--sparse' option presents a serious
444 drawback. Namely, in order to determine if the file is sparse `tar'
445 has to read it before trying to archive it, so in total the file is
446 read *twice*. So, always bear in mind that the time needed to process
447 all files with this option is roughly twice the time needed to archive
450 When using `POSIX' archive format, GNU `tar' is able to store sparse
451 files using in three distinct ways, called "sparse formats". A sparse
452 format is identified by its "number", consisting, as usual of two
453 decimal numbers, delimited by a dot. By default, format `1.0' is used.
454 If, for some reason, you wish to use an earlier format, you can select
455 it using `--sparse-version' option.
457 `--sparse-version=VERSION'
458 Select the format to store sparse files in. Valid VERSION values
459 are: `0.0', `0.1' and `1.0'. *Note Sparse Formats::, for a
460 detailed description of each format.
462 Using `--sparse-format' option implies `--sparse'.
465 File: tar.info, Node: Attributes, Next: Portability, Prev: Compression, Up: Formats
467 8.2 Handling File Attributes
468 ============================
470 When `tar' reads files, it updates their access times. To avoid this,
471 use the `--atime-preserve[=METHOD]' option, which can either reset the
472 access time retroactively or avoid changing it in the first place.
475 `--atime-preserve=replace'
476 `--atime-preserve=system'
477 Preserve the access times of files that are read. This works only
478 for files that you own, unless you have superuser privileges.
480 `--atime-preserve=replace' works on most systems, but it also
481 restores the data modification time and updates the status change
482 time. Hence it doesn't interact with incremental dumps nicely
483 (*note Incremental Dumps::), and it can set access or data
484 modification times incorrectly if other programs access the file
485 while `tar' is running.
487 `--atime-preserve=system' avoids changing the access time in the
488 first place, if the operating system supports this.
489 Unfortunately, this may or may not work on any given operating
490 system or file system. If `tar' knows for sure it won't work, it
491 complains right away.
493 Currently `--atime-preserve' with no operand defaults to
494 `--atime-preserve=replace', but this is intended to change to
495 `--atime-preserve=system' when the latter is better-supported.
499 Do not extract data modification time.
501 When this option is used, `tar' leaves the data modification times
502 of the files it extracts as the times when the files were
503 extracted, instead of setting it to the times recorded in the
506 This option is meaningless with `--list' (`-t').
509 Create extracted files with the same ownership they have in the
512 This is the default behavior for the superuser, so this option is
513 meaningful only for non-root users, when `tar' is executed on
514 those systems able to give files away. This is considered as a
515 security flaw by many people, at least because it makes quite
516 difficult to correctly account users for the disk space they
517 occupy. Also, the `suid' or `sgid' attributes of files are easily
518 and silently lost when files are given away.
520 When writing an archive, `tar' writes the user ID and user name
521 separately. If it can't find a user name (because the user ID is
522 not in `/etc/passwd'), then it does not write one. When restoring,
523 it tries to look the name (if one was written) up in
524 `/etc/passwd'. If it fails, then it uses the user ID stored in
529 Do not attempt to restore ownership when extracting. This is the
530 default behavior for ordinary users, so this option has an effect
531 only for the superuser.
534 The `--numeric-owner' option allows (ANSI) archives to be written
535 without user/group name information or such information to be
536 ignored when extracting. It effectively disables the generation
537 and/or use of user/group name information. This option forces
538 extraction using the numeric ids from the archive, ignoring the
541 This is useful in certain circumstances, when restoring a backup
542 from an emergency floppy with different passwd/group files for
543 example. It is otherwise impossible to extract files with the
544 right ownerships if the password file in use during the extraction
545 does not match the one belonging to the file system(s) being
546 extracted. This occurs, for example, if you are restoring your
547 files after a major crash and had booted from an emergency floppy
548 with no password file or put your disk into another machine to do
551 The numeric ids are _always_ saved into `tar' archives. The
552 identifying names are added at create time when provided by the
553 system, unless `--format=oldgnu' is used. Numeric ids could be
554 used when moving archives between a collection of machines using a
555 centralized management for attribution of numeric ids to users and
556 groups. This is often made through using the NIS capabilities.
558 When making a `tar' file for distribution to other sites, it is
559 sometimes cleaner to use a single owner for all files in the
560 distribution, and nicer to specify the write permission bits of the
561 files as stored in the archive independently of their actual value
562 on the file system. The way to prepare a clean distribution is
563 usually to have some Makefile rule creating a directory, copying
564 all needed files in that directory, then setting ownership and
565 permissions as wanted (there are a lot of possible schemes), and
566 only then making a `tar' archive out of this directory, before
567 cleaning everything out. Of course, we could add a lot of options
568 to GNU `tar' for fine tuning permissions and ownership. This is
569 not the good way, I think. GNU `tar' is already crowded with
570 options and moreover, the approach just explained gives you a
571 great deal of control already.
575 `--preserve-permissions'
576 Extract all protection information.
578 This option causes `tar' to set the modes (access permissions) of
579 extracted files exactly as recorded in the archive. If this option
580 is not used, the current `umask' setting limits the permissions on
581 extracted files. This option is by default enabled when `tar' is
582 executed by a superuser.
584 This option is meaningless with `--list' (`-t').
587 Same as both `--same-permissions' and `--same-order'.
589 This option is deprecated, and will be removed in GNU `tar'
594 File: tar.info, Node: Portability, Next: cpio, Prev: Attributes, Up: Formats
596 8.3 Making `tar' Archives More Portable
597 =======================================
599 Creating a `tar' archive on a particular system that is meant to be
600 useful later on many other machines and with other versions of `tar' is
601 more challenging than you might think. `tar' archive formats have been
602 evolving since the first versions of Unix. Many such formats are
603 around, and are not always compatible with each other. This section
604 discusses a few problems, and gives some advice about making `tar'
605 archives more portable.
607 One golden rule is simplicity. For example, limit your `tar'
608 archives to contain only regular files and directories, avoiding other
609 kind of special files. Do not attempt to save sparse files or
610 contiguous files as such. Let's discuss a few more problems, in turn.
614 * Portable Names:: Portable Names
615 * dereference:: Symbolic Links
616 * hard links:: Hard Links
617 * old:: Old V7 Archives
618 * ustar:: Ustar Archives
619 * gnu:: GNU and old GNU format archives.
620 * posix:: POSIX archives
621 * Checksumming:: Checksumming Problems
622 * Large or Negative Values:: Large files, negative time stamps, etc.
623 * Other Tars:: How to Extract GNU-Specific Data Using
624 Other `tar' Implementations
627 File: tar.info, Node: Portable Names, Next: dereference, Up: Portability
632 Use portable file and member names. A name is portable if it contains
633 only ASCII letters and digits, `/', `.', `_', and `-'; it cannot be
634 empty, start with `-' or `//', or contain `/-'. Avoid deep directory
635 nesting. For portability to old Unix hosts, limit your file name
636 components to 14 characters or less.
638 If you intend to have your `tar' archives to be read under MSDOS,
639 you should not rely on case distinction for file names, and you might
640 use the GNU `doschk' program for helping you further diagnosing illegal
641 MSDOS names, which are even more limited than System V's.
644 File: tar.info, Node: dereference, Next: hard links, Prev: Portable Names, Up: Portability
649 Normally, when `tar' archives a symbolic link, it writes a block to the
650 archive naming the target of the link. In that way, the `tar' archive
651 is a faithful record of the file system contents. When `--dereference'
652 (`-h') is used with `--create' (`-c'), `tar' archives the files
653 symbolic links point to, instead of the links themselves.
655 When creating portable archives, use `--dereference' (`-h'): some
656 systems do not support symbolic links, and moreover, your distribution
657 might be unusable if it contains unresolved symbolic links.
659 When reading from an archive, the `--dereference' (`-h') option
660 causes `tar' to follow an already-existing symbolic link when `tar'
661 writes or reads a file named in the archive. Ordinarily, `tar' does
662 not follow such a link, though it may remove the link before writing a
663 new file. *Note Dealing with Old Files::.
665 The `--dereference' option is unsafe if an untrusted user can modify
666 directories while `tar' is running. *Note Security::.
669 File: tar.info, Node: hard links, Next: old, Prev: dereference, Up: Portability
674 Normally, when `tar' archives a hard link, it writes a block to the
675 archive naming the target of the link (a `1' type block). In that way,
676 the actual file contents is stored in file only once. For example,
677 consider the following two files:
680 -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
681 -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
683 Here, `jeden' is a link to `one'. When archiving this directory
684 with a verbose level 2, you will get an output similar to the following:
686 $ tar cfvv ../archive.tar .
687 drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
688 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
689 hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
691 The last line shows that, instead of storing two copies of the file,
692 `tar' stored it only once, under the name `jeden', and stored file
693 `one' as a hard link to this file.
695 It may be important to know that all hard links to the given file are
696 stored in the archive. For example, this may be necessary for exact
697 reproduction of the file system. The following option does that:
701 Check the number of links dumped for each processed file. If this
702 number does not match the total number of hard links for the file,
703 print a warning message.
705 For example, trying to archive only file `jeden' with this option
706 produces the following diagnostics:
708 $ tar -c -f ../archive.tar -l jeden
709 tar: Missing links to `jeden'.
711 Although creating special records for hard links helps keep a
712 faithful record of the file system contents and makes archives more
713 compact, it may present some difficulties when extracting individual
714 members from the archive. For example, trying to extract file `one'
715 from the archive created in previous examples produces, in the absense
718 $ tar xf archive.tar ./one
719 tar: ./one: Cannot hard link to `./jeden': No such file or directory
720 tar: Error exit delayed from previous errors
722 The reason for this behavior is that `tar' cannot seek back in the
723 archive to the previous member (in this case, `one'), to extract it(1).
724 If you wish to avoid such problems at the cost of a bigger archive, use
725 the following option:
728 Dereference hard links and store the files they refer to.
730 For example, trying this option on our two sample files, we get two
731 copies in the archive, each of which can then be extracted
732 independently of the other:
734 $ tar -c -vv -f ../archive.tar --hard-dereference .
735 drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
736 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
737 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one
739 ---------- Footnotes ----------
741 (1) There are plans to fix this in future releases.
744 File: tar.info, Node: old, Next: ustar, Prev: hard links, Up: Portability
746 8.3.4 Old V7 Archives
747 ---------------------
749 Certain old versions of `tar' cannot handle additional information
750 recorded by newer `tar' programs. To create an archive in V7 format
751 (not ANSI), which can be read by these old versions, specify the
752 `--format=v7' option in conjunction with the `--create' (`-c') (`tar'
753 also accepts `--portability' or `--old-archive' for this option). When
754 you specify it, `tar' leaves out information about directories, pipes,
755 fifos, contiguous files, and device files, and specifies file ownership
756 by group and user IDs instead of group and user names.
758 When updating an archive, do not use `--format=v7' unless the
759 archive was created using this option.
761 In most cases, a _new_ format archive can be read by an _old_ `tar'
762 program without serious trouble, so this option should seldom be
763 needed. On the other hand, most modern `tar's are able to read old
764 format archives, so it might be safer for you to always use
765 `--format=v7' for your distributions. Notice, however, that `ustar'
766 format is a better alternative, as it is free from many of `v7''s
770 File: tar.info, Node: ustar, Next: gnu, Prev: old, Up: Portability
772 8.3.5 Ustar Archive Format
773 --------------------------
775 Archive format defined by POSIX.1-1988 specification is called `ustar'.
776 Although it is more flexible than the V7 format, it still has many
777 restrictions (*note ustar: Formats, for the detailed description of
778 `ustar' format). Along with V7 format, `ustar' format is a good choice
779 for archives intended to be read with other implementations of `tar'.
781 To create archive in `ustar' format, use `--format=ustar' option in
782 conjunction with the `--create' (`-c').
785 File: tar.info, Node: gnu, Next: posix, Prev: ustar, Up: Portability
787 8.3.6 GNU and old GNU `tar' format
788 ----------------------------------
790 GNU `tar' was based on an early draft of the POSIX 1003.1 `ustar'
791 standard. GNU extensions to `tar', such as the support for file names
792 longer than 100 characters, use portions of the `tar' header record
793 which were specified in that POSIX draft as unused. Subsequent changes
794 in POSIX have allocated the same parts of the header record for other
795 purposes. As a result, GNU `tar' format is incompatible with the
796 current POSIX specification, and with `tar' programs that follow it.
798 In the majority of cases, `tar' will be configured to create this
799 format by default. This will change in future releases, since we plan
800 to make `POSIX' format the default.
802 To force creation a GNU `tar' archive, use option `--format=gnu'.
805 File: tar.info, Node: posix, Next: Checksumming, Prev: gnu, Up: Portability
807 8.3.7 GNU `tar' and POSIX `tar'
808 -------------------------------
810 Starting from version 1.14 GNU `tar' features full support for
811 POSIX.1-2001 archives.
813 A POSIX conformant archive will be created if `tar' was given
814 `--format=posix' (`--format=pax') option. No special option is
815 required to read and extract from a POSIX archive.
819 * PAX keywords:: Controlling Extended Header Keywords.
822 File: tar.info, Node: PAX keywords, Up: posix
824 8.3.7.1 Controlling Extended Header Keywords
825 ............................................
827 `--pax-option=KEYWORD-LIST'
828 Handle keywords in PAX extended headers. This option is
829 equivalent to `-o' option of the `pax' utility.
831 KEYWORD-LIST is a comma-separated list of keyword options, each
832 keyword option taking one of the following forms:
835 When used with one of archive-creation commands, this option
836 instructs `tar' to omit from extended header records that it
837 produces any keywords matching the string PATTERN.
839 When used in extract or list mode, this option instructs tar to
840 ignore any keywords matching the given PATTERN in the extended
841 header records. In both cases, matching is performed using the
842 pattern matching notation described in POSIX 1003.2, 3.13 (*note
843 wildcards::). For example:
845 --pax-option delete=security.*
847 would suppress security-related information.
850 This keyword allows user control over the name that is written
851 into the ustar header blocks for the extended headers. The name
852 is obtained from STRING after making the following substitutions:
854 Meta-character Replaced By
855 --------------------------------------------------------
856 %d The directory name of the file,
857 equivalent to the result of the
858 `dirname' utility on the translated
860 %f The name of the file with the
861 directory information stripped,
862 equivalent to the result of the
863 `basename' utility on the translated
865 %p The process ID of the `tar' process.
868 Any other `%' characters in STRING produce undefined results.
870 If no option `exthdr.name=string' is specified, `tar' will use the
871 following default value:
876 This keyword defines the value of the `mtime' field that is
877 written into the ustar header blocks for the extended headers. By
878 default, the `mtime' field is set to the modification time of the
879 archive member described by that extended headers.
881 `globexthdr.name=STRING'
882 This keyword allows user control over the name that is written into
883 the ustar header blocks for global extended header records. The
884 name is obtained from the contents of STRING, after making the
885 following substitutions:
887 Meta-character Replaced By
888 --------------------------------------------------------
889 %n An integer that represents the
890 sequence number of the global
891 extended header record in the
892 archive, starting at 1.
893 %p The process ID of the `tar' process.
896 Any other `%' characters in STRING produce undefined results.
898 If no option `globexthdr.name=string' is specified, `tar' will use
899 the following default value:
901 $TMPDIR/GlobalHead.%p.%n
903 where `$TMPDIR' represents the value of the TMPDIR environment
904 variable. If TMPDIR is not set, `tar' uses `/tmp'.
906 `globexthdr.mtime=VALUE'
907 This keyword defines the value of the `mtime' field that is
908 written into the ustar header blocks for the global extended
909 headers. By default, the `mtime' field is set to the time when
913 When used with one of archive-creation commands, these
914 keyword/value pairs will be included at the beginning of the
915 archive in a global extended header record. When used with one of
916 archive-reading commands, `tar' will behave as if it has
917 encountered these keyword/value pairs at the beginning of the
918 archive in a global extended header record.
921 When used with one of archive-creation commands, these
922 keyword/value pairs will be included as records at the beginning
923 of an extended header for each file. This is effectively
924 equivalent to KEYWORD=VALUE form except that it creates no global
925 extended header records.
927 When used with one of archive-reading commands, `tar' will behave
928 as if these keyword/value pairs were included as records at the
929 end of each extended header; thus, they will override any global or
930 file-specific extended header record keywords of the same names.
931 For example, in the command:
933 tar --format=posix --create \
934 --file archive --pax-option gname:=user .
936 the group name will be forced to a new value for all files stored
939 In any of the forms described above, the VALUE may be a string
940 enclosed in curly braces. In that case, the string between the braces
941 is understood either as a textual time representation, as described in
942 *note Date input formats::, or a name of the existing file, starting
943 with `/' or `.'. In the latter case, the modification time of that
946 For example, to set all modification times to the current date, you
947 use the following option:
949 --pax-option='mtime:={now}'
951 Note quoting of the option's argument.
953 As another example, here is the option that ensures that any two
954 archives created using it, will be binary equivalent if they have the
957 --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0
960 File: tar.info, Node: Checksumming, Next: Large or Negative Values, Prev: posix, Up: Portability
962 8.3.8 Checksumming Problems
963 ---------------------------
965 SunOS and HP-UX `tar' fail to accept archives created using GNU `tar'
966 and containing non-ASCII file names, that is, file names having
967 characters with the eight bit set, because they use signed checksums,
968 while GNU `tar' uses unsigned checksums while creating archives, as per
969 POSIX standards. On reading, GNU `tar' computes both checksums and
970 accepts any. It is somewhat worrying that a lot of people may go
971 around doing backup of their files using faulty (or at least
972 non-standard) software, not learning about it until it's time to
973 restore their missing files with an incompatible file extractor, or
976 GNU `tar' computes checksums both ways, and accept any on read, so
977 GNU tar can read Sun tapes even with their wrong checksums. GNU `tar'
978 produces the standard checksum, however, raising incompatibilities with
979 Sun. That is to say, GNU `tar' has not been modified to _produce_
980 incorrect archives to be read by buggy `tar''s. I've been told that
981 more recent Sun `tar' now read standard archives, so maybe Sun did a
982 similar patch, after all?
984 The story seems to be that when Sun first imported `tar' sources on
985 their system, they recompiled it without realizing that the checksums
986 were computed differently, because of a change in the default signing
987 of `char''s in their compiler. So they started computing checksums
988 wrongly. When they later realized their mistake, they merely decided
989 to stay compatible with it, and with themselves afterwards.
990 Presumably, but I do not really know, HP-UX has chosen that their `tar'
991 archives to be compatible with Sun's. The current standards do not
992 favor Sun `tar' format. In any case, it now falls on the shoulders of
993 SunOS and HP-UX users to get a `tar' able to read the good archives
997 File: tar.info, Node: Large or Negative Values, Next: Other Tars, Prev: Checksumming, Up: Portability
999 8.3.9 Large or Negative Values
1000 ------------------------------
1002 _(This message will disappear, once this node revised.)_
1004 The above sections suggest to use `oldest possible' archive format if
1005 in doubt. However, sometimes it is not possible. If you attempt to
1006 archive a file whose metadata cannot be represented using required
1007 format, GNU `tar' will print error message and ignore such a file. You
1008 will than have to switch to a format that is able to handle such
1009 values. The format summary table (*note Formats::) will help you to do
1012 In particular, when trying to archive files larger than 8GB or with
1013 timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16
1014 12:56:31 UTC, you will have to chose between GNU and POSIX archive
1015 formats. When considering which format to choose, bear in mind that
1016 the GNU format uses two's-complement base-256 notation to store values
1017 that do not fit into standard ustar range. Such archives can generally
1018 be read only by a GNU `tar' implementation. Moreover, they sometimes
1019 cannot be correctly restored on another hosts even by GNU `tar'. For
1020 example, using two's complement representation for negative time stamps
1021 that assumes a signed 32-bit `time_t' generates archives that are not
1022 portable to hosts with differing `time_t' representations.
1024 On the other hand, POSIX archives, generally speaking, can be
1025 extracted by any tar implementation that understands older ustar
1026 format. The only exception are files larger than 8GB.
1029 File: tar.info, Node: Other Tars, Prev: Large or Negative Values, Up: Portability
1031 8.3.10 How to Extract GNU-Specific Data Using Other `tar' Implementations
1032 -------------------------------------------------------------------------
1034 In previous sections you became acquainted with various quirks
1035 necessary to make your archives portable. Sometimes you may need to
1036 extract archives containing GNU-specific members using some third-party
1037 `tar' implementation or an older version of GNU `tar'. Of course your
1038 best bet is to have GNU `tar' installed, but if it is for some reason
1039 impossible, this section will explain how to cope without it.
1041 When we speak about "GNU-specific" members we mean two classes of
1042 them: members split between the volumes of a multi-volume archive and
1043 sparse members. You will be able to always recover such members if the
1044 archive is in PAX format. In addition split members can be recovered
1045 from archives in old GNU format. The following subsections describe
1046 the required procedures in detail.
1050 * Split Recovery:: Members Split Between Volumes
1051 * Sparse Recovery:: Sparse Members
1054 File: tar.info, Node: Split Recovery, Next: Sparse Recovery, Up: Other Tars
1056 8.3.10.1 Extracting Members Split Between Volumes
1057 .................................................
1059 If a member is split between several volumes of an old GNU format
1060 archive most third party `tar' implementation will fail to extract it.
1061 To extract it, use `tarcat' program (*note Tarcat::). This program is
1062 available from GNU `tar' home page
1063 (http://www.gnu.org/software/tar/utils/tarcat.html). It concatenates
1064 several archive volumes into a single valid archive. For example, if
1065 you have three volumes named from `vol-1.tar' to `vol-3.tar', you can
1066 do the following to extract them using a third-party `tar':
1068 $ tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -
1070 You could use this approach for most (although not all) PAX format
1071 archives as well. However, extracting split members from a PAX archive
1072 is a much easier task, because PAX volumes are constructed in such a
1073 way that each part of a split member is extracted to a different file
1074 by `tar' implementations that are not aware of GNU extensions. More
1075 specifically, the very first part retains its original name, and all
1076 subsequent parts are named using the pattern:
1078 %d/GNUFileParts.%p/%f.%n
1080 where symbols preceeded by `%' are "macro characters" that have the
1083 Meta-character Replaced By
1084 ------------------------------------------------------------
1085 %d The directory name of the file,
1086 equivalent to the result of the
1087 `dirname' utility on its full name.
1088 %f The file name of the file, equivalent
1089 to the result of the `basename' utility
1091 %p The process ID of the `tar' process that
1092 created the archive.
1093 %n Ordinal number of this particular part.
1095 For example, if the file `var/longfile' was split during archive
1096 creation between three volumes, and the creator `tar' process had
1097 process ID `27962', then the member names will be:
1100 var/GNUFileParts.27962/longfile.1
1101 var/GNUFileParts.27962/longfile.2
1103 When you extract your archive using a third-party `tar', these files
1104 will be created on your disk, and the only thing you will need to do to
1105 restore your file in its original form is concatenate them in the
1106 proper order, for example:
1109 $ cat GNUFileParts.27962/longfile.1 \
1110 GNUFileParts.27962/longfile.2 >> longfile
1111 $ rm -f GNUFileParts.27962
1113 Notice, that if the `tar' implementation you use supports PAX format
1114 archives, it will probably emit warnings about unknown keywords during
1115 extraction. They will look like this:
1118 Unknown extended header keyword 'GNU.volume.filename' ignored.
1119 Unknown extended header keyword 'GNU.volume.size' ignored.
1120 Unknown extended header keyword 'GNU.volume.offset' ignored.
1122 You can safely ignore these warnings.
1124 If your `tar' implementation is not PAX-aware, you will get more
1125 warnings and more files generated on your disk, e.g.:
1128 var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
1130 Unexpected EOF in archive
1132 tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file
1133 GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type
1134 'x', extracted as normal file
1136 Ignore these warnings. The `PaxHeaders.*' directories created will
1137 contain files with "extended header keywords" describing the extracted
1138 files. You can delete them, unless they describe sparse members. Read
1139 further to learn more about them.
1142 File: tar.info, Node: Sparse Recovery, Prev: Split Recovery, Up: Other Tars
1144 8.3.10.2 Extracting Sparse Members
1145 ..................................
1147 Any `tar' implementation will be able to extract sparse members from a
1148 PAX archive. However, the extracted files will be "condensed", i.e.,
1149 any zero blocks will be removed from them. When we restore such a
1150 condensed file to its original form, by adding zero blocks (or "holes")
1151 back to their original locations, we call this process "expanding" a
1152 compressed sparse file.
1154 To expand a file, you will need a simple auxiliary program called
1155 `xsparse'. It is available in source form from GNU `tar' home page
1156 (http://www.gnu.org/software/tar/utils/xsparse.html).
1158 Let's begin with archive members in "sparse format version 1.0"(1),
1159 which are the easiest to expand. The condensed file will contain both
1160 file map and file data, so no additional data will be needed to restore
1161 it. If the original file name was `DIR/NAME', then the condensed file
1162 will be named `DIR/GNUSparseFile.N/NAME', where N is a decimal
1165 To expand a version 1.0 file, run `xsparse' as follows:
1167 $ xsparse `cond-file'
1169 where `cond-file' is the name of the condensed file. The utility will
1170 deduce the name for the resulting expanded file using the following
1173 1. If `cond-file' does not contain any directories, `../cond-file'
1176 2. If `cond-file' has the form `DIR/T/NAME', where both T and NAME
1177 are simple names, with no `/' characters in them, the output file
1178 name will be `DIR/NAME'.
1180 3. Otherwise, if `cond-file' has the form `DIR/NAME', the output file
1181 name will be `NAME'.
1183 In the unlikely case when this algorithm does not suit your needs,
1184 you can explicitly specify output file name as a second argument to the
1187 $ xsparse `cond-file' `out-file'
1189 It is often a good idea to run `xsparse' in "dry run" mode first.
1190 In this mode, the command does not actually expand the file, but
1191 verbosely lists all actions it would be taking to do so. The dry run
1192 mode is enabled by `-n' command line argument:
1194 $ xsparse -n /home/gray/GNUSparseFile.6058/sparsefile
1195 Reading v.1.0 sparse map
1196 Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
1197 `/home/gray/sparsefile'
1200 To actually expand the file, you would run:
1202 $ xsparse /home/gray/GNUSparseFile.6058/sparsefile
1204 The program behaves the same way all UNIX utilities do: it will keep
1205 quiet unless it has simething important to tell you (e.g. an error
1206 condition or something). If you wish it to produce verbose output,
1207 similar to that from the dry run mode, use `-v' option:
1209 $ xsparse -v /home/gray/GNUSparseFile.6058/sparsefile
1210 Reading v.1.0 sparse map
1211 Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
1212 `/home/gray/sparsefile'
1215 Additionally, if your `tar' implementation has extracted the
1216 "extended headers" for this file, you can instruct `xstar' to use them
1217 in order to verify the integrity of the expanded file. The option `-x'
1218 sets the name of the extended header file to use. Continuing our
1221 $ xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \
1222 /home/gray/GNUSparseFile.6058/sparsefile
1223 Reading extended header file
1224 Found variable GNU.sparse.major = 1
1225 Found variable GNU.sparse.minor = 0
1226 Found variable GNU.sparse.name = sparsefile
1227 Found variable GNU.sparse.realsize = 217481216
1228 Reading v.1.0 sparse map
1229 Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
1230 `/home/gray/sparsefile'
1233 An "extended header" is a special `tar' archive header that precedes
1234 an archive member and contains a set of "variables", describing the
1235 member properties that cannot be stored in the standard `ustar' header.
1236 While optional for expanding sparse version 1.0 members, the use of
1237 extended headers is mandatory when expanding sparse members in older
1238 sparse formats: v.0.0 and v.0.1 (The sparse formats are described in
1239 detail in *note Sparse Formats::.) So, for these formats, the question
1240 is: how to obtain extended headers from the archive?
1242 If you use a `tar' implementation that does not support PAX format,
1243 extended headers for each member will be extracted as a separate file.
1244 If we represent the member name as `DIR/NAME', then the extended header
1245 file will be named `DIR/PaxHeaders.N/NAME', where N is an integer
1248 Things become more difficult if your `tar' implementation does
1249 support PAX headers, because in this case you will have to manually
1250 extract the headers. We recommend the following algorithm:
1252 1. Consult the documentation of your `tar' implementation for an
1253 option that prints "block numbers" along with the archive listing
1254 (analogous to GNU `tar''s `-R' option). For example, `star' has
1257 2. Obtain verbose listing using the `block number' option, and find
1258 block numbers of the sparse member in question and the member
1259 immediately following it. For example, running `star' on our
1262 $ star -t -v -block-number -f arc.tar
1264 star: Unknown extended header keyword 'GNU.sparse.size' ignored.
1265 star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored.
1266 star: Unknown extended header keyword 'GNU.sparse.name' ignored.
1267 star: Unknown extended header keyword 'GNU.sparse.map' ignored.
1268 block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile
1269 block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README
1272 (as usual, ignore the warnings about unknown keywords.)
1274 3. Let SIZE be the size of the sparse member, BS be its block number
1275 and BN be the block number of the next member. Compute:
1277 N = BS - BN - SIZE/512 - 2
1279 This number gives the size of the extended header part in tar
1280 "blocks". In our example, this formula gives: `897 - 56 - 425984
1283 4. Use `dd' to extract the headers:
1285 dd if=ARCHIVE of=HNAME bs=512 skip=BS count=N
1287 where ARCHIVE is the archive name, HNAME is a name of the file to
1288 store the extended header in, BS and N are computed in previous
1291 In our example, this command will be
1293 $ dd if=arc.tar of=xhdr bs=512 skip=56 count=7
1295 Finally, you can expand the condensed file, using the obtained
1298 $ xsparse -v -x xhdr GNUSparseFile.6058/sparsefile
1299 Reading extended header file
1300 Found variable GNU.sparse.size = 217481216
1301 Found variable GNU.sparse.numblocks = 208
1302 Found variable GNU.sparse.name = sparsefile
1303 Found variable GNU.sparse.map = 0,2048,1050624,2048,...
1304 Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile'
1307 ---------- Footnotes ----------
1311 (2) Technically speaking, N is a "process ID" of the `tar' process
1312 which created the archive (*note PAX keywords::).
1315 File: tar.info, Node: cpio, Prev: Portability, Up: Formats
1317 8.4 Comparison of `tar' and `cpio'
1318 ==================================
1320 _(This message will disappear, once this node revised.)_
1322 The `cpio' archive formats, like `tar', do have maximum file name
1323 lengths. The binary and old ASCII formats have a maximum file length
1324 of 256, and the new ASCII and CRC ASCII formats have a max file length
1325 of 1024. GNU `cpio' can read and write archives with arbitrary file
1326 name lengths, but other `cpio' implementations may crash unexplainedly
1327 trying to read them.
1329 `tar' handles symbolic links in the form in which it comes in BSD;
1330 `cpio' doesn't handle symbolic links in the form in which it comes in
1331 System V prior to SVR4, and some vendors may have added symlinks to
1332 their system without enhancing `cpio' to know about them. Others may
1333 have enhanced it in a way other than the way I did it at Sun, and which
1334 was adopted by AT&T (and which is, I think, also present in the `cpio'
1335 that Berkeley picked up from AT&T and put into a later BSD release--I
1336 think I gave them my changes).
1338 (SVR4 does some funny stuff with `tar'; basically, its `cpio' can
1339 handle `tar' format input, and write it on output, and it probably
1340 handles symbolic links. They may not have bothered doing anything to
1341 enhance `tar' as a result.)
1343 `cpio' handles special files; traditional `tar' doesn't.
1345 `tar' comes with V7, System III, System V, and BSD source; `cpio'
1346 comes only with System III, System V, and later BSD (4.3-tahoe and
1349 `tar''s way of handling multiple hard links to a file can handle
1350 file systems that support 32-bit i-numbers (e.g., the BSD file system);
1351 `cpio's way requires you to play some games (in its "binary" format,
1352 i-numbers are only 16 bits, and in its "portable ASCII" format, they're
1353 18 bits--it would have to play games with the "file system ID" field of
1354 the header to make sure that the file system ID/i-number pairs of
1355 different files were always different), and I don't know which `cpio's,
1356 if any, play those games. Those that don't might get confused and
1357 think two files are the same file when they're not, and make hard links
1360 `tar's way of handling multiple hard links to a file places only one
1361 copy of the link on the tape, but the name attached to that copy is the
1362 _only_ one you can use to retrieve the file; `cpio's way puts one copy
1363 for every link, but you can retrieve it using any of the names.
1365 What type of check sum (if any) is used, and how is this
1368 See the attached manual pages for `tar' and `cpio' format. `tar'
1369 uses a checksum which is the sum of all the bytes in the `tar' header
1370 for a file; `cpio' uses no checksum.
1372 If anyone knows why `cpio' was made when `tar' was present at the
1375 It wasn't. `cpio' first showed up in PWB/UNIX 1.0; no
1376 generally-available version of UNIX had `tar' at the time. I don't
1377 know whether any version that was generally available _within AT&T_ had
1378 `tar', or, if so, whether the people within AT&T who did `cpio' knew
1381 On restore, if there is a corruption on a tape `tar' will stop at
1382 that point, while `cpio' will skip over it and try to restore the rest
1385 The main difference is just in the command syntax and header format.
1387 `tar' is a little more tape-oriented in that everything is blocked
1388 to start on a record boundary.
1390 Is there any differences between the ability to recover crashed
1391 archives between the two of them. (Is there any chance of
1392 recovering crashed archives at all.)
1394 Theoretically it should be easier under `tar' since the blocking
1395 lets you find a header with some variation of `dd skip=NN'. However,
1396 modern `cpio''s and variations have an option to just search for the
1397 next file header after an error with a reasonable chance of resyncing.
1398 However, lots of tape driver software won't allow you to continue past
1399 a media error which should be the only reason for getting out of sync
1400 unless a file changed sizes while you were writing the archive.
1402 If anyone knows why `cpio' was made when `tar' was present at the
1403 unix scene, please tell me about this too.
1405 Probably because it is more media efficient (by not blocking
1406 everything and using only the space needed for the headers where `tar'
1407 always uses 512 bytes per file header) and it knows how to archive
1410 You might want to look at the freely available alternatives. The
1411 major ones are `afio', GNU `tar', and `pax', each of which have their
1412 own extensions with some backwards compatibility.
1414 Sparse files were `tar'red as sparse files (which you can easily
1415 test, because the resulting archive gets smaller, and GNU `cpio' can no
1419 File: tar.info, Node: Media, Next: Reliability and security, Prev: Formats, Up: Top
1421 9 Tapes and Other Archive Media
1422 *******************************
1424 _(This message will disappear, once this node revised.)_
1426 A few special cases about tape handling warrant more detailed
1427 description. These special cases are discussed below.
1429 Many complexities surround the use of `tar' on tape drives. Since
1430 the creation and manipulation of archives located on magnetic tape was
1431 the original purpose of `tar', it contains many features making such
1432 manipulation easier.
1434 Archives are usually written on dismountable media--tape cartridges,
1435 mag tapes, or floppy disks.
1437 The amount of data a tape or disk holds depends not only on its size,
1438 but also on how it is formatted. A 2400 foot long reel of mag tape
1439 holds 40 megabytes of data when formatted at 1600 bits per inch. The
1440 physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
1442 Magnetic media are re-usable--once the archive on a tape is no longer
1443 needed, the archive can be erased and the tape or disk used over.
1444 Media quality does deteriorate with use, however. Most tapes or disks
1445 should be discarded when they begin to produce data errors. EXABYTE
1446 tape cartridges should be discarded when they generate an "error count"
1447 (number of non-usable bits) of more than 10k.
1449 Magnetic media are written and erased using magnetic fields, and
1450 should be protected from such fields to avoid damage to stored data.
1451 Sticking a floppy disk to a filing cabinet using a magnet is probably
1456 * Device:: Device selection and switching
1457 * Remote Tape Server::
1458 * Common Problems and Solutions::
1459 * Blocking:: Blocking
1460 * Many:: Many archives on one tape
1461 * Using Multiple Tapes:: Using Multiple Tapes
1462 * label:: Including a Label in the Archive
1464 * Write Protection::
1467 File: tar.info, Node: Device, Next: Remote Tape Server, Up: Media
1469 9.1 Device Selection and Switching
1470 ==================================
1472 _(This message will disappear, once this node revised.)_
1474 `-f [HOSTNAME:]FILE'
1475 `--file=[HOSTNAME:]FILE'
1476 Use archive file or device FILE on HOSTNAME.
1478 This option is used to specify the file name of the archive `tar'
1481 If the file name is `-', `tar' reads the archive from standard input
1482 (when listing or extracting), or writes it to standard output (when
1483 creating). If the `-' file name is given when updating an archive,
1484 `tar' will read the original archive from its standard input, and will
1485 write the entire new archive to its standard output.
1487 If the file name contains a `:', it is interpreted as `hostname:file
1488 name'. If the HOSTNAME contains an "at" sign (`@'), it is treated as
1489 `user@hostname:file name'. In either case, `tar' will invoke the
1490 command `rsh' (or `remsh') to start up an `/usr/libexec/rmt' on the
1491 remote machine. If you give an alternate login name, it will be given
1492 to the `rsh'. Naturally, the remote machine must have an executable
1493 `/usr/libexec/rmt'. This program is free software from the University
1494 of California, and a copy of the source code can be found with the
1495 sources for `tar'; it's compiled and installed by default. The exact
1496 path to this utility is determined when configuring the package. It is
1497 `PREFIX/libexec/rmt', where PREFIX stands for your installation prefix.
1498 This location may also be overridden at runtime by using the
1499 `--rmt-command=COMMAND' option (*Note --rmt-command: Option Summary,
1500 for detailed description of this option. *Note Remote Tape Server::,
1501 for the description of `rmt' command).
1503 If this option is not given, but the environment variable `TAPE' is
1504 set, its value is used; otherwise, old versions of `tar' used a default
1505 archive name (which was picked when `tar' was compiled). The default
1506 is normally set up to be the "first" tape drive or other transportable
1507 I/O medium on the system.
1509 Starting with version 1.11.5, GNU `tar' uses standard input and
1510 standard output as the default device, and I will not try anymore
1511 supporting automatic device detection at installation time. This was
1512 failing really in too many cases, it was hopeless. This is now
1513 completely left to the installer to override standard input and
1514 standard output for default device, if this seems preferable. Further,
1515 I think _most_ actual usages of `tar' are done with pipes or disks, not
1516 really tapes, cartridges or diskettes.
1518 Some users think that using standard input and output is running
1519 after trouble. This could lead to a nasty surprise on your screen if
1520 you forget to specify an output file name--especially if you are going
1521 through a network or terminal server capable of buffering large amounts
1522 of output. We had so many bug reports in that area of configuring
1523 default tapes automatically, and so many contradicting requests, that
1524 we finally consider the problem to be portably intractable. We could
1525 of course use something like `/dev/tape' as a default, but this is
1526 _also_ running after various kind of trouble, going from hung processes
1527 to accidental destruction of real tapes. After having seen all this
1528 mess, using standard input and output as a default really sounds like
1529 the only clean choice left, and a very useful one too.
1531 GNU `tar' reads and writes archive in records, I suspect this is the
1532 main reason why block devices are preferred over character devices.
1533 Most probably, block devices are more efficient too. The installer
1534 could also check for `DEFTAPE' in `<sys/mtio.h>'.
1537 Archive file is local even if it contains a colon.
1539 `--rsh-command=COMMAND'
1540 Use remote COMMAND instead of `rsh'. This option exists so that
1541 people who use something other than the standard `rsh' (e.g., a
1542 Kerberized `rsh') can access a remote device.
1544 When this command is not used, the shell command found when the
1545 `tar' program was installed is used instead. This is the first
1546 found of `/usr/ucb/rsh', `/usr/bin/remsh', `/usr/bin/rsh',
1547 `/usr/bsd/rsh' or `/usr/bin/nsh'. The installer may have
1548 overridden this by defining the environment variable `RSH' _at
1552 Specify drive and density.
1556 Create/list/extract multi-volume archive.
1558 This option causes `tar' to write a "multi-volume" archive--one
1559 that may be larger than will fit on the medium used to hold it.
1560 *Note Multi-Volume Archives::.
1563 `--tape-length=SIZE[SUF]'
1564 Change tape after writing SIZE units of data. Unless SUF is
1565 given, SIZE is treated as kilobytes, i.e. `SIZE x 1024' bytes.
1566 The following suffixes alter this behavior:
1568 Suffix Units Byte Equivalent
1569 --------------------------------------------------------
1571 B Kilobytes SIZE x 1024
1573 G Gigabytes SIZE x 1024^3
1574 K Kilobytes SIZE x 1024
1575 k Kilobytes SIZE x 1024
1576 M Megabytes SIZE x 1024^2
1577 P Petabytes SIZE x 1024^5
1578 T Terabytes SIZE x 1024^4
1581 Table 9.1: Size Suffixes
1583 This option might be useful when your tape drivers do not
1584 properly detect end of physical tapes. By being slightly
1585 conservative on the maximum tape length, you might avoid the
1589 `--info-script=FILE'
1590 `--new-volume-script=FILE'
1591 Execute `file' at end of each tape. This implies
1592 `--multi-volume' (`-M'). *Note info-script::, for a detailed
1593 description of this option.
1596 File: tar.info, Node: Remote Tape Server, Next: Common Problems and Solutions, Prev: Device, Up: Media
1598 9.2 Remote Tape Server
1599 ======================
1601 In order to access the tape drive on a remote machine, `tar' uses the
1602 remote tape server written at the University of California at Berkeley.
1603 The remote tape server must be installed as `PREFIX/libexec/rmt' on any
1604 machine whose tape drive you want to use. `tar' calls `rmt' by running
1605 an `rsh' or `remsh' to the remote machine, optionally using a different
1606 login name if one is supplied.
1608 A copy of the source for the remote tape server is provided. It is
1609 Copyright (C) 1983 by the Regents of the University of California, but
1610 can be freely distributed. It is compiled and installed by default.
1612 Unless you use the `--absolute-names' (`-P') option, GNU `tar' will
1613 not allow you to create an archive that contains absolute file names (a
1614 file name beginning with `/'.) If you try, `tar' will automatically
1615 remove the leading `/' from the file names it stores in the archive.
1616 It will also type a warning message telling you what it is doing.
1618 When reading an archive that was created with a different `tar'
1619 program, GNU `tar' automatically extracts entries in the archive which
1620 have absolute file names as if the file names were not absolute. This
1621 is an important feature. A visitor here once gave a `tar' tape to an
1622 operator to restore; the operator used Sun `tar' instead of GNU `tar',
1623 and the result was that it replaced large portions of our `/bin' and
1624 friends with versions from the tape; needless to say, we were unhappy
1625 about having to recover the file system from backup tapes.
1627 For example, if the archive contained a file `/usr/bin/computoy',
1628 GNU `tar' would extract the file to `usr/bin/computoy', relative to the
1629 current directory. If you want to extract the files in an archive to
1630 the same absolute names that they had when the archive was created, you
1631 should do a `cd /' before extracting the files from the archive, or you
1632 should either use the `--absolute-names' option, or use the command
1635 Some versions of Unix (Ultrix 3.1 is known to have this problem),
1636 can claim that a short write near the end of a tape succeeded, when it
1637 actually failed. This will result in the -M option not working
1638 correctly. The best workaround at the moment is to use a significantly
1639 larger blocking factor than the default 20.
1641 In order to update an archive, `tar' must be able to backspace the
1642 archive in order to reread or rewrite a record that was just read (or
1643 written). This is currently possible only on two kinds of files: normal
1644 disk files (or any other file that can be backspaced with `lseek'), and
1645 industry-standard 9-track magnetic tape (or any other kind of tape that
1646 can be backspaced with the `MTIOCTOP' `ioctl').
1648 This means that the `--append', `--concatenate', and `--delete'
1649 commands will not work on any other kind of file. Some media simply
1650 cannot be backspaced, which means these commands and options will never
1651 be able to work on them. These non-backspacing media include pipes and
1652 cartridge tape drives.
1654 Some other media can be backspaced, and `tar' will work on them once
1655 `tar' is modified to do so.
1657 Archives created with the `--multi-volume', `--label', and
1658 `--incremental' (`-G') options may not be readable by other version of
1659 `tar'. In particular, restoring a file that was split over a volume
1660 boundary will require some careful work with `dd', if it can be done at
1661 all. Other versions of `tar' may also create an empty file whose name
1662 is that of the volume header. Some versions of `tar' may create normal
1663 files instead of directories archived with the `--incremental' (`-G')
1667 File: tar.info, Node: Common Problems and Solutions, Next: Blocking, Prev: Remote Tape Server, Up: Media
1669 9.3 Some Common Problems and their Solutions
1670 ============================================
1674 no such file or directory
1678 directory checksum error
1681 errors from media/system:
1686 File: tar.info, Node: Blocking, Next: Many, Prev: Common Problems and Solutions, Up: Media
1691 "Block" and "record" terminology is rather confused, and it is also
1692 confusing to the expert reader. On the other hand, readers who are new
1693 to the field have a fresh mind, and they may safely skip the next two
1694 paragraphs, as the remainder of this manual uses those two terms in a
1695 quite consistent way.
1697 John Gilmore, the writer of the public domain `tar' from which GNU
1698 `tar' was originally derived, wrote (June 1995):
1700 The nomenclature of tape drives comes from IBM, where I believe
1701 they were invented for the IBM 650 or so. On IBM mainframes, what
1702 is recorded on tape are tape blocks. The logical organization of
1703 data is into records. There are various ways of putting records
1704 into blocks, including `F' (fixed sized records), `V' (variable
1705 sized records), `FB' (fixed blocked: fixed size records, N to a
1706 block), `VB' (variable size records, N to a block), `VSB'
1707 (variable spanned blocked: variable sized records that can occupy
1708 more than one block), etc. The `JCL' `DD RECFORM=' parameter
1709 specified this to the operating system.
1711 The Unix man page on `tar' was totally confused about this. When
1712 I wrote `PD TAR', I used the historically correct terminology
1713 (`tar' writes data records, which are grouped into blocks). It
1714 appears that the bogus terminology made it into POSIX (no surprise
1715 here), and now Franc,ois has migrated that terminology back into
1716 the source code too.
1718 The term "physical block" means the basic transfer chunk from or to
1719 a device, after which reading or writing may stop without anything
1720 being lost. In this manual, the term "block" usually refers to a disk
1721 physical block, _assuming_ that each disk block is 512 bytes in length.
1722 It is true that some disk devices have different physical blocks, but
1723 `tar' ignore these differences in its own format, which is meant to be
1724 portable, so a `tar' block is always 512 bytes in length, and "block"
1725 always mean a `tar' block. The term "logical block" often represents
1726 the basic chunk of allocation of many disk blocks as a single entity,
1727 which the operating system treats somewhat atomically; this concept is
1728 only barely used in GNU `tar'.
1730 The term "physical record" is another way to speak of a physical
1731 block, those two terms are somewhat interchangeable. In this manual,
1732 the term "record" usually refers to a tape physical block, _assuming_
1733 that the `tar' archive is kept on magnetic tape. It is true that
1734 archives may be put on disk or used with pipes, but nevertheless, `tar'
1735 tries to read and write the archive one "record" at a time, whatever
1736 the medium in use. One record is made up of an integral number of
1737 blocks, and this operation of putting many disk blocks into a single
1738 tape block is called "reblocking", or more simply, "blocking". The
1739 term "logical record" refers to the logical organization of many
1740 characters into something meaningful to the application. The term
1741 "unit record" describes a small set of characters which are transmitted
1742 whole to or by the application, and often refers to a line of text.
1743 Those two last terms are unrelated to what we call a "record" in GNU
1746 When writing to tapes, `tar' writes the contents of the archive in
1747 chunks known as "records". To change the default blocking factor, use
1748 the `--blocking-factor=512-SIZE' (`-b 512-SIZE') option. Each record
1749 will then be composed of 512-SIZE blocks. (Each `tar' block is 512
1750 bytes. *Note Standard::.) Each file written to the archive uses at
1751 least one full record. As a result, using a larger record size can
1752 result in more wasted space for small files. On the other hand, a
1753 larger record size can often be read and written much more efficiently.
1755 Further complicating the problem is that some tape drives ignore the
1756 blocking entirely. For these, a larger record size can still improve
1757 performance (because the software layers above the tape drive still
1758 honor the blocking), but not as dramatically as on tape drives that
1761 When reading an archive, `tar' can usually figure out the record
1762 size on itself. When this is the case, and a non-standard record size
1763 was used when the archive was created, `tar' will print a message about
1764 a non-standard blocking factor, and then operate normally. On some
1765 tape devices, however, `tar' cannot figure out the record size itself.
1766 On most of those, you can specify a blocking factor (with
1767 `--blocking-factor') larger than the actual blocking factor, and then
1768 use the `--read-full-records' (`-B') option. (If you specify a
1769 blocking factor with `--blocking-factor' and don't use the
1770 `--read-full-records' option, then `tar' will not attempt to figure out
1771 the recording size itself.) On some devices, you must always specify
1772 the record size exactly with `--blocking-factor' when reading, because
1773 `tar' cannot figure it out. In any case, use `--list' (`-t') before
1774 doing any extractions to see whether `tar' is reading the archive
1777 `tar' blocks are all fixed size (512 bytes), and its scheme for
1778 putting them into records is to put a whole number of them (one or
1779 more) into each record. `tar' records are all the same size; at the
1780 end of the file there's a block containing all zeros, which is how you
1781 tell that the remainder of the last record(s) are garbage.
1783 In a standard `tar' file (no options), the block size is 512 and the
1784 record size is 10240, for a blocking factor of 20. What the
1785 `--blocking-factor' option does is sets the blocking factor, changing
1786 the record size while leaving the block size at 512 bytes. 20 was fine
1787 for ancient 800 or 1600 bpi reel-to-reel tape drives; most tape drives
1788 these days prefer much bigger records in order to stream and not waste
1789 tape. When writing tapes for myself, some tend to use a factor of the
1790 order of 2048, say, giving a record size of around one megabyte.
1792 If you use a blocking factor larger than 20, older `tar' programs
1793 might not be able to read the archive, so we recommend this as a limit
1794 to use in practice. GNU `tar', however, will support arbitrarily large
1795 record sizes, limited only by the amount of virtual memory or the
1796 physical characteristics of the tape device.
1800 * Format Variations:: Format Variations
1801 * Blocking Factor:: The Blocking Factor of an Archive
1804 File: tar.info, Node: Format Variations, Next: Blocking Factor, Up: Blocking
1806 9.4.1 Format Variations
1807 -----------------------
1809 _(This message will disappear, once this node revised.)_
1811 Format parameters specify how an archive is written on the archive
1812 media. The best choice of format parameters will vary depending on the
1813 type and number of files being archived, and on the media used to store
1816 To specify format parameters when accessing or creating an archive,
1817 you can use the options described in the following sections. If you do
1818 not specify any format parameters, `tar' uses default parameters. You
1819 cannot modify a compressed archive. If you create an archive with the
1820 `--blocking-factor' option specified (*note Blocking Factor::), you
1821 must specify that blocking-factor when operating on the archive. *Note
1822 Formats::, for other examples of format parameter considerations.
1825 File: tar.info, Node: Blocking Factor, Prev: Format Variations, Up: Blocking
1827 9.4.2 The Blocking Factor of an Archive
1828 ---------------------------------------
1830 _(This message will disappear, once this node revised.)_
1832 The data in an archive is grouped into blocks, which are 512 bytes.
1833 Blocks are read and written in whole number multiples called "records".
1834 The number of blocks in a record (i.e., the size of a record in units
1835 of 512 bytes) is called the "blocking factor". The
1836 `--blocking-factor=512-SIZE' (`-b 512-SIZE') option specifies the
1837 blocking factor of an archive. The default blocking factor is
1838 typically 20 (i.e., 10240 bytes), but can be specified at installation.
1839 To find out the blocking factor of an existing archive, use `tar --list
1840 --file=ARCHIVE-NAME'. This may not work on some devices.
1842 Records are separated by gaps, which waste space on the archive
1843 media. If you are archiving on magnetic tape, using a larger blocking
1844 factor (and therefore larger records) provides faster throughput and
1845 allows you to fit more data on a tape (because there are fewer gaps).
1846 If you are archiving on cartridge, a very large blocking factor (say
1847 126 or more) greatly increases performance. A smaller blocking factor,
1848 on the other hand, may be useful when archiving small files, to avoid
1849 archiving lots of nulls as `tar' fills out the archive to the end of
1850 the record. In general, the ideal record size depends on the size of
1851 the inter-record gaps on the tape you are using, and the average size
1852 of the files you are archiving. *Note create::, for information on
1855 Archives with blocking factors larger than 20 cannot be read by very
1856 old versions of `tar', or by some newer versions of `tar' running on
1857 old machines with small address spaces. With GNU `tar', the blocking
1858 factor of an archive is limited only by the maximum record size of the
1859 device containing the archive, or by the amount of available virtual
1862 Also, on some systems, not using adequate blocking factors, as
1863 sometimes imposed by the device drivers, may yield unexpected
1864 diagnostics. For example, this has been reported:
1866 Cannot write to /dev/dlt: Invalid argument
1868 In such cases, it sometimes happen that the `tar' bundled by the system
1869 is aware of block size idiosyncrasies, while GNU `tar' requires an
1870 explicit specification for the block size, which it cannot guess. This
1871 yields some people to consider GNU `tar' is misbehaving, because by
1872 comparison, `the bundle `tar' works OK'. Adding `-b 256', for example,
1873 might resolve the problem.
1875 If you use a non-default blocking factor when you create an archive,
1876 you must specify the same blocking factor when you modify that archive.
1877 Some archive devices will also require you to specify the blocking
1878 factor when reading that archive, however this is not typically the
1879 case. Usually, you can use `--list' (`-t') without specifying a
1880 blocking factor--`tar' reports a non-default record size and then lists
1881 the archive members as it would normally. To extract files from an
1882 archive with a non-standard blocking factor (particularly if you're not
1883 sure what the blocking factor is), you can usually use the
1884 `--read-full-records' (`-B') option while specifying a blocking factor
1885 larger then the blocking factor of the archive (i.e., `tar --extract
1886 --read-full-records --blocking-factor=300'). *Note list::, for more
1887 information on the `--list' (`-t') operation. *Note Reading::, for a
1888 more detailed explanation of that option.
1890 `--blocking-factor=NUMBER'
1892 Specifies the blocking factor of an archive. Can be used with any
1893 operation, but is usually not necessary with `--list' (`-t').
1898 `--blocking-factor=BLOCKS'
1899 Set record size to BLOCKS*512 bytes.
1901 This option is used to specify a "blocking factor" for the archive.
1902 When reading or writing the archive, `tar', will do reads and
1903 writes of the archive in records of BLOCK*512 bytes. This is true
1904 even when the archive is compressed. Some devices requires that
1905 all write operations be a multiple of a certain size, and so, `tar'
1906 pads the archive out to the next record boundary.
1908 The default blocking factor is set when `tar' is compiled, and is
1909 typically 20. Blocking factors larger than 20 cannot be read by
1910 very old versions of `tar', or by some newer versions of `tar'
1911 running on old machines with small address spaces.
1913 With a magnetic tape, larger records give faster throughput and fit
1914 more data on a tape (because there are fewer inter-record gaps).
1915 If the archive is in a disk file or a pipe, you may want to specify
1916 a smaller blocking factor, since a large one will result in a large
1917 number of null bytes at the end of the archive.
1919 When writing cartridge or other streaming tapes, a much larger
1920 blocking factor (say 126 or more) will greatly increase
1921 performance. However, you must specify the same blocking factor
1922 when reading or updating the archive.
1924 Apparently, Exabyte drives have a physical block size of 8K bytes.
1925 If we choose our blocksize as a multiple of 8k bytes, then the
1926 problem seems to disappear. Id est, we are using block size of
1927 112 right now, and we haven't had the problem since we switched...
1929 With GNU `tar' the blocking factor is limited only by the maximum
1930 record size of the device containing the archive, or by the amount
1931 of available virtual memory.
1933 However, deblocking or reblocking is virtually avoided in a special
1934 case which often occurs in practice, but which requires all the
1935 following conditions to be simultaneously true:
1936 * the archive is subject to a compression option,
1938 * the archive is not handled through standard input or output,
1939 nor redirected nor piped,
1941 * the archive is directly handled to a local disk, instead of
1944 * `--blocking-factor' is not explicitly specified on the `tar'
1947 If the output goes directly to a local disk, and not through
1948 stdout, then the last write is not extended to a full record size.
1949 Otherwise, reblocking occurs. Here are a few other remarks on this
1952 * `gzip' will complain about trailing garbage if asked to
1953 uncompress a compressed archive on tape, there is an option
1954 to turn the message off, but it breaks the regularity of
1955 simply having to use `PROG -d' for decompression. It would
1956 be nice if gzip was silently ignoring any number of trailing
1957 zeros. I'll ask Jean-loup Gailly, by sending a copy of this
1960 * `compress' does not show this problem, but as Jean-loup
1961 pointed out to Michael, `compress -d' silently adds garbage
1962 after the result of decompression, which tar ignores because
1963 it already recognized its end-of-file indicator. So this bug
1964 may be safely ignored.
1966 * `gzip -d -q' will be silent about the trailing zeros indeed,
1967 but will still return an exit status of 2 which tar reports
1968 in turn. `tar' might ignore the exit status returned, but I
1969 hate doing that, as it weakens the protection `tar' offers
1970 users against other possible problems at decompression time.
1971 If `gzip' was silently skipping trailing zeros _and_ also
1972 avoiding setting the exit status in this innocuous case, that
1973 would solve this situation.
1975 * `tar' should become more solid at not stopping to read a pipe
1976 at the first null block encountered. This inelegantly breaks
1977 the pipe. `tar' should rather drain the pipe out before
1982 Ignore blocks of zeros in archive (means EOF).
1984 The `--ignore-zeros' (`-i') option causes `tar' to ignore blocks
1985 of zeros in the archive. Normally a block of zeros indicates the
1986 end of the archive, but when reading a damaged archive, or one
1987 which was created by concatenating several archives together, this
1988 option allows `tar' to read the entire archive. This option is
1989 not on by default because many versions of `tar' write garbage
1990 after the zeroed blocks.
1992 Note that this option causes `tar' to read to the end of the
1993 archive file, which may sometimes avoid problems when multiple
1994 files are stored on a single physical tape.
1997 `--read-full-records'
1998 Reblock as we read (for reading 4.2BSD pipes).
2000 If `--read-full-records' is used, `tar' will not panic if an
2001 attempt to read a record from the archive does not return a full
2002 record. Instead, `tar' will keep reading until it has obtained a
2005 This option is turned on by default when `tar' is reading an
2006 archive from standard input, or from a remote machine. This is
2007 because on BSD Unix systems, a read of a pipe will return however
2008 much happens to be in the pipe, even if it is less than `tar'
2009 requested. If this option was not used, `tar' would fail as soon
2010 as it read an incomplete record from the pipe.
2012 This option is also useful with the commands for updating an
2018 When handling various tapes or cartridges, you have to take care of
2019 selecting a proper blocking, that is, the number of disk blocks you put
2020 together as a single tape block on the tape, without intervening tape
2021 gaps. A "tape gap" is a small landing area on the tape with no
2022 information on it, used for decelerating the tape to a full stop, and
2023 for later regaining the reading or writing speed. When the tape driver
2024 starts reading a record, the record has to be read whole without
2025 stopping, as a tape gap is needed to stop the tape motion without
2028 Using higher blocking (putting more disk blocks per tape block) will
2029 use the tape more efficiently as there will be less tape gaps. But
2030 reading such tapes may be more difficult for the system, as more memory
2031 will be required to receive at once the whole record. Further, if
2032 there is a reading error on a huge record, this is less likely that the
2033 system will succeed in recovering the information. So, blocking should
2034 not be too low, nor it should be too high. `tar' uses by default a
2035 blocking of 20 for historical reasons, and it does not really matter
2036 when reading or writing to disk. Current tape technology would easily
2037 accommodate higher blockings. Sun recommends a blocking of 126 for
2038 Exabytes and 96 for DATs. We were told that for some DLT drives, the
2039 blocking should be a multiple of 4Kb, preferably 64Kb (`-b 128') or 256
2040 for decent performance. Other manufacturers may use different
2041 recommendations for the same tapes. This might also depends of the
2042 buffering techniques used inside modern tape controllers. Some imposes
2043 a minimum blocking, or a maximum blocking. Others request blocking to
2044 be some exponent of two.
2046 So, there is no fixed rule for blocking. But blocking at read time
2047 should ideally be the same as blocking used at write time. At one place
2048 I know, with a wide variety of equipment, they found it best to use a
2049 blocking of 32 to guarantee that their tapes are fully interchangeable.
2051 I was also told that, for recycled tapes, prior erasure (by the same
2052 drive unit that will be used to create the archives) sometimes lowers
2053 the error rates observed at rewriting time.
2055 I might also use `--number-blocks' instead of `--block-number', so
2056 `--block' will then expand to `--blocking-factor' unambiguously.
2059 File: tar.info, Node: Many, Next: Using Multiple Tapes, Prev: Blocking, Up: Media
2061 9.5 Many Archives on One Tape
2062 =============================
2064 Most tape devices have two entries in the `/dev' directory, or entries
2065 that come in pairs, which differ only in the minor number for this
2066 device. Let's take for example `/dev/tape', which often points to the
2067 only or usual tape device of a given system. There might be a
2068 corresponding `/dev/nrtape' or `/dev/ntape'. The simpler name is the
2069 _rewinding_ version of the device, while the name having `nr' in it is
2070 the _no rewinding_ version of the same device.
2072 A rewinding tape device will bring back the tape to its beginning
2073 point automatically when this device is opened or closed. Since `tar'
2074 opens the archive file before using it and closes it afterwards, this
2075 means that a simple:
2077 $ tar cf /dev/tape DIRECTORY
2079 will reposition the tape to its beginning both prior and after saving
2080 DIRECTORY contents to it, thus erasing prior tape contents and making
2081 it so that any subsequent write operation will destroy what has just
2084 So, a rewinding device is normally meant to hold one and only one
2085 file. If you want to put more than one `tar' archive on a given tape,
2086 you will need to avoid using the rewinding version of the tape device.
2087 You will also have to pay special attention to tape positioning.
2088 Errors in positioning may overwrite the valuable data already on your
2089 tape. Many people, burnt by past experiences, will only use rewinding
2090 devices and limit themselves to one file per tape, precisely to avoid
2091 the risk of such errors. Be fully aware that writing at the wrong
2092 position on a tape loses all information past this point and most
2093 probably until the end of the tape, and this destroyed information
2094 _cannot_ be recovered.
2096 To save DIRECTORY-1 as a first archive at the beginning of a tape,
2097 and leave that tape ready for a second archive, you should use:
2099 $ mt -f /dev/nrtape rewind
2100 $ tar cf /dev/nrtape DIRECTORY-1
2102 "Tape marks" are special magnetic patterns written on the tape
2103 media, which are later recognizable by the reading hardware. These
2104 marks are used after each file, when there are many on a single tape.
2105 An empty file (that is to say, two tape marks in a row) signal the
2106 logical end of the tape, after which no file exist. Usually,
2107 non-rewinding tape device drivers will react to the close request issued
2108 by `tar' by first writing two tape marks after your archive, and by
2109 backspacing over one of these. So, if you remove the tape at that time
2110 from the tape drive, it is properly terminated. But if you write
2111 another file at the current position, the second tape mark will be
2112 erased by the new information, leaving only one tape mark between files.
2114 So, you may now save DIRECTORY-2 as a second archive after the first
2115 on the same tape by issuing the command:
2117 $ tar cf /dev/nrtape DIRECTORY-2
2119 and so on for all the archives you want to put on the same tape.
2121 Another usual case is that you do not write all the archives the same
2122 day, and you need to remove and store the tape between two archive
2123 sessions. In general, you must remember how many files are already
2124 saved on your tape. Suppose your tape already has 16 files on it, and
2125 that you are ready to write the 17th. You have to take care of skipping
2126 the first 16 tape marks before saving DIRECTORY-17, say, by using these
2129 $ mt -f /dev/nrtape rewind
2130 $ mt -f /dev/nrtape fsf 16
2131 $ tar cf /dev/nrtape DIRECTORY-17
2133 In all the previous examples, we put aside blocking considerations,
2134 but you should do the proper things for that as well. *Note Blocking::.
2138 * Tape Positioning:: Tape Positions and Tape Marks
2139 * mt:: The `mt' Utility
2142 File: tar.info, Node: Tape Positioning, Next: mt, Up: Many
2144 9.5.1 Tape Positions and Tape Marks
2145 -----------------------------------
2147 _(This message will disappear, once this node revised.)_
2149 Just as archives can store more than one file from the file system,
2150 tapes can store more than one archive file. To keep track of where
2151 archive files (or any other type of file stored on tape) begin and end,
2152 tape archive devices write magnetic "tape marks" on the archive media.
2153 Tape drives write one tape mark between files, two at the end of all
2156 If you think of data as a series of records "rrrr"'s, and tape marks
2157 as "*"'s, a tape might look like the following:
2159 rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
2161 Tape devices read and write tapes using a read/write "tape head"--a
2162 physical part of the device which can only access one point on the tape
2163 at a time. When you use `tar' to read or write archive data from a
2164 tape device, the device will begin reading or writing from wherever on
2165 the tape the tape head happens to be, regardless of which archive or
2166 what part of the archive the tape head is on. Before writing an
2167 archive, you should make sure that no data on the tape will be
2168 overwritten (unless it is no longer needed). Before reading an
2169 archive, you should make sure the tape head is at the beginning of the
2170 archive you want to read. You can do it manually via `mt' utility
2171 (*note mt::). The `restore' script does that automatically (*note
2172 Scripted Restoration::).
2174 If you want to add new archive file entries to a tape, you should
2175 advance the tape to the end of the existing file entries, backspace
2176 over the last tape mark, and write the new archive file. If you were
2177 to add two archives to the example above, the tape might look like the
2180 rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
2183 File: tar.info, Node: mt, Prev: Tape Positioning, Up: Many
2185 9.5.2 The `mt' Utility
2186 ----------------------
2188 _(This message will disappear, once this node revised.)_
2190 *Note Blocking Factor::.
2192 You can use the `mt' utility to advance or rewind a tape past a
2193 specified number of archive files on the tape. This will allow you to
2194 move to the beginning of an archive before extracting or reading it, or
2195 to the end of all the archives before writing a new one.
2197 The syntax of the `mt' command is:
2199 mt [-f TAPENAME] OPERATION [NUMBER]
2201 where TAPENAME is the name of the tape device, NUMBER is the number
2202 of times an operation is performed (with a default of one), and
2203 OPERATION is one of the following:
2207 Writes NUMBER tape marks at the current position on the tape.
2210 Moves tape position forward NUMBER files.
2213 Moves tape position back NUMBER files.
2216 Rewinds the tape. (Ignores NUMBER.)
2220 Rewinds the tape and takes the tape device off-line. (Ignores
2224 Prints status information about the tape unit.
2227 If you don't specify a TAPENAME, `mt' uses the environment variable
2228 `TAPE'; if `TAPE' is not set, `mt' will use the default device
2229 specified in your `sys/mtio.h' file (`DEFTAPE' variable). If this is
2230 not defined, the program will display a descriptive error message and
2233 `mt' returns a 0 exit status when the operation(s) were successful,
2234 1 if the command was unrecognized, and 2 if an operation failed.
2237 File: tar.info, Node: Using Multiple Tapes, Next: label, Prev: Many, Up: Media
2239 9.6 Using Multiple Tapes
2240 ========================
2242 Often you might want to write a large archive, one larger than will fit
2243 on the actual tape you are using. In such a case, you can run multiple
2244 `tar' commands, but this can be inconvenient, particularly if you are
2245 using options like `--exclude=PATTERN' or dumping entire file systems.
2246 Therefore, `tar' provides a special mode for creating multi-volume
2249 "Multi-volume" archive is a single `tar' archive, stored on several
2250 media volumes of fixed size. Although in this section we will often
2251 call `volume' a "tape", there is absolutely no requirement for
2252 multi-volume archives to be stored on tapes. Instead, they can use
2253 whatever media type the user finds convenient, they can even be located
2256 When creating a multi-volume archive, GNU `tar' continues to fill
2257 current volume until it runs out of space, then it switches to next
2258 volume (usually the operator is queried to replace the tape on this
2259 point), and continues working on the new volume. This operation
2260 continues until all requested files are dumped. If GNU `tar' detects
2261 end of media while dumping a file, such a file is archived in split
2262 form. Some very big files can even be split across several volumes.
2264 Each volume is itself a valid GNU `tar' archive, so it can be read
2265 without any special options. Consequently any file member residing
2266 entirely on one volume can be extracted or otherwise operated upon
2267 without needing the other volume. Sure enough, to extract a split
2268 member you would need all volumes its parts reside on.
2270 Multi-volume archives suffer from several limitations. In
2271 particular, they cannot be compressed.
2273 GNU `tar' is able to create multi-volume archives of two formats
2274 (*note Formats::): `GNU' and `POSIX'.
2278 * Multi-Volume Archives:: Archives Longer than One Tape or Disk
2279 * Tape Files:: Tape Files
2280 * Tarcat:: Concatenate Volumes into a Single Archive
2283 File: tar.info, Node: Multi-Volume Archives, Next: Tape Files, Up: Using Multiple Tapes
2285 9.6.1 Archives Longer than One Tape or Disk
2286 -------------------------------------------
2288 To create an archive that is larger than will fit on a single unit of
2289 the media, use the `--multi-volume' (`-M') option in conjunction with
2290 the `--create' option (*note create::). A "multi-volume" archive can
2291 be manipulated like any other archive (provided the `--multi-volume'
2292 option is specified), but is stored on more than one tape or file.
2294 When you specify `--multi-volume', `tar' does not report an error
2295 when it comes to the end of an archive volume (when reading), or the
2296 end of the media (when writing). Instead, it prompts you to load a new
2297 storage volume. If the archive is on a magnetic tape, you should
2298 change tapes when you see the prompt; if the archive is on a floppy
2299 disk, you should change disks; etc.
2303 Creates a multi-volume archive, when used in conjunction with
2304 `--create' (`-c'). To perform any other operation on a
2305 multi-volume archive, specify `--multi-volume' in conjunction with
2306 that operation. For example:
2308 $ tar --create --multi-volume --file=/dev/tape FILES
2310 The method `tar' uses to detect end of tape is not perfect, and
2311 fails on some operating systems or on some devices. If `tar' cannot
2312 detect the end of the tape itself, you can use `--tape-length' option
2313 to inform it about the capacity of the tape:
2315 `--tape-length=SIZE[SUF]'
2317 Set maximum length of a volume. The SUF, if given, specifies
2318 units in which SIZE is expressed, e.g. `2M' mean 2 megabytes
2319 (*note Table 9.1: size-suffixes, for a list of allowed size
2320 suffixes). Without SUF, units of 1024 bytes (kilobyte) are
2323 This option selects `--multi-volume' automatically. For example:
2325 $ tar --create --tape-length=41943040 --file=/dev/tape FILES
2327 or, which is equivalent:
2329 $ tar --create --tape-length=4G --file=/dev/tape FILES
2331 When GNU `tar' comes to the end of a storage media, it asks you to
2332 change the volume. The built-in prompt for POSIX locale is(1):
2334 Prepare volume #N for `ARCHIVE' and hit return:
2336 where N is the ordinal number of the volume to be created and ARCHIVE
2337 is archive file or device name.
2339 When prompting for a new tape, `tar' accepts any of the following
2343 Request `tar' to explain possible responses.
2346 Request `tar' to exit immediately.
2349 Request `tar' to write the next volume on the file FILE-NAME.
2352 Request `tar' to run a subshell. This option can be disabled by
2353 giving `--restrict' command line option to `tar'(2).
2356 Request `tar' to begin writing the next volume.
2358 (You should only type `y' after you have changed the tape; otherwise
2359 `tar' will write over the volume it just finished.)
2361 The volume number used by `tar' in its tape-changing prompt can be
2362 changed; if you give the `--volno-file=FILE-OF-NUMBER' option, then
2363 FILE-OF-NUMBER should be an non-existing file to be created, or else, a
2364 file already containing a decimal number. That number will be used as
2365 the volume number of the first volume written. When `tar' is finished,
2366 it will rewrite the file with the now-current volume number. (This does
2367 not change the volume number written on a tape label, as per *note
2368 label::, it _only_ affects the number used in the prompt.)
2370 If you want more elaborate behavior than this, you can write a
2371 special "new volume script", that will be responsible for changing the
2372 volume, and instruct `tar' to use it instead of its normal prompting
2375 `--info-script=SCRIPT-NAME'
2376 `--new-volume-script=SCRIPT-NAME'
2378 Specify the full name of the volume script to use. The script can
2379 be used to eject cassettes, or to broadcast messages such as
2380 `Someone please come change my tape' when performing unattended
2383 The SCRIPT-NAME is executed without any command line arguments. It
2384 inherits `tar''s shell environment. Additional data is passed to it
2385 via the following environment variables:
2388 GNU `tar' version number.
2391 The name of the archive `tar' is processing.
2393 `TAR_BLOCKING_FACTOR'
2394 Current blocking factor (*note Blocking::).
2397 Ordinal number of the volume `tar' is about to start.
2400 A short option describing the operation `tar' is executing. *Note
2401 Operations::, for a complete list of subcommand options.
2404 Format of the archive being processed. *Note Formats::, for a
2405 complete list of archive format names.
2408 File descriptor which can be used to communicate the new volume
2411 The volume script can instruct `tar' to use new archive name, by
2412 writing in to file descriptor `$TAR_FD' (see below for an example).
2414 If the info script fails, `tar' exits; otherwise, it begins writing
2417 If you want `tar' to cycle through a series of files or tape drives,
2418 there are three approaches to choose from. First of all, you can give
2419 `tar' multiple `--file' options. In this case the specified files will
2420 be used, in sequence, as the successive volumes of the archive. Only
2421 when the first one in the sequence needs to be used again will `tar'
2422 prompt for a tape change (or run the info script). For example,
2423 suppose someone has two tape drives on a system named `/dev/tape0' and
2424 `/dev/tape1'. For having GNU `tar' to switch to the second drive when
2425 it needs to write the second tape, and then back to the first tape,
2426 etc., just do either of:
2428 $ tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 FILES
2429 $ tar cMff /dev/tape0 /dev/tape1 FILES
2431 The second method is to use the `n' response to the tape-change
2434 Finally, the most flexible approach is to use a volume script, that
2435 writes new archive name to the file descriptor `$TAR_FD'. For example,
2436 the following volume script will create a series of archive files, named
2437 `ARCHIVE-VOL', where ARCHIVE is the name of the archive being created
2438 (as given by `--file' option) and VOL is the ordinal number of the
2439 archive being created:
2442 echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
2444 name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
2445 case $TAR_SUBCOMMAND in
2447 -d|-x|-t) test -r ${name:-$TAR_ARCHIVE}-$TAR_VOLUME || exit 1
2452 echo ${name:-$TAR_ARCHIVE}-$TAR_VOLUME >&$TAR_FD
2454 The same script can be used while listing, comparing or extracting
2455 from the created archive. For example:
2457 # Create a multi-volume archive:
2458 $ tar -c -L1024 -f archive.tar -F new-volume .
2459 # Extract from the created archive:
2460 $ tar -x -f archive.tar -F new-volume .
2462 Notice, that the first command had to use `-L' option, since otherwise
2463 GNU `tar' will end up writing everything to file `archive.tar'.
2465 You can read each individual volume of a multi-volume archive as if
2466 it were an archive by itself. For example, to list the contents of one
2467 volume, use `--list', without `--multi-volume' specified. To extract
2468 an archive member from one volume (assuming it is described that
2469 volume), use `--extract', again without `--multi-volume'.
2471 If an archive member is split across volumes (i.e., its entry begins
2472 on one volume of the media and ends on another), you need to specify
2473 `--multi-volume' to extract it successfully. In this case, you should
2474 load the volume where the archive member starts, and use `tar --extract
2475 --multi-volume'--`tar' will prompt for later volumes as it needs them.
2476 *Note extracting archives::, for more information about extracting
2479 Multi-volume archives can be modified like any other archive. To add
2480 files to a multi-volume archive, you need to only mount the last volume
2481 of the archive media (and new volumes, if needed). For all other
2482 operations, you need to use the entire archive.
2484 If a multi-volume archive was labeled using `--label=ARCHIVE-LABEL'
2485 (*note label::) when it was created, `tar' will not automatically label
2486 volumes which are added later. To label subsequent volumes, specify
2487 `--label=ARCHIVE-LABEL' again in conjunction with the `--append',
2488 `--update' or `--concatenate' operation.
2490 Notice that multi-volume support is a GNU extension and the archives
2491 created in this mode should be read only using GNU `tar'. If you
2492 absolutely have to process such archives using a third-party `tar'
2493 implementation, read *note Split Recovery::.
2495 ---------- Footnotes ----------
2497 (1) If you run GNU `tar' under a different locale, the translation
2498 to the locale's language will be used.
2500 (2) *Note --restrict::, for more information about this option.
2503 File: tar.info, Node: Tape Files, Next: Tarcat, Prev: Multi-Volume Archives, Up: Using Multiple Tapes
2508 _(This message will disappear, once this node revised.)_
2510 To give the archive a name which will be recorded in it, use the
2511 `--label=VOLUME-LABEL' (`-V VOLUME-LABEL') option. This will write a
2512 special block identifying VOLUME-LABEL as the name of the archive to
2513 the front of the archive which will be displayed when the archive is
2514 listed with `--list'. If you are creating a multi-volume archive with
2515 `--multi-volume' (*note Using Multiple Tapes::), then the volume label
2516 will have `Volume NNN' appended to the name you give, where NNN is the
2517 number of the volume of the archive. If you use the
2518 `--label=VOLUME-LABEL' option when reading an archive, it checks to
2519 make sure the label on the tape matches the one you gave. *Note
2522 When `tar' writes an archive to tape, it creates a single tape file.
2523 If multiple archives are written to the same tape, one after the other,
2524 they each get written as separate tape files. When extracting, it is
2525 necessary to position the tape at the right place before running `tar'.
2526 To do this, use the `mt' command. For more information on the `mt'
2527 command and on the organization of tapes into a sequence of tape files,
2530 People seem to often do:
2532 --label="SOME-PREFIX `date +SOME-FORMAT`"
2534 or such, for pushing a common date in all volumes or an archive set.
2537 File: tar.info, Node: Tarcat, Prev: Tape Files, Up: Using Multiple Tapes
2539 9.6.3 Concatenate Volumes into a Single Archive
2540 -----------------------------------------------
2542 Sometimes it is necessary to convert existing GNU `tar' multi-volume
2543 archive to a single `tar' archive. Simply concatenating all volumes
2544 into one will not work, since each volume carries an additional
2545 information at the beginning. GNU `tar' is shipped with the shell
2546 script `tarcat' designed for this purpose.
2548 The script takes a list of files comprising a multi-volume archive
2549 and creates the resulting archive at the standard output. For example:
2551 tarcat vol.1 vol.2 vol.3 | tar tf -
2553 The script implements a simple heuristics to determine the format of
2554 the first volume file and to decide how to process the rest of the
2555 files. However, it makes no attempt to verify whether the files are
2556 given in order or even if they are valid `tar' archives. It uses `dd'
2557 and does not filter its standard error, so you will usually see lots of
2561 File: tar.info, Node: label, Next: verify, Prev: Using Multiple Tapes, Up: Media
2563 9.7 Including a Label in the Archive
2564 ====================================
2566 To avoid problems caused by misplaced paper labels on the archive
2567 media, you can include a "label" entry -- an archive member which
2568 contains the name of the archive -- in the archive itself. Use the
2569 `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') option(1) in conjunction
2570 with the `--create' operation to include a label entry in the archive
2571 as it is being created.
2573 `--label=ARCHIVE-LABEL'
2575 Includes an "archive-label" at the beginning of the archive when
2576 the archive is being created, when used in conjunction with the
2577 `--create' operation. Checks to make sure the archive label
2578 matches the one specified (when used in conjunction with any other
2581 If you create an archive using both `--label=ARCHIVE-LABEL' (`-V
2582 ARCHIVE-LABEL') and `--multi-volume' (`-M'), each volume of the archive
2583 will have an archive label of the form `ARCHIVE-LABEL Volume N', where
2584 N is 1 for the first volume, 2 for the next, and so on. *Note Using
2585 Multiple Tapes::, for information on creating multiple volume archives.
2587 The volume label will be displayed by `--list' along with the file
2588 contents. If verbose display is requested, it will also be explicitly
2589 marked as in the example below:
2591 $ tar --verbose --list --file=iamanarchive
2592 V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
2593 -rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename
2595 However, `--list' option will cause listing entire contents of the
2596 archive, which may be undesirable (for example, if the archive is
2597 stored on a tape). You can request checking only the volume label by
2598 specifying `--test-label' option. This option reads only the first
2599 block of an archive, so it can be used with slow storage devices. For
2602 $ tar --test-label --file=iamanarchive
2605 If `--test-label' is used with one or more command line arguments,
2606 `tar' compares the volume label with each argument. It exits with code
2607 0 if a match is found, and with code 1 otherwise(2). No output is
2608 displayed, unless you also used the `--verbose' option. For example:
2610 $ tar --test-label --file=iamanarchive 'iamalabel'
2612 $ tar --test-label --file=iamanarchive 'alabel'
2615 When used with the `--verbose' option, `tar' prints the actual
2616 volume label (if any), and a verbose diagnostics in case of a mismatch:
2618 $ tar --test-label --verbose --file=iamanarchive 'iamalabel'
2621 $ tar --test-label --verbose --file=iamanarchive 'alabel'
2623 tar: Archive label mismatch
2626 If you request any operation, other than `--create', along with
2627 using `--label' option, `tar' will first check if the archive label
2628 matches the one specified and will refuse to proceed if it does not.
2629 Use this as a safety precaution to avoid accidentally overwriting
2630 existing archives. For example, if you wish to add files to `archive',
2631 presumably labeled with string `My volume', you will get:
2633 $ tar -rf archive --label 'My volume' .
2634 tar: Archive not labeled to match `My volume'
2636 in case its label does not match. This will work even if `archive' is
2639 Similarly, `tar' will refuse to list or extract the archive if its
2640 label doesn't match the ARCHIVE-LABEL specified. In those cases,
2641 ARCHIVE-LABEL argument is interpreted as a globbing-style pattern which
2642 must match the actual magnetic volume label. *Note exclude::, for a
2643 precise description of how match is attempted(3). If the switch
2644 `--multi-volume' (`-M') is being used, the volume label matcher will
2645 also suffix ARCHIVE-LABEL by ` Volume [1-9]*' if the initial match
2646 fails, before giving up. Since the volume numbering is automatically
2647 added in labels at creation time, it sounded logical to equally help
2648 the user taking care of it when the archive is being read.
2650 You can also use `--label' to get a common information on all tapes
2651 of a series. For having this information different in each series
2652 created through a single script used on a regular basis, just manage to
2653 get some date string as part of the label. For example:
2655 $ tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"
2656 $ tar --create --file=/dev/tape --multi-volume \
2657 --label="Daily backup for `date +%Y-%m-%d`"
2659 Some more notes about volume labels:
2661 * Each label has its own date and time, which corresponds to the
2662 time when GNU `tar' initially attempted to write it, often soon
2663 after the operator launches `tar' or types the carriage return
2664 telling that the next tape is ready.
2666 * Comparing date labels to get an idea of tape throughput is
2667 unreliable. It gives correct results only if the delays for
2668 rewinding tapes and the operator switching them were negligible,
2669 which is usually not the case.
2671 ---------- Footnotes ----------
2673 (1) Until version 1.10, that option was called `--volume', but is
2674 not available under that name anymore.
2676 (2) Note that GNU `tar' versions up to 1.23 indicated mismatch with
2677 an exit code 2 and printed a spurious diagnostics on stderr.
2679 (3) Previous versions of `tar' used full regular expression
2680 matching, or before that, only exact string matching, instead of
2681 wildcard matchers. We decided for the sake of simplicity to use a
2682 uniform matching device through `tar'.
2685 File: tar.info, Node: verify, Next: Write Protection, Prev: label, Up: Media
2687 9.8 Verifying Data as It is Stored
2688 ==================================
2692 Attempt to verify the archive after writing.
2694 This option causes `tar' to verify the archive after writing it.
2695 Each volume is checked after it is written, and any discrepancies are
2696 recorded on the standard error output.
2698 Verification requires that the archive be on a back-space-able
2699 medium. This means pipes, some cartridge tape drives, and some other
2700 devices cannot be verified.
2702 You can insure the accuracy of an archive by comparing files in the
2703 system with archive members. `tar' can compare an archive to the file
2704 system as the archive is being written, to verify a write operation, or
2705 can compare a previously written archive, to insure that it is up to
2708 To check for discrepancies in an archive immediately after it is
2709 written, use the `--verify' (`-W') option in conjunction with the
2710 `--create' operation. When this option is specified, `tar' checks
2711 archive members against their counterparts in the file system, and
2712 reports discrepancies on the standard error.
2714 To verify an archive, you must be able to read it from before the end
2715 of the last written entry. This option is useful for detecting data
2716 errors on some tapes. Archives written to pipes, some cartridge tape
2717 drives, and some other devices cannot be verified.
2719 One can explicitly compare an already made archive with the file
2720 system by using the `--compare' (`--diff', `-d') option, instead of
2721 using the more automatic `--verify' option. *Note compare::.
2723 Note that these two options have a slightly different intent. The
2724 `--compare' option checks how identical are the logical contents of some
2725 archive with what is on your disks, while the `--verify' option is
2726 really for checking if the physical contents agree and if the recording
2727 media itself is of dependable quality. So, for the `--verify'
2728 operation, `tar' tries to defeat all in-memory cache pertaining to the
2729 archive, while it lets the speed optimization undisturbed for the
2730 `--compare' option. If you nevertheless use `--compare' for media
2731 verification, you may have to defeat the in-memory cache yourself,
2732 maybe by opening and reclosing the door latch of your recording unit,
2733 forcing some doubt in your operating system about the fact this is
2734 really the same volume as the one just written or read.
2736 The `--verify' option would not be necessary if drivers were indeed
2737 able to detect dependably all write failures. This sometimes require
2738 many magnetic heads, some able to read after the writes occurred. One
2739 would not say that drivers unable to detect all cases are necessarily
2740 flawed, as long as programming is concerned.
2742 The `--verify' (`-W') option will not work in conjunction with the
2743 `--multi-volume' (`-M') option or the `--append' (`-r'), `--update'
2744 (`-u') and `--delete' operations. *Note Operations::, for more
2745 information on these operations.
2747 Also, since `tar' normally strips leading `/' from file names (*note
2748 absolute::), a command like `tar --verify -cf /tmp/foo.tar /etc' will
2749 work as desired only if the working directory is `/', as `tar' uses the
2750 archive's relative member names (e.g., `etc/motd') when verifying the
2754 File: tar.info, Node: Write Protection, Prev: verify, Up: Media
2756 9.9 Write Protection
2757 ====================
2759 Almost all tapes and diskettes, and in a few rare cases, even disks can
2760 be "write protected", to protect data on them from being changed. Once
2761 an archive is written, you should write protect the media to prevent
2762 the archive from being accidentally overwritten or deleted. (This will
2763 protect the archive from being changed with a tape or floppy drive--it
2764 will not protect it from magnet fields or other physical hazards.)
2766 The write protection device itself is usually an integral part of the
2767 physical media, and can be a two position (write enabled/write
2768 disabled) switch, a notch which can be popped out or covered, a ring
2769 which can be removed from the center of a tape reel, or some other
2773 File: tar.info, Node: Reliability and security, Next: Changes, Prev: Media, Up: Top
2775 10 Reliability and Security
2776 ***************************
2778 The `tar' command reads and writes files as any other application does,
2779 and is subject to the usual caveats about reliability and security.
2780 This section contains some commonsense advice on the topic.
2788 File: tar.info, Node: Reliability, Next: Security, Up: Reliability and security
2793 Ideally, when `tar' is creating an archive, it reads from a file system
2794 that is not being modified, and encounters no errors or inconsistencies
2795 while reading and writing. If this is the case, the archive should
2796 faithfully reflect what was read. Similarly, when extracting from an
2797 archive, ideally `tar' ideally encounters no errors and the extracted
2798 files faithfully reflect what was in the archive.
2800 However, when reading or writing real-world file systems, several
2801 things can go wrong; these include permissions problems, corruption of
2802 data, and race conditions.
2806 * Permissions problems::
2807 * Data corruption and repair::
2811 File: tar.info, Node: Permissions problems, Next: Data corruption and repair, Up: Reliability
2813 10.1.1 Permissions Problems
2814 ---------------------------
2816 If `tar' encounters errors while reading or writing files, it normally
2817 reports an error and exits with nonzero status. The work it does may
2818 therefore be incomplete. For example, when creating an archive, if
2819 `tar' cannot read a file then it cannot copy the file into the archive.
2822 File: tar.info, Node: Data corruption and repair, Next: Race conditions, Prev: Permissions problems, Up: Reliability
2824 10.1.2 Data Corruption and Repair
2825 ---------------------------------
2827 If an archive becomes corrupted by an I/O error, this may corrupt the
2828 data in an extracted file. Worse, it may corrupt the file's metadata,
2829 which may cause later parts of the archive to become misinterpreted.
2830 An tar-format archive contains a checksum that most likely will detect
2831 errors in the metadata, but it will not detect errors in the data.
2833 If data corruption is a concern, you can compute and check your own
2834 checksums of an archive by using other programs, such as `cksum'.
2836 When attempting to recover from a read error or data corruption in an
2837 archive, you may need to skip past the questionable data and read the
2838 rest of the archive. This requires some expertise in the archive
2839 format and in other software tools.
2842 File: tar.info, Node: Race conditions, Prev: Data corruption and repair, Up: Reliability
2844 10.1.3 Race conditions
2845 ----------------------
2847 If some other process is modifying the file system while `tar' is
2848 reading or writing files, the result may well be inconsistent due to
2849 race conditions. For example, if another process creates some files in
2850 a directory while `tar' is creating an archive containing the
2851 directory's files, `tar' may see some of the files but not others, or
2852 it may see a file that is in the process of being created. The
2853 resulting archive may not be a snapshot of the file system at any point
2854 in time. If an application such as a database system depends on an
2855 accurate snapshot, restoring from the `tar' archive of a live file
2856 system may therefore break that consistency and may break the
2857 application. The simplest way to avoid the consistency issues is to
2858 avoid making other changes to the file system while tar is reading it
2861 When creating an archive, several options are available to avoid race
2862 conditions. Some hosts have a way of snapshotting a file system, or of
2863 temporarily suspending all changes to a file system, by (say)
2864 suspending the only virtual machine that can modify a file system; if
2865 you use these facilities and have `tar -c' read from a snapshot when
2866 creating an archive, you can avoid inconsistency problems. More
2867 drastically, before starting `tar' you could suspend or shut down all
2868 processes other than `tar' that have access to the file system, or you
2869 could unmount the file system and then mount it read-only.
2871 When extracting from an archive, one approach to avoid race
2872 conditions is to create a directory that no other process can write to,
2873 and extract into that.
2876 File: tar.info, Node: Security, Prev: Reliability, Up: Reliability and security
2881 In some cases `tar' may be used in an adversarial situation, where an
2882 untrusted user is attempting to gain information about or modify
2883 otherwise-inaccessible files. Dealing with untrusted data (that is,
2884 data generated by an untrusted user) typically requires extra care,
2885 because even the smallest mistake in the use of `tar' is more likely to
2886 be exploited by an adversary than by a race condition.
2892 * Live untrusted data::
2893 * Security rules of thumb::
2896 File: tar.info, Node: Privacy, Next: Integrity, Up: Security
2901 Standard privacy concerns apply when using `tar'. For example, suppose
2902 you are archiving your home directory into a file
2903 `/archive/myhome.tar'. Any secret information in your home directory,
2904 such as your SSH secret keys, are copied faithfully into the archive.
2905 Therefore, if your home directory contains any file that should not be
2906 read by some other user, the archive itself should be not be readable
2907 by that user. And even if the archive's data are inaccessible to
2908 untrusted users, its metadata (such as size or last-modified date) may
2909 reveal some information about your home directory; if the metadata are
2910 intended to be private, the archive's parent directory should also be
2911 inaccessible to untrusted users.
2913 One precaution is to create `/archive' so that it is not accessible
2914 to any user, unless that user also has permission to access all the
2915 files in your home directory.
2917 Similarly, when extracting from an archive, take care that the
2918 permissions of the extracted files are not more generous than what you
2919 want. Even if the archive itself is readable only to you, files
2920 extracted from it have their own permissions that may differ.
2923 File: tar.info, Node: Integrity, Next: Live untrusted data, Prev: Privacy, Up: Security
2928 When creating archives, take care that they are not writable by a
2929 untrusted user; otherwise, that user could modify the archive, and when
2930 you later extract from the archive you will get incorrect data.
2932 When `tar' extracts from an archive, by default it writes into files
2933 relative to the working directory. If the archive was generated by an
2934 untrusted user, that user therefore can write into any file under the
2935 working directory. If the working directory contains a symbolic link
2936 to another directory, the untrusted user can also write into any file
2937 under the referenced directory. When extracting from an untrusted
2938 archive, it is therefore good practice to create an empty directory and
2939 run `tar' in that directory.
2941 When extracting from two or more untrusted archives, each one should
2942 be extracted independently, into different empty directories.
2943 Otherwise, the first archive could create a symbolic link into an area
2944 outside the working directory, and the second one could follow the link
2945 and overwrite data that is not under the working directory. For
2946 example, when restoring from a series of incremental dumps, the
2947 archives should have been created by a trusted process, as otherwise
2948 the incremental restores might alter data outside the working directory.
2950 If you use the `--absolute-names' (`-P') option when extracting,
2951 `tar' respects any file names in the archive, even file names that
2952 begin with `/' or contain `..'. As this lets the archive overwrite any
2953 file in your system that you can write, the `--absolute-names' (`-P')
2954 option should be used only for trusted archives.
2956 Conversely, with the `--keep-old-files' (`-k') option, `tar' refuses
2957 to replace existing files when extracting; and with the
2958 `--no-overwrite-dir' option, `tar' refuses to replace the permissions
2959 or ownership of already-existing directories. These options may help
2960 when extracting from untrusted archives.
2963 File: tar.info, Node: Live untrusted data, Next: Security rules of thumb, Prev: Integrity, Up: Security
2965 10.2.3 Dealing with Live Untrusted Data
2966 ---------------------------------------
2968 Extra care is required when creating from or extracting into a file
2969 system that is accessible to untrusted users. For example, superusers
2970 who invoke `tar' must be wary about its actions being hijacked by an
2971 adversary who is reading or writing the file system at the same time
2972 that `tar' is operating.
2974 When creating an archive from a live file system, `tar' is
2975 vulnerable to denial-of-service attacks. For example, an adversarial
2976 user could create the illusion of an indefinitely-deep directory
2977 hierarchy `d/e/f/g/...' by creating directories one step ahead of
2978 `tar', or the illusion of an indefinitely-long file by creating a
2979 sparse file but arranging for blocks to be allocated just before `tar'
2980 reads them. There is no easy way for `tar' to distinguish these
2981 scenarios from legitimate uses, so you may need to monitor `tar', just
2982 as you'd need to monitor any other system service, to detect such
2985 While a superuser is extracting from an archive into a live file
2986 system, an untrusted user might replace a directory with a symbolic
2987 link, in hopes that `tar' will follow the symbolic link and extract
2988 data into files that the untrusted user does not have access to. Even
2989 if the archive was generated by the superuser, it may contain a file
2990 such as `d/etc/passwd' that the untrusted user earlier created in order
2991 to break in; if the untrusted user replaces the directory `d/etc' with
2992 a symbolic link to `/etc' while `tar' is running, `tar' will overwrite
2993 `/etc/passwd'. This attack can be prevented by extracting into a
2994 directory that is inaccessible to untrusted users.
2996 Similar attacks via symbolic links are also possible when creating an
2997 archive, if the untrusted user can modify an ancestor of a top-level
2998 argument of `tar'. For example, an untrusted user that can modify
2999 `/home/eve' can hijack a running instance of `tar -cf -
3000 /home/eve/Documents/yesterday' by replacing `/home/eve/Documents' with
3001 a symbolic link to some other location. Attacks like these can be
3002 prevented by making sure that untrusted users cannot modify any files
3003 that are top-level arguments to `tar', or any ancestor directories of
3007 File: tar.info, Node: Security rules of thumb, Prev: Live untrusted data, Up: Security
3009 10.2.4 Security Rules of Thumb
3010 ------------------------------
3012 This section briefly summarizes rules of thumb for avoiding security
3015 * Protect archives at least as much as you protect any of the files
3018 * Extract from an untrusted archive only into an otherwise-empty
3019 directory. This directory and its parent should be accessible
3020 only to trusted users. For example:
3023 $ mkdir -m go-rwx dir
3025 $ tar -xvf /archives/got-it-off-the-net.tar.gz
3027 As a corollary, do not do an incremental restore from an untrusted
3030 * Do not let untrusted users access files extracted from untrusted
3031 archives without checking first for problems such as setuid
3034 * Do not let untrusted users modify directories that are ancestors of
3035 top-level arguments of `tar'. For example, while you are
3036 executing `tar -cf /archive/u-home.tar /u/home', do not let an
3037 untrusted user modify `/', `/archive', or `/u'.
3039 * Pay attention to the diagnostics and exit status of `tar'.
3041 * When archiving live file systems, monitor running instances of
3042 `tar' to detect denial-of-service attacks.
3044 * Avoid unusual options such as `--absolute-names' (`-P'),
3045 `--dereference' (`-h'), `--overwrite', `--recursive-unlink', and
3046 `--remove-files' unless you understand their security implications.
3050 File: tar.info, Node: Changes, Next: Configuring Help Summary, Prev: Reliability and security, Up: Top
3055 This appendix lists some important user-visible changes between version
3056 GNU `tar' 1.24 and previous versions. An up-to-date version of this
3057 document is available at the GNU `tar' documentation page
3058 (http://www.gnu.org/software/tar/manual/changes.html).
3060 Use of globbing patterns when listing and extracting.
3061 Previous versions of GNU tar assumed shell-style globbing when
3062 extracting from or listing an archive. For example:
3064 $ tar xf foo.tar '*.c'
3066 would extract all files whose names end in `.c'. This behavior
3067 was not documented and was incompatible with traditional tar
3068 implementations. Therefore, starting from version 1.15.91, GNU tar
3069 no longer uses globbing by default. For example, the above
3070 invocation is now interpreted as a request to extract from the
3071 archive the file named `*.c'.
3073 To facilitate transition to the new behavior for those users who
3074 got used to the previous incorrect one, `tar' will print a warning
3075 if it finds out that a requested member was not found in the
3076 archive and its name looks like a globbing pattern. For example:
3078 $ tar xf foo.tar '*.c'
3079 tar: Pattern matching characters used in file names. Please,
3080 tar: use --wildcards to enable pattern matching, or --no-wildcards to
3081 tar: suppress this warning.
3082 tar: *.c: Not found in archive
3083 tar: Error exit delayed from previous errors
3085 To treat member names as globbing patterns, use the `--wildcards'
3086 option. If you want to tar to mimic the behavior of versions
3087 prior to 1.15.91, add this option to your `TAR_OPTIONS' variable.
3089 *Note wildcards::, for the detailed discussion of the use of
3090 globbing patterns by GNU `tar'.
3092 Use of short option `-o'.
3093 Earlier versions of GNU `tar' understood `-o' command line option
3094 as a synonym for `--old-archive'.
3096 GNU `tar' starting from version 1.13.90 understands this option as
3097 a synonym for `--no-same-owner'. This is compatible with UNIX98
3098 `tar' implementations.
3100 However, to facilitate transition, `-o' option retains its old
3101 semantics when it is used with one of archive-creation commands.
3102 Users are encouraged to use `--format=oldgnu' instead.
3104 It is especially important, since versions of GNU Automake up to
3105 and including 1.8.4 invoke tar with this option to produce
3106 distribution tarballs. *Note v7: Formats, for the detailed
3107 discussion of this issue and its implications.
3109 *Note tar-formats: (automake)Options, for a description on how to
3110 use various archive formats with `automake'.
3112 Future versions of GNU `tar' will understand `-o' only as a
3113 synonym for `--no-same-owner'.
3115 Use of short option `-l'
3116 Earlier versions of GNU `tar' understood `-l' option as a synonym
3117 for `--one-file-system'. Since such usage contradicted to UNIX98
3118 specification and harmed compatibility with other implementations,
3119 it was declared deprecated in version 1.14. However, to
3120 facilitate transition to its new semantics, it was supported by
3121 versions 1.15 and 1.15.90. The present use of `-l' as a short
3122 variant of `--check-links' was introduced in version 1.15.91.
3124 Use of options `--portability' and `--old-archive'
3125 These options are deprecated. Please use `--format=v7' instead.
3127 Use of option `--posix'
3128 This option is deprecated. Please use `--format=posix' instead.
3131 File: tar.info, Node: Configuring Help Summary, Next: Fixing Snapshot Files, Prev: Changes, Up: Top
3133 Appendix B Configuring Help Summary
3134 ***********************************
3136 Running `tar --help' displays the short `tar' option summary (*note
3137 help::). This summary is organized by "groups" of semantically close
3138 options. The options within each group are printed in the following
3139 order: a short option, eventually followed by a list of corresponding
3140 long option names, followed by a short description of the option. For
3141 example, here is an excerpt from the actual `tar --help' output:
3143 Main operation mode:
3145 -A, --catenate, --concatenate append tar files to an archive
3146 -c, --create create a new archive
3147 -d, --diff, --compare find differences between archive and
3149 --delete delete from the archive
3151 The exact visual representation of the help output is configurable
3152 via `ARGP_HELP_FMT' environment variable. The value of this variable is
3153 a comma-separated list of "format variable" assignments. There are two
3154 kinds of format variables. An "offset variable" keeps the offset of
3155 some part of help output text from the leftmost column on the screen. A
3156 "boolean" variable is a flag that toggles some output feature on or
3157 off. Depending on the type of the corresponding variable, there are two
3158 kinds of assignments:
3161 The assignment to an offset variable has the following syntax:
3165 where VARIABLE is the variable name, and VALUE is a numeric value
3166 to be assigned to the variable.
3169 To assign `true' value to a variable, simply put this variable
3170 name. To assign `false' value, prefix the variable name with
3173 # Assign `true' value:
3175 # Assign `false' value:
3178 Following variables are declared:
3180 -- Help Output: boolean dup-args
3181 If true, arguments for an option are shown with both short and long
3182 options, even when a given option has both forms, for example:
3184 -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
3186 If false, then if an option has both short and long forms, the
3187 argument is only shown with the long one, for example:
3189 -f, --file=ARCHIVE use archive file or device ARCHIVE
3191 and a message indicating that the argument is applicable to both
3192 forms is printed below the options. This message can be disabled
3193 using `dup-args-note' (see below).
3195 The default is false.
3197 -- Help Output: boolean dup-args-note
3198 If this variable is true, which is the default, the following
3199 notice is displayed at the end of the help output:
3201 Mandatory or optional arguments to long options are also
3202 mandatory or optional for any corresponding short options.
3204 Setting `no-dup-args-note' inhibits this message. Normally, only
3205 one of variables `dup-args' or `dup-args-note' should be set.
3207 -- Help Output: offset short-opt-col
3208 Column in which short options start. Default is 2.
3210 $ tar --help|grep ARCHIVE
3211 -f, --file=ARCHIVE use archive file or device ARCHIVE
3212 $ ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE
3213 -f, --file=ARCHIVE use archive file or device ARCHIVE
3215 -- Help Output: offset long-opt-col
3216 Column in which long options start. Default is 6. For example:
3218 $ tar --help|grep ARCHIVE
3219 -f, --file=ARCHIVE use archive file or device ARCHIVE
3220 $ ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE
3221 -f, --file=ARCHIVE use archive file or device ARCHIVE
3223 -- Help Output: offset doc-opt-col
3224 Column in which "doc options" start. A doc option isn't actually
3225 an option, but rather an arbitrary piece of documentation that is
3226 displayed in much the same manner as the options. For example, in
3227 the description of `--format' option:
3229 -H, --format=FORMAT create archive of the given format.
3231 FORMAT is one of the following:
3233 gnu GNU tar 1.13.x format
3234 oldgnu GNU format as per tar <= 1.12
3235 pax POSIX 1003.1-2001 (pax) format
3237 ustar POSIX 1003.1-1988 (ustar) format
3238 v7 old V7 tar format
3240 the format names are doc options. Thus, if you set
3241 `ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output
3242 will look as follows:
3244 -H, --format=FORMAT create archive of the given format.
3246 FORMAT is one of the following:
3248 gnu GNU tar 1.13.x format
3249 oldgnu GNU format as per tar <= 1.12
3250 pax POSIX 1003.1-2001 (pax) format
3252 ustar POSIX 1003.1-1988 (ustar) format
3253 v7 old V7 tar format
3255 -- Help Output: offset opt-doc-col
3256 Column in which option description starts. Default is 29.
3258 $ tar --help|grep ARCHIVE
3259 -f, --file=ARCHIVE use archive file or device ARCHIVE
3260 $ ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE
3261 -f, --file=ARCHIVE use archive file or device ARCHIVE
3262 $ ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE
3264 use archive file or device ARCHIVE
3266 Notice, that the description starts on a separate line if
3267 `opt-doc-col' value is too small.
3269 -- Help Output: offset header-col
3270 Column in which "group headers" are printed. A group header is a
3271 descriptive text preceding an option group. For example, in the
3274 Main operation mode:
3276 -A, --catenate, --concatenate append tar files to
3278 -c, --create create a new archive
3279 `Main operation mode:' is the group header.
3281 The default value is 1.
3283 -- Help Output: offset usage-indent
3284 Indentation of wrapped usage lines. Affects `--usage' output.
3287 -- Help Output: offset rmargin
3288 Right margin of the text output. Used for wrapping.
3291 File: tar.info, Node: Fixing Snapshot Files, Next: Tar Internals, Prev: Configuring Help Summary, Up: Top
3293 Appendix C Fixing Snapshot Files
3294 ********************************
3296 Sometimes device numbers can change after upgrading your kernel version
3297 or reconfiguring the hardware. Reportedly this is the case with some
3298 newer Linux kernels, when using LVM. In majority of cases this change
3299 is unnoticed by the users. However, it influences `tar' incremental
3300 backups: the device number is stored in tar snapshot files (*note
3301 Snapshot Files::) and is used to determine whether the file has changed
3302 since the last backup. If the device numbers change for some reason,
3303 the next backup you run will be a full backup.
3305 To minimize the impact in these cases, GNU `tar' comes with the
3306 `tar-snapshot-edit' utility for inspecting and updating device numbers
3307 in snapshot files. The utility, written by Dustin J. Mitchell, is
3308 available from GNU `tar' home page
3309 (http://www.gnu.org/software/tar/utils/tar-snapshot-edit.html).
3311 To obtain the device numbers used in the snapshot file, run
3313 $ tar-snapshot-edit SNAPFILE
3315 where SNAPFILE is the name of the snapshot file (you can supply as many
3316 files as you wish in a single command line).
3318 To update all occurrences of the given device number in the file, use
3319 `-r' option. It takes a single argument of the form `OLDDEV-NEWDEV',
3320 where OLDDEV is the device number used in the snapshot file, and NEWDEV
3321 is the corresponding new device number. Both numbers may be specified
3322 in hex (e.g., `0xfe01'), decimal (e.g., `65025'), or as a major:minor
3323 number pair (e.g., `254:1'). To change several device numbers at once,
3324 specify them in a single comma-separated list, as in `-r
3325 0x3060-0x4500,0x307-0x4600'.
3327 Before updating the snapshot file, it is a good idea to create a
3328 backup copy of it. This is accomplished by `-b' option. The name of
3329 the backup file is obtained by appending `~' to the original file name.
3332 $ tar-snapshot-edit /var/backup/snap.a
3334 /tmp/snap: Device 0x0306 occurs 634 times.
3335 $ tar-snapshot-edit -b -r 0x0306-0x4500 /var/backup/snap.a
3339 File: tar.info, Node: Tar Internals, Next: Genfile, Prev: Fixing Snapshot Files, Up: Top
3341 Appendix D Tar Internals
3342 ************************
3346 * Standard:: Basic Tar Format
3347 * Extensions:: GNU Extensions to the Archive Format
3348 * Sparse Formats:: Storing Sparse Files
3353 File: tar.info, Node: Standard, Next: Extensions, Up: Tar Internals
3358 _(This message will disappear, once this node revised.)_
3360 While an archive may contain many files, the archive itself is a single
3361 ordinary file. Like any other file, an archive file can be written to
3362 a storage device such as a tape or disk, sent through a pipe or over a
3363 network, saved on the active file system, or even stored in another
3364 archive. An archive file is not easy to read or manipulate without
3365 using the `tar' utility or Tar mode in GNU Emacs.
3367 Physically, an archive consists of a series of file entries
3368 terminated by an end-of-archive entry, which consists of two 512 blocks
3369 of zero bytes. A file entry usually describes one of the files in the
3370 archive (an "archive member"), and consists of a file header and the
3371 contents of the file. File headers contain file names and statistics,
3372 checksum information which `tar' uses to detect file corruption, and
3373 information about file types.
3375 Archives are permitted to have more than one member with the same
3376 member name. One way this situation can occur is if more than one
3377 version of a file has been stored in the archive. For information
3378 about adding new versions of a file to an archive, see *note update::.
3380 In addition to entries describing archive members, an archive may
3381 contain entries which `tar' itself uses to store information. *Note
3382 label::, for an example of such an archive entry.
3384 A `tar' archive file contains a series of blocks. Each block
3385 contains `BLOCKSIZE' bytes. Although this format may be thought of as
3386 being on magnetic tape, other media are often used.
3388 Each file archived is represented by a header block which describes
3389 the file, followed by zero or more blocks which give the contents of
3390 the file. At the end of the archive file there are two 512-byte blocks
3391 filled with binary zeros as an end-of-file marker. A reasonable system
3392 should write such end-of-file marker at the end of an archive, but must
3393 not assume that such a block exists when reading an archive. In
3394 particular GNU `tar' always issues a warning if it does not encounter
3397 The blocks may be "blocked" for physical I/O operations. Each
3398 record of N blocks (where N is set by the `--blocking-factor=512-SIZE'
3399 (`-b 512-SIZE') option to `tar') is written with a single `write ()'
3400 operation. On magnetic tapes, the result of such a write is a single
3401 record. When writing an archive, the last record of blocks should be
3402 written at the full size, with blocks after the zero block containing
3403 all zeros. When reading an archive, a reasonable system should
3404 properly handle an archive whose last record is shorter than the rest,
3405 or which contains garbage records after a zero block.
3407 The header block is defined in C as follows. In the GNU `tar'
3408 distribution, this is part of file `src/tar.h':
3411 /* tar Header Block, from POSIX 1003.1-1990. */
3417 char name[100]; /* 0 */
3418 char mode[8]; /* 100 */
3419 char uid[8]; /* 108 */
3420 char gid[8]; /* 116 */
3421 char size[12]; /* 124 */
3422 char mtime[12]; /* 136 */
3423 char chksum[8]; /* 148 */
3424 char typeflag; /* 156 */
3425 char linkname[100]; /* 157 */
3426 char magic[6]; /* 257 */
3427 char version[2]; /* 263 */
3428 char uname[32]; /* 265 */
3429 char gname[32]; /* 297 */
3430 char devmajor[8]; /* 329 */
3431 char devminor[8]; /* 337 */
3432 char prefix[155]; /* 345 */
3436 #define TMAGIC "ustar" /* ustar and a null */
3438 #define TVERSION "00" /* 00 and no null */
3441 /* Values used in typeflag field. */
3442 #define REGTYPE '0' /* regular file */
3443 #define AREGTYPE '\0' /* regular file */
3444 #define LNKTYPE '1' /* link */
3445 #define SYMTYPE '2' /* reserved */
3446 #define CHRTYPE '3' /* character special */
3447 #define BLKTYPE '4' /* block special */
3448 #define DIRTYPE '5' /* directory */
3449 #define FIFOTYPE '6' /* FIFO special */
3450 #define CONTTYPE '7' /* reserved */
3452 #define XHDTYPE 'x' /* Extended header referring to the
3453 next file in the archive */
3454 #define XGLTYPE 'g' /* Global extended header */
3456 /* Bits used in the mode field, values in octal. */
3457 #define TSUID 04000 /* set UID on execution */
3458 #define TSGID 02000 /* set GID on execution */
3459 #define TSVTX 01000 /* reserved */
3460 /* file permissions */
3461 #define TUREAD 00400 /* read by owner */
3462 #define TUWRITE 00200 /* write by owner */
3463 #define TUEXEC 00100 /* execute/search by owner */
3464 #define TGREAD 00040 /* read by group */
3465 #define TGWRITE 00020 /* write by group */
3466 #define TGEXEC 00010 /* execute/search by group */
3467 #define TOREAD 00004 /* read by other */
3468 #define TOWRITE 00002 /* write by other */
3469 #define TOEXEC 00001 /* execute/search by other */
3471 /* tar Header Block, GNU extensions. */
3473 /* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for
3474 contiguous files, so maybe disobeying the `reserved' comment in POSIX
3475 header description. I suspect these were meant to be used this way, and
3476 should not have really been `reserved' in the published standards. */
3478 /* *BEWARE* *BEWARE* *BEWARE* that the following information is still
3479 boiling, and may change. Even if the OLDGNU format description should be
3480 accurate, the so-called GNU format is not yet fully decided. It is
3481 surely meant to use only extensions allowed by POSIX, but the sketch
3482 below repeats some ugliness from the OLDGNU format, which should rather
3483 go away. Sparse files should be saved in such a way that they do *not*
3484 require two passes at archive creation time. Huge files get some POSIX
3485 fields to overflow, alternate solutions have to be sought for this. */
3487 /* Descriptor for a single file hole. */
3491 char offset[12]; /* 0 */
3492 char numbytes[12]; /* 12 */
3496 /* Sparse files are not supported in POSIX ustar format. For sparse files
3497 with a POSIX header, a GNU extra header is provided which holds overall
3498 sparse information and a few sparse descriptors. When an old GNU header
3499 replaces both the POSIX header and the GNU extra header, it holds some
3500 sparse descriptors too. Whether POSIX or not, if more sparse descriptors
3501 are still needed, they are put into as many successive sparse headers as
3502 necessary. The following constants tell how many sparse descriptors fit
3503 in each kind of header able to hold them. */
3505 #define SPARSES_IN_EXTRA_HEADER 16
3506 #define SPARSES_IN_OLDGNU_HEADER 4
3507 #define SPARSES_IN_SPARSE_HEADER 21
3509 /* Extension header for sparse files, used immediately after the GNU extra
3510 header, and used only if all sparse information cannot fit into that
3511 extra header. There might even be many such extension headers, one after
3512 the other, until all sparse information has been recorded. */
3514 struct sparse_header
3516 struct sparse sp[SPARSES_IN_SPARSE_HEADER];
3518 char isextended; /* 504 */
3522 /* The old GNU format header conflicts with POSIX format in such a way that
3523 POSIX archives may fool old GNU tar's, and POSIX tar's might well be
3524 fooled by old GNU tar archives. An old GNU format header uses the space
3525 used by the prefix field in a POSIX header, and cumulates information
3526 normally found in a GNU extra header. With an old GNU tar header, we
3527 never see any POSIX header nor GNU extra header. Supplementary sparse
3528 headers are allowed, however. */
3530 struct oldgnu_header
3532 char unused_pad1[345]; /* 0 */
3533 char atime[12]; /* 345 Incr. archive: atime of the file */
3534 char ctime[12]; /* 357 Incr. archive: ctime of the file */
3535 char offset[12]; /* 369 Multivolume archive: the offset of
3536 the start of this volume */
3537 char longnames[4]; /* 381 Not used */
3538 char unused_pad2; /* 385 */
3539 struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
3541 char isextended; /* 482 Sparse file: Extension sparse header
3543 char realsize[12]; /* 483 Sparse file: Real size*/
3547 /* OLDGNU_MAGIC uses both magic and version fields, which are contiguous.
3548 Found in an archive, it indicates an old GNU header format, which will be
3549 hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are
3550 valid, though the header is not truly POSIX conforming. */
3551 #define OLDGNU_MAGIC "ustar " /* 7 chars and a null */
3553 /* The standards committee allows only capital A through capital Z for
3554 user-defined expansion. Other letters in use include:
3556 'A' Solaris Access Control List
3557 'E' Solaris Extended Attribute File
3558 'I' Inode only, as in 'star'
3559 'N' Obsolete GNU tar, for file names that do not fit into the main header.
3560 'X' POSIX 1003.1-2001 eXtended (VU version) */
3562 /* This is a dir entry that contains the names of files that were in the
3563 dir at the time the dump was made. */
3564 #define GNUTYPE_DUMPDIR 'D'
3566 /* Identifies the *next* file on the tape as having a long linkname. */
3567 #define GNUTYPE_LONGLINK 'K'
3569 /* Identifies the *next* file on the tape as having a long name. */
3570 #define GNUTYPE_LONGNAME 'L'
3572 /* This is the continuation of a file that began on another volume. */
3573 #define GNUTYPE_MULTIVOL 'M'
3575 /* This is for sparse files. */
3576 #define GNUTYPE_SPARSE 'S'
3578 /* This file is a tape/volume header. Ignore it on extraction. */
3579 #define GNUTYPE_VOLHDR 'V'
3581 /* Solaris extended header */
3582 #define SOLARIS_XHDTYPE 'X'
3584 /* Jo"rg Schilling star header */
3588 char name[100]; /* 0 */
3589 char mode[8]; /* 100 */
3590 char uid[8]; /* 108 */
3591 char gid[8]; /* 116 */
3592 char size[12]; /* 124 */
3593 char mtime[12]; /* 136 */
3594 char chksum[8]; /* 148 */
3595 char typeflag; /* 156 */
3596 char linkname[100]; /* 157 */
3597 char magic[6]; /* 257 */
3598 char version[2]; /* 263 */
3599 char uname[32]; /* 265 */
3600 char gname[32]; /* 297 */
3601 char devmajor[8]; /* 329 */
3602 char devminor[8]; /* 337 */
3603 char prefix[131]; /* 345 */
3604 char atime[12]; /* 476 */
3605 char ctime[12]; /* 488 */
3609 #define SPARSES_IN_STAR_HEADER 4
3610 #define SPARSES_IN_STAR_EXT_HEADER 21
3612 struct star_in_header
3614 char fill[345]; /* 0 Everything that is before t_prefix */
3615 char prefix[1]; /* 345 t_name prefix */
3616 char fill2; /* 346 */
3617 char fill3[8]; /* 347 */
3618 char isextended; /* 355 */
3619 struct sparse sp[SPARSES_IN_STAR_HEADER]; /* 356 */
3620 char realsize[12]; /* 452 Actual size of the file */
3621 char offset[12]; /* 464 Offset of multivolume contents */
3622 char atime[12]; /* 476 */
3623 char ctime[12]; /* 488 */
3624 char mfill[8]; /* 500 */
3625 char xmagic[4]; /* 508 "tar" */
3628 struct star_ext_header
3630 struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
3634 All characters in header blocks are represented by using 8-bit
3635 characters in the local variant of ASCII. Each field within the
3636 structure is contiguous; that is, there is no padding used within the
3637 structure. Each character on the archive medium is stored contiguously.
3639 Bytes representing the contents of files (after the header block of
3640 each file) are not translated in any way and are not constrained to
3641 represent characters in any character set. The `tar' format does not
3642 distinguish text files from binary files, and no translation of file
3643 contents is performed.
3645 The `name', `linkname', `magic', `uname', and `gname' are
3646 null-terminated character strings. All other fields are zero-filled
3647 octal numbers in ASCII. Each numeric field of width W contains W minus
3648 1 digits, and a null.
3650 The `name' field is the file name of the file, with directory names
3651 (if any) preceding the file name, separated by slashes.
3653 The `mode' field provides nine bits specifying file permissions and
3654 three bits to specify the Set UID, Set GID, and Save Text ("sticky")
3655 modes. Values for these bits are defined above. When special
3656 permissions are required to create a file with a given mode, and the
3657 user restoring files from the archive does not hold such permissions,
3658 the mode bit(s) specifying those special permissions are ignored.
3659 Modes which are not supported by the operating system restoring files
3660 from the archive will be ignored. Unsupported modes should be faked up
3661 when creating or updating an archive; e.g., the group permission could
3662 be copied from the _other_ permission.
3664 The `uid' and `gid' fields are the numeric user and group ID of the
3665 file owners, respectively. If the operating system does not support
3666 numeric user or group IDs, these fields should be ignored.
3668 The `size' field is the size of the file in bytes; linked files are
3669 archived with this field specified as zero.
3671 The `mtime' field is the data modification time of the file at the
3672 time it was archived. It is the ASCII representation of the octal
3673 value of the last time the file's contents were modified, represented
3674 as an integer number of seconds since January 1, 1970, 00:00
3675 Coordinated Universal Time.
3677 The `chksum' field is the ASCII representation of the octal value of
3678 the simple sum of all bytes in the header block. Each 8-bit byte in
3679 the header is added to an unsigned integer, initialized to zero, the
3680 precision of which shall be no less than seventeen bits. When
3681 calculating the checksum, the `chksum' field is treated as if it were
3684 The `typeflag' field specifies the type of file archived. If a
3685 particular implementation does not recognize or permit the specified
3686 type, the file will be extracted as if it were a regular file. As this
3687 action occurs, `tar' issues a warning to the standard error.
3689 The `atime' and `ctime' fields are used in making incremental
3690 backups; they store, respectively, the particular file's access and
3691 status change times.
3693 The `offset' is used by the `--multi-volume' (`-M') option, when
3694 making a multi-volume archive. The offset is number of bytes into the
3695 file that we need to restart at to continue the file on the next tape,
3696 i.e., where we store the location that a continued file is continued at.
3698 The following fields were added to deal with sparse files. A file
3699 is "sparse" if it takes in unallocated blocks which end up being
3700 represented as zeros, i.e., no useful data. A test to see if a file is
3701 sparse is to look at the number blocks allocated for it versus the
3702 number of characters in the file; if there are fewer blocks allocated
3703 for the file than would normally be allocated for a file of that size,
3704 then the file is sparse. This is the method `tar' uses to detect a
3705 sparse file, and once such a file is detected, it is treated
3706 differently from non-sparse files.
3708 Sparse files are often `dbm' files, or other database-type files
3709 which have data at some points and emptiness in the greater part of the
3710 file. Such files can appear to be very large when an `ls -l' is done
3711 on them, when in truth, there may be a very small amount of important
3712 data contained in the file. It is thus undesirable to have `tar' think
3713 that it must back up this entire file, as great quantities of room are
3714 wasted on empty blocks, which can lead to running out of room on a tape
3715 far earlier than is necessary. Thus, sparse files are dealt with so
3716 that these empty blocks are not written to the tape. Instead, what is
3717 written to the tape is a description, of sorts, of the sparse file:
3718 where the holes are, how big the holes are, and how much data is found
3719 at the end of the hole. This way, the file takes up potentially far
3720 less room on the tape, and when the file is extracted later on, it will
3721 look exactly the way it looked beforehand. The following is a
3722 description of the fields used to handle a sparse file:
3724 The `sp' is an array of `struct sparse'. Each `struct sparse'
3725 contains two 12-character strings which represent an offset into the
3726 file and a number of bytes to be written at that offset. The offset is
3727 absolute, and not relative to the offset in preceding array element.
3729 The header can hold four of these `struct sparse' at the moment; if
3730 more are needed, they are not stored in the header.
3732 The `isextended' flag is set when an `extended_header' is needed to
3733 deal with a file. Note that this means that this flag can only be set
3734 when dealing with a sparse file, and it is only set in the event that
3735 the description of the file will not fit in the allotted room for
3736 sparse structures in the header. In other words, an extended_header is
3739 The `extended_header' structure is used for sparse files which need
3740 more sparse structures than can fit in the header. The header can fit
3741 4 such structures; if more are needed, the flag `isextended' gets set
3742 and the next block is an `extended_header'.
3744 Each `extended_header' structure contains an array of 21 sparse
3745 structures, along with a similar `isextended' flag that the header had.
3746 There can be an indeterminate number of such `extended_header's to
3747 describe a sparse file.
3751 These flags represent a regular file. In order to be compatible
3752 with older versions of `tar', a `typeflag' value of `AREGTYPE'
3753 should be silently recognized as a regular file. New archives
3754 should be created using `REGTYPE'. Also, for backward
3755 compatibility, `tar' treats a regular file whose name ends with a
3756 slash as a directory.
3759 This flag represents a file linked to another file, of any type,
3760 previously archived. Such files are identified in Unix by each
3761 file having the same device and inode number. The linked-to name
3762 is specified in the `linkname' field with a trailing null.
3765 This represents a symbolic link to another file. The linked-to
3766 name is specified in the `linkname' field with a trailing null.
3770 These represent character special files and block special files
3771 respectively. In this case the `devmajor' and `devminor' fields
3772 will contain the major and minor device numbers respectively.
3773 Operating systems may map the device specifications to their own
3774 local specification, or may ignore the entry.
3777 This flag specifies a directory or sub-directory. The directory
3778 name in the `name' field should end with a slash. On systems where
3779 disk allocation is performed on a directory basis, the `size' field
3780 will contain the maximum number of bytes (which may be rounded to
3781 the nearest disk block allocation unit) which the directory may
3782 hold. A `size' field of zero indicates no such limiting. Systems
3783 which do not support limiting in this manner should ignore the
3787 This specifies a FIFO special file. Note that the archiving of a
3788 FIFO file archives the existence of this file and not its contents.
3791 This specifies a contiguous file, which is the same as a normal
3792 file except that, in operating systems which support it, all its
3793 space is allocated contiguously on the disk. Operating systems
3794 which do not allow contiguous allocation should silently treat this
3795 type as a normal file.
3798 These are reserved for custom implementations. Some of these are
3799 used in the GNU modified format, as described below.
3802 Other values are reserved for specification in future revisions of
3803 the P1003 standard, and should not be used by any `tar' program.
3805 The `magic' field indicates that this archive was output in the
3806 P1003 archive format. If this field contains `TMAGIC', the `uname' and
3807 `gname' fields will contain the ASCII representation of the owner and
3808 group of the file respectively. If found, the user and group IDs are
3809 used rather than the values in the `uid' and `gid' fields.
3811 For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990,
3812 pages 169-173 (section 10.1) for `Archive/Interchange File Format'; and
3813 IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
3814 (section E.4.48) for `pax - Portable archive interchange'.
3817 File: tar.info, Node: Extensions, Next: Sparse Formats, Prev: Standard, Up: Tar Internals
3819 GNU Extensions to the Archive Format
3820 ====================================
3822 _(This message will disappear, once this node revised.)_
3824 The GNU format uses additional file types to describe new types of
3825 files in an archive. These are listed below.
3829 This represents a directory and a list of files created by the
3830 `--incremental' (`-G') option. The `size' field gives the total
3831 size of the associated list of files. Each file name is preceded
3832 by either a `Y' (the file should be in this archive) or an `N'.
3833 (The file is a directory, or is not stored in the archive.) Each
3834 file name is terminated by a null. There is an additional null
3835 after the last file name.
3839 This represents a file continued from another volume of a
3840 multi-volume archive created with the `--multi-volume' (`-M')
3841 option. The original type of the file is not given here. The
3842 `size' field gives the maximum size of this piece of the file
3843 (assuming the volume does not end before the file is written out).
3844 The `offset' field gives the offset from the beginning of the file
3845 where this part of the file begins. Thus `size' plus `offset'
3846 should equal the original size of the file.
3850 This flag indicates that we are dealing with a sparse file. Note
3851 that archiving a sparse file requires special operations to find
3852 holes in the file, which mark the positions of these holes, along
3853 with the number of bytes of data to be found after the hole.
3857 This file type is used to mark the volume header that was given
3858 with the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') option when
3859 the archive was created. The `name' field contains the `name'
3860 given after the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL')
3861 option. The `size' field is zero. Only the first file in each
3862 volume of an archive should have this type.
3865 You may have trouble reading a GNU format archive on a non-GNU
3866 system if the options `--incremental' (`-G'), `--multi-volume' (`-M'),
3867 `--sparse' (`-S'), or `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') were
3868 used when writing the archive. In general, if `tar' does not use the
3869 GNU-added fields of the header, other versions of `tar' should be able
3870 to read the archive. Otherwise, the `tar' program will give an error,
3871 the most likely one being a checksum error.
3874 File: tar.info, Node: Sparse Formats, Next: Snapshot Files, Prev: Extensions, Up: Tar Internals
3876 Storing Sparse Files
3877 ====================
3879 The notion of sparse file, and the ways of handling it from the point
3880 of view of GNU `tar' user have been described in detail in *note
3881 sparse::. This chapter describes the internal format GNU `tar' uses to
3884 The support for sparse files in GNU `tar' has a long history. The
3885 earliest version featuring this support that I was able to find was
3886 1.09, released in November, 1990. The format introduced back then is
3887 called "old GNU" sparse format and in spite of the fact that its design
3888 contained many flaws, it was the only format GNU `tar' supported until
3889 version 1.14 (May, 2004), which introduced initial support for sparse
3890 archives in PAX archives (*note posix::). This format was not free
3891 from design flaws, either and it was subsequently improved in versions
3892 1.15.2 (November, 2005) and 1.15.92 (June, 2006).
3894 In addition to GNU sparse format, GNU `tar' is able to read and
3895 extract sparse files archived by `star'.
3897 The following subsections describe each format in detail.
3902 * PAX 0:: PAX Format, Versions 0.0 and 0.1
3903 * PAX 1:: PAX Format, Version 1.0
3906 File: tar.info, Node: Old GNU Format, Next: PAX 0, Up: Sparse Formats
3908 D.0.1 Old GNU Format
3909 --------------------
3911 The format introduced in November 1990 (v. 1.09) was designed on top of
3912 standard `ustar' headers in such an unfortunate way that some of its
3913 fields overwrote fields required by POSIX.
3915 An old GNU sparse header is designated by type `S'
3916 (`GNUTYPE_SPARSE') and has the following layout:
3918 Offset Size Name Data type Contents
3919 ----------------------------------------------------------------------------
3921 345 12 atime Number `atime' of the file.
3922 357 12 ctime Number `ctime' of the file .
3923 369 12 offset Number For multivolume archives:
3924 the offset of the start of
3928 386 96 sp `sparse_header'(4 entries) File map.
3929 482 1 isextended Bool `1' if an extension sparse
3932 483 12 realsize Number Real size of the file.
3934 Each of `sparse_header' object at offset 386 describes a single data
3935 chunk. It has the following structure:
3937 Offset Size Data type Contents
3938 ---------------------------------------------------------------------------
3939 0 12 Number Offset of the beginning of the chunk.
3940 12 12 Number Size of the chunk.
3942 If the member contains more than four chunks, the `isextended' field
3943 of the header has the value `1' and the main header is followed by one
3944 or more "extension headers". Each such header has the following
3947 Offset Size Name Data type Contents
3948 ----------------------------------------------------------------------------
3949 0 21 sp `sparse_header' (21 entries) File map.
3950 504 1 isextended Bool `1' if an extension sparse
3951 header follows, or `0'
3954 A header with `isextended=0' ends the map.
3957 File: tar.info, Node: PAX 0, Next: PAX 1, Prev: Old GNU Format, Up: Sparse Formats
3959 D.0.2 PAX Format, Versions 0.0 and 0.1
3960 --------------------------------------
3962 There are two formats available in this branch. The version `0.0' is
3963 the initial version of sparse format used by `tar' versions
3964 1.14-1.15.1. The sparse file map is kept in extended (`x') PAX header
3968 Real size of the stored file;
3970 `GNU.sparse.numblocks'
3971 Number of blocks in the sparse map;
3974 Offset of the data block;
3976 `GNU.sparse.numbytes'
3977 Size of the data block.
3979 The latter two variables repeat for each data block, so the overall
3980 structure is like this:
3982 GNU.sparse.size=SIZE
3983 GNU.sparse.numblocks=NUMBLOCKS
3984 repeat NUMBLOCKS times
3985 GNU.sparse.offset=OFFSET
3986 GNU.sparse.numbytes=NUMBYTES
3989 This format presented the following two problems:
3991 1. Whereas the POSIX specification allows a variable to appear
3992 multiple times in a header, it requires that only the last
3993 occurrence be meaningful. Thus, multiple occurrences of
3994 `GNU.sparse.offset' and `GNU.sparse.numbytes' are conflicting with
3997 2. Attempting to extract such archives using a third-party's `tar'
3998 results in extraction of sparse files in _condensed form_. If the
3999 `tar' implementation in question does not support POSIX format, it
4000 will also extract a file containing extension header attributes.
4001 This file can be used to expand the file to its original state.
4002 However, posix-aware `tar's will usually ignore the unknown
4003 variables, which makes restoring the file more difficult. *Note
4004 Extraction of sparse members in v.0.0 format: extracting sparse
4005 v.0.x, for the detailed description of how to restore such members
4006 using non-GNU `tar's.
4008 GNU `tar' 1.15.2 introduced sparse format version `0.1', which
4009 attempted to solve these problems. As its predecessor, this format
4010 stores sparse map in the extended POSIX header. It retains
4011 `GNU.sparse.size' and `GNU.sparse.numblocks' variables, but instead of
4012 `GNU.sparse.offset'/`GNU.sparse.numbytes' pairs it uses a single
4016 Map of non-null data chunks. It is a string consisting of
4017 comma-separated values "OFFSET,SIZE[,OFFSET-1,SIZE-1...]"
4019 To address the 2nd problem, the `name' field in `ustar' is replaced
4020 with a special name, constructed using the following pattern:
4022 %d/GNUSparseFile.%p/%f
4024 The real name of the sparse file is stored in the variable
4025 `GNU.sparse.name'. Thus, those `tar' implementations that are not
4026 aware of GNU extensions will at least extract the files into separate
4027 directories, giving the user a possibility to expand it afterwards.
4028 *Note Extraction of sparse members in v.0.1 format: extracting sparse
4029 v.0.x, for the detailed description of how to restore such members
4030 using non-GNU `tar's.
4032 The resulting `GNU.sparse.map' string can be _very_ long. Although
4033 POSIX does not impose any limit on the length of a `x' header variable,
4034 this possibly can confuse some `tar's.
4037 File: tar.info, Node: PAX 1, Prev: PAX 0, Up: Sparse Formats
4039 D.0.3 PAX Format, Version 1.0
4040 -----------------------------
4042 The version `1.0' of sparse format was introduced with GNU `tar'
4043 1.15.92. Its main objective was to make the resulting file extractable
4044 with little effort even by non-posix aware `tar' implementations.
4045 Starting from this version, the extended header preceding a sparse
4046 member always contains the following variables that identify the format
4055 The `name' field in `ustar' header contains a special name,
4056 constructed using the following pattern:
4058 %d/GNUSparseFile.%p/%f
4060 The real name of the sparse file is stored in the variable
4061 `GNU.sparse.name'. The real size of the file is stored in the variable
4062 `GNU.sparse.realsize'.
4064 The sparse map itself is stored in the file data block, preceding
4065 the actual file data. It consists of a series of octal numbers of
4066 arbitrary length, delimited by newlines. The map is padded with nulls
4067 to the nearest block boundary.
4069 The first number gives the number of entries in the map. Following
4070 are map entries, each one consisting of two numbers giving the offset
4071 and size of the data block it describes.
4073 The format is designed in such a way that non-posix aware `tar's and
4074 `tar's not supporting `GNU.sparse.*' keywords will extract each sparse
4075 file in its condensed form with the file map prepended and will place it
4076 into a separate directory. Then, using a simple program it would be
4077 possible to expand the file to its original form even without GNU `tar'.
4078 *Note Sparse Recovery::, for the detailed information on how to extract
4079 sparse members without GNU `tar'.
4082 File: tar.info, Node: Snapshot Files, Next: Dumpdir, Prev: Sparse Formats, Up: Tar Internals
4084 Format of the Incremental Snapshot Files
4085 ========================================
4087 A "snapshot file" (or "directory file") is created during incremental
4088 backups (*note Incremental Dumps::). It contains the status of the
4089 file system at the time of the dump and is used to determine which
4090 files were modified since the last backup.
4092 GNU `tar' version 1.24 supports three snapshot file formats. The
4093 first format, called "format 0", is the one used by GNU `tar' versions
4094 up to 1.15.1. The second format, called "format 1" is an extended
4095 version of this format, that contains more metadata and allows for
4096 further extensions. It was used by version 1.15.1. Starting from
4097 version 1.16 and up to 1.24, the "format 2" is used.
4099 GNU `tar' is able to read all three formats, but will create
4100 snapshots only in format 2.
4102 This appendix describes all three formats in detail.
4104 0. `Format 0' snapshot file begins with a line containing a decimal
4105 number that represents a UNIX timestamp of the beginning of the
4106 last archivation. This line is followed by directory metadata
4107 descriptions, one per line. Each description has the following
4115 A single plus character (`+'), if this directory is located on
4116 an NFS-mounted partition, or a single space otherwise;
4119 Device number of the directory;
4122 I-node number of the directory;
4125 Name of the directory. Any special characters (white-space,
4126 backslashes, etc.) are quoted.
4128 1. `Format 1' snapshot file begins with a line specifying the
4129 format of the file. This line has the following structure:
4131 `GNU tar-'TAR-VERSION`-'INCR-FORMAT-VERSION
4133 where TAR-VERSION is the version number of GNU `tar'
4134 implementation that created this snapshot, and INCR-FORMAT-VERSION
4135 is the version number of the snapshot format (in this case `1').
4137 Next line contains two decimal numbers, representing the time of
4138 the last backup. First number is the number of seconds, the second
4139 one is the number of nanoseconds, since the beginning of the epoch.
4141 Lines that follow contain directory metadata, one line per
4142 directory. Each line is formatted as follows:
4144 [NFS]MTIME-SEC MTIME-NSEC DEV INODE NAME
4146 where MTIME-SEC and MTIME-NSEC represent last modification time of
4147 this directory with nanosecond precision; NFS, DEV, INODE and NAME
4148 have the same meaning as with `format 0'.
4150 2. `Format 2' snapshot file begins with a format identifier, as
4151 described for version 1, e.g.:
4155 This line is followed by newline. Rest of file consists of
4156 records, separated by null (ASCII 0) characters. Thus, in contrast
4157 to the previous formats, format 2 snapshot is a binary file.
4159 First two records are decimal numbers, representing the time of
4160 the last backup. First number is the number of seconds, the
4161 second one is the number of nanoseconds, since the beginning of the
4162 epoch. These are followed by arbitrary number of directory
4165 Each "directory record" contains a set of metadata describing a
4166 particular directory. Parts of a directory record are delimited
4167 with ASCII 0 characters. The following table describes each part.
4168 The "Number" type in this table stands for a decimal number in
4171 Field Type Description
4172 ---------------------------------------------------------------------
4173 nfs Character `1' if the directory is located on an
4174 NFS-mounted partition, or `0' otherwise;
4175 mtime-sec Number Modification time, seconds;
4176 mtime-nano Number Modification time, nanoseconds;
4177 dev-no Number Device number;
4178 i-no Number I-node number;
4179 name String Directory name; in contrast to the
4180 previous versions it is not quoted;
4181 contents Dumpdir Contents of the directory; *Note
4182 Dumpdir::, for a description of its
4186 Dumpdirs stored in snapshot files contain only records of types
4191 File: tar.info, Node: Dumpdir, Prev: Snapshot Files, Up: Tar Internals
4196 Incremental archives keep information about contents of each dumped
4197 directory in special data blocks called "dumpdirs".
4199 Dumpdir is a sequence of entries of the following form:
4203 where C is one of the "control codes" described below, FILENAME is the
4204 name of the file C operates upon, and `\0' represents a nul character
4205 (ASCII 0). The white space characters were added for readability, real
4206 dumpdirs do not contain them.
4208 Each dumpdir ends with a single nul character.
4210 The following table describes control codes and their meanings:
4213 FILENAME is contained in the archive.
4216 FILENAME was present in the directory at the time the archive was
4217 made, yet it was not dumped to the archive, because it had not
4218 changed since the last backup.
4221 FILENAME is a directory.
4224 This code requests renaming of the FILENAME to the name specified
4225 with the `T' command, that immediately follows it.
4228 Specify target file name for `R' command (see below).
4231 Specify "temporary directory" name for a rename operation (see
4234 Codes `Y', `N' and `D' require FILENAME argument to be a relative
4235 file name to the directory this dumpdir describes, whereas codes `R',
4236 `T' and `X' require their argument to be an absolute file name.
4238 The three codes `R', `T' and `X' specify a "renaming operation". In
4239 the simplest case it is:
4241 R`source'\0T`dest'\0
4243 which means "rename file `source' to file `dest'".
4245 However, there are cases that require using a "temporary directory".
4246 For example, consider the following scenario:
4248 1. Previous run dumped a directory `foo' which contained the
4249 following three directories:
4255 2. They were renamed _cyclically_, so that:
4261 3. New incremental dump was made.
4263 This case cannot be handled by three successive renames, since
4264 renaming `a' to `b' will destroy the existing directory. To correctly
4265 process it, GNU `tar' needs a temporary directory, so it creates the
4266 following dumpdir (newlines have been added for readability):
4274 The first command, `Xfoo\0', instructs the extractor to create a
4275 temporary directory in the directory `foo'. Second command,
4276 `Rfoo/aT\0', says "rename file `foo/a' to the temporary directory that
4277 has just been created" (empty file name after a command means use
4278 temporary directory). Third and fourth commands work as usual, and,
4279 finally, the last command, `R\0Tfoo/a\0' tells tar to rename the
4280 temporary directory to `foo/a'.
4282 The exact placement of a dumpdir in the archive depends on the
4283 archive format (*note Formats::):
4287 In PAX archives, dumpdir is stored in the extended header of the
4288 corresponding directory, in variable `GNU.dumpdir'.
4290 * GNU and old GNU archives
4292 These formats implement special header type `D', which is similar
4293 to ustar header `5' (directory), except that it precedes a data
4294 block containing the dumpdir.
4297 File: tar.info, Node: Genfile, Next: Free Software Needs Free Documentation, Prev: Tar Internals, Up: Top
4302 This appendix describes `genfile', an auxiliary program used in the GNU
4303 tar testsuite. If you are not interested in developing GNU tar, skip
4306 Initially, `genfile' was used to generate data files for the
4307 testsuite, hence its name. However, new operation modes were being
4308 implemented as the testsuite grew more sophisticated, and now `genfile'
4309 is a multi-purpose instrument.
4311 There are three basic operation modes:
4314 This is the default mode. In this mode, `genfile' generates data
4318 In this mode `genfile' displays status of specified files.
4320 Synchronous Execution.
4321 In this mode `genfile' executes the given program with
4322 `--checkpoint' option and executes a set of actions when specified
4323 checkpoints are reached.
4327 * Generate Mode:: File Generation Mode.
4328 * Status Mode:: File Status Mode.
4329 * Exec Mode:: Synchronous Execution mode.
4332 File: tar.info, Node: Generate Mode, Next: Status Mode, Up: Genfile
4337 In this mode `genfile' creates a data file for the test suite. The size
4338 of the file is given with the `--length' (`-l') option. By default the
4339 file contents is written to the standard output, this can be changed
4340 using `--file' (`-f') command line option. Thus, the following two
4341 commands are equivalent:
4343 genfile --length 100 > outfile
4344 genfile --length 100 --file outfile
4346 If `--length' is not given, `genfile' will generate an empty
4349 The command line option `--seek=N' istructs `genfile' to skip the
4350 given number of bytes (N) in the output file before writing to it. It
4351 is similar to the `seek=N' of the `dd' utility.
4353 You can instruct `genfile' to create several files at one go, by
4354 giving it `--files-from' (`-T') option followed by a name of file
4355 containing a list of file names. Using dash (`-') instead of the file
4356 name causes `genfile' to read file list from the standard input. For
4359 # Read file names from file `file.list'
4360 genfile --files-from file.list
4361 # Read file names from standard input
4362 genfile --files-from -
4364 The list file is supposed to contain one file name per line. To use
4365 file lists separated by ASCII NUL character, use `--null' (`-0')
4366 command line option:
4368 genfile --null --files-from file.list
4370 The default data pattern for filling the generated file consists of
4371 first 256 letters of ASCII code, repeated enough times to fill the
4372 entire file. This behavior can be changed with `--pattern' option. This
4373 option takes a mandatory argument, specifying pattern name to use.
4374 Currently two patterns are implemented:
4377 The default pattern as described above.
4380 Fills the file with zeroes.
4382 If no file name was given, the program exits with the code `0'.
4383 Otherwise, it exits with `0' only if it was able to create a file of
4384 the specified length.
4386 Special option `--sparse' (`-s') instructs `genfile' to create a
4387 sparse file. Sparse files consist of "data fragments", separated by
4388 "holes" or blocks of zeros. On many operating systems, actual disk
4389 storage is not allocated for holes, but they are counted in the length
4390 of the file. To create a sparse file, `genfile' should know where to
4391 put data fragments, and what data to use to fill them. So, when
4392 `--sparse' is given the rest of the command line specifies a so-called
4395 The file map consists of any number of "fragment descriptors". Each
4396 descriptor is composed of two values: a number, specifying fragment
4397 offset from the end of the previous fragment or, for the very first
4398 fragment, from the beginning of the file, and "contents string", i.e.,
4399 a string of characters, specifying the pattern to fill the fragment
4400 with. File offset can be suffixed with the following quantifiers:
4404 The number is expressed in kilobytes.
4408 The number is expressed in megabytes.
4412 The number is expressed in gigabytes.
4414 For each letter in contents string `genfile' will generate a "block"
4415 of data, filled with this letter and will write it to the fragment. The
4416 size of block is given by `--block-size' option. It defaults to 512.
4417 Thus, if the string consists of N characters, the resulting file
4418 fragment will contain `N*BLOCK-SIZE' of data.
4420 Last fragment descriptor can have only file offset part. In this
4421 case `genfile' will create a hole at the end of the file up to the
4424 For example, consider the following invocation:
4426 genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K
4428 It will create 3101184-bytes long file of the following structure:
4430 Offset Length Contents
4431 0 4*512=2048 Four 512-byte blocks, filled
4432 with letters `A', `B', `C' and
4434 2048 1046528 Zero bytes
4435 1050624 5*512=2560 Five blocks, filled with letters
4436 `E', `F', `G', `H', `I'.
4437 1053184 2048000 Zero bytes
4439 The exit code of `genfile --status' command is `0' only if created
4440 file is actually sparse.
4443 File: tar.info, Node: Status Mode, Next: Exec Mode, Prev: Generate Mode, Up: Genfile
4448 In status mode, `genfile' prints file system status for each file
4449 specified in the command line. This mode is toggled by `--stat' (`-S')
4450 command line option. An optional argument to this option specifies
4451 output "format": a comma-separated list of `struct stat' fields to be
4452 displayed. This list can contain following identifiers :
4459 Device number in decimal.
4467 File mode in octal. Optional NUMBER specifies octal mask to be
4468 applied to the mode before outputting. For example, `--stat
4469 mode.777' will preserve lower nine bits of it. Notice, that you
4470 can use any punctuation character in place of `.'.
4474 Number of hard links.
4486 File size in decimal.
4490 The size in bytes of each file block.
4494 Number of blocks allocated.
4498 Time of last access.
4502 Time of last modification
4506 Time of last status change
4509 A boolean value indicating whether the file is `sparse'.
4511 Modification times are displayed in UTC as UNIX timestamps, unless
4512 suffixed with `H' (for "human-readable"), as in `ctimeH', in which case
4513 usual `tar tv' output format is used.
4515 The default output format is: `name,dev,ino,mode,
4516 nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime'.
4518 For example, the following command will display file names and
4519 corresponding times of last access for each file in the current working
4522 genfile --stat=name,atime *
4525 File: tar.info, Node: Exec Mode, Prev: Status Mode, Up: Genfile
4530 This mode is designed for testing the behavior of `paxutils' commands
4531 when some of the files change during archiving. It is an experimental
4534 The `Exec Mode' is toggled by `--run' command line option (or its
4535 alias `-r'). The non-optional arguments to `getopt' give the command
4536 line to be executed. Normally, it should contain at least the
4537 `--checkpoint' option.
4539 A set of options is provided for defining checkpoint values and
4540 actions to be executed upon reaching them. Checkpoint values are
4541 introduced with the `--checkpoint' command line option. Argument to
4542 this option is the number of checkpoint in decimal.
4544 Any number of "actions" may be specified after a checkpoint.
4545 Available actions are
4549 Truncate FILE to the size specified by previous `--length' option
4550 (or 0, if it is not given).
4553 Append data to FILE. The size of data and its pattern are given by
4554 previous `--length' and `pattern' options.
4557 Update the access and modification times of FILE. These timestamps
4558 are changed to the current time, unless `--date' option was given,
4559 in which case they are changed to the specified time. Argument to
4560 `--date' option is a date specification in an almost arbitrary
4561 format (*note Date input formats::).
4564 Execute given shell command.
4569 Option `--verbose' instructs `genfile' to print on standard output
4570 notifications about checkpoints being executed and to verbosely
4571 describe exit status of the command.
4573 While the command is being executed its standard output remains
4574 connected to descriptor 1. All messages it prints to file descriptor 2,
4575 except checkpoint notifications, are forwarded to standard error.
4577 `Genfile' exits with the exit status of the executed command.
4579 For compatibility with previous `genfile' versions, the `--run'
4580 option takes an optional argument. If used this way, its argument
4581 supplies the command line to be executed. There should be no
4582 non-optional arguments in the `genfile' command line.
4584 The actual command line is constructed by inserting the
4585 `--checkpoint' option between the command name and its first argument
4586 (if any). Due to this, the argument to `--run' may not use traditional
4587 `tar' option syntax, i.e., the following is wrong:
4590 genfile --run='tar cf foo bar'
4592 Use the following syntax instead:
4594 genfile --run='tar -cf foo bar' ACTIONS...
4596 The above command line is equivalent to
4598 genfile ACTIONS... -- tar -cf foo bar
4600 Notice, that the use of compatibility mode is deprecated.
4603 File: tar.info, Node: Free Software Needs Free Documentation, Next: GNU Free Documentation License, Prev: Genfile, Up: Top
4605 Appendix F Free Software Needs Free Documentation
4606 *************************************************
4608 The biggest deficiency in the free software community today is not in
4609 the software--it is the lack of good free documentation that we can
4610 include with the free software. Many of our most important programs do
4611 not come with free reference manuals and free introductory texts.
4612 Documentation is an essential part of any software package; when an
4613 important free software package does not come with a free manual and a
4614 free tutorial, that is a major gap. We have many such gaps today.
4616 Consider Perl, for instance. The tutorial manuals that people
4617 normally use are non-free. How did this come about? Because the
4618 authors of those manuals published them with restrictive terms--no
4619 copying, no modification, source files not available--which exclude
4620 them from the free software world.
4622 That wasn't the first time this sort of thing happened, and it was
4623 far from the last. Many times we have heard a GNU user eagerly
4624 describe a manual that he is writing, his intended contribution to the
4625 community, only to learn that he had ruined everything by signing a
4626 publication contract to make it non-free.
4628 Free documentation, like free software, is a matter of freedom, not
4629 price. The problem with the non-free manual is not that publishers
4630 charge a price for printed copies--that in itself is fine. (The Free
4631 Software Foundation sells printed copies of manuals, too.) The problem
4632 is the restrictions on the use of the manual. Free manuals are
4633 available in source code form, and give you permission to copy and
4634 modify. Non-free manuals do not allow this.
4636 The criteria of freedom for a free manual are roughly the same as for
4637 free software. Redistribution (including the normal kinds of
4638 commercial redistribution) must be permitted, so that the manual can
4639 accompany every copy of the program, both on-line and on paper.
4641 Permission for modification of the technical content is crucial too.
4642 When people modify the software, adding or changing features, if they
4643 are conscientious they will change the manual too--so they can provide
4644 accurate and clear documentation for the modified program. A manual
4645 that leaves you no choice but to write a new manual to document a
4646 changed version of the program is not really available to our community.
4648 Some kinds of limits on the way modification is handled are
4649 acceptable. For example, requirements to preserve the original
4650 author's copyright notice, the distribution terms, or the list of
4651 authors, are ok. It is also no problem to require modified versions to
4652 include notice that they were modified. Even entire sections that may
4653 not be deleted or changed are acceptable, as long as they deal with
4654 nontechnical topics (like this one). These kinds of restrictions are
4655 acceptable because they don't obstruct the community's normal use of
4658 However, it must be possible to modify all the _technical_ content
4659 of the manual, and then distribute the result in all the usual media,
4660 through all the usual channels. Otherwise, the restrictions obstruct
4661 the use of the manual, it is not free, and we need another manual to
4664 Please spread the word about this issue. Our community continues to
4665 lose manuals to proprietary publishing. If we spread the word that
4666 free software needs free reference manuals and free tutorials, perhaps
4667 the next person who wants to contribute by writing documentation will
4668 realize, before it is too late, that only free manuals contribute to
4669 the free software community.
4671 If you are writing documentation, please insist on publishing it
4672 under the GNU Free Documentation License or another free documentation
4673 license. Remember that this decision requires your approval--you don't
4674 have to let the publisher decide. Some commercial publishers will use
4675 a free license if you insist, but they will not propose the option; it
4676 is up to you to raise the issue and say firmly that this is what you
4677 want. If the publisher you are dealing with refuses, please try other
4678 publishers. If you're not sure whether a proposed license is free,
4679 write to <licensing@gnu.org>.
4681 You can encourage commercial publishers to sell more free, copylefted
4682 manuals and tutorials by buying them, and particularly by buying copies
4683 from the publishers that paid for their writing or for major
4684 improvements. Meanwhile, try to avoid buying non-free documentation at
4685 all. Check the distribution terms of a manual before you buy it, and
4686 insist that whoever seeks your business must respect your freedom.
4687 Check the history of the book, and try reward the publishers that have
4688 paid or pay the authors to work on it.
4690 The Free Software Foundation maintains a list of free documentation
4691 published by other publishers, at
4692 `http://www.fsf.org/doc/other-free-books.html'.
4695 File: tar.info, Node: GNU Free Documentation License, Next: Index of Command Line Options, Prev: Free Software Needs Free Documentation, Up: Top
4697 Appendix G GNU Free Documentation License
4698 *****************************************
4700 Version 1.3, 3 November 2008
4702 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
4705 Everyone is permitted to copy and distribute verbatim copies
4706 of this license document, but changing it is not allowed.
4710 The purpose of this License is to make a manual, textbook, or other
4711 functional and useful document "free" in the sense of freedom: to
4712 assure everyone the effective freedom to copy and redistribute it,
4713 with or without modifying it, either commercially or
4714 noncommercially. Secondarily, this License preserves for the
4715 author and publisher a way to get credit for their work, while not
4716 being considered responsible for modifications made by others.
4718 This License is a kind of "copyleft", which means that derivative
4719 works of the document must themselves be free in the same sense.
4720 It complements the GNU General Public License, which is a copyleft
4721 license designed for free software.
4723 We have designed this License in order to use it for manuals for
4724 free software, because free software needs free documentation: a
4725 free program should come with manuals providing the same freedoms
4726 that the software does. But this License is not limited to
4727 software manuals; it can be used for any textual work, regardless
4728 of subject matter or whether it is published as a printed book.
4729 We recommend this License principally for works whose purpose is
4730 instruction or reference.
4732 1. APPLICABILITY AND DEFINITIONS
4734 This License applies to any manual or other work, in any medium,
4735 that contains a notice placed by the copyright holder saying it
4736 can be distributed under the terms of this License. Such a notice
4737 grants a world-wide, royalty-free license, unlimited in duration,
4738 to use that work under the conditions stated herein. The
4739 "Document", below, refers to any such manual or work. Any member
4740 of the public is a licensee, and is addressed as "you". You
4741 accept the license if you copy, modify or distribute the work in a
4742 way requiring permission under copyright law.
4744 A "Modified Version" of the Document means any work containing the
4745 Document or a portion of it, either copied verbatim, or with
4746 modifications and/or translated into another language.
4748 A "Secondary Section" is a named appendix or a front-matter section
4749 of the Document that deals exclusively with the relationship of the
4750 publishers or authors of the Document to the Document's overall
4751 subject (or to related matters) and contains nothing that could
4752 fall directly within that overall subject. (Thus, if the Document
4753 is in part a textbook of mathematics, a Secondary Section may not
4754 explain any mathematics.) The relationship could be a matter of
4755 historical connection with the subject or with related matters, or
4756 of legal, commercial, philosophical, ethical or political position
4759 The "Invariant Sections" are certain Secondary Sections whose
4760 titles are designated, as being those of Invariant Sections, in
4761 the notice that says that the Document is released under this
4762 License. If a section does not fit the above definition of
4763 Secondary then it is not allowed to be designated as Invariant.
4764 The Document may contain zero Invariant Sections. If the Document
4765 does not identify any Invariant Sections then there are none.
4767 The "Cover Texts" are certain short passages of text that are
4768 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
4769 that says that the Document is released under this License. A
4770 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
4771 be at most 25 words.
4773 A "Transparent" copy of the Document means a machine-readable copy,
4774 represented in a format whose specification is available to the
4775 general public, that is suitable for revising the document
4776 straightforwardly with generic text editors or (for images
4777 composed of pixels) generic paint programs or (for drawings) some
4778 widely available drawing editor, and that is suitable for input to
4779 text formatters or for automatic translation to a variety of
4780 formats suitable for input to text formatters. A copy made in an
4781 otherwise Transparent file format whose markup, or absence of
4782 markup, has been arranged to thwart or discourage subsequent
4783 modification by readers is not Transparent. An image format is
4784 not Transparent if used for any substantial amount of text. A
4785 copy that is not "Transparent" is called "Opaque".
4787 Examples of suitable formats for Transparent copies include plain
4788 ASCII without markup, Texinfo input format, LaTeX input format,
4789 SGML or XML using a publicly available DTD, and
4790 standard-conforming simple HTML, PostScript or PDF designed for
4791 human modification. Examples of transparent image formats include
4792 PNG, XCF and JPG. Opaque formats include proprietary formats that
4793 can be read and edited only by proprietary word processors, SGML or
4794 XML for which the DTD and/or processing tools are not generally
4795 available, and the machine-generated HTML, PostScript or PDF
4796 produced by some word processors for output purposes only.
4798 The "Title Page" means, for a printed book, the title page itself,
4799 plus such following pages as are needed to hold, legibly, the
4800 material this License requires to appear in the title page. For
4801 works in formats which do not have any title page as such, "Title
4802 Page" means the text near the most prominent appearance of the
4803 work's title, preceding the beginning of the body of the text.
4805 The "publisher" means any person or entity that distributes copies
4806 of the Document to the public.
4808 A section "Entitled XYZ" means a named subunit of the Document
4809 whose title either is precisely XYZ or contains XYZ in parentheses
4810 following text that translates XYZ in another language. (Here XYZ
4811 stands for a specific section name mentioned below, such as
4812 "Acknowledgements", "Dedications", "Endorsements", or "History".)
4813 To "Preserve the Title" of such a section when you modify the
4814 Document means that it remains a section "Entitled XYZ" according
4817 The Document may include Warranty Disclaimers next to the notice
4818 which states that this License applies to the Document. These
4819 Warranty Disclaimers are considered to be included by reference in
4820 this License, but only as regards disclaiming warranties: any other
4821 implication that these Warranty Disclaimers may have is void and
4822 has no effect on the meaning of this License.
4826 You may copy and distribute the Document in any medium, either
4827 commercially or noncommercially, provided that this License, the
4828 copyright notices, and the license notice saying this License
4829 applies to the Document are reproduced in all copies, and that you
4830 add no other conditions whatsoever to those of this License. You
4831 may not use technical measures to obstruct or control the reading
4832 or further copying of the copies you make or distribute. However,
4833 you may accept compensation in exchange for copies. If you
4834 distribute a large enough number of copies you must also follow
4835 the conditions in section 3.
4837 You may also lend copies, under the same conditions stated above,
4838 and you may publicly display copies.
4840 3. COPYING IN QUANTITY
4842 If you publish printed copies (or copies in media that commonly
4843 have printed covers) of the Document, numbering more than 100, and
4844 the Document's license notice requires Cover Texts, you must
4845 enclose the copies in covers that carry, clearly and legibly, all
4846 these Cover Texts: Front-Cover Texts on the front cover, and
4847 Back-Cover Texts on the back cover. Both covers must also clearly
4848 and legibly identify you as the publisher of these copies. The
4849 front cover must present the full title with all words of the
4850 title equally prominent and visible. You may add other material
4851 on the covers in addition. Copying with changes limited to the
4852 covers, as long as they preserve the title of the Document and
4853 satisfy these conditions, can be treated as verbatim copying in
4856 If the required texts for either cover are too voluminous to fit
4857 legibly, you should put the first ones listed (as many as fit
4858 reasonably) on the actual cover, and continue the rest onto
4861 If you publish or distribute Opaque copies of the Document
4862 numbering more than 100, you must either include a
4863 machine-readable Transparent copy along with each Opaque copy, or
4864 state in or with each Opaque copy a computer-network location from
4865 which the general network-using public has access to download
4866 using public-standard network protocols a complete Transparent
4867 copy of the Document, free of added material. If you use the
4868 latter option, you must take reasonably prudent steps, when you
4869 begin distribution of Opaque copies in quantity, to ensure that
4870 this Transparent copy will remain thus accessible at the stated
4871 location until at least one year after the last time you
4872 distribute an Opaque copy (directly or through your agents or
4873 retailers) of that edition to the public.
4875 It is requested, but not required, that you contact the authors of
4876 the Document well before redistributing any large number of
4877 copies, to give them a chance to provide you with an updated
4878 version of the Document.
4882 You may copy and distribute a Modified Version of the Document
4883 under the conditions of sections 2 and 3 above, provided that you
4884 release the Modified Version under precisely this License, with
4885 the Modified Version filling the role of the Document, thus
4886 licensing distribution and modification of the Modified Version to
4887 whoever possesses a copy of it. In addition, you must do these
4888 things in the Modified Version:
4890 A. Use in the Title Page (and on the covers, if any) a title
4891 distinct from that of the Document, and from those of
4892 previous versions (which should, if there were any, be listed
4893 in the History section of the Document). You may use the
4894 same title as a previous version if the original publisher of
4895 that version gives permission.
4897 B. List on the Title Page, as authors, one or more persons or
4898 entities responsible for authorship of the modifications in
4899 the Modified Version, together with at least five of the
4900 principal authors of the Document (all of its principal
4901 authors, if it has fewer than five), unless they release you
4902 from this requirement.
4904 C. State on the Title page the name of the publisher of the
4905 Modified Version, as the publisher.
4907 D. Preserve all the copyright notices of the Document.
4909 E. Add an appropriate copyright notice for your modifications
4910 adjacent to the other copyright notices.
4912 F. Include, immediately after the copyright notices, a license
4913 notice giving the public permission to use the Modified
4914 Version under the terms of this License, in the form shown in
4917 G. Preserve in that license notice the full lists of Invariant
4918 Sections and required Cover Texts given in the Document's
4921 H. Include an unaltered copy of this License.
4923 I. Preserve the section Entitled "History", Preserve its Title,
4924 and add to it an item stating at least the title, year, new
4925 authors, and publisher of the Modified Version as given on
4926 the Title Page. If there is no section Entitled "History" in
4927 the Document, create one stating the title, year, authors,
4928 and publisher of the Document as given on its Title Page,
4929 then add an item describing the Modified Version as stated in
4930 the previous sentence.
4932 J. Preserve the network location, if any, given in the Document
4933 for public access to a Transparent copy of the Document, and
4934 likewise the network locations given in the Document for
4935 previous versions it was based on. These may be placed in
4936 the "History" section. You may omit a network location for a
4937 work that was published at least four years before the
4938 Document itself, or if the original publisher of the version
4939 it refers to gives permission.
4941 K. For any section Entitled "Acknowledgements" or "Dedications",
4942 Preserve the Title of the section, and preserve in the
4943 section all the substance and tone of each of the contributor
4944 acknowledgements and/or dedications given therein.
4946 L. Preserve all the Invariant Sections of the Document,
4947 unaltered in their text and in their titles. Section numbers
4948 or the equivalent are not considered part of the section
4951 M. Delete any section Entitled "Endorsements". Such a section
4952 may not be included in the Modified Version.
4954 N. Do not retitle any existing section to be Entitled
4955 "Endorsements" or to conflict in title with any Invariant
4958 O. Preserve any Warranty Disclaimers.
4960 If the Modified Version includes new front-matter sections or
4961 appendices that qualify as Secondary Sections and contain no
4962 material copied from the Document, you may at your option
4963 designate some or all of these sections as invariant. To do this,
4964 add their titles to the list of Invariant Sections in the Modified
4965 Version's license notice. These titles must be distinct from any
4966 other section titles.
4968 You may add a section Entitled "Endorsements", provided it contains
4969 nothing but endorsements of your Modified Version by various
4970 parties--for example, statements of peer review or that the text
4971 has been approved by an organization as the authoritative
4972 definition of a standard.
4974 You may add a passage of up to five words as a Front-Cover Text,
4975 and a passage of up to 25 words as a Back-Cover Text, to the end
4976 of the list of Cover Texts in the Modified Version. Only one
4977 passage of Front-Cover Text and one of Back-Cover Text may be
4978 added by (or through arrangements made by) any one entity. If the
4979 Document already includes a cover text for the same cover,
4980 previously added by you or by arrangement made by the same entity
4981 you are acting on behalf of, you may not add another; but you may
4982 replace the old one, on explicit permission from the previous
4983 publisher that added the old one.
4985 The author(s) and publisher(s) of the Document do not by this
4986 License give permission to use their names for publicity for or to
4987 assert or imply endorsement of any Modified Version.
4989 5. COMBINING DOCUMENTS
4991 You may combine the Document with other documents released under
4992 this License, under the terms defined in section 4 above for
4993 modified versions, provided that you include in the combination
4994 all of the Invariant Sections of all of the original documents,
4995 unmodified, and list them all as Invariant Sections of your
4996 combined work in its license notice, and that you preserve all
4997 their Warranty Disclaimers.
4999 The combined work need only contain one copy of this License, and
5000 multiple identical Invariant Sections may be replaced with a single
5001 copy. If there are multiple Invariant Sections with the same name
5002 but different contents, make the title of each such section unique
5003 by adding at the end of it, in parentheses, the name of the
5004 original author or publisher of that section if known, or else a
5005 unique number. Make the same adjustment to the section titles in
5006 the list of Invariant Sections in the license notice of the
5009 In the combination, you must combine any sections Entitled
5010 "History" in the various original documents, forming one section
5011 Entitled "History"; likewise combine any sections Entitled
5012 "Acknowledgements", and any sections Entitled "Dedications". You
5013 must delete all sections Entitled "Endorsements."
5015 6. COLLECTIONS OF DOCUMENTS
5017 You may make a collection consisting of the Document and other
5018 documents released under this License, and replace the individual
5019 copies of this License in the various documents with a single copy
5020 that is included in the collection, provided that you follow the
5021 rules of this License for verbatim copying of each of the
5022 documents in all other respects.
5024 You may extract a single document from such a collection, and
5025 distribute it individually under this License, provided you insert
5026 a copy of this License into the extracted document, and follow
5027 this License in all other respects regarding verbatim copying of
5030 7. AGGREGATION WITH INDEPENDENT WORKS
5032 A compilation of the Document or its derivatives with other
5033 separate and independent documents or works, in or on a volume of
5034 a storage or distribution medium, is called an "aggregate" if the
5035 copyright resulting from the compilation is not used to limit the
5036 legal rights of the compilation's users beyond what the individual
5037 works permit. When the Document is included in an aggregate, this
5038 License does not apply to the other works in the aggregate which
5039 are not themselves derivative works of the Document.
5041 If the Cover Text requirement of section 3 is applicable to these
5042 copies of the Document, then if the Document is less than one half
5043 of the entire aggregate, the Document's Cover Texts may be placed
5044 on covers that bracket the Document within the aggregate, or the
5045 electronic equivalent of covers if the Document is in electronic
5046 form. Otherwise they must appear on printed covers that bracket
5047 the whole aggregate.
5051 Translation is considered a kind of modification, so you may
5052 distribute translations of the Document under the terms of section
5053 4. Replacing Invariant Sections with translations requires special
5054 permission from their copyright holders, but you may include
5055 translations of some or all Invariant Sections in addition to the
5056 original versions of these Invariant Sections. You may include a
5057 translation of this License, and all the license notices in the
5058 Document, and any Warranty Disclaimers, provided that you also
5059 include the original English version of this License and the
5060 original versions of those notices and disclaimers. In case of a
5061 disagreement between the translation and the original version of
5062 this License or a notice or disclaimer, the original version will
5065 If a section in the Document is Entitled "Acknowledgements",
5066 "Dedications", or "History", the requirement (section 4) to
5067 Preserve its Title (section 1) will typically require changing the
5072 You may not copy, modify, sublicense, or distribute the Document
5073 except as expressly provided under this License. Any attempt
5074 otherwise to copy, modify, sublicense, or distribute it is void,
5075 and will automatically terminate your rights under this License.
5077 However, if you cease all violation of this License, then your
5078 license from a particular copyright holder is reinstated (a)
5079 provisionally, unless and until the copyright holder explicitly
5080 and finally terminates your license, and (b) permanently, if the
5081 copyright holder fails to notify you of the violation by some
5082 reasonable means prior to 60 days after the cessation.
5084 Moreover, your license from a particular copyright holder is
5085 reinstated permanently if the copyright holder notifies you of the
5086 violation by some reasonable means, this is the first time you have
5087 received notice of violation of this License (for any work) from
5088 that copyright holder, and you cure the violation prior to 30 days
5089 after your receipt of the notice.
5091 Termination of your rights under this section does not terminate
5092 the licenses of parties who have received copies or rights from
5093 you under this License. If your rights have been terminated and
5094 not permanently reinstated, receipt of a copy of some or all of
5095 the same material does not give you any rights to use it.
5097 10. FUTURE REVISIONS OF THIS LICENSE
5099 The Free Software Foundation may publish new, revised versions of
5100 the GNU Free Documentation License from time to time. Such new
5101 versions will be similar in spirit to the present version, but may
5102 differ in detail to address new problems or concerns. See
5103 `http://www.gnu.org/copyleft/'.
5105 Each version of the License is given a distinguishing version
5106 number. If the Document specifies that a particular numbered
5107 version of this License "or any later version" applies to it, you
5108 have the option of following the terms and conditions either of
5109 that specified version or of any later version that has been
5110 published (not as a draft) by the Free Software Foundation. If
5111 the Document does not specify a version number of this License,
5112 you may choose any version ever published (not as a draft) by the
5113 Free Software Foundation. If the Document specifies that a proxy
5114 can decide which future versions of this License can be used, that
5115 proxy's public statement of acceptance of a version permanently
5116 authorizes you to choose that version for the Document.
5120 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
5121 World Wide Web server that publishes copyrightable works and also
5122 provides prominent facilities for anybody to edit those works. A
5123 public wiki that anybody can edit is an example of such a server.
5124 A "Massive Multiauthor Collaboration" (or "MMC") contained in the
5125 site means any set of copyrightable works thus published on the MMC
5128 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
5129 license published by Creative Commons Corporation, a not-for-profit
5130 corporation with a principal place of business in San Francisco,
5131 California, as well as future copyleft versions of that license
5132 published by that same organization.
5134 "Incorporate" means to publish or republish a Document, in whole or
5135 in part, as part of another Document.
5137 An MMC is "eligible for relicensing" if it is licensed under this
5138 License, and if all works that were first published under this
5139 License somewhere other than this MMC, and subsequently
5140 incorporated in whole or in part into the MMC, (1) had no cover
5141 texts or invariant sections, and (2) were thus incorporated prior
5142 to November 1, 2008.
5144 The operator of an MMC Site may republish an MMC contained in the
5145 site under CC-BY-SA on the same site at any time before August 1,
5146 2009, provided the MMC is eligible for relicensing.
5149 ADDENDUM: How to use this License for your documents
5150 ====================================================
5152 To use this License in a document you have written, include a copy of
5153 the License in the document and put the following copyright and license
5154 notices just after the title page:
5156 Copyright (C) YEAR YOUR NAME.
5157 Permission is granted to copy, distribute and/or modify this document
5158 under the terms of the GNU Free Documentation License, Version 1.3
5159 or any later version published by the Free Software Foundation;
5160 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
5161 Texts. A copy of the license is included in the section entitled ``GNU
5162 Free Documentation License''.
5164 If you have Invariant Sections, Front-Cover Texts and Back-Cover
5165 Texts, replace the "with...Texts." line with this:
5167 with the Invariant Sections being LIST THEIR TITLES, with
5168 the Front-Cover Texts being LIST, and with the Back-Cover Texts
5171 If you have Invariant Sections without Cover Texts, or some other
5172 combination of the three, merge those two alternatives to suit the
5175 If your document contains nontrivial examples of program code, we
5176 recommend releasing these examples in parallel under your choice of
5177 free software license, such as the GNU General Public License, to
5178 permit their use in free software.
5181 File: tar.info, Node: Index of Command Line Options, Next: Index, Prev: GNU Free Documentation License, Up: Top
5183 Appendix H Index of Command Line Options
5184 ****************************************
5186 This appendix contains an index of all GNU `tar' long command line
5187 options. The options are listed without the preceding double-dash. For
5188 a cross-reference of short command line options, see *note Short Option
5194 * absolute-names: absolute. (line 10)
5195 * absolute-names, summary: Option Summary. (line 6)
5196 * add-file: files. (line 84)
5197 * after-date: after. (line 24)
5198 * after-date, summary: Option Summary. (line 12)
5199 * anchored: controlling pattern-matching.
5201 * anchored, summary: Option Summary. (line 15)
5202 * append <1>: appending files. (line 6)
5203 * append: append. (line 6)
5204 * append, summary: Operation Summary. (line 6)
5205 * atime-preserve: Attributes. (line 10)
5206 * atime-preserve, summary: Option Summary. (line 19)
5207 * auto-compress: gzip. (line 144)
5208 * auto-compress, summary: Option Summary. (line 65)
5209 * backup: backup. (line 41)
5210 * backup, summary: Option Summary. (line 71)
5211 * block-number: verbose. (line 115)
5212 * block-number, summary: Option Summary. (line 76)
5213 * blocking-factor: Blocking Factor. (line 8)
5214 * blocking-factor, summary: Option Summary. (line 82)
5215 * bzip2, summary: Option Summary. (line 87)
5216 * catenate: concatenate. (line 6)
5217 * catenate, summary: Operation Summary. (line 10)
5218 * check-device, described: Incremental Dumps. (line 108)
5219 * check-device, summary: Option Summary. (line 92)
5220 * check-links, described: hard links. (line 31)
5221 * check-links, summary: Option Summary. (line 143)
5222 * checkpoint: checkpoints. (line 6)
5223 * checkpoint, defined: checkpoints. (line 13)
5224 * checkpoint, summary: Option Summary. (line 97)
5225 * checkpoint-action: checkpoints. (line 6)
5226 * checkpoint-action, defined: checkpoints. (line 22)
5227 * checkpoint-action, summary: Option Summary. (line 105)
5228 * compare: compare. (line 6)
5229 * compare, summary: Operation Summary. (line 14)
5230 * compress: gzip. (line 101)
5231 * compress, summary: Option Summary. (line 152)
5232 * concatenate: concatenate. (line 6)
5233 * concatenate, summary: Operation Summary. (line 20)
5234 * confirmation, summary: Option Summary. (line 159)
5235 * create, additional options: create options. (line 6)
5236 * create, complementary notes: Basic tar. (line 11)
5237 * create, introduced: Creating the archive.
5239 * create, summary: Operation Summary. (line 25)
5240 * create, using with --verbose: create verbose. (line 6)
5241 * create, using with --verify: verify. (line 24)
5242 * delay-directory-restore: Directory Modification Times and Permissions.
5244 * delay-directory-restore, summary: Option Summary. (line 162)
5245 * delete: delete. (line 6)
5246 * delete, summary: Operation Summary. (line 29)
5247 * delete, using before -append: append. (line 47)
5248 * dereference: dereference. (line 6)
5249 * dereference, summary: Option Summary. (line 167)
5250 * diff, summary: Operation Summary. (line 33)
5251 * directory: directory. (line 11)
5252 * directory, summary: Option Summary. (line 173)
5253 * directory, using in --files-from argument: files. (line 60)
5254 * exclude: exclude. (line 6)
5255 * exclude, potential problems with: problems with exclude.
5257 * exclude, summary: Option Summary. (line 180)
5258 * exclude-backups: exclude. (line 82)
5259 * exclude-backups, summary: Option Summary. (line 184)
5260 * exclude-caches: exclude. (line 105)
5261 * exclude-caches, summary: Option Summary. (line 192)
5262 * exclude-caches-all: exclude. (line 113)
5263 * exclude-caches-all, summary: Option Summary. (line 205)
5264 * exclude-caches-under: exclude. (line 109)
5265 * exclude-caches-under, summary: Option Summary. (line 199)
5266 * exclude-from: exclude. (line 6)
5267 * exclude-from, summary: Option Summary. (line 187)
5268 * exclude-tag: exclude. (line 122)
5269 * exclude-tag, summary: Option Summary. (line 209)
5270 * exclude-tag-all: exclude. (line 130)
5271 * exclude-tag-all, summary: Option Summary. (line 219)
5272 * exclude-tag-under: exclude. (line 126)
5273 * exclude-tag-under, summary: Option Summary. (line 214)
5274 * exclude-vcs: exclude. (line 37)
5275 * exclude-vcs, summary: Option Summary. (line 223)
5276 * extract: extract. (line 6)
5277 * extract, additional options: extract options. (line 6)
5278 * extract, complementary notes: Basic tar. (line 48)
5279 * extract, summary: Operation Summary. (line 37)
5280 * extract, using with --listed-incremental: Incremental Dumps.
5282 * file: file. (line 6)
5283 * file, short description: file. (line 15)
5284 * file, summary: Option Summary. (line 229)
5285 * file, tutorial: file tutorial. (line 6)
5286 * files-from: files. (line 14)
5287 * files-from, summary: Option Summary. (line 235)
5288 * force-local, short description: Device. (line 70)
5289 * force-local, summary: Option Summary. (line 241)
5290 * format, summary: Option Summary. (line 246)
5291 * full-time, summary: Option Summary. (line 271)
5292 * get, summary: Operation Summary. (line 42)
5293 * group: override. (line 75)
5294 * group, summary: Option Summary. (line 289)
5295 * gunzip, summary: Option Summary. (line 297)
5296 * gzip: gzip. (line 79)
5297 * gzip, summary: Option Summary. (line 297)
5298 * hard-dereference, described: hard links. (line 59)
5299 * hard-dereference, summary: Option Summary. (line 305)
5300 * help: help tutorial. (line 6)
5301 * help, introduction: help. (line 27)
5302 * help, summary: Option Summary. (line 311)
5303 * ignore-case: controlling pattern-matching.
5305 * ignore-case, summary: Option Summary. (line 316)
5306 * ignore-command-error: Writing to an External Program.
5308 * ignore-command-error, summary: Option Summary. (line 320)
5309 * ignore-failed-read: Ignore Failed Read. (line 7)
5310 * ignore-failed-read, summary: Option Summary. (line 324)
5311 * ignore-zeros: Ignore Zeros. (line 6)
5312 * ignore-zeros, short description: Blocking Factor. (line 156)
5313 * ignore-zeros, summary: Option Summary. (line 328)
5314 * incremental, summary: Option Summary. (line 333)
5315 * incremental, using with --list: Incremental Dumps. (line 186)
5316 * index-file, summary: Option Summary. (line 340)
5317 * info-script: Multi-Volume Archives.
5319 * info-script, short description: Device. (line 122)
5320 * info-script, summary: Option Summary. (line 343)
5321 * interactive: interactive. (line 14)
5322 * interactive, summary: Option Summary. (line 351)
5323 * keep-newer-files: Keep Newer Files. (line 6)
5324 * keep-newer-files, summary: Option Summary. (line 358)
5325 * keep-old-files: Keep Old Files. (line 6)
5326 * keep-old-files, introduced: Dealing with Old Files.
5328 * keep-old-files, summary: Option Summary. (line 362)
5329 * label <1>: label. (line 6)
5330 * label: Tape Files. (line 6)
5331 * label, summary: Option Summary. (line 367)
5332 * level, described: Incremental Dumps. (line 76)
5333 * level, summary: Option Summary. (line 374)
5334 * list: list. (line 6)
5335 * list, summary: Operation Summary. (line 46)
5336 * list, using with --incremental: Incremental Dumps. (line 186)
5337 * list, using with --listed-incremental: Incremental Dumps. (line 186)
5338 * list, using with --verbose: list. (line 30)
5339 * list, using with file name arguments: list. (line 68)
5340 * listed-incremental, described: Incremental Dumps. (line 14)
5341 * listed-incremental, summary: Option Summary. (line 384)
5342 * listed-incremental, using with --extract: Incremental Dumps.
5344 * listed-incremental, using with --list: Incremental Dumps. (line 186)
5345 * lzip: gzip. (line 92)
5346 * lzip, summary: Option Summary. (line 392)
5347 * lzma: gzip. (line 95)
5348 * lzma, summary: Option Summary. (line 396)
5349 * lzop: gzip. (line 98)
5350 * mode: override. (line 14)
5351 * mode, summary: Option Summary. (line 404)
5352 * mtime: override. (line 29)
5353 * mtime, summary: Option Summary. (line 410)
5354 * multi-volume: Multi-Volume Archives.
5356 * multi-volume, short description: Device. (line 88)
5357 * multi-volume, summary: Option Summary. (line 419)
5358 * new-volume-script: Multi-Volume Archives.
5360 * new-volume-script, short description: Device. (line 122)
5361 * new-volume-script, summary: Option Summary. (line 343)
5362 * newer: after. (line 24)
5363 * newer, summary: Option Summary. (line 427)
5364 * newer-mtime: after. (line 35)
5365 * newer-mtime, summary: Option Summary. (line 435)
5366 * no-anchored: controlling pattern-matching.
5368 * no-anchored, summary: Option Summary. (line 440)
5369 * no-auto-compress, summary: Option Summary. (line 444)
5370 * no-check-device, described: Incremental Dumps. (line 104)
5371 * no-check-device, summary: Option Summary. (line 448)
5372 * no-delay-directory-restore: Directory Modification Times and Permissions.
5374 * no-delay-directory-restore, summary: Option Summary. (line 453)
5375 * no-ignore-case: controlling pattern-matching.
5377 * no-ignore-case, summary: Option Summary. (line 459)
5378 * no-ignore-command-error: Writing to an External Program.
5380 * no-ignore-command-error, summary: Option Summary. (line 462)
5381 * no-null, described: nul. (line 15)
5382 * no-null, summary: Option Summary. (line 466)
5383 * no-overwrite-dir, summary: Option Summary. (line 471)
5384 * no-quote-chars, summary: Option Summary. (line 475)
5385 * no-recursion: recurse. (line 11)
5386 * no-recursion, summary: Option Summary. (line 480)
5387 * no-same-owner: Attributes. (line 63)
5388 * no-same-owner, summary: Option Summary. (line 484)
5389 * no-same-permissions, summary: Option Summary. (line 490)
5390 * no-seek, summary: Option Summary. (line 495)
5391 * no-unquote: Selecting Archive Members.
5393 * no-unquote, summary: Option Summary. (line 500)
5394 * no-wildcards: controlling pattern-matching.
5396 * no-wildcards, summary: Option Summary. (line 504)
5397 * no-wildcards-match-slash: controlling pattern-matching.
5399 * no-wildcards-match-slash, summary: Option Summary. (line 507)
5400 * null, described: nul. (line 11)
5401 * null, summary: Option Summary. (line 510)
5402 * numeric-owner: Attributes. (line 69)
5403 * numeric-owner, summary: Option Summary. (line 516)
5404 * occurrence, described: append. (line 34)
5405 * occurrence, summary: Option Summary. (line 533)
5406 * old-archive, summary: Option Summary. (line 547)
5407 * one-file-system: one. (line 14)
5408 * one-file-system, summary: Option Summary. (line 550)
5409 * overwrite: Overwrite Old Files. (line 6)
5410 * overwrite, introduced: Dealing with Old Files.
5412 * overwrite, summary: Option Summary. (line 555)
5413 * overwrite-dir: Overwrite Old Files. (line 28)
5414 * overwrite-dir, introduced: Dealing with Old Files.
5416 * overwrite-dir, summary: Option Summary. (line 559)
5417 * owner: override. (line 57)
5418 * owner, summary: Option Summary. (line 563)
5419 * pax-option: PAX keywords. (line 6)
5420 * pax-option, summary: Option Summary. (line 572)
5421 * portability, summary: Option Summary. (line 578)
5422 * posix, summary: Option Summary. (line 582)
5423 * preserve: Attributes. (line 122)
5424 * preserve, summary: Option Summary. (line 585)
5425 * preserve-order: Same Order. (line 6)
5426 * preserve-order, summary: Option Summary. (line 589)
5427 * preserve-permissions: Setting Access Permissions.
5429 * preserve-permissions, short description: Attributes. (line 109)
5430 * preserve-permissions, summary: Option Summary. (line 592)
5431 * quote-chars, summary: Option Summary. (line 602)
5432 * quoting-style: quoting styles. (line 38)
5433 * quoting-style, summary: Option Summary. (line 606)
5434 * read-full-records <1>: read full records. (line 6)
5435 * read-full-records: Reading. (line 6)
5436 * read-full-records, short description: Blocking Factor. (line 172)
5437 * read-full-records, summary: Option Summary. (line 613)
5438 * record-size, summary: Option Summary. (line 618)
5439 * recursion: recurse. (line 22)
5440 * recursion, summary: Option Summary. (line 625)
5441 * recursive-unlink: Recursive Unlink. (line 6)
5442 * recursive-unlink, summary: Option Summary. (line 629)
5443 * remove-files: remove files. (line 6)
5444 * remove-files, summary: Option Summary. (line 634)
5445 * restrict, summary: Option Summary. (line 638)
5446 * rmt-command, summary: Option Summary. (line 643)
5447 * rsh-command: Device. (line 73)
5448 * rsh-command, summary: Option Summary. (line 647)
5449 * same-order: Same Order. (line 6)
5450 * same-order, summary: Option Summary. (line 651)
5451 * same-owner: Attributes. (line 44)
5452 * same-owner, summary: Option Summary. (line 659)
5453 * same-permissions: Setting Access Permissions.
5455 * same-permissions, short description: Attributes. (line 109)
5456 * same-permissions, summary: Option Summary. (line 592)
5457 * seek, summary: Option Summary. (line 668)
5458 * show-defaults: defaults. (line 6)
5459 * show-defaults, summary: Option Summary. (line 677)
5460 * show-omitted-dirs: verbose. (line 107)
5461 * show-omitted-dirs, summary: Option Summary. (line 689)
5462 * show-stored-names: list. (line 60)
5463 * show-stored-names, summary: Option Summary. (line 693)
5464 * show-transformed-names: transform. (line 45)
5465 * show-transformed-names, summary: Option Summary. (line 693)
5466 * sparse: sparse. (line 22)
5467 * sparse, summary: Option Summary. (line 701)
5468 * sparse-version: sparse. (line 57)
5469 * sparse-version, summary: Option Summary. (line 706)
5470 * starting-file: Starting File. (line 6)
5471 * starting-file, summary: Option Summary. (line 711)
5472 * strip-components: transform. (line 25)
5473 * strip-components, summary: Option Summary. (line 717)
5474 * suffix: backup. (line 68)
5475 * suffix, summary: Option Summary. (line 726)
5476 * tape-length: Multi-Volume Archives.
5478 * tape-length, short description: Device. (line 96)
5479 * tape-length, summary: Option Summary. (line 730)
5480 * test-label: label. (line 35)
5481 * test-label, summary: Option Summary. (line 739)
5482 * to-command: Writing to an External Program.
5484 * to-command, summary: Option Summary. (line 743)
5485 * to-stdout: Writing to Standard Output.
5487 * to-stdout, summary: Option Summary. (line 747)
5488 * totals: verbose. (line 46)
5489 * totals, summary: Option Summary. (line 752)
5490 * touch <1>: Attributes. (line 33)
5491 * touch: Data Modification Times.
5493 * touch, summary: Option Summary. (line 757)
5494 * transform: transform. (line 74)
5495 * transform, summary: Option Summary. (line 763)
5496 * uncompress: gzip. (line 101)
5497 * uncompress, summary: Option Summary. (line 152)
5498 * ungzip: gzip. (line 79)
5499 * ungzip, summary: Option Summary. (line 297)
5500 * unlink-first: Unlink First. (line 6)
5501 * unlink-first, introduced: Dealing with Old Files.
5503 * unlink-first, summary: Option Summary. (line 783)
5504 * unquote: Selecting Archive Members.
5506 * unquote, summary: Option Summary. (line 789)
5507 * update <1>: how to update. (line 6)
5508 * update: update. (line 6)
5509 * update, summary: Operation Summary. (line 50)
5510 * usage: help. (line 54)
5511 * use-compress-program: gzip. (line 166)
5512 * use-compress-program, summary: Option Summary. (line 793)
5513 * utc, summary: Option Summary. (line 798)
5514 * verbose: verbose. (line 18)
5515 * verbose, introduced: verbose tutorial. (line 6)
5516 * verbose, summary: Option Summary. (line 802)
5517 * verbose, using with --create: create verbose. (line 6)
5518 * verbose, using with --list: list. (line 30)
5519 * verify, short description: verify. (line 8)
5520 * verify, summary: Option Summary. (line 809)
5521 * verify, using with --create: verify. (line 24)
5522 * version: help. (line 6)
5523 * version, summary: Option Summary. (line 814)
5524 * volno-file: Multi-Volume Archives.
5526 * volno-file, summary: Option Summary. (line 819)
5527 * warning, explained: warnings. (line 12)
5528 * warning, summary: Option Summary. (line 824)
5529 * wildcards: controlling pattern-matching.
5531 * wildcards, summary: Option Summary. (line 829)
5532 * wildcards-match-slash: controlling pattern-matching.
5534 * wildcards-match-slash, summary: Option Summary. (line 833)
5535 * xform: transform. (line 74)
5536 * xform, summary: Option Summary. (line 763)
5537 * xz: gzip. (line 84)
5538 * xz, summary: Option Summary. (line 836)
5541 File: tar.info, Node: Index, Prev: Index of Command Line Options, Up: Top
5549 * %s: Directory has been renamed from %s, warning message: warnings.
5551 * %s: Directory has been renamed, warning message: warnings. (line 94)
5552 * %s: Directory is new, warning message: warnings. (line 96)
5553 * %s: directory is on a different device: not purging, warning message: warnings.
5555 * -after-date and -update compared: after. (line 19)
5556 * -newer-mtime and -update compared: after. (line 19)
5557 * A lone zero block at, warning message: warnings. (line 35)
5558 * abbreviations for months: Calendar date items. (line 38)
5559 * absolute file names <1>: Remote Tape Server. (line 17)
5560 * absolute file names: absolute. (line 6)
5561 * Adding archives to an archive: concatenate. (line 6)
5562 * Adding files to an Archive: appending files. (line 6)
5563 * ADMINISTRATOR: General-Purpose Variables.
5565 * Age, excluding files by: after. (line 6)
5566 * ago in date strings: Relative items in date strings.
5568 * all: warnings. (line 28)
5569 * alone-zero-block: warnings. (line 35)
5570 * am in date strings: Time of day items. (line 22)
5571 * Appending files to an Archive: appending files. (line 6)
5572 * appending files to existing archive: append. (line 6)
5573 * Arch, excluding files: exclude. (line 37)
5574 * archive: Definitions. (line 6)
5575 * Archive creation: file. (line 34)
5576 * archive member: Definitions. (line 15)
5577 * Archive Name: file. (line 6)
5578 * Archive, creation of: create. (line 8)
5579 * Archives, Appending files to: appending files. (line 6)
5580 * archives, binary equivalent: PAX keywords. (line 132)
5581 * Archiving Directories: create dir. (line 6)
5582 * archiving files: Top. (line 24)
5583 * ARGP_HELP_FMT, environment variable: Configuring Help Summary.
5585 * arguments to long options: Long Options. (line 31)
5586 * arguments to old options: Old Options. (line 17)
5587 * arguments to short options: Short Options. (line 13)
5588 * atrributes, files: Attributes. (line 6)
5589 * Attempting extraction of symbolic links as hard links, warning message: warnings.
5591 * authors of parse_datetime: Authors of parse_datetime.
5593 * Avoiding recursion in directories: recurse. (line 6)
5594 * backup options: backup. (line 6)
5595 * backup suffix: backup. (line 68)
5596 * BACKUP_DIRS: General-Purpose Variables.
5598 * BACKUP_FILES: General-Purpose Variables.
5600 * BACKUP_HOUR: General-Purpose Variables.
5602 * backups <1>: Backups. (line 6)
5603 * backups: backup. (line 41)
5604 * bad-dumpdir: warnings. (line 102)
5605 * basic operations: Operations. (line 6)
5606 * Bazaar, excluding files: exclude. (line 37)
5607 * beginning of time, for POSIX: Seconds since the Epoch.
5609 * bell, checkpoint action: checkpoints. (line 65)
5610 * Bellovin, Steven M.: Authors of parse_datetime.
5612 * Berets, Jim: Authors of parse_datetime.
5614 * Berry, K.: Authors of parse_datetime.
5616 * binary equivalent archives, creating: PAX keywords. (line 132)
5617 * block: Blocking. (line 6)
5618 * Block number where error occurred: verbose. (line 115)
5619 * BLOCKING: General-Purpose Variables.
5621 * blocking factor: Blocking Factor. (line 194)
5622 * Blocking Factor: Blocking Factor. (line 6)
5623 * Blocks per record: Blocking Factor. (line 6)
5624 * bug reports: Reports. (line 6)
5625 * Bytes per record: Blocking Factor. (line 6)
5626 * bzip2: gzip. (line 6)
5627 * cachedir: warnings. (line 43)
5628 * calendar date item: Calendar date items. (line 6)
5629 * case, ignored in dates: General date syntax. (line 64)
5630 * cat vs concatenate: concatenate. (line 63)
5631 * Changing directory mid-stream: directory. (line 6)
5632 * Character class, excluding characters from: wildcards. (line 34)
5633 * checkpoints, defined: checkpoints. (line 6)
5634 * Choosing an archive file: file. (line 6)
5635 * comments, in dates: General date syntax. (line 64)
5636 * compress: gzip. (line 6)
5637 * Compressed archives: gzip. (line 6)
5638 * concatenate vs cat: concatenate. (line 63)
5639 * Concatenating Archives: concatenate. (line 6)
5640 * contains a cache directory tag, warning message: warnings. (line 43)
5641 * contiguous-cast: warnings. (line 74)
5642 * corrupted archives <1>: gzip. (line 134)
5643 * corrupted archives: Full Dumps. (line 8)
5644 * Creation of the archive: create. (line 8)
5645 * Current %s is newer or same age, warning message: warnings. (line 83)
5646 * CVS, excluding files: exclude. (line 37)
5647 * Darcs, excluding files: exclude. (line 37)
5648 * DAT blocking: Blocking Factor. (line 204)
5649 * Data Modification time, excluding files by: after. (line 6)
5650 * Data modification times of extracted files: Data Modification Times.
5652 * date format, ISO 8601: Calendar date items. (line 30)
5653 * date input formats: Date input formats. (line 6)
5654 * day in date strings: Relative items in date strings.
5656 * day of week item: Day of week items. (line 6)
5657 * Deleting files from an archive: delete. (line 6)
5658 * Deleting from tape archives: delete. (line 17)
5659 * dereferencing hard links: hard links. (line 6)
5660 * Descending directories, avoiding: recurse. (line 6)
5661 * Device numbers, changing: Fixing Snapshot Files.
5663 * Device numbers, using in incremental backups: Incremental Dumps.
5665 * Directories, Archiving: create dir. (line 6)
5666 * Directories, avoiding recursion: recurse. (line 6)
5667 * Directory, changing mid-stream: directory. (line 6)
5668 * DIRLIST: General-Purpose Variables.
5670 * displacement of dates: Relative items in date strings.
5672 * doc-opt-col: Configuring Help Summary.
5674 * door ignored, warning message: warnings. (line 50)
5675 * dot, checkpoint action: checkpoints. (line 80)
5676 * Double-checking a write operation: verify. (line 6)
5677 * DUMP_BEGIN: User Hooks. (line 32)
5678 * DUMP_END: User Hooks. (line 36)
5679 * DUMP_REMIND_SCRIPT: General-Purpose Variables.
5681 * dumps, full: Full Dumps. (line 8)
5682 * dup-args: Configuring Help Summary.
5684 * dup-args-note: Configuring Help Summary.
5686 * echo, checkpoint action: checkpoints. (line 25)
5687 * Eggert, Paul: Authors of parse_datetime.
5689 * End-of-archive blocks, ignoring: Ignore Zeros. (line 6)
5690 * End-of-archive info script: Multi-Volume Archives.
5692 * entry: Naming tar Archives. (line 11)
5693 * epoch, for POSIX: Seconds since the Epoch.
5695 * Error message, block number of: verbose. (line 125)
5696 * Exabyte blocking: Blocking Factor. (line 204)
5697 * exclude: exclude. (line 12)
5698 * exclude-caches: exclude. (line 93)
5699 * exclude-from: exclude. (line 25)
5700 * exclude-tag: exclude. (line 116)
5701 * Excluding characters from a character class: wildcards. (line 34)
5702 * Excluding file by age: after. (line 6)
5703 * Excluding files by file system: exclude. (line 6)
5704 * Excluding files by name and pattern: exclude. (line 6)
5705 * Exec Mode, genfile: Exec Mode. (line 6)
5706 * exec, checkpoint action: checkpoints. (line 96)
5707 * existing backup method: backup. (line 59)
5708 * exit status: Synopsis. (line 67)
5709 * Extracting contiguous files as regular files, warning message: warnings.
5711 * extracting Nth copy of the file: append. (line 34)
5712 * Extraction: extract. (line 6)
5713 * extraction: Definitions. (line 22)
5714 * file archival: Top. (line 24)
5715 * file attributes: Attributes. (line 6)
5716 * file changed as we read it, warning message: warnings. (line 64)
5717 * file is on a different filesystem, warning message: warnings.
5719 * file is the archive; not dumped, warning message: warnings. (line 58)
5720 * file is unchanged; not dumped, warning message: warnings. (line 55)
5721 * File lists separated by NUL characters: Generate Mode. (line 33)
5722 * file name: Definitions. (line 15)
5723 * File Name arguments, alternatives: files. (line 6)
5724 * File name arguments, using --list with: list. (line 68)
5725 * file name read contains nul character, warning message: warnings.
5727 * file names, absolute: absolute. (line 6)
5728 * File names, excluding files by: exclude. (line 6)
5729 * File names, terminated by NUL: nul. (line 6)
5730 * File names, using hard links: hard links. (line 6)
5731 * File names, using symbolic links: dereference. (line 6)
5732 * File removed before we read it, warning message: warnings. (line 61)
5733 * File shrank by %s bytes, warning message: warnings. (line 44)
5734 * File system boundaries, not crossing: one. (line 6)
5735 * file-changed: warnings. (line 64)
5736 * file-ignored: warnings. (line 50)
5737 * file-removed: warnings. (line 61)
5738 * file-shrank: warnings. (line 44)
5739 * file-unchanged: warnings. (line 55)
5740 * FILELIST: General-Purpose Variables.
5742 * filename-with-nuls: warnings. (line 32)
5743 * find, using with tar <1>: recurse. (line 11)
5744 * find, using with tar: files. (line 6)
5745 * first in date strings: General date syntax. (line 26)
5746 * format 0, snapshot file: Snapshot Files. (line 23)
5747 * format 1, snapshot file: Snapshot Files. (line 47)
5748 * format 2, snapshot file: Snapshot Files. (line 69)
5749 * Format Options: Format Variations. (line 6)
5750 * Format Parameters: Format Variations. (line 6)
5751 * Format, old style: old. (line 6)
5752 * fortnight in date strings: Relative items in date strings.
5754 * free documentation: Free Software Needs Free Documentation.
5756 * full dumps: Full Dumps. (line 8)
5757 * future time stamps: Large or Negative Values.
5759 * general date syntax: General date syntax. (line 6)
5760 * Generate Mode, genfile: Generate Mode. (line 6)
5761 * genfile: Genfile. (line 6)
5762 * genfile, create file: Generate Mode. (line 6)
5763 * genfile, creating sparse files: Generate Mode. (line 55)
5764 * genfile, generate mode: Generate Mode. (line 6)
5765 * genfile, reading a list of file names: Generate Mode. (line 22)
5766 * genfile, seeking to a given offset: Generate Mode. (line 18)
5767 * Getting program version number: help. (line 6)
5768 * git, excluding files: exclude. (line 37)
5769 * GNU archive format: gnu. (line 6)
5770 * GNU.sparse.major, extended header variable: PAX 1. (line 14)
5771 * GNU.sparse.map, extended header variable: PAX 0. (line 60)
5772 * GNU.sparse.minor, extended header variable: PAX 1. (line 17)
5773 * GNU.sparse.name, extended header variable: PAX 0. (line 68)
5774 * GNU.sparse.name, extended header variable, in v.1.0: PAX 1. (line 24)
5775 * GNU.sparse.numblocks, extended header variable: PAX 0. (line 15)
5776 * GNU.sparse.numbytes, extended header variable: PAX 0. (line 21)
5777 * GNU.sparse.offset, extended header variable: PAX 0. (line 18)
5778 * GNU.sparse.realsize, extended header variable: PAX 1. (line 24)
5779 * GNU.sparse.size, extended header variable: PAX 0. (line 11)
5780 * gnupg, using with tar: gzip. (line 181)
5781 * gpg, using with tar: gzip. (line 181)
5782 * gzip: gzip. (line 6)
5783 * hard links, dereferencing: hard links. (line 6)
5784 * header-col: Configuring Help Summary.
5786 * hook: User Hooks. (line 13)
5787 * hour in date strings: Relative items in date strings.
5789 * ignore-archive: warnings. (line 58)
5790 * ignore-newer: warnings. (line 83)
5791 * Ignoring end-of-archive blocks: Ignore Zeros. (line 6)
5792 * Ignoring unknown extended header keyword `%s', warning message: warnings.
5794 * implausibly old time stamp %s, warning message: warnings. (line 72)
5795 * Info script: Multi-Volume Archives.
5797 * Interactive operation: interactive. (line 6)
5798 * ISO 8601 date format: Calendar date items. (line 30)
5799 * items in date strings: General date syntax. (line 6)
5800 * Labeling an archive: label. (line 6)
5801 * labeling archives: Tape Files. (line 6)
5802 * Labeling multi-volume archives: label. (line 6)
5803 * Labels on the archive media: label. (line 6)
5804 * language, in dates: General date syntax. (line 40)
5805 * Large lists of file names on small machines: Same Order. (line 6)
5806 * large values: Large or Negative Values.
5808 * last DAY: Day of week items. (line 15)
5809 * last in date strings: General date syntax. (line 26)
5810 * Laszlo Ersek: lbzip2. (line 6)
5811 * lbzip2: lbzip2. (line 6)
5812 * Listing all tar options: help. (line 27)
5813 * listing member and file names: list. (line 41)
5814 * Listing volume label: label. (line 27)
5815 * Lists of file names: files. (line 6)
5816 * Local and remote archives: file. (line 71)
5817 * long options: Long Options. (line 6)
5818 * long options with mandatory arguments: Long Options. (line 31)
5819 * long options with optional arguments: Long Options. (line 40)
5820 * long-opt-col: Configuring Help Summary.
5822 * lzip: gzip. (line 6)
5823 * lzma: gzip. (line 6)
5824 * lzop: gzip. (line 6)
5825 * MacKenzie, David: Authors of parse_datetime.
5827 * Malformed dumpdir: 'X' never used, warning message: warnings.
5829 * member: Definitions. (line 15)
5830 * member name: Definitions. (line 15)
5831 * members, multiple: multiple. (line 6)
5832 * Members, replacing with other members: append. (line 47)
5833 * Mercurial, excluding files: exclude. (line 37)
5834 * Meyering, Jim: Authors of parse_datetime.
5836 * Middle of the archive, starting in the: Starting File. (line 11)
5837 * midnight in date strings: Time of day items. (line 22)
5838 * minute in date strings: Relative items in date strings.
5840 * minutes, time zone correction by: Time of day items. (line 30)
5841 * Modes of extracted files: Setting Access Permissions.
5843 * Modification time, excluding files by: after. (line 6)
5844 * Modification times of extracted files: Data Modification Times.
5846 * month in date strings: Relative items in date strings.
5848 * month names in date strings: Calendar date items. (line 38)
5849 * months, written-out: General date syntax. (line 36)
5850 * MT: General-Purpose Variables.
5852 * MT_BEGIN: Magnetic Tape Control.
5854 * MT_OFFLINE: Magnetic Tape Control.
5856 * MT_REWIND: Magnetic Tape Control.
5858 * MT_STATUS: Magnetic Tape Control.
5860 * Multi-volume archives: Multi-Volume Archives.
5862 * multiple members: multiple. (line 6)
5863 * Mutli-volume archives in PAX format, extracting using non-GNU tars: Split Recovery.
5865 * Mutli-volume archives, extracting using non-GNU tars: Split Recovery.
5867 * Naming an archive: file. (line 6)
5868 * negative time stamps: Large or Negative Values.
5870 * new-directory: warnings. (line 96)
5871 * next DAY: Day of week items. (line 15)
5872 * next in date strings: General date syntax. (line 26)
5873 * none: warnings. (line 29)
5874 * noon in date strings: Time of day items. (line 22)
5875 * now in date strings: Relative items in date strings.
5877 * ntape device: Many. (line 6)
5878 * NUL-terminated file names: nul. (line 6)
5879 * Number of blocks per record: Blocking Factor. (line 6)
5880 * Number of bytes per record: Blocking Factor. (line 6)
5881 * numbered backup method: backup. (line 55)
5882 * numbers, written-out: General date syntax. (line 26)
5883 * Obtaining help: help. (line 27)
5884 * Obtaining total status information: verbose. (line 46)
5885 * Old GNU archive format: gnu. (line 6)
5886 * Old GNU sparse format: Old GNU Format. (line 6)
5887 * old option style: Old Options. (line 6)
5888 * old options with mandatory arguments: Old Options. (line 17)
5889 * Old style archives: old. (line 6)
5890 * Old style format: old. (line 6)
5891 * opt-doc-col: Configuring Help Summary.
5893 * option syntax, traditional: Old Options. (line 58)
5894 * optional arguments to long options: Long Options. (line 40)
5895 * optional arguments to short options: Short Options. (line 22)
5896 * options for use with --extract: extract options. (line 6)
5897 * Options when reading archives: Reading. (line 6)
5898 * Options, archive format specifying: Format Variations. (line 6)
5899 * Options, format specifying: Format Variations. (line 6)
5900 * options, GNU style: Long Options. (line 6)
5901 * options, long style: Long Options. (line 6)
5902 * options, mixing different styles: Mixing. (line 6)
5903 * options, mnemonic names: Long Options. (line 6)
5904 * options, old style: Old Options. (line 6)
5905 * options, short style: Short Options. (line 6)
5906 * options, traditional: Short Options. (line 6)
5907 * ordinal numbers: General date syntax. (line 26)
5908 * Overwriting old files, prevention: Dealing with Old Files.
5910 * parse_datetime: Date input formats. (line 6)
5911 * pattern, genfile: Generate Mode. (line 39)
5912 * PAX archive format: posix. (line 6)
5913 * Permissions of extracted files: Setting Access Permissions.
5915 * Pinard, F.: Authors of parse_datetime.
5917 * pm in date strings: Time of day items. (line 22)
5918 * POSIX archive format: posix. (line 6)
5919 * Progress information: verbose. (line 83)
5920 * Protecting old files: Dealing with Old Files.
5922 * pure numbers in date strings: Pure numbers in date strings.
5924 * RCS, excluding files: exclude. (line 37)
5925 * Reading file names from a file: files. (line 6)
5926 * Reading incomplete records: Reading. (line 6)
5927 * record: Blocking. (line 6)
5928 * Record Size: Blocking Factor. (line 6)
5929 * Records, incomplete: Reading. (line 6)
5930 * Recursion in directories, avoiding: recurse. (line 6)
5931 * relative items in date strings: Relative items in date strings.
5933 * Remote devices: file. (line 60)
5934 * remote tape drive: Remote Tape Server. (line 6)
5935 * Removing files from an archive: delete. (line 6)
5936 * rename-directory: warnings. (line 94)
5937 * Replacing members with other members: append. (line 47)
5938 * reporting bugs: Reports. (line 6)
5939 * RESTORE_BEGIN: User Hooks. (line 39)
5940 * RESTORE_END: User Hooks. (line 42)
5941 * Resurrecting files from an archive: extract. (line 6)
5942 * Retrieving files from an archive: extract. (line 6)
5943 * return status: Synopsis. (line 67)
5944 * rmargin: Configuring Help Summary.
5946 * rmt: Remote Tape Server. (line 6)
5947 * RSH: General-Purpose Variables.
5949 * RSH_COMMAND: General-Purpose Variables.
5951 * Running out of space: Scarce. (line 8)
5952 * Salz, Rich: Authors of parse_datetime.
5954 * SCCS, excluding files: exclude. (line 37)
5955 * short options: Short Options. (line 6)
5956 * short options with mandatory arguments: Short Options. (line 13)
5957 * short options with optional arguments: Short Options. (line 22)
5958 * short-opt-col: Configuring Help Summary.
5960 * simple backup method: backup. (line 64)
5961 * SIMPLE_BACKUP_SUFFIX: backup. (line 68)
5962 * sleep, checkpoint action: checkpoints. (line 90)
5963 * SLEEP_MESSAGE: General-Purpose Variables.
5965 * SLEEP_TIME: General-Purpose Variables.
5967 * Small memory: Scarce. (line 8)
5968 * snapshot file, format 0: Snapshot Files. (line 23)
5969 * snapshot file, format 1: Snapshot Files. (line 47)
5970 * snapshot file, format 2: Snapshot Files. (line 69)
5971 * snapshot files, editing: Fixing Snapshot Files.
5973 * snapshot files, fixing device numbers: Fixing Snapshot Files.
5975 * socket ignored, warning message: warnings. (line 50)
5976 * Sparse Files: sparse. (line 6)
5977 * sparse files v.0.0, extracting with non-GNU tars: Sparse Recovery.
5979 * sparse files v.0.1, extracting with non-GNU tars: Sparse Recovery.
5981 * sparse files v.1.0, extracting with non-GNU tars: Sparse Recovery.
5983 * Sparse files, creating using genfile: Generate Mode. (line 55)
5984 * sparse files, extracting with non-GNU tars: Sparse Recovery.
5986 * sparse formats: Sparse Formats. (line 6)
5987 * sparse formats, defined: sparse. (line 50)
5988 * sparse formats, Old GNU: Old GNU Format. (line 6)
5989 * sparse formats, v.0.0: PAX 0. (line 6)
5990 * sparse formats, v.0.1: PAX 0. (line 52)
5991 * sparse formats, v.1.0: PAX 1. (line 6)
5992 * sparse versions: Sparse Formats. (line 6)
5993 * Specifying archive members: Selecting Archive Members.
5995 * Specifying files to act on: Selecting Archive Members.
5997 * Standard input and output: file. (line 39)
5998 * Standard output, writing extracted files to: Writing to Standard Output.
6000 * Storing archives in compressed format: gzip. (line 6)
6001 * SVN, excluding files: exclude. (line 37)
6002 * Symbolic link as file name: dereference. (line 6)
6003 * symlink-cast: warnings. (line 77)
6004 * TAPE: file tutorial. (line 14)
6005 * tape blocking: Blocking Factor. (line 194)
6006 * tape marks: Many. (line 44)
6007 * tape positioning: Many. (line 26)
6008 * TAPE_FILE: General-Purpose Variables.
6010 * Tapes, using --delete and: delete. (line 17)
6011 * TAR: General-Purpose Variables.
6013 * tar: What tar Does. (line 6)
6014 * tar archive: Definitions. (line 6)
6015 * Tar archive formats: Formats. (line 6)
6016 * tar entry: Naming tar Archives. (line 11)
6017 * tar file: Naming tar Archives. (line 11)
6018 * tar to a remote device: file. (line 60)
6019 * tar to standard input and output: file. (line 39)
6020 * tar-snapshot-edit: Fixing Snapshot Files.
6022 * TAR_ARCHIVE, checkpoint script environment: checkpoints. (line 108)
6023 * TAR_ARCHIVE, info script environment variable: Multi-Volume Archives.
6025 * TAR_ARCHIVE, to-command environment: Writing to an External Program.
6027 * TAR_ATIME, to-command environment: Writing to an External Program.
6029 * TAR_BLOCKING_FACTOR, checkpoint script environment: checkpoints.
6031 * TAR_BLOCKING_FACTOR, info script environment variable: Multi-Volume Archives.
6033 * TAR_BLOCKING_FACTOR, to-command environment: Writing to an External Program.
6035 * TAR_CHECKPOINT, checkpoint script environment: checkpoints. (line 114)
6036 * TAR_CTIME, to-command environment: Writing to an External Program.
6038 * TAR_FD, info script environment variable: Multi-Volume Archives.
6040 * TAR_FILENAME, to-command environment: Writing to an External Program.
6042 * TAR_FILETYPE, to-command environment: Writing to an External Program.
6044 * TAR_FORMAT, checkpoint script environment: checkpoints. (line 121)
6045 * TAR_FORMAT, info script environment variable: Multi-Volume Archives.
6047 * TAR_FORMAT, to-command environment: Writing to an External Program.
6049 * TAR_GID, to-command environment: Writing to an External Program.
6051 * TAR_GNAME, to-command environment: Writing to an External Program.
6053 * TAR_MODE, to-command environment: Writing to an External Program.
6055 * TAR_MTIME, to-command environment: Writing to an External Program.
6057 * TAR_OPTIONS, environment variable: using tar options. (line 30)
6058 * TAR_REALNAME, to-command environment: Writing to an External Program.
6060 * TAR_SIZE, to-command environment: Writing to an External Program.
6062 * TAR_SUBCOMMAND, checkpoint script environment: checkpoints. (line 117)
6063 * TAR_SUBCOMMAND, info script environment variable: Multi-Volume Archives.
6065 * TAR_UID, to-command environment: Writing to an External Program.
6067 * TAR_UNAME, to-command environment: Writing to an External Program.
6069 * TAR_VERSION, checkpoint script environment: checkpoints. (line 105)
6070 * TAR_VERSION, info script environment variable: Multi-Volume Archives.
6072 * TAR_VERSION, to-command environment: Writing to an External Program.
6074 * TAR_VOLUME, info script environment variable: Multi-Volume Archives.
6076 * TAR_VOLUME, to-command environment: Writing to an External Program.
6078 * tarcat: Tarcat. (line 6)
6079 * this in date strings: Relative items in date strings.
6081 * time of day item: Time of day items. (line 6)
6082 * time stamp %s is %s s in the future, warning message: warnings.
6084 * time zone correction: Time of day items. (line 30)
6085 * time zone item <1>: Time zone items. (line 6)
6086 * time zone item: General date syntax. (line 44)
6087 * timestamp: warnings. (line 72)
6088 * today in date strings: Relative items in date strings.
6090 * tomorrow in date strings: Relative items in date strings.
6092 * ttyout, checkpoint action: checkpoints. (line 70)
6093 * TZ: Specifying time zone rules.
6095 * Ultrix 3.1 and write failure: Remote Tape Server. (line 40)
6096 * Unknown file type `%c', extracted as normal file, warning message: warnings.
6098 * Unknown file type; file ignored, warning message: warnings. (line 50)
6099 * unknown-cast: warnings. (line 80)
6100 * unknown-keyword: warnings. (line 86)
6101 * unpacking: Definitions. (line 22)
6102 * Updating an archive: update. (line 6)
6103 * usage-indent: Configuring Help Summary.
6105 * Using encrypted archives: gzip. (line 181)
6106 * ustar archive format: ustar. (line 6)
6107 * uuencode: Applications. (line 8)
6108 * v7 archive format: old. (line 6)
6109 * VCS, excluding files: exclude. (line 37)
6110 * Verbose operation: verbose. (line 18)
6111 * Verifying a write operation: verify. (line 6)
6112 * Verifying the currency of an archive: compare. (line 6)
6113 * version control system, excluding files: exclude. (line 37)
6114 * Version of the tar program: help. (line 6)
6115 * version-control Emacs variable: backup. (line 49)
6116 * VERSION_CONTROL: backup. (line 41)
6117 * volno file: Multi-Volume Archives.
6119 * VOLNO_FILE: General-Purpose Variables.
6121 * Volume label, listing: label. (line 27)
6122 * Volume number file: Multi-Volume Archives.
6124 * week in date strings: Relative items in date strings.
6126 * Where is the archive?: file. (line 6)
6127 * Working directory, specifying: directory. (line 6)
6128 * Writing extracted files to standard output: Writing to Standard Output.
6130 * Writing new archives: file. (line 34)
6131 * xdev: warnings. (line 47)
6132 * XLIST: General-Purpose Variables.
6134 * xsparse: Sparse Recovery. (line 13)
6135 * year in date strings: Relative items in date strings.
6137 * yesterday in date strings: Relative items in date strings.