1 This is tar.info, produced by makeinfo version 4.13 from tar.texi.
3 This manual is for GNU `tar' (version 1.27, 24 September 2013), which
4 creates and extracts files from archives.
6 Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2013 Free Software
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 the Invariant Sections being "GNU General Public
13 License", with the Front-Cover Texts being "A GNU Manual", and
14 with the Back-Cover Texts as in (a) below. A copy of the license
15 is included in the section entitled "GNU Free Documentation
18 (a) The FSF's Back-Cover Text is: "You have the freedom to copy
19 and modify this GNU manual."
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: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats
34 7.7 Relative items in date strings
35 ==================================
37 "Relative items" adjust a date (or the current date if none) forward or
38 backward. The effects of relative items accumulate. Here are some
46 The unit of time displacement may be selected by the string `year'
47 or `month' for moving by whole years or months. These are fuzzy units,
48 as years and months are not all of equal duration. More precise units
49 are `fortnight' which is worth 14 days, `week' worth 7 days, `day'
50 worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
51 seconds, and `second' or `sec' worth one second. An `s' suffix on
52 these units is accepted and ignored.
54 The unit of time may be preceded by a multiplier, given as an
55 optionally signed number. Unsigned numbers are taken as positively
56 signed. No number at all implies 1 for a multiplier. Following a
57 relative item by the string `ago' is equivalent to preceding the unit
58 by a multiplier with value -1.
60 The string `tomorrow' is worth one day in the future (equivalent to
61 `day'), the string `yesterday' is worth one day in the past (equivalent
64 The strings `now' or `today' are relative items corresponding to
65 zero-valued time displacement, these strings come from the fact a
66 zero-valued time displacement represents the current time when not
67 otherwise changed by previous items. They may be used to stress other
68 items, like in `12:00 today'. The string `this' also has the meaning
69 of a zero-valued time displacement, but is preferred in date strings
72 When a relative item causes the resulting date to cross a boundary
73 where the clocks were adjusted, typically for daylight saving time, the
74 resulting date and time are adjusted accordingly.
76 The fuzz in units can cause problems with relative items. For
77 example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because
78 2003-06-31 is an invalid date. To determine the previous month more
79 reliably, you can ask for the month before the 15th of the current
83 Thu, 31 Jul 2003 13:02:39 -0700
84 $ date --date='-1 month' +'Last month was %B?'
86 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
89 Also, take care when manipulating dates around clock changes such as
90 daylight saving leaps. In a few cases these have added or subtracted
91 as much as 24 hours from the clock, so it is often wise to adopt
92 universal time by setting the `TZ' environment variable to `UTC0'
93 before embarking on calendrical calculations.
96 File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats
98 7.8 Pure numbers in date strings
99 ================================
101 The precise interpretation of a pure decimal number depends on the
102 context in the date string.
104 If the decimal number is of the form YYYYMMDD and no other calendar
105 date item (*note Calendar date items::) appears before it in the date
106 string, then YYYY is read as the year, MM as the month number and DD as
107 the day of the month, for the specified calendar date.
109 If the decimal number is of the form HHMM and no other time of day
110 item appears before it in the date string, then HH is read as the hour
111 of the day and MM as the minute of the hour, for the specified time of
112 day. MM can also be omitted.
114 If both a calendar date and a time of day appear to the left of a
115 number in the date string, but no relative item, then the number
119 File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats
121 7.9 Seconds since the Epoch
122 ===========================
124 If you precede a number with `@', it represents an internal time stamp
125 as a count of seconds. The number can contain an internal decimal
126 point (either `.' or `,'); any excess precision not supported by the
127 internal representation is truncated toward minus infinity. Such a
128 number cannot be combined with any other date item, as it specifies a
131 Internally, computer times are represented as a count of seconds
132 since an epoch--a well-defined point of time. On GNU and POSIX
133 systems, the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this
134 time, `@1' represents 1970-01-01 00:00:01 UTC, and so forth. GNU and
135 most other POSIX-compliant systems support such times as an extension
136 to POSIX, using negative counts, so that `@-1' represents 1969-12-31
139 Traditional Unix systems count seconds with 32-bit two's-complement
140 integers and can represent times from 1901-12-13 20:45:52 through
141 2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of
142 seconds with nanosecond subcounts, and can represent all the times in
143 the known lifetime of the universe to a resolution of 1 nanosecond.
145 On most hosts, these counts ignore the presence of leap seconds.
146 For example, on most hosts `@915148799' represents 1998-12-31 23:59:59
147 UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no
148 way to represent the intervening leap second 1998-12-31 23:59:60 UTC.
151 File: tar.info, Node: Specifying time zone rules, Next: Authors of parse_datetime, Prev: Seconds since the Epoch, Up: Date input formats
153 7.10 Specifying time zone rules
154 ===============================
156 Normally, dates are interpreted using the rules of the current time
157 zone, which in turn are specified by the `TZ' environment variable, or
158 by a system default if `TZ' is not set. To specify a different set of
159 default time zone rules that apply just to one date, start the date
160 with a string of the form `TZ="RULE"'. The two quote characters (`"')
161 must be present in the date, and any quotes or backslashes within RULE
162 must be escaped by a backslash.
164 For example, with the GNU `date' command you can answer the question
165 "What time is it in New York when a Paris clock shows 6:30am on October
166 31, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown
167 in the following shell transcript:
169 $ export TZ="America/New_York"
170 $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
171 Sun Oct 31 01:30:00 EDT 2004
173 In this example, the `--date' operand begins with its own `TZ'
174 setting, so the rest of that operand is processed according to
175 `Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it
176 were in Paris. However, since the output of the `date' command is
177 processed according to the overall time zone rules, it uses New York
178 time. (Paris was normally six hours ahead of New York in 2004, but
179 this example refers to a brief Halloween period when the gap was five
182 A `TZ' value is a rule that typically names a location in the `tz'
183 database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of
184 location names appears in the TWiki Date and Time Gateway
185 (http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a
186 colon before a location name in a `TZ' setting, e.g.,
187 `TZ=":America/New_York"'.
189 The `tz' database includes a wide variety of locations ranging from
190 `Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea
191 and have your own private time zone, or if you are using a non-GNU host
192 that does not support the `tz' database, you may need to use a POSIX
193 rule instead. Simple POSIX rules like `UTC0' specify a time zone
194 without daylight saving time; other rules can specify simple daylight
195 saving regimes. *Note Specifying the Time Zone with `TZ': (libc)TZ
199 File: tar.info, Node: Authors of parse_datetime, Prev: Specifying time zone rules, Up: Date input formats
201 7.11 Authors of `parse_datetime'
202 ================================
204 `parse_datetime' started life as `getdate', as originally implemented
205 by Steven M. Bellovin (<smb@research.att.com>) while at the University
206 of North Carolina at Chapel Hill. The code was later tweaked by a
207 couple of people on Usenet, then completely overhauled by Rich $alz
208 (<rsalz@bbn.com>) and Jim Berets (<jberets@bbn.com>) in August, 1990.
209 Various revisions for the GNU system were made by David MacKenzie, Jim
210 Meyering, Paul Eggert and others, including renaming it to `get_date' to
211 avoid a conflict with the alternative Posix function `getdate', and a
212 later rename to `parse_datetime'. The Posix function `getdate' can
213 parse more locale-specific dates using `strptime', but relies on an
214 environment variable and external file, and lacks the thread-safety of
217 This chapter was originally produced by Franc,ois Pinard
218 (<pinard@iro.umontreal.ca>) from the `parse_datetime.y' source code,
219 and then edited by K. Berry (<kb@cs.umb.edu>).
222 File: tar.info, Node: Formats, Next: Media, Prev: Date input formats, Up: Top
224 8 Controlling the Archive Format
225 ********************************
227 Due to historical reasons, there are several formats of tar archives.
228 All of them are based on the same principles, but have some subtle
229 differences that often make them incompatible with each other.
231 GNU tar is able to create and handle archives in a variety of
232 formats. The most frequently used formats are (in alphabetical order):
235 Format used by GNU `tar' versions up to 1.13.25. This format
236 derived from an early POSIX standard, adding some improvements
237 such as sparse file handling and incremental archives.
238 Unfortunately these features were implemented in a way
239 incompatible with other archive formats.
241 Archives in `gnu' format are able to hold file names of unlimited
245 Format used by GNU `tar' of versions prior to 1.12.
248 Archive format, compatible with the V7 implementation of tar. This
249 format imposes a number of limitations. The most important of them
252 1. The maximum length of a file name is limited to 99 characters.
254 2. The maximum length of a symbolic link is limited to 99
257 3. It is impossible to store special files (block and character
260 4. Maximum value of user or group ID is limited to 2097151
263 5. V7 archives do not contain symbolic ownership information
264 (user and group name of the file owner).
266 This format has traditionally been used by Automake when producing
267 Makefiles. This practice will change in the future, in the
268 meantime, however this means that projects containing file names
269 more than 99 characters long will not be able to use GNU `tar'
270 1.27 and Automake prior to 1.9.
273 Archive format defined by POSIX.1-1988 specification. It stores
274 symbolic ownership information. It is also able to store special
275 files. However, it imposes several restrictions as well:
277 1. The maximum length of a file name is limited to 256
278 characters, provided that the file name can be split at a
279 directory separator in two parts, first of them being at most
280 155 bytes long. So, in most cases the maximum file name
281 length will be shorter than 256 characters.
283 2. The maximum length of a symbolic link name is limited to 100
286 3. Maximum size of a file the archive is able to accommodate is
289 4. Maximum value of UID/GID is 2097151.
291 5. Maximum number of bits in device major and minor numbers is
295 Format used by Jo"rg Schilling `star' implementation. GNU `tar'
296 is able to read `star' archives but currently does not produce
300 Archive format defined by POSIX.1-2001 specification. This is the
301 most flexible and feature-rich format. It does not impose any
302 restrictions on file sizes or file name lengths. This format is
303 quite recent, so not all tar implementations are able to handle it
304 properly. However, this format is designed in such a way that any
305 tar implementation able to read `ustar' archives will be able to
306 read most `posix' archives as well, with the only exception that
307 any additional information (such as long file names etc.) will in
308 such case be extracted as plain text files along with the files it
311 This archive format will be the default format for future versions
315 The following table summarizes the limitations of each of these
318 Format UID File Size File Name Devn
319 --------------------------------------------------------------------
320 gnu 1.8e19 Unlimited Unlimited 63
321 oldgnu 1.8e19 Unlimited Unlimited 63
322 v7 2097151 8GB 99 n/a
323 ustar 2097151 8GB 256 21
324 posix Unlimited Unlimited Unlimited Unlimited
326 The default format for GNU `tar' is defined at compilation time.
327 You may check it by running `tar --help', and examining the last lines
328 of its output. Usually, GNU `tar' is configured to create archives in
329 `gnu' format, however, future version will switch to `posix'.
333 * Compression:: Using Less Space through Compression
334 * Attributes:: Handling File Attributes
335 * Portability:: Making `tar' Archives More Portable
336 * cpio:: Comparison of `tar' and `cpio'
339 File: tar.info, Node: Compression, Next: Attributes, Up: Formats
341 8.1 Using Less Space through Compression
342 ========================================
346 * gzip:: Creating and Reading Compressed Archives
347 * sparse:: Archiving Sparse Files
350 File: tar.info, Node: gzip, Next: sparse, Up: Compression
352 8.1.1 Creating and Reading Compressed Archives
353 ----------------------------------------------
355 GNU `tar' is able to create and read compressed archives. It supports
356 a wide variety of compression programs, namely: `gzip', `bzip2',
357 `lzip', `lzma', `lzop', `xz' and traditional `compress'. The latter is
358 supported mostly for backward compatibility, and we recommend against
359 using it, because it is by far less effective than the other
360 compression programs(1).
362 Creating a compressed archive is simple: you just specify a
363 "compression option" along with the usual archive creation commands.
364 The compression option is `-z' (`--gzip') to create a `gzip' compressed
365 archive, `-j' (`--bzip2') to create a `bzip2' compressed archive,
366 `--lzip' to create an lzip compressed archive, `-J' (`--xz') to create
367 an XZ archive, `--lzma' to create an LZMA compressed archive, `--lzop'
368 to create an LSOP archive, and `-Z' (`--compress') to use `compress'
369 program. For example:
371 $ tar czf archive.tar.gz .
373 You can also let GNU `tar' select the compression program based on
374 the suffix of the archive file name. This is done using
375 `--auto-compress' (`-a') command line option. For example, the
376 following invocation will use `bzip2' for compression:
378 $ tar caf archive.tar.bz2 .
380 whereas the following one will use `lzma':
382 $ tar caf archive.tar.lzma .
384 For a complete list of file name suffixes recognized by GNU `tar',
385 see *note auto-compress::.
387 Reading compressed archive is even simpler: you don't need to specify
388 any additional options as GNU `tar' recognizes its format
389 automatically. Thus, the following commands will list and extract the
390 archive created in previous example:
392 # List the compressed archive
393 $ tar tf archive.tar.gz
394 # Extract the compressed archive
395 $ tar xf archive.tar.gz
397 The format recognition algorithm is based on "signatures", a special
398 byte sequences in the beginning of file, that are specific for certain
399 compression formats. If this approach fails, `tar' falls back to using
400 archive name suffix to determine its format (*note auto-compress::, for
401 a list of recognized suffixes).
403 Some compression programs are able to handle different compression
404 formats. GNU `tar' uses this, if the principal decompressor for the
405 given format is not available. For example, if `compress' is not
406 installed, `tar' will try to use `gzip'. As of version 1.27 the
407 following alternatives are tried(2):
409 Format Main decompressor Alternatives
410 ---------------------------------------------------------------------
411 compress compress gzip
415 The only case when you have to specify a decompression option while
416 reading the archive is when reading from a pipe or from a tape drive
417 that does not support random access. However, in this case GNU `tar'
418 will indicate which option you should use. For example:
420 $ cat archive.tar.gz | tar tf -
421 tar: Archive is compressed. Use -z option
422 tar: Error is not recoverable: exiting now
424 If you see such diagnostics, just add the suggested option to the
425 invocation of GNU `tar':
427 $ cat archive.tar.gz | tar tzf -
429 Notice also, that there are several restrictions on operations on
430 compressed archives. First of all, compressed archives cannot be
431 modified, i.e., you cannot update (`--update', alias `-u') them or
432 delete (`--delete') members from them or add (`--append', alias `-r')
433 members to them. Likewise, you cannot append another `tar' archive to
434 a compressed archive using `--concatenate' (`-A'). Secondly,
435 multi-volume archives cannot be compressed.
437 The following options allow to select a particular compressor
443 Filter the archive through `gzip'.
447 Filter the archive through `xz'.
451 Filter the archive through `bzip2'.
454 Filter the archive through `lzip'.
457 Filter the archive through `lzma'.
460 Filter the archive through `lzop'.
465 Filter the archive through `compress'.
467 When any of these options is given, GNU `tar' searches the compressor
468 binary in the current path and invokes it. The name of the compressor
469 program is specified at compilation time using a corresponding
470 `--with-COMPNAME' option to `configure', e.g. `--with-bzip2' to select
471 a specific `bzip2' binary. *Note lbzip2::, for a detailed discussion.
473 The output produced by `tar --help' shows the actual compressor
474 names along with each of these options.
476 You can use any of these options on physical devices (tape drives,
477 etc.) and remote files as well as on normal files; data to or from such
478 devices or remote files is reblocked by another copy of the `tar'
479 program to enforce the specified (or default) record size. The default
480 compression parameters are used. Most compression programs let you
481 override these by setting a program-specific environment variable. For
482 example, with `gzip' you can set `GZIP':
484 $ GZIP='-9 -n' tar czf archive.tar.gz subdir
485 Another way would be to use the `-I' option instead (see below),
488 $ tar -cf archive.tar.gz -I 'gzip -9 -n' subdir
490 Finally, the third, traditional, way to do this is to use a pipe:
492 $ tar cf - subdir | gzip -9 -n > archive.tar.gz
494 Compressed archives are easily corrupted, because compressed files
495 have little redundancy. The adaptive nature of the compression scheme
496 means that the compression tables are implicitly spread all over the
497 archive. If you lose a few blocks, the dynamic construction of the
498 compression tables becomes unsynchronized, and there is little chance
499 that you could recover later in the archive.
501 Other compression options provide better control over creating
502 compressed archives. These are:
506 Select a compression program to use by the archive file name
507 suffix. The following suffixes are recognized:
509 Suffix Compression program
510 --------------------------------------------------------------
526 `--use-compress-program=COMMAND'
528 Use external compression program COMMAND. Use this option if you
529 are not happy with the compression program associated with the
530 suffix at compile time or if you have a compression program that
531 GNU `tar' does not support. The COMMAND argument is a valid
532 command invocation, as you would type it at the command line
533 prompt, with any additional options as needed. Enclose it in
534 quotes if it contains white space (see *note Running External
535 Commands: external, for more detail).
537 The COMMAND should follow two conventions:
539 First, when invoked without additional options, it should read data
540 from standard input, compress it and output it on standard output.
542 Secondly, if invoked with the additional `-d' option, it should do
543 exactly the opposite, i.e., read the compressed data from the
544 standard input and produce uncompressed data on the standard
547 The latter requirement means that you must not use the `-d' option
548 as a part of the COMMAND itself.
550 The `--use-compress-program' option, in particular, lets you
551 implement your own filters, not necessarily dealing with
552 compression/decompression. For example, suppose you wish to implement
553 PGP encryption on top of compression, using `gpg' (*note gpg:
554 (gpg)Top.). The following script does that:
558 -d) gpg --decrypt - | gzip -d -c;;
559 '') gzip -c | gpg -s;;
560 *) echo "Unknown option $1">&2; exit 1;;
563 Suppose you name it `gpgz' and save it somewhere in your `PATH'.
564 Then the following command will create a compressed archive signed with
567 $ tar -cf foo.tar.gpgz -Igpgz .
569 Likewise, the command below will list its contents:
571 $ tar -tf foo.tar.gpgz -Igpgz .
575 * lbzip2:: Using lbzip2 with GNU `tar'.
577 ---------- Footnotes ----------
579 (1) It also had patent problems in the past.
581 (2) To verbosely trace the decompressor selection, use the
582 `--warning=decompress-program' option (*note decompress-program:
586 File: tar.info, Node: lbzip2, Up: gzip
588 8.1.1.1 Using lbzip2 with GNU `tar'.
589 ....................................
591 `Lbzip2' is a multithreaded utility for handling `bzip2' compression,
592 written by Laszlo Ersek. It makes use of multiple processors to speed
593 up its operation and in general works considerably faster than `bzip2'.
594 For a detailed description of `lbzip2' see
595 `http://freshmeat.net/projects/lbzip2' and lbzip2: parallel bzip2
597 (http://www.linuxinsight.com/lbzip2-parallel-bzip2-utility.html).
599 Recent versions of `lbzip2' are mostly command line compatible with
600 `bzip2', which makes it possible to automatically invoke it via the
601 `--bzip2' GNU `tar' command line option. To do so, GNU `tar' must be
602 configured with the `--with-bzip2' command line option, like this:
604 $ ./configure --with-bzip2=lbzip2 [OTHER-OPTIONS]
606 Once configured and compiled this way, `tar --help' will show the
609 $ tar --help | grep -- --bzip2
610 -j, --bzip2 filter the archive through lbzip2
612 which means that running `tar --bzip2' will invoke `lbzip2'.
615 File: tar.info, Node: sparse, Prev: gzip, Up: Compression
617 8.1.2 Archiving Sparse Files
618 ----------------------------
620 Files in the file system occasionally have "holes". A "hole" in a file
621 is a section of the file's contents which was never written. The
622 contents of a hole reads as all zeros. On many operating systems,
623 actual disk storage is not allocated for holes, but they are counted in
624 the length of the file. If you archive such a file, `tar' could create
625 an archive longer than the original. To have `tar' attempt to
626 recognize the holes in a file, use `--sparse' (`-S'). When you use
627 this option, then, for any file using less disk space than would be
628 expected from its length, `tar' searches the file for consecutive
629 stretches of zeros. It then records in the archive for the file where
630 the consecutive stretches of zeros are, and only archives the "real
631 contents" of the file. On extraction (using `--sparse' is not needed
632 on extraction) any such files have holes created wherever the
633 continuous stretches of zeros were found. Thus, if you use `--sparse',
634 `tar' archives won't take more space than the original.
638 This option instructs `tar' to test each file for sparseness
639 before attempting to archive it. If the file is found to be
640 sparse it is treated specially, thus allowing to decrease the
641 amount of space used by its image in the archive.
643 This option is meaningful only when creating or updating archives.
644 It has no effect on extraction.
646 Consider using `--sparse' when performing file system backups, to
647 avoid archiving the expanded forms of files stored sparsely in the
650 Even if your system has no sparse files currently, some may be
651 created in the future. If you use `--sparse' while making file system
652 backups as a matter of course, you can be assured the archive will
653 never take more space on the media than the files take on disk
654 (otherwise, archiving a disk filled with sparse files might take
655 hundreds of tapes). *Note Incremental Dumps::.
657 However, be aware that `--sparse' option presents a serious
658 drawback. Namely, in order to determine if the file is sparse `tar'
659 has to read it before trying to archive it, so in total the file is
660 read *twice*. So, always bear in mind that the time needed to process
661 all files with this option is roughly twice the time needed to archive
664 When using `POSIX' archive format, GNU `tar' is able to store sparse
665 files using in three distinct ways, called "sparse formats". A sparse
666 format is identified by its "number", consisting, as usual of two
667 decimal numbers, delimited by a dot. By default, format `1.0' is used.
668 If, for some reason, you wish to use an earlier format, you can select
669 it using `--sparse-version' option.
671 `--sparse-version=VERSION'
672 Select the format to store sparse files in. Valid VERSION values
673 are: `0.0', `0.1' and `1.0'. *Note Sparse Formats::, for a
674 detailed description of each format.
676 Using `--sparse-format' option implies `--sparse'.
679 File: tar.info, Node: Attributes, Next: Portability, Prev: Compression, Up: Formats
681 8.2 Handling File Attributes
682 ============================
684 When `tar' reads files, it updates their access times. To avoid this,
685 use the `--atime-preserve[=METHOD]' option, which can either reset the
686 access time retroactively or avoid changing it in the first place.
689 `--atime-preserve=replace'
690 `--atime-preserve=system'
691 Preserve the access times of files that are read. This works only
692 for files that you own, unless you have superuser privileges.
694 `--atime-preserve=replace' works on most systems, but it also
695 restores the data modification time and updates the status change
696 time. Hence it doesn't interact with incremental dumps nicely
697 (*note Incremental Dumps::), and it can set access or data
698 modification times incorrectly if other programs access the file
699 while `tar' is running.
701 `--atime-preserve=system' avoids changing the access time in the
702 first place, if the operating system supports this.
703 Unfortunately, this may or may not work on any given operating
704 system or file system. If `tar' knows for sure it won't work, it
705 complains right away.
707 Currently `--atime-preserve' with no operand defaults to
708 `--atime-preserve=replace', but this is intended to change to
709 `--atime-preserve=system' when the latter is better-supported.
713 Do not extract data modification time.
715 When this option is used, `tar' leaves the data modification times
716 of the files it extracts as the times when the files were
717 extracted, instead of setting it to the times recorded in the
720 This option is meaningless with `--list' (`-t').
723 Create extracted files with the same ownership they have in the
726 This is the default behavior for the superuser, so this option is
727 meaningful only for non-root users, when `tar' is executed on
728 those systems able to give files away. This is considered as a
729 security flaw by many people, at least because it makes quite
730 difficult to correctly account users for the disk space they
731 occupy. Also, the `suid' or `sgid' attributes of files are easily
732 and silently lost when files are given away.
734 When writing an archive, `tar' writes the user ID and user name
735 separately. If it can't find a user name (because the user ID is
736 not in `/etc/passwd'), then it does not write one. When restoring,
737 it tries to look the name (if one was written) up in
738 `/etc/passwd'. If it fails, then it uses the user ID stored in
743 Do not attempt to restore ownership when extracting. This is the
744 default behavior for ordinary users, so this option has an effect
745 only for the superuser.
748 The `--numeric-owner' option allows (ANSI) archives to be written
749 without user/group name information or such information to be
750 ignored when extracting. It effectively disables the generation
751 and/or use of user/group name information. This option forces
752 extraction using the numeric ids from the archive, ignoring the
755 This is useful in certain circumstances, when restoring a backup
756 from an emergency floppy with different passwd/group files for
757 example. It is otherwise impossible to extract files with the
758 right ownerships if the password file in use during the extraction
759 does not match the one belonging to the file system(s) being
760 extracted. This occurs, for example, if you are restoring your
761 files after a major crash and had booted from an emergency floppy
762 with no password file or put your disk into another machine to do
765 The numeric ids are _always_ saved into `tar' archives. The
766 identifying names are added at create time when provided by the
767 system, unless `--format=oldgnu' is used. Numeric ids could be
768 used when moving archives between a collection of machines using a
769 centralized management for attribution of numeric ids to users and
770 groups. This is often made through using the NIS capabilities.
772 When making a `tar' file for distribution to other sites, it is
773 sometimes cleaner to use a single owner for all files in the
774 distribution, and nicer to specify the write permission bits of the
775 files as stored in the archive independently of their actual value
776 on the file system. The way to prepare a clean distribution is
777 usually to have some Makefile rule creating a directory, copying
778 all needed files in that directory, then setting ownership and
779 permissions as wanted (there are a lot of possible schemes), and
780 only then making a `tar' archive out of this directory, before
781 cleaning everything out. Of course, we could add a lot of options
782 to GNU `tar' for fine tuning permissions and ownership. This is
783 not the good way, I think. GNU `tar' is already crowded with
784 options and moreover, the approach just explained gives you a
785 great deal of control already.
789 `--preserve-permissions'
790 Extract all protection information.
792 This option causes `tar' to set the modes (access permissions) of
793 extracted files exactly as recorded in the archive. If this option
794 is not used, the current `umask' setting limits the permissions on
795 extracted files. This option is by default enabled when `tar' is
796 executed by a superuser.
798 This option is meaningless with `--list' (`-t').
801 Same as both `--same-permissions' and `--same-order'.
803 This option is deprecated, and will be removed in GNU `tar'
808 File: tar.info, Node: Portability, Next: cpio, Prev: Attributes, Up: Formats
810 8.3 Making `tar' Archives More Portable
811 =======================================
813 Creating a `tar' archive on a particular system that is meant to be
814 useful later on many other machines and with other versions of `tar' is
815 more challenging than you might think. `tar' archive formats have been
816 evolving since the first versions of Unix. Many such formats are
817 around, and are not always compatible with each other. This section
818 discusses a few problems, and gives some advice about making `tar'
819 archives more portable.
821 One golden rule is simplicity. For example, limit your `tar'
822 archives to contain only regular files and directories, avoiding other
823 kind of special files. Do not attempt to save sparse files or
824 contiguous files as such. Let's discuss a few more problems, in turn.
828 * Portable Names:: Portable Names
829 * dereference:: Symbolic Links
830 * hard links:: Hard Links
831 * old:: Old V7 Archives
832 * ustar:: Ustar Archives
833 * gnu:: GNU and old GNU format archives.
834 * posix:: POSIX archives
835 * Checksumming:: Checksumming Problems
836 * Large or Negative Values:: Large files, negative time stamps, etc.
837 * Other Tars:: How to Extract GNU-Specific Data Using
838 Other `tar' Implementations
841 File: tar.info, Node: Portable Names, Next: dereference, Up: Portability
846 Use portable file and member names. A name is portable if it contains
847 only ASCII letters and digits, `/', `.', `_', and `-'; it cannot be
848 empty, start with `-' or `//', or contain `/-'. Avoid deep directory
849 nesting. For portability to old Unix hosts, limit your file name
850 components to 14 characters or less.
852 If you intend to have your `tar' archives to be read under MSDOS,
853 you should not rely on case distinction for file names, and you might
854 use the GNU `doschk' program for helping you further diagnosing illegal
855 MSDOS names, which are even more limited than System V's.
858 File: tar.info, Node: dereference, Next: hard links, Prev: Portable Names, Up: Portability
863 Normally, when `tar' archives a symbolic link, it writes a block to the
864 archive naming the target of the link. In that way, the `tar' archive
865 is a faithful record of the file system contents. When `--dereference'
866 (`-h') is used with `--create' (`-c'), `tar' archives the files
867 symbolic links point to, instead of the links themselves.
869 When creating portable archives, use `--dereference' (`-h'): some
870 systems do not support symbolic links, and moreover, your distribution
871 might be unusable if it contains unresolved symbolic links.
873 When reading from an archive, the `--dereference' (`-h') option
874 causes `tar' to follow an already-existing symbolic link when `tar'
875 writes or reads a file named in the archive. Ordinarily, `tar' does
876 not follow such a link, though it may remove the link before writing a
877 new file. *Note Dealing with Old Files::.
879 The `--dereference' option is unsafe if an untrusted user can modify
880 directories while `tar' is running. *Note Security::.
883 File: tar.info, Node: hard links, Next: old, Prev: dereference, Up: Portability
888 Normally, when `tar' archives a hard link, it writes a block to the
889 archive naming the target of the link (a `1' type block). In that way,
890 the actual file contents is stored in file only once. For example,
891 consider the following two files:
894 -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
895 -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
897 Here, `jeden' is a link to `one'. When archiving this directory
898 with a verbose level 2, you will get an output similar to the following:
900 $ tar cvvf ../archive.tar .
901 drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
902 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
903 hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
905 The last line shows that, instead of storing two copies of the file,
906 `tar' stored it only once, under the name `jeden', and stored file
907 `one' as a hard link to this file.
909 It may be important to know that all hard links to the given file are
910 stored in the archive. For example, this may be necessary for exact
911 reproduction of the file system. The following option does that:
915 Check the number of links dumped for each processed file. If this
916 number does not match the total number of hard links for the file,
917 print a warning message.
919 For example, trying to archive only file `jeden' with this option
920 produces the following diagnostics:
922 $ tar -c -f ../archive.tar -l jeden
923 tar: Missing links to 'jeden'.
925 Although creating special records for hard links helps keep a
926 faithful record of the file system contents and makes archives more
927 compact, it may present some difficulties when extracting individual
928 members from the archive. For example, trying to extract file `one'
929 from the archive created in previous examples produces, in the absense
932 $ tar xf archive.tar ./one
933 tar: ./one: Cannot hard link to './jeden': No such file or directory
934 tar: Error exit delayed from previous errors
936 The reason for this behavior is that `tar' cannot seek back in the
937 archive to the previous member (in this case, `one'), to extract it(1).
938 If you wish to avoid such problems at the cost of a bigger archive, use
939 the following option:
942 Dereference hard links and store the files they refer to.
944 For example, trying this option on our two sample files, we get two
945 copies in the archive, each of which can then be extracted
946 independently of the other:
948 $ tar -c -vv -f ../archive.tar --hard-dereference .
949 drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
950 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
951 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one
953 ---------- Footnotes ----------
955 (1) There are plans to fix this in future releases.
958 File: tar.info, Node: old, Next: ustar, Prev: hard links, Up: Portability
960 8.3.4 Old V7 Archives
961 ---------------------
963 Certain old versions of `tar' cannot handle additional information
964 recorded by newer `tar' programs. To create an archive in V7 format
965 (not ANSI), which can be read by these old versions, specify the
966 `--format=v7' option in conjunction with the `--create' (`-c') (`tar'
967 also accepts `--portability' or `--old-archive' for this option). When
968 you specify it, `tar' leaves out information about directories, pipes,
969 fifos, contiguous files, and device files, and specifies file ownership
970 by group and user IDs instead of group and user names.
972 When updating an archive, do not use `--format=v7' unless the
973 archive was created using this option.
975 In most cases, a _new_ format archive can be read by an _old_ `tar'
976 program without serious trouble, so this option should seldom be
977 needed. On the other hand, most modern `tar's are able to read old
978 format archives, so it might be safer for you to always use
979 `--format=v7' for your distributions. Notice, however, that `ustar'
980 format is a better alternative, as it is free from many of `v7''s
984 File: tar.info, Node: ustar, Next: gnu, Prev: old, Up: Portability
986 8.3.5 Ustar Archive Format
987 --------------------------
989 Archive format defined by POSIX.1-1988 specification is called `ustar'.
990 Although it is more flexible than the V7 format, it still has many
991 restrictions (*note ustar: Formats, for the detailed description of
992 `ustar' format). Along with V7 format, `ustar' format is a good choice
993 for archives intended to be read with other implementations of `tar'.
995 To create archive in `ustar' format, use `--format=ustar' option in
996 conjunction with the `--create' (`-c').
999 File: tar.info, Node: gnu, Next: posix, Prev: ustar, Up: Portability
1001 8.3.6 GNU and old GNU `tar' format
1002 ----------------------------------
1004 GNU `tar' was based on an early draft of the POSIX 1003.1 `ustar'
1005 standard. GNU extensions to `tar', such as the support for file names
1006 longer than 100 characters, use portions of the `tar' header record
1007 which were specified in that POSIX draft as unused. Subsequent changes
1008 in POSIX have allocated the same parts of the header record for other
1009 purposes. As a result, GNU `tar' format is incompatible with the
1010 current POSIX specification, and with `tar' programs that follow it.
1012 In the majority of cases, `tar' will be configured to create this
1013 format by default. This will change in future releases, since we plan
1014 to make `POSIX' format the default.
1016 To force creation a GNU `tar' archive, use option `--format=gnu'.
1019 File: tar.info, Node: posix, Next: Checksumming, Prev: gnu, Up: Portability
1021 8.3.7 GNU `tar' and POSIX `tar'
1022 -------------------------------
1024 Starting from version 1.14 GNU `tar' features full support for
1025 POSIX.1-2001 archives.
1027 A POSIX conformant archive will be created if `tar' was given
1028 `--format=posix' (`--format=pax') option. No special option is
1029 required to read and extract from a POSIX archive.
1033 * PAX keywords:: Controlling Extended Header Keywords.
1036 File: tar.info, Node: PAX keywords, Up: posix
1038 8.3.7.1 Controlling Extended Header Keywords
1039 ............................................
1041 `--pax-option=KEYWORD-LIST'
1042 Handle keywords in PAX extended headers. This option is
1043 equivalent to `-o' option of the `pax' utility.
1045 KEYWORD-LIST is a comma-separated list of keyword options, each
1046 keyword option taking one of the following forms:
1049 When used with one of archive-creation commands, this option
1050 instructs `tar' to omit from extended header records that it
1051 produces any keywords matching the string PATTERN.
1053 When used in extract or list mode, this option instructs tar to
1054 ignore any keywords matching the given PATTERN in the extended
1055 header records. In both cases, matching is performed using the
1056 pattern matching notation described in POSIX 1003.2, 3.13 (*note
1057 wildcards::). For example:
1059 --pax-option delete=security.*
1061 would suppress security-related information.
1063 `exthdr.name=STRING'
1064 This keyword allows user control over the name that is written
1065 into the ustar header blocks for the extended headers. The name
1066 is obtained from STRING after making the following substitutions:
1068 Meta-character Replaced By
1069 --------------------------------------------------------
1070 %d The directory name of the file,
1071 equivalent to the result of the
1072 `dirname' utility on the translated
1074 %f The name of the file with the
1075 directory information stripped,
1076 equivalent to the result of the
1077 `basename' utility on the translated
1079 %p The process ID of the `tar' process.
1082 Any other `%' characters in STRING produce undefined results.
1084 If no option `exthdr.name=string' is specified, `tar' will use the
1085 following default value:
1089 `exthdr.mtime=VALUE'
1090 This keyword defines the value of the `mtime' field that is
1091 written into the ustar header blocks for the extended headers. By
1092 default, the `mtime' field is set to the modification time of the
1093 archive member described by that extended headers.
1095 `globexthdr.name=STRING'
1096 This keyword allows user control over the name that is written into
1097 the ustar header blocks for global extended header records. The
1098 name is obtained from the contents of STRING, after making the
1099 following substitutions:
1101 Meta-character Replaced By
1102 --------------------------------------------------------
1103 %n An integer that represents the
1104 sequence number of the global
1105 extended header record in the
1106 archive, starting at 1.
1107 %p The process ID of the `tar' process.
1110 Any other `%' characters in STRING produce undefined results.
1112 If no option `globexthdr.name=string' is specified, `tar' will use
1113 the following default value:
1115 $TMPDIR/GlobalHead.%p.%n
1117 where `$TMPDIR' represents the value of the TMPDIR environment
1118 variable. If TMPDIR is not set, `tar' uses `/tmp'.
1120 `globexthdr.mtime=VALUE'
1121 This keyword defines the value of the `mtime' field that is
1122 written into the ustar header blocks for the global extended
1123 headers. By default, the `mtime' field is set to the time when
1127 When used with one of archive-creation commands, these
1128 keyword/value pairs will be included at the beginning of the
1129 archive in a global extended header record. When used with one of
1130 archive-reading commands, `tar' will behave as if it has
1131 encountered these keyword/value pairs at the beginning of the
1132 archive in a global extended header record.
1135 When used with one of archive-creation commands, these
1136 keyword/value pairs will be included as records at the beginning
1137 of an extended header for each file. This is effectively
1138 equivalent to KEYWORD=VALUE form except that it creates no global
1139 extended header records.
1141 When used with one of archive-reading commands, `tar' will behave
1142 as if these keyword/value pairs were included as records at the
1143 end of each extended header; thus, they will override any global or
1144 file-specific extended header record keywords of the same names.
1145 For example, in the command:
1147 tar --format=posix --create \
1148 --file archive --pax-option gname:=user .
1150 the group name will be forced to a new value for all files stored
1153 In any of the forms described above, the VALUE may be a string
1154 enclosed in curly braces. In that case, the string between the braces
1155 is understood either as a textual time representation, as described in
1156 *note Date input formats::, or a name of the existing file, starting
1157 with `/' or `.'. In the latter case, the modification time of that
1160 For example, to set all modification times to the current date, you
1161 use the following option:
1163 --pax-option='mtime:={now}'
1165 Note quoting of the option's argument.
1167 As another example, here is the option that ensures that any two
1168 archives created using it, will be binary equivalent if they have the
1171 --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0
1174 File: tar.info, Node: Checksumming, Next: Large or Negative Values, Prev: posix, Up: Portability
1176 8.3.8 Checksumming Problems
1177 ---------------------------
1179 SunOS and HP-UX `tar' fail to accept archives created using GNU `tar'
1180 and containing non-ASCII file names, that is, file names having
1181 characters with the eight bit set, because they use signed checksums,
1182 while GNU `tar' uses unsigned checksums while creating archives, as per
1183 POSIX standards. On reading, GNU `tar' computes both checksums and
1184 accepts any. It is somewhat worrying that a lot of people may go
1185 around doing backup of their files using faulty (or at least
1186 non-standard) software, not learning about it until it's time to
1187 restore their missing files with an incompatible file extractor, or
1190 GNU `tar' computes checksums both ways, and accept any on read, so
1191 GNU tar can read Sun tapes even with their wrong checksums. GNU `tar'
1192 produces the standard checksum, however, raising incompatibilities with
1193 Sun. That is to say, GNU `tar' has not been modified to _produce_
1194 incorrect archives to be read by buggy `tar''s. I've been told that
1195 more recent Sun `tar' now read standard archives, so maybe Sun did a
1196 similar patch, after all?
1198 The story seems to be that when Sun first imported `tar' sources on
1199 their system, they recompiled it without realizing that the checksums
1200 were computed differently, because of a change in the default signing
1201 of `char''s in their compiler. So they started computing checksums
1202 wrongly. When they later realized their mistake, they merely decided
1203 to stay compatible with it, and with themselves afterwards.
1204 Presumably, but I do not really know, HP-UX has chosen that their `tar'
1205 archives to be compatible with Sun's. The current standards do not
1206 favor Sun `tar' format. In any case, it now falls on the shoulders of
1207 SunOS and HP-UX users to get a `tar' able to read the good archives
1211 File: tar.info, Node: Large or Negative Values, Next: Other Tars, Prev: Checksumming, Up: Portability
1213 8.3.9 Large or Negative Values
1214 ------------------------------
1216 _(This message will disappear, once this node revised.)_
1218 The above sections suggest to use `oldest possible' archive format if
1219 in doubt. However, sometimes it is not possible. If you attempt to
1220 archive a file whose metadata cannot be represented using required
1221 format, GNU `tar' will print error message and ignore such a file. You
1222 will than have to switch to a format that is able to handle such
1223 values. The format summary table (*note Formats::) will help you to do
1226 In particular, when trying to archive files larger than 8GB or with
1227 timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16
1228 12:56:31 UTC, you will have to chose between GNU and POSIX archive
1229 formats. When considering which format to choose, bear in mind that
1230 the GNU format uses two's-complement base-256 notation to store values
1231 that do not fit into standard ustar range. Such archives can generally
1232 be read only by a GNU `tar' implementation. Moreover, they sometimes
1233 cannot be correctly restored on another hosts even by GNU `tar'. For
1234 example, using two's complement representation for negative time stamps
1235 that assumes a signed 32-bit `time_t' generates archives that are not
1236 portable to hosts with differing `time_t' representations.
1238 On the other hand, POSIX archives, generally speaking, can be
1239 extracted by any tar implementation that understands older ustar
1240 format. The only exception are files larger than 8GB.
1243 File: tar.info, Node: Other Tars, Prev: Large or Negative Values, Up: Portability
1245 8.3.10 How to Extract GNU-Specific Data Using Other `tar' Implementations
1246 -------------------------------------------------------------------------
1248 In previous sections you became acquainted with various quirks
1249 necessary to make your archives portable. Sometimes you may need to
1250 extract archives containing GNU-specific members using some third-party
1251 `tar' implementation or an older version of GNU `tar'. Of course your
1252 best bet is to have GNU `tar' installed, but if it is for some reason
1253 impossible, this section will explain how to cope without it.
1255 When we speak about "GNU-specific" members we mean two classes of
1256 them: members split between the volumes of a multi-volume archive and
1257 sparse members. You will be able to always recover such members if the
1258 archive is in PAX format. In addition split members can be recovered
1259 from archives in old GNU format. The following subsections describe
1260 the required procedures in detail.
1264 * Split Recovery:: Members Split Between Volumes
1265 * Sparse Recovery:: Sparse Members
1268 File: tar.info, Node: Split Recovery, Next: Sparse Recovery, Up: Other Tars
1270 8.3.10.1 Extracting Members Split Between Volumes
1271 .................................................
1273 If a member is split between several volumes of an old GNU format
1274 archive most third party `tar' implementation will fail to extract it.
1275 To extract it, use `tarcat' program (*note Tarcat::). This program is
1276 available from GNU `tar' home page
1277 (http://www.gnu.org/software/tar/utils/tarcat.html). It concatenates
1278 several archive volumes into a single valid archive. For example, if
1279 you have three volumes named from `vol-1.tar' to `vol-3.tar', you can
1280 do the following to extract them using a third-party `tar':
1282 $ tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -
1284 You could use this approach for most (although not all) PAX format
1285 archives as well. However, extracting split members from a PAX archive
1286 is a much easier task, because PAX volumes are constructed in such a
1287 way that each part of a split member is extracted to a different file
1288 by `tar' implementations that are not aware of GNU extensions. More
1289 specifically, the very first part retains its original name, and all
1290 subsequent parts are named using the pattern:
1292 %d/GNUFileParts.%p/%f.%n
1294 where symbols preceeded by `%' are "macro characters" that have the
1297 Meta-character Replaced By
1298 ------------------------------------------------------------
1299 %d The directory name of the file,
1300 equivalent to the result of the
1301 `dirname' utility on its full name.
1302 %f The file name of the file, equivalent
1303 to the result of the `basename' utility
1305 %p The process ID of the `tar' process that
1306 created the archive.
1307 %n Ordinal number of this particular part.
1309 For example, if the file `var/longfile' was split during archive
1310 creation between three volumes, and the creator `tar' process had
1311 process ID `27962', then the member names will be:
1314 var/GNUFileParts.27962/longfile.1
1315 var/GNUFileParts.27962/longfile.2
1317 When you extract your archive using a third-party `tar', these files
1318 will be created on your disk, and the only thing you will need to do to
1319 restore your file in its original form is concatenate them in the
1320 proper order, for example:
1323 $ cat GNUFileParts.27962/longfile.1 \
1324 GNUFileParts.27962/longfile.2 >> longfile
1325 $ rm -f GNUFileParts.27962
1327 Notice, that if the `tar' implementation you use supports PAX format
1328 archives, it will probably emit warnings about unknown keywords during
1329 extraction. They will look like this:
1332 Unknown extended header keyword 'GNU.volume.filename' ignored.
1333 Unknown extended header keyword 'GNU.volume.size' ignored.
1334 Unknown extended header keyword 'GNU.volume.offset' ignored.
1336 You can safely ignore these warnings.
1338 If your `tar' implementation is not PAX-aware, you will get more
1339 warnings and more files generated on your disk, e.g.:
1342 var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
1344 Unexpected EOF in archive
1346 tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file
1347 GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type
1348 'x', extracted as normal file
1350 Ignore these warnings. The `PaxHeaders.*' directories created will
1351 contain files with "extended header keywords" describing the extracted
1352 files. You can delete them, unless they describe sparse members. Read
1353 further to learn more about them.
1356 File: tar.info, Node: Sparse Recovery, Prev: Split Recovery, Up: Other Tars
1358 8.3.10.2 Extracting Sparse Members
1359 ..................................
1361 Any `tar' implementation will be able to extract sparse members from a
1362 PAX archive. However, the extracted files will be "condensed", i.e.,
1363 any zero blocks will be removed from them. When we restore such a
1364 condensed file to its original form, by adding zero blocks (or "holes")
1365 back to their original locations, we call this process "expanding" a
1366 compressed sparse file.
1368 To expand a file, you will need a simple auxiliary program called
1369 `xsparse'. It is available in source form from GNU `tar' home page
1370 (http://www.gnu.org/software/tar/utils/xsparse.html).
1372 Let's begin with archive members in "sparse format version 1.0"(1),
1373 which are the easiest to expand. The condensed file will contain both
1374 file map and file data, so no additional data will be needed to restore
1375 it. If the original file name was `DIR/NAME', then the condensed file
1376 will be named `DIR/GNUSparseFile.N/NAME', where N is a decimal
1379 To expand a version 1.0 file, run `xsparse' as follows:
1381 $ xsparse `cond-file'
1383 where `cond-file' is the name of the condensed file. The utility will
1384 deduce the name for the resulting expanded file using the following
1387 1. If `cond-file' does not contain any directories, `../cond-file'
1390 2. If `cond-file' has the form `DIR/T/NAME', where both T and NAME
1391 are simple names, with no `/' characters in them, the output file
1392 name will be `DIR/NAME'.
1394 3. Otherwise, if `cond-file' has the form `DIR/NAME', the output file
1395 name will be `NAME'.
1397 In the unlikely case when this algorithm does not suit your needs,
1398 you can explicitly specify output file name as a second argument to the
1401 $ xsparse `cond-file' `out-file'
1403 It is often a good idea to run `xsparse' in "dry run" mode first.
1404 In this mode, the command does not actually expand the file, but
1405 verbosely lists all actions it would be taking to do so. The dry run
1406 mode is enabled by `-n' command line argument:
1408 $ xsparse -n /home/gray/GNUSparseFile.6058/sparsefile
1409 Reading v.1.0 sparse map
1410 Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
1411 '/home/gray/sparsefile'
1414 To actually expand the file, you would run:
1416 $ xsparse /home/gray/GNUSparseFile.6058/sparsefile
1418 The program behaves the same way all UNIX utilities do: it will keep
1419 quiet unless it has simething important to tell you (e.g. an error
1420 condition or something). If you wish it to produce verbose output,
1421 similar to that from the dry run mode, use `-v' option:
1423 $ xsparse -v /home/gray/GNUSparseFile.6058/sparsefile
1424 Reading v.1.0 sparse map
1425 Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
1426 '/home/gray/sparsefile'
1429 Additionally, if your `tar' implementation has extracted the
1430 "extended headers" for this file, you can instruct `xstar' to use them
1431 in order to verify the integrity of the expanded file. The option `-x'
1432 sets the name of the extended header file to use. Continuing our
1435 $ xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \
1436 /home/gray/GNUSparseFile.6058/sparsefile
1437 Reading extended header file
1438 Found variable GNU.sparse.major = 1
1439 Found variable GNU.sparse.minor = 0
1440 Found variable GNU.sparse.name = sparsefile
1441 Found variable GNU.sparse.realsize = 217481216
1442 Reading v.1.0 sparse map
1443 Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
1444 '/home/gray/sparsefile'
1447 An "extended header" is a special `tar' archive header that precedes
1448 an archive member and contains a set of "variables", describing the
1449 member properties that cannot be stored in the standard `ustar' header.
1450 While optional for expanding sparse version 1.0 members, the use of
1451 extended headers is mandatory when expanding sparse members in older
1452 sparse formats: v.0.0 and v.0.1 (The sparse formats are described in
1453 detail in *note Sparse Formats::.) So, for these formats, the question
1454 is: how to obtain extended headers from the archive?
1456 If you use a `tar' implementation that does not support PAX format,
1457 extended headers for each member will be extracted as a separate file.
1458 If we represent the member name as `DIR/NAME', then the extended header
1459 file will be named `DIR/PaxHeaders.N/NAME', where N is an integer
1462 Things become more difficult if your `tar' implementation does
1463 support PAX headers, because in this case you will have to manually
1464 extract the headers. We recommend the following algorithm:
1466 1. Consult the documentation of your `tar' implementation for an
1467 option that prints "block numbers" along with the archive listing
1468 (analogous to GNU `tar''s `-R' option). For example, `star' has
1471 2. Obtain verbose listing using the `block number' option, and find
1472 block numbers of the sparse member in question and the member
1473 immediately following it. For example, running `star' on our
1476 $ star -t -v -block-number -f arc.tar
1478 star: Unknown extended header keyword 'GNU.sparse.size' ignored.
1479 star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored.
1480 star: Unknown extended header keyword 'GNU.sparse.name' ignored.
1481 star: Unknown extended header keyword 'GNU.sparse.map' ignored.
1482 block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile
1483 block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README
1486 (as usual, ignore the warnings about unknown keywords.)
1488 3. Let SIZE be the size of the sparse member, BS be its block number
1489 and BN be the block number of the next member. Compute:
1491 N = BS - BN - SIZE/512 - 2
1493 This number gives the size of the extended header part in tar
1494 "blocks". In our example, this formula gives: `897 - 56 - 425984
1497 4. Use `dd' to extract the headers:
1499 dd if=ARCHIVE of=HNAME bs=512 skip=BS count=N
1501 where ARCHIVE is the archive name, HNAME is a name of the file to
1502 store the extended header in, BS and N are computed in previous
1505 In our example, this command will be
1507 $ dd if=arc.tar of=xhdr bs=512 skip=56 count=7
1509 Finally, you can expand the condensed file, using the obtained
1512 $ xsparse -v -x xhdr GNUSparseFile.6058/sparsefile
1513 Reading extended header file
1514 Found variable GNU.sparse.size = 217481216
1515 Found variable GNU.sparse.numblocks = 208
1516 Found variable GNU.sparse.name = sparsefile
1517 Found variable GNU.sparse.map = 0,2048,1050624,2048,...
1518 Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile'
1521 ---------- Footnotes ----------
1525 (2) Technically speaking, N is a "process ID" of the `tar' process
1526 which created the archive (*note PAX keywords::).
1529 File: tar.info, Node: cpio, Prev: Portability, Up: Formats
1531 8.4 Comparison of `tar' and `cpio'
1532 ==================================
1534 _(This message will disappear, once this node revised.)_
1536 The `cpio' archive formats, like `tar', do have maximum file name
1537 lengths. The binary and old ASCII formats have a maximum file length
1538 of 256, and the new ASCII and CRC ASCII formats have a max file length
1539 of 1024. GNU `cpio' can read and write archives with arbitrary file
1540 name lengths, but other `cpio' implementations may crash unexplainedly
1541 trying to read them.
1543 `tar' handles symbolic links in the form in which it comes in BSD;
1544 `cpio' doesn't handle symbolic links in the form in which it comes in
1545 System V prior to SVR4, and some vendors may have added symlinks to
1546 their system without enhancing `cpio' to know about them. Others may
1547 have enhanced it in a way other than the way I did it at Sun, and which
1548 was adopted by AT&T (and which is, I think, also present in the `cpio'
1549 that Berkeley picked up from AT&T and put into a later BSD release--I
1550 think I gave them my changes).
1552 (SVR4 does some funny stuff with `tar'; basically, its `cpio' can
1553 handle `tar' format input, and write it on output, and it probably
1554 handles symbolic links. They may not have bothered doing anything to
1555 enhance `tar' as a result.)
1557 `cpio' handles special files; traditional `tar' doesn't.
1559 `tar' comes with V7, System III, System V, and BSD source; `cpio'
1560 comes only with System III, System V, and later BSD (4.3-tahoe and
1563 `tar''s way of handling multiple hard links to a file can handle
1564 file systems that support 32-bit i-numbers (e.g., the BSD file system);
1565 `cpio's way requires you to play some games (in its "binary" format,
1566 i-numbers are only 16 bits, and in its "portable ASCII" format, they're
1567 18 bits--it would have to play games with the "file system ID" field of
1568 the header to make sure that the file system ID/i-number pairs of
1569 different files were always different), and I don't know which `cpio's,
1570 if any, play those games. Those that don't might get confused and
1571 think two files are the same file when they're not, and make hard links
1574 `tar's way of handling multiple hard links to a file places only one
1575 copy of the link on the tape, but the name attached to that copy is the
1576 _only_ one you can use to retrieve the file; `cpio's way puts one copy
1577 for every link, but you can retrieve it using any of the names.
1579 What type of check sum (if any) is used, and how is this
1582 See the attached manual pages for `tar' and `cpio' format. `tar'
1583 uses a checksum which is the sum of all the bytes in the `tar' header
1584 for a file; `cpio' uses no checksum.
1586 If anyone knows why `cpio' was made when `tar' was present at the
1589 It wasn't. `cpio' first showed up in PWB/UNIX 1.0; no
1590 generally-available version of UNIX had `tar' at the time. I don't
1591 know whether any version that was generally available _within AT&T_ had
1592 `tar', or, if so, whether the people within AT&T who did `cpio' knew
1595 On restore, if there is a corruption on a tape `tar' will stop at
1596 that point, while `cpio' will skip over it and try to restore the rest
1599 The main difference is just in the command syntax and header format.
1601 `tar' is a little more tape-oriented in that everything is blocked
1602 to start on a record boundary.
1604 Is there any differences between the ability to recover crashed
1605 archives between the two of them. (Is there any chance of
1606 recovering crashed archives at all.)
1608 Theoretically it should be easier under `tar' since the blocking
1609 lets you find a header with some variation of `dd skip=NN'. However,
1610 modern `cpio''s and variations have an option to just search for the
1611 next file header after an error with a reasonable chance of resyncing.
1612 However, lots of tape driver software won't allow you to continue past
1613 a media error which should be the only reason for getting out of sync
1614 unless a file changed sizes while you were writing the archive.
1616 If anyone knows why `cpio' was made when `tar' was present at the
1617 unix scene, please tell me about this too.
1619 Probably because it is more media efficient (by not blocking
1620 everything and using only the space needed for the headers where `tar'
1621 always uses 512 bytes per file header) and it knows how to archive
1624 You might want to look at the freely available alternatives. The
1625 major ones are `afio', GNU `tar', and `pax', each of which have their
1626 own extensions with some backwards compatibility.
1628 Sparse files were `tar'red as sparse files (which you can easily
1629 test, because the resulting archive gets smaller, and GNU `cpio' can no
1633 File: tar.info, Node: Media, Next: Reliability and security, Prev: Formats, Up: Top
1635 9 Tapes and Other Archive Media
1636 *******************************
1638 _(This message will disappear, once this node revised.)_
1640 A few special cases about tape handling warrant more detailed
1641 description. These special cases are discussed below.
1643 Many complexities surround the use of `tar' on tape drives. Since
1644 the creation and manipulation of archives located on magnetic tape was
1645 the original purpose of `tar', it contains many features making such
1646 manipulation easier.
1648 Archives are usually written on dismountable media--tape cartridges,
1649 mag tapes, or floppy disks.
1651 The amount of data a tape or disk holds depends not only on its size,
1652 but also on how it is formatted. A 2400 foot long reel of mag tape
1653 holds 40 megabytes of data when formatted at 1600 bits per inch. The
1654 physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
1656 Magnetic media are re-usable--once the archive on a tape is no longer
1657 needed, the archive can be erased and the tape or disk used over.
1658 Media quality does deteriorate with use, however. Most tapes or disks
1659 should be discarded when they begin to produce data errors. EXABYTE
1660 tape cartridges should be discarded when they generate an "error count"
1661 (number of non-usable bits) of more than 10k.
1663 Magnetic media are written and erased using magnetic fields, and
1664 should be protected from such fields to avoid damage to stored data.
1665 Sticking a floppy disk to a filing cabinet using a magnet is probably
1670 * Device:: Device selection and switching
1671 * Remote Tape Server::
1672 * Common Problems and Solutions::
1673 * Blocking:: Blocking
1674 * Many:: Many archives on one tape
1675 * Using Multiple Tapes:: Using Multiple Tapes
1676 * label:: Including a Label in the Archive
1678 * Write Protection::
1681 File: tar.info, Node: Device, Next: Remote Tape Server, Up: Media
1683 9.1 Device Selection and Switching
1684 ==================================
1686 _(This message will disappear, once this node revised.)_
1688 `-f [HOSTNAME:]FILE'
1689 `--file=[HOSTNAME:]FILE'
1690 Use archive file or device FILE on HOSTNAME.
1692 This option is used to specify the file name of the archive `tar'
1695 If the file name is `-', `tar' reads the archive from standard input
1696 (when listing or extracting), or writes it to standard output (when
1697 creating). If the `-' file name is given when updating an archive,
1698 `tar' will read the original archive from its standard input, and will
1699 write the entire new archive to its standard output.
1701 If the file name contains a `:', it is interpreted as `hostname:file
1702 name'. If the HOSTNAME contains an "at" sign (`@'), it is treated as
1703 `user@hostname:file name'. In either case, `tar' will invoke the
1704 command `rsh' (or `remsh') to start up an `/usr/libexec/rmt' on the
1705 remote machine. If you give an alternate login name, it will be given
1706 to the `rsh'. Naturally, the remote machine must have an executable
1707 `/usr/libexec/rmt'. This program is free software from the University
1708 of California, and a copy of the source code can be found with the
1709 sources for `tar'; it's compiled and installed by default. The exact
1710 path to this utility is determined when configuring the package. It is
1711 `PREFIX/libexec/rmt', where PREFIX stands for your installation prefix.
1712 This location may also be overridden at runtime by using the
1713 `--rmt-command=COMMAND' option (*Note --rmt-command: Option Summary,
1714 for detailed description of this option. *Note Remote Tape Server::,
1715 for the description of `rmt' command).
1717 If this option is not given, but the environment variable `TAPE' is
1718 set, its value is used; otherwise, old versions of `tar' used a default
1719 archive name (which was picked when `tar' was compiled). The default
1720 is normally set up to be the "first" tape drive or other transportable
1721 I/O medium on the system.
1723 Starting with version 1.11.5, GNU `tar' uses standard input and
1724 standard output as the default device, and I will not try anymore
1725 supporting automatic device detection at installation time. This was
1726 failing really in too many cases, it was hopeless. This is now
1727 completely left to the installer to override standard input and
1728 standard output for default device, if this seems preferable. Further,
1729 I think _most_ actual usages of `tar' are done with pipes or disks, not
1730 really tapes, cartridges or diskettes.
1732 Some users think that using standard input and output is running
1733 after trouble. This could lead to a nasty surprise on your screen if
1734 you forget to specify an output file name--especially if you are going
1735 through a network or terminal server capable of buffering large amounts
1736 of output. We had so many bug reports in that area of configuring
1737 default tapes automatically, and so many contradicting requests, that
1738 we finally consider the problem to be portably intractable. We could
1739 of course use something like `/dev/tape' as a default, but this is
1740 _also_ running after various kind of trouble, going from hung processes
1741 to accidental destruction of real tapes. After having seen all this
1742 mess, using standard input and output as a default really sounds like
1743 the only clean choice left, and a very useful one too.
1745 GNU `tar' reads and writes archive in records, I suspect this is the
1746 main reason why block devices are preferred over character devices.
1747 Most probably, block devices are more efficient too. The installer
1748 could also check for `DEFTAPE' in `<sys/mtio.h>'.
1751 Archive file is local even if it contains a colon.
1753 `--rsh-command=COMMAND'
1754 Use remote COMMAND instead of `rsh'. This option exists so that
1755 people who use something other than the standard `rsh' (e.g., a
1756 Kerberized `rsh') can access a remote device.
1758 When this command is not used, the shell command found when the
1759 `tar' program was installed is used instead. This is the first
1760 found of `/usr/ucb/rsh', `/usr/bin/remsh', `/usr/bin/rsh',
1761 `/usr/bsd/rsh' or `/usr/bin/nsh'. The installer may have
1762 overridden this by defining the environment variable `RSH' _at
1766 Specify drive and density.
1770 Create/list/extract multi-volume archive.
1772 This option causes `tar' to write a "multi-volume" archive--one
1773 that may be larger than will fit on the medium used to hold it.
1774 *Note Multi-Volume Archives::.
1777 `--tape-length=SIZE[SUF]'
1778 Change tape after writing SIZE units of data. Unless SUF is
1779 given, SIZE is treated as kilobytes, i.e. `SIZE x 1024' bytes.
1780 The following suffixes alter this behavior:
1782 Suffix Units Byte Equivalent
1783 --------------------------------------------------------
1785 B Kilobytes SIZE x 1024
1787 G Gigabytes SIZE x 1024^3
1788 K Kilobytes SIZE x 1024
1789 k Kilobytes SIZE x 1024
1790 M Megabytes SIZE x 1024^2
1791 P Petabytes SIZE x 1024^5
1792 T Terabytes SIZE x 1024^4
1795 Table 9.1: Size Suffixes
1797 This option might be useful when your tape drivers do not
1798 properly detect end of physical tapes. By being slightly
1799 conservative on the maximum tape length, you might avoid the
1803 `--info-script=COMMAND'
1804 `--new-volume-script=COMMAND'
1805 Execute COMMAND at end of each tape. This implies
1806 `--multi-volume' (`-M'). *Note info-script::, for a detailed
1807 description of this option.
1810 File: tar.info, Node: Remote Tape Server, Next: Common Problems and Solutions, Prev: Device, Up: Media
1812 9.2 Remote Tape Server
1813 ======================
1815 In order to access the tape drive on a remote machine, `tar' uses the
1816 remote tape server written at the University of California at Berkeley.
1817 The remote tape server must be installed as `PREFIX/libexec/rmt' on any
1818 machine whose tape drive you want to use. `tar' calls `rmt' by running
1819 an `rsh' or `remsh' to the remote machine, optionally using a different
1820 login name if one is supplied.
1822 A copy of the source for the remote tape server is provided. Its
1823 source code can be freely distributed. It is compiled and installed by
1826 Unless you use the `--absolute-names' (`-P') option, GNU `tar' will
1827 not allow you to create an archive that contains absolute file names (a
1828 file name beginning with `/'.) If you try, `tar' will automatically
1829 remove the leading `/' from the file names it stores in the archive.
1830 It will also type a warning message telling you what it is doing.
1832 When reading an archive that was created with a different `tar'
1833 program, GNU `tar' automatically extracts entries in the archive which
1834 have absolute file names as if the file names were not absolute. This
1835 is an important feature. A visitor here once gave a `tar' tape to an
1836 operator to restore; the operator used Sun `tar' instead of GNU `tar',
1837 and the result was that it replaced large portions of our `/bin' and
1838 friends with versions from the tape; needless to say, we were unhappy
1839 about having to recover the file system from backup tapes.
1841 For example, if the archive contained a file `/usr/bin/computoy',
1842 GNU `tar' would extract the file to `usr/bin/computoy', relative to the
1843 current directory. If you want to extract the files in an archive to
1844 the same absolute names that they had when the archive was created, you
1845 should do a `cd /' before extracting the files from the archive, or you
1846 should either use the `--absolute-names' option, or use the command
1849 Some versions of Unix (Ultrix 3.1 is known to have this problem),
1850 can claim that a short write near the end of a tape succeeded, when it
1851 actually failed. This will result in the -M option not working
1852 correctly. The best workaround at the moment is to use a significantly
1853 larger blocking factor than the default 20.
1855 In order to update an archive, `tar' must be able to backspace the
1856 archive in order to reread or rewrite a record that was just read (or
1857 written). This is currently possible only on two kinds of files: normal
1858 disk files (or any other file that can be backspaced with `lseek'), and
1859 industry-standard 9-track magnetic tape (or any other kind of tape that
1860 can be backspaced with the `MTIOCTOP' `ioctl').
1862 This means that the `--append', `--concatenate', and `--delete'
1863 commands will not work on any other kind of file. Some media simply
1864 cannot be backspaced, which means these commands and options will never
1865 be able to work on them. These non-backspacing media include pipes and
1866 cartridge tape drives.
1868 Some other media can be backspaced, and `tar' will work on them once
1869 `tar' is modified to do so.
1871 Archives created with the `--multi-volume', `--label', and
1872 `--incremental' (`-G') options may not be readable by other version of
1873 `tar'. In particular, restoring a file that was split over a volume
1874 boundary will require some careful work with `dd', if it can be done at
1875 all. Other versions of `tar' may also create an empty file whose name
1876 is that of the volume header. Some versions of `tar' may create normal
1877 files instead of directories archived with the `--incremental' (`-G')
1881 File: tar.info, Node: Common Problems and Solutions, Next: Blocking, Prev: Remote Tape Server, Up: Media
1883 9.3 Some Common Problems and their Solutions
1884 ============================================
1888 no such file or directory
1892 directory checksum error
1895 errors from media/system:
1900 File: tar.info, Node: Blocking, Next: Many, Prev: Common Problems and Solutions, Up: Media
1905 "Block" and "record" terminology is rather confused, and it is also
1906 confusing to the expert reader. On the other hand, readers who are new
1907 to the field have a fresh mind, and they may safely skip the next two
1908 paragraphs, as the remainder of this manual uses those two terms in a
1909 quite consistent way.
1911 John Gilmore, the writer of the public domain `tar' from which GNU
1912 `tar' was originally derived, wrote (June 1995):
1914 The nomenclature of tape drives comes from IBM, where I believe
1915 they were invented for the IBM 650 or so. On IBM mainframes, what
1916 is recorded on tape are tape blocks. The logical organization of
1917 data is into records. There are various ways of putting records
1918 into blocks, including `F' (fixed sized records), `V' (variable
1919 sized records), `FB' (fixed blocked: fixed size records, N to a
1920 block), `VB' (variable size records, N to a block), `VSB'
1921 (variable spanned blocked: variable sized records that can occupy
1922 more than one block), etc. The `JCL' `DD RECFORM=' parameter
1923 specified this to the operating system.
1925 The Unix man page on `tar' was totally confused about this. When
1926 I wrote `PD TAR', I used the historically correct terminology
1927 (`tar' writes data records, which are grouped into blocks). It
1928 appears that the bogus terminology made it into POSIX (no surprise
1929 here), and now Franc,ois has migrated that terminology back into
1930 the source code too.
1932 The term "physical block" means the basic transfer chunk from or to
1933 a device, after which reading or writing may stop without anything
1934 being lost. In this manual, the term "block" usually refers to a disk
1935 physical block, _assuming_ that each disk block is 512 bytes in length.
1936 It is true that some disk devices have different physical blocks, but
1937 `tar' ignore these differences in its own format, which is meant to be
1938 portable, so a `tar' block is always 512 bytes in length, and "block"
1939 always mean a `tar' block. The term "logical block" often represents
1940 the basic chunk of allocation of many disk blocks as a single entity,
1941 which the operating system treats somewhat atomically; this concept is
1942 only barely used in GNU `tar'.
1944 The term "physical record" is another way to speak of a physical
1945 block, those two terms are somewhat interchangeable. In this manual,
1946 the term "record" usually refers to a tape physical block, _assuming_
1947 that the `tar' archive is kept on magnetic tape. It is true that
1948 archives may be put on disk or used with pipes, but nevertheless, `tar'
1949 tries to read and write the archive one "record" at a time, whatever
1950 the medium in use. One record is made up of an integral number of
1951 blocks, and this operation of putting many disk blocks into a single
1952 tape block is called "reblocking", or more simply, "blocking". The
1953 term "logical record" refers to the logical organization of many
1954 characters into something meaningful to the application. The term
1955 "unit record" describes a small set of characters which are transmitted
1956 whole to or by the application, and often refers to a line of text.
1957 Those two last terms are unrelated to what we call a "record" in GNU
1960 When writing to tapes, `tar' writes the contents of the archive in
1961 chunks known as "records". To change the default blocking factor, use
1962 the `--blocking-factor=512-SIZE' (`-b 512-SIZE') option. Each record
1963 will then be composed of 512-SIZE blocks. (Each `tar' block is 512
1964 bytes. *Note Standard::.) Each file written to the archive uses at
1965 least one full record. As a result, using a larger record size can
1966 result in more wasted space for small files. On the other hand, a
1967 larger record size can often be read and written much more efficiently.
1969 Further complicating the problem is that some tape drives ignore the
1970 blocking entirely. For these, a larger record size can still improve
1971 performance (because the software layers above the tape drive still
1972 honor the blocking), but not as dramatically as on tape drives that
1975 When reading an archive, `tar' can usually figure out the record
1976 size on itself. When this is the case, and a non-standard record size
1977 was used when the archive was created, `tar' will print a message about
1978 a non-standard blocking factor, and then operate normally(1). On some
1979 tape devices, however, `tar' cannot figure out the record size itself.
1980 On most of those, you can specify a blocking factor (with
1981 `--blocking-factor') larger than the actual blocking factor, and then
1982 use the `--read-full-records' (`-B') option. (If you specify a
1983 blocking factor with `--blocking-factor' and don't use the
1984 `--read-full-records' option, then `tar' will not attempt to figure out
1985 the recording size itself.) On some devices, you must always specify
1986 the record size exactly with `--blocking-factor' when reading, because
1987 `tar' cannot figure it out. In any case, use `--list' (`-t') before
1988 doing any extractions to see whether `tar' is reading the archive
1991 `tar' blocks are all fixed size (512 bytes), and its scheme for
1992 putting them into records is to put a whole number of them (one or
1993 more) into each record. `tar' records are all the same size; at the
1994 end of the file there's a block containing all zeros, which is how you
1995 tell that the remainder of the last record(s) are garbage.
1997 In a standard `tar' file (no options), the block size is 512 and the
1998 record size is 10240, for a blocking factor of 20. What the
1999 `--blocking-factor' option does is sets the blocking factor, changing
2000 the record size while leaving the block size at 512 bytes. 20 was fine
2001 for ancient 800 or 1600 bpi reel-to-reel tape drives; most tape drives
2002 these days prefer much bigger records in order to stream and not waste
2003 tape. When writing tapes for myself, some tend to use a factor of the
2004 order of 2048, say, giving a record size of around one megabyte.
2006 If you use a blocking factor larger than 20, older `tar' programs
2007 might not be able to read the archive, so we recommend this as a limit
2008 to use in practice. GNU `tar', however, will support arbitrarily large
2009 record sizes, limited only by the amount of virtual memory or the
2010 physical characteristics of the tape device.
2014 * Format Variations:: Format Variations
2015 * Blocking Factor:: The Blocking Factor of an Archive
2017 ---------- Footnotes ----------
2019 (1) If this message is not needed, you can turn it off using the
2020 `--warning=no-record-size' option.
2023 File: tar.info, Node: Format Variations, Next: Blocking Factor, Up: Blocking
2025 9.4.1 Format Variations
2026 -----------------------
2028 _(This message will disappear, once this node revised.)_
2030 Format parameters specify how an archive is written on the archive
2031 media. The best choice of format parameters will vary depending on the
2032 type and number of files being archived, and on the media used to store
2035 To specify format parameters when accessing or creating an archive,
2036 you can use the options described in the following sections. If you do
2037 not specify any format parameters, `tar' uses default parameters. You
2038 cannot modify a compressed archive. If you create an archive with the
2039 `--blocking-factor' option specified (*note Blocking Factor::), you
2040 must specify that blocking-factor when operating on the archive. *Note
2041 Formats::, for other examples of format parameter considerations.
2044 File: tar.info, Node: Blocking Factor, Prev: Format Variations, Up: Blocking
2046 9.4.2 The Blocking Factor of an Archive
2047 ---------------------------------------
2049 _(This message will disappear, once this node revised.)_
2051 The data in an archive is grouped into blocks, which are 512 bytes.
2052 Blocks are read and written in whole number multiples called "records".
2053 The number of blocks in a record (i.e., the size of a record in units
2054 of 512 bytes) is called the "blocking factor". The
2055 `--blocking-factor=512-SIZE' (`-b 512-SIZE') option specifies the
2056 blocking factor of an archive. The default blocking factor is
2057 typically 20 (i.e., 10240 bytes), but can be specified at installation.
2058 To find out the blocking factor of an existing archive, use `tar --list
2059 --file=ARCHIVE-NAME'. This may not work on some devices.
2061 Records are separated by gaps, which waste space on the archive
2062 media. If you are archiving on magnetic tape, using a larger blocking
2063 factor (and therefore larger records) provides faster throughput and
2064 allows you to fit more data on a tape (because there are fewer gaps).
2065 If you are archiving on cartridge, a very large blocking factor (say
2066 126 or more) greatly increases performance. A smaller blocking factor,
2067 on the other hand, may be useful when archiving small files, to avoid
2068 archiving lots of nulls as `tar' fills out the archive to the end of
2069 the record. In general, the ideal record size depends on the size of
2070 the inter-record gaps on the tape you are using, and the average size
2071 of the files you are archiving. *Note create::, for information on
2074 Archives with blocking factors larger than 20 cannot be read by very
2075 old versions of `tar', or by some newer versions of `tar' running on
2076 old machines with small address spaces. With GNU `tar', the blocking
2077 factor of an archive is limited only by the maximum record size of the
2078 device containing the archive, or by the amount of available virtual
2081 Also, on some systems, not using adequate blocking factors, as
2082 sometimes imposed by the device drivers, may yield unexpected
2083 diagnostics. For example, this has been reported:
2085 Cannot write to /dev/dlt: Invalid argument
2087 In such cases, it sometimes happen that the `tar' bundled by the system
2088 is aware of block size idiosyncrasies, while GNU `tar' requires an
2089 explicit specification for the block size, which it cannot guess. This
2090 yields some people to consider GNU `tar' is misbehaving, because by
2091 comparison, `the bundle `tar' works OK'. Adding `-b 256', for example,
2092 might resolve the problem.
2094 If you use a non-default blocking factor when you create an archive,
2095 you must specify the same blocking factor when you modify that archive.
2096 Some archive devices will also require you to specify the blocking
2097 factor when reading that archive, however this is not typically the
2098 case. Usually, you can use `--list' (`-t') without specifying a
2099 blocking factor--`tar' reports a non-default record size and then lists
2100 the archive members as it would normally. To extract files from an
2101 archive with a non-standard blocking factor (particularly if you're not
2102 sure what the blocking factor is), you can usually use the
2103 `--read-full-records' (`-B') option while specifying a blocking factor
2104 larger then the blocking factor of the archive (i.e., `tar --extract
2105 --read-full-records --blocking-factor=300'). *Note list::, for more
2106 information on the `--list' (`-t') operation. *Note Reading::, for a
2107 more detailed explanation of that option.
2109 `--blocking-factor=NUMBER'
2111 Specifies the blocking factor of an archive. Can be used with any
2112 operation, but is usually not necessary with `--list' (`-t').
2117 `--blocking-factor=BLOCKS'
2118 Set record size to BLOCKS*512 bytes.
2120 This option is used to specify a "blocking factor" for the archive.
2121 When reading or writing the archive, `tar', will do reads and
2122 writes of the archive in records of BLOCK*512 bytes. This is true
2123 even when the archive is compressed. Some devices requires that
2124 all write operations be a multiple of a certain size, and so, `tar'
2125 pads the archive out to the next record boundary.
2127 The default blocking factor is set when `tar' is compiled, and is
2128 typically 20. Blocking factors larger than 20 cannot be read by
2129 very old versions of `tar', or by some newer versions of `tar'
2130 running on old machines with small address spaces.
2132 With a magnetic tape, larger records give faster throughput and fit
2133 more data on a tape (because there are fewer inter-record gaps).
2134 If the archive is in a disk file or a pipe, you may want to specify
2135 a smaller blocking factor, since a large one will result in a large
2136 number of null bytes at the end of the archive.
2138 When writing cartridge or other streaming tapes, a much larger
2139 blocking factor (say 126 or more) will greatly increase
2140 performance. However, you must specify the same blocking factor
2141 when reading or updating the archive.
2143 Apparently, Exabyte drives have a physical block size of 8K bytes.
2144 If we choose our blocksize as a multiple of 8k bytes, then the
2145 problem seems to disappear. Id est, we are using block size of
2146 112 right now, and we haven't had the problem since we switched...
2148 With GNU `tar' the blocking factor is limited only by the maximum
2149 record size of the device containing the archive, or by the amount
2150 of available virtual memory.
2152 However, deblocking or reblocking is virtually avoided in a special
2153 case which often occurs in practice, but which requires all the
2154 following conditions to be simultaneously true:
2155 * the archive is subject to a compression option,
2157 * the archive is not handled through standard input or output,
2158 nor redirected nor piped,
2160 * the archive is directly handled to a local disk, instead of
2163 * `--blocking-factor' is not explicitly specified on the `tar'
2166 If the output goes directly to a local disk, and not through
2167 stdout, then the last write is not extended to a full record size.
2168 Otherwise, reblocking occurs. Here are a few other remarks on this
2171 * `gzip' will complain about trailing garbage if asked to
2172 uncompress a compressed archive on tape, there is an option
2173 to turn the message off, but it breaks the regularity of
2174 simply having to use `PROG -d' for decompression. It would
2175 be nice if gzip was silently ignoring any number of trailing
2176 zeros. I'll ask Jean-loup Gailly, by sending a copy of this
2179 * `compress' does not show this problem, but as Jean-loup
2180 pointed out to Michael, `compress -d' silently adds garbage
2181 after the result of decompression, which tar ignores because
2182 it already recognized its end-of-file indicator. So this bug
2183 may be safely ignored.
2185 * `gzip -d -q' will be silent about the trailing zeros indeed,
2186 but will still return an exit status of 2 which tar reports
2187 in turn. `tar' might ignore the exit status returned, but I
2188 hate doing that, as it weakens the protection `tar' offers
2189 users against other possible problems at decompression time.
2190 If `gzip' was silently skipping trailing zeros _and_ also
2191 avoiding setting the exit status in this innocuous case, that
2192 would solve this situation.
2194 * `tar' should become more solid at not stopping to read a pipe
2195 at the first null block encountered. This inelegantly breaks
2196 the pipe. `tar' should rather drain the pipe out before
2201 Ignore blocks of zeros in archive (means EOF).
2203 The `--ignore-zeros' (`-i') option causes `tar' to ignore blocks
2204 of zeros in the archive. Normally a block of zeros indicates the
2205 end of the archive, but when reading a damaged archive, or one
2206 which was created by concatenating several archives together, this
2207 option allows `tar' to read the entire archive. This option is
2208 not on by default because many versions of `tar' write garbage
2209 after the zeroed blocks.
2211 Note that this option causes `tar' to read to the end of the
2212 archive file, which may sometimes avoid problems when multiple
2213 files are stored on a single physical tape.
2216 `--read-full-records'
2217 Reblock as we read (for reading 4.2BSD pipes).
2219 If `--read-full-records' is used, `tar' will not panic if an
2220 attempt to read a record from the archive does not return a full
2221 record. Instead, `tar' will keep reading until it has obtained a
2224 This option is turned on by default when `tar' is reading an
2225 archive from standard input, or from a remote machine. This is
2226 because on BSD Unix systems, a read of a pipe will return however
2227 much happens to be in the pipe, even if it is less than `tar'
2228 requested. If this option was not used, `tar' would fail as soon
2229 as it read an incomplete record from the pipe.
2231 This option is also useful with the commands for updating an
2237 When handling various tapes or cartridges, you have to take care of
2238 selecting a proper blocking, that is, the number of disk blocks you put
2239 together as a single tape block on the tape, without intervening tape
2240 gaps. A "tape gap" is a small landing area on the tape with no
2241 information on it, used for decelerating the tape to a full stop, and
2242 for later regaining the reading or writing speed. When the tape driver
2243 starts reading a record, the record has to be read whole without
2244 stopping, as a tape gap is needed to stop the tape motion without
2247 Using higher blocking (putting more disk blocks per tape block) will
2248 use the tape more efficiently as there will be less tape gaps. But
2249 reading such tapes may be more difficult for the system, as more memory
2250 will be required to receive at once the whole record. Further, if
2251 there is a reading error on a huge record, this is less likely that the
2252 system will succeed in recovering the information. So, blocking should
2253 not be too low, nor it should be too high. `tar' uses by default a
2254 blocking of 20 for historical reasons, and it does not really matter
2255 when reading or writing to disk. Current tape technology would easily
2256 accommodate higher blockings. Sun recommends a blocking of 126 for
2257 Exabytes and 96 for DATs. We were told that for some DLT drives, the
2258 blocking should be a multiple of 4Kb, preferably 64Kb (`-b 128') or 256
2259 for decent performance. Other manufacturers may use different
2260 recommendations for the same tapes. This might also depends of the
2261 buffering techniques used inside modern tape controllers. Some imposes
2262 a minimum blocking, or a maximum blocking. Others request blocking to
2263 be some exponent of two.
2265 So, there is no fixed rule for blocking. But blocking at read time
2266 should ideally be the same as blocking used at write time. At one place
2267 I know, with a wide variety of equipment, they found it best to use a
2268 blocking of 32 to guarantee that their tapes are fully interchangeable.
2270 I was also told that, for recycled tapes, prior erasure (by the same
2271 drive unit that will be used to create the archives) sometimes lowers
2272 the error rates observed at rewriting time.
2274 I might also use `--number-blocks' instead of `--block-number', so
2275 `--block' will then expand to `--blocking-factor' unambiguously.
2278 File: tar.info, Node: Many, Next: Using Multiple Tapes, Prev: Blocking, Up: Media
2280 9.5 Many Archives on One Tape
2281 =============================
2283 Most tape devices have two entries in the `/dev' directory, or entries
2284 that come in pairs, which differ only in the minor number for this
2285 device. Let's take for example `/dev/tape', which often points to the
2286 only or usual tape device of a given system. There might be a
2287 corresponding `/dev/nrtape' or `/dev/ntape'. The simpler name is the
2288 _rewinding_ version of the device, while the name having `nr' in it is
2289 the _no rewinding_ version of the same device.
2291 A rewinding tape device will bring back the tape to its beginning
2292 point automatically when this device is opened or closed. Since `tar'
2293 opens the archive file before using it and closes it afterwards, this
2294 means that a simple:
2296 $ tar cf /dev/tape DIRECTORY
2298 will reposition the tape to its beginning both prior and after saving
2299 DIRECTORY contents to it, thus erasing prior tape contents and making
2300 it so that any subsequent write operation will destroy what has just
2303 So, a rewinding device is normally meant to hold one and only one
2304 file. If you want to put more than one `tar' archive on a given tape,
2305 you will need to avoid using the rewinding version of the tape device.
2306 You will also have to pay special attention to tape positioning.
2307 Errors in positioning may overwrite the valuable data already on your
2308 tape. Many people, burnt by past experiences, will only use rewinding
2309 devices and limit themselves to one file per tape, precisely to avoid
2310 the risk of such errors. Be fully aware that writing at the wrong
2311 position on a tape loses all information past this point and most
2312 probably until the end of the tape, and this destroyed information
2313 _cannot_ be recovered.
2315 To save DIRECTORY-1 as a first archive at the beginning of a tape,
2316 and leave that tape ready for a second archive, you should use:
2318 $ mt -f /dev/nrtape rewind
2319 $ tar cf /dev/nrtape DIRECTORY-1
2321 "Tape marks" are special magnetic patterns written on the tape
2322 media, which are later recognizable by the reading hardware. These
2323 marks are used after each file, when there are many on a single tape.
2324 An empty file (that is to say, two tape marks in a row) signal the
2325 logical end of the tape, after which no file exist. Usually,
2326 non-rewinding tape device drivers will react to the close request issued
2327 by `tar' by first writing two tape marks after your archive, and by
2328 backspacing over one of these. So, if you remove the tape at that time
2329 from the tape drive, it is properly terminated. But if you write
2330 another file at the current position, the second tape mark will be
2331 erased by the new information, leaving only one tape mark between files.
2333 So, you may now save DIRECTORY-2 as a second archive after the first
2334 on the same tape by issuing the command:
2336 $ tar cf /dev/nrtape DIRECTORY-2
2338 and so on for all the archives you want to put on the same tape.
2340 Another usual case is that you do not write all the archives the same
2341 day, and you need to remove and store the tape between two archive
2342 sessions. In general, you must remember how many files are already
2343 saved on your tape. Suppose your tape already has 16 files on it, and
2344 that you are ready to write the 17th. You have to take care of skipping
2345 the first 16 tape marks before saving DIRECTORY-17, say, by using these
2348 $ mt -f /dev/nrtape rewind
2349 $ mt -f /dev/nrtape fsf 16
2350 $ tar cf /dev/nrtape DIRECTORY-17
2352 In all the previous examples, we put aside blocking considerations,
2353 but you should do the proper things for that as well. *Note Blocking::.
2357 * Tape Positioning:: Tape Positions and Tape Marks
2358 * mt:: The `mt' Utility
2361 File: tar.info, Node: Tape Positioning, Next: mt, Up: Many
2363 9.5.1 Tape Positions and Tape Marks
2364 -----------------------------------
2366 _(This message will disappear, once this node revised.)_
2368 Just as archives can store more than one file from the file system,
2369 tapes can store more than one archive file. To keep track of where
2370 archive files (or any other type of file stored on tape) begin and end,
2371 tape archive devices write magnetic "tape marks" on the archive media.
2372 Tape drives write one tape mark between files, two at the end of all
2375 If you think of data as a series of records "rrrr"'s, and tape marks
2376 as "*"'s, a tape might look like the following:
2378 rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
2380 Tape devices read and write tapes using a read/write "tape head"--a
2381 physical part of the device which can only access one point on the tape
2382 at a time. When you use `tar' to read or write archive data from a
2383 tape device, the device will begin reading or writing from wherever on
2384 the tape the tape head happens to be, regardless of which archive or
2385 what part of the archive the tape head is on. Before writing an
2386 archive, you should make sure that no data on the tape will be
2387 overwritten (unless it is no longer needed). Before reading an
2388 archive, you should make sure the tape head is at the beginning of the
2389 archive you want to read. You can do it manually via `mt' utility
2390 (*note mt::). The `restore' script does that automatically (*note
2391 Scripted Restoration::).
2393 If you want to add new archive file entries to a tape, you should
2394 advance the tape to the end of the existing file entries, backspace
2395 over the last tape mark, and write the new archive file. If you were
2396 to add two archives to the example above, the tape might look like the
2399 rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
2402 File: tar.info, Node: mt, Prev: Tape Positioning, Up: Many
2404 9.5.2 The `mt' Utility
2405 ----------------------
2407 _(This message will disappear, once this node revised.)_
2409 *Note Blocking Factor::.
2411 You can use the `mt' utility to advance or rewind a tape past a
2412 specified number of archive files on the tape. This will allow you to
2413 move to the beginning of an archive before extracting or reading it, or
2414 to the end of all the archives before writing a new one.
2416 The syntax of the `mt' command is:
2418 mt [-f TAPENAME] OPERATION [NUMBER]
2420 where TAPENAME is the name of the tape device, NUMBER is the number
2421 of times an operation is performed (with a default of one), and
2422 OPERATION is one of the following:
2426 Writes NUMBER tape marks at the current position on the tape.
2429 Moves tape position forward NUMBER files.
2432 Moves tape position back NUMBER files.
2435 Rewinds the tape. (Ignores NUMBER.)
2439 Rewinds the tape and takes the tape device off-line. (Ignores
2443 Prints status information about the tape unit.
2446 If you don't specify a TAPENAME, `mt' uses the environment variable
2447 `TAPE'; if `TAPE' is not set, `mt' will use the default device
2448 specified in your `sys/mtio.h' file (`DEFTAPE' variable). If this is
2449 not defined, the program will display a descriptive error message and
2452 `mt' returns a 0 exit status when the operation(s) were successful,
2453 1 if the command was unrecognized, and 2 if an operation failed.
2456 File: tar.info, Node: Using Multiple Tapes, Next: label, Prev: Many, Up: Media
2458 9.6 Using Multiple Tapes
2459 ========================
2461 Often you might want to write a large archive, one larger than will fit
2462 on the actual tape you are using. In such a case, you can run multiple
2463 `tar' commands, but this can be inconvenient, particularly if you are
2464 using options like `--exclude=PATTERN' or dumping entire file systems.
2465 Therefore, `tar' provides a special mode for creating multi-volume
2468 "Multi-volume" archive is a single `tar' archive, stored on several
2469 media volumes of fixed size. Although in this section we will often
2470 call `volume' a "tape", there is absolutely no requirement for
2471 multi-volume archives to be stored on tapes. Instead, they can use
2472 whatever media type the user finds convenient, they can even be located
2475 When creating a multi-volume archive, GNU `tar' continues to fill
2476 current volume until it runs out of space, then it switches to next
2477 volume (usually the operator is queried to replace the tape on this
2478 point), and continues working on the new volume. This operation
2479 continues until all requested files are dumped. If GNU `tar' detects
2480 end of media while dumping a file, such a file is archived in split
2481 form. Some very big files can even be split across several volumes.
2483 Each volume is itself a valid GNU `tar' archive, so it can be read
2484 without any special options. Consequently any file member residing
2485 entirely on one volume can be extracted or otherwise operated upon
2486 without needing the other volume. Sure enough, to extract a split
2487 member you would need all volumes its parts reside on.
2489 Multi-volume archives suffer from several limitations. In
2490 particular, they cannot be compressed.
2492 GNU `tar' is able to create multi-volume archives of two formats
2493 (*note Formats::): `GNU' and `POSIX'.
2497 * Multi-Volume Archives:: Archives Longer than One Tape or Disk
2498 * Tape Files:: Tape Files
2499 * Tarcat:: Concatenate Volumes into a Single Archive
2502 File: tar.info, Node: Multi-Volume Archives, Next: Tape Files, Up: Using Multiple Tapes
2504 9.6.1 Archives Longer than One Tape or Disk
2505 -------------------------------------------
2507 To create an archive that is larger than will fit on a single unit of
2508 the media, use the `--multi-volume' (`-M') option in conjunction with
2509 the `--create' option (*note create::). A "multi-volume" archive can
2510 be manipulated like any other archive (provided the `--multi-volume'
2511 option is specified), but is stored on more than one tape or file.
2513 When you specify `--multi-volume', `tar' does not report an error
2514 when it comes to the end of an archive volume (when reading), or the
2515 end of the media (when writing). Instead, it prompts you to load a new
2516 storage volume. If the archive is on a magnetic tape, you should
2517 change tapes when you see the prompt; if the archive is on a floppy
2518 disk, you should change disks; etc.
2522 Creates a multi-volume archive, when used in conjunction with
2523 `--create' (`-c'). To perform any other operation on a
2524 multi-volume archive, specify `--multi-volume' in conjunction with
2525 that operation. For example:
2527 $ tar --create --multi-volume --file=/dev/tape FILES
2529 The method `tar' uses to detect end of tape is not perfect, and
2530 fails on some operating systems or on some devices. If `tar' cannot
2531 detect the end of the tape itself, you can use `--tape-length' option
2532 to inform it about the capacity of the tape:
2534 `--tape-length=SIZE[SUF]'
2536 Set maximum length of a volume. The SUF, if given, specifies
2537 units in which SIZE is expressed, e.g. `2M' mean 2 megabytes
2538 (*note Table 9.1: size-suffixes, for a list of allowed size
2539 suffixes). Without SUF, units of 1024 bytes (kilobyte) are
2542 This option selects `--multi-volume' automatically. For example:
2544 $ tar --create --tape-length=41943040 --file=/dev/tape FILES
2546 or, which is equivalent:
2548 $ tar --create --tape-length=4G --file=/dev/tape FILES
2550 When GNU `tar' comes to the end of a storage media, it asks you to
2551 change the volume. The built-in prompt for POSIX locale is(1):
2553 Prepare volume #N for 'ARCHIVE' and hit return:
2555 where N is the ordinal number of the volume to be created and ARCHIVE
2556 is archive file or device name.
2558 When prompting for a new tape, `tar' accepts any of the following
2562 Request `tar' to explain possible responses.
2565 Request `tar' to exit immediately.
2568 Request `tar' to write the next volume on the file FILE-NAME.
2571 Request `tar' to run a subshell. This option can be disabled by
2572 giving `--restrict' command line option to `tar'(2).
2575 Request `tar' to begin writing the next volume.
2577 (You should only type `y' after you have changed the tape; otherwise
2578 `tar' will write over the volume it just finished.)
2580 The volume number used by `tar' in its tape-changing prompt can be
2581 changed; if you give the `--volno-file=FILE-OF-NUMBER' option, then
2582 FILE-OF-NUMBER should be an non-existing file to be created, or else, a
2583 file already containing a decimal number. That number will be used as
2584 the volume number of the first volume written. When `tar' is finished,
2585 it will rewrite the file with the now-current volume number. (This does
2586 not change the volume number written on a tape label, as per *note
2587 label::, it _only_ affects the number used in the prompt.)
2589 If you want more elaborate behavior than this, you can write a
2590 special "new volume script", that will be responsible for changing the
2591 volume, and instruct `tar' to use it instead of its normal prompting
2594 `--info-script=COMMAND'
2595 `--new-volume-script=COMMAND'
2597 Specify the command to invoke when switching volumes. The COMMAND
2598 can be used to eject cassettes, or to broadcast messages such as
2599 `Someone please come change my tape' when performing unattended
2602 The COMMAND can contain additional options, if such are needed.
2603 *Note Running External Commands: external, for a detailed discussion of
2604 the way GNU `tar' runs external commands. It inherits `tar''s shell
2605 environment. Additional data is passed to it via the following
2606 environment variables:
2609 GNU `tar' version number.
2612 The name of the archive `tar' is processing.
2614 `TAR_BLOCKING_FACTOR'
2615 Current blocking factor (*note Blocking::).
2618 Ordinal number of the volume `tar' is about to start.
2621 A short option describing the operation `tar' is executing. *Note
2622 Operations::, for a complete list of subcommand options.
2625 Format of the archive being processed. *Note Formats::, for a
2626 complete list of archive format names.
2629 File descriptor which can be used to communicate the new volume
2632 These variables can be used in the COMMAND itself, provided that
2633 they are properly quoted to prevent them from being expanded by the
2634 shell that invokes `tar'.
2636 The volume script can instruct `tar' to use new archive name, by
2637 writing in to file descriptor `$TAR_FD' (see below for an example).
2639 If the info script fails, `tar' exits; otherwise, it begins writing
2642 If you want `tar' to cycle through a series of files or tape drives,
2643 there are three approaches to choose from. First of all, you can give
2644 `tar' multiple `--file' options. In this case the specified files will
2645 be used, in sequence, as the successive volumes of the archive. Only
2646 when the first one in the sequence needs to be used again will `tar'
2647 prompt for a tape change (or run the info script). For example,
2648 suppose someone has two tape drives on a system named `/dev/tape0' and
2649 `/dev/tape1'. For having GNU `tar' to switch to the second drive when
2650 it needs to write the second tape, and then back to the first tape,
2651 etc., just do either of:
2653 $ tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 FILES
2654 $ tar -cM -f /dev/tape0 -f /dev/tape1 FILES
2656 The second method is to use the `n' response to the tape-change
2659 Finally, the most flexible approach is to use a volume script, that
2660 writes new archive name to the file descriptor `$TAR_FD'. For example,
2661 the following volume script will create a series of archive files, named
2662 `ARCHIVE-VOL', where ARCHIVE is the name of the archive being created
2663 (as given by `--file' option) and VOL is the ordinal number of the
2664 archive being created:
2667 # For this script it's advisable to use a shell, such as Bash,
2668 # that supports a TAR_FD value greater than 9.
2670 echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
2672 name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
2673 case $TAR_SUBCOMMAND in
2675 -d|-x|-t) test -r ${name:-$TAR_ARCHIVE}-$TAR_VOLUME || exit 1
2680 echo ${name:-$TAR_ARCHIVE}-$TAR_VOLUME >&$TAR_FD
2682 The same script can be used while listing, comparing or extracting
2683 from the created archive. For example:
2685 # Create a multi-volume archive:
2686 $ tar -c -L1024 -f archive.tar -F new-volume .
2687 # Extract from the created archive:
2688 $ tar -x -f archive.tar -F new-volume .
2690 Notice, that the first command had to use `-L' option, since otherwise
2691 GNU `tar' will end up writing everything to file `archive.tar'.
2693 You can read each individual volume of a multi-volume archive as if
2694 it were an archive by itself. For example, to list the contents of one
2695 volume, use `--list', without `--multi-volume' specified. To extract
2696 an archive member from one volume (assuming it is described that
2697 volume), use `--extract', again without `--multi-volume'.
2699 If an archive member is split across volumes (i.e., its entry begins
2700 on one volume of the media and ends on another), you need to specify
2701 `--multi-volume' to extract it successfully. In this case, you should
2702 load the volume where the archive member starts, and use `tar --extract
2703 --multi-volume'--`tar' will prompt for later volumes as it needs them.
2704 *Note extracting archives::, for more information about extracting
2707 Multi-volume archives can be modified like any other archive. To add
2708 files to a multi-volume archive, you need to only mount the last volume
2709 of the archive media (and new volumes, if needed). For all other
2710 operations, you need to use the entire archive.
2712 If a multi-volume archive was labeled using `--label=ARCHIVE-LABEL'
2713 (*note label::) when it was created, `tar' will not automatically label
2714 volumes which are added later. To label subsequent volumes, specify
2715 `--label=ARCHIVE-LABEL' again in conjunction with the `--append',
2716 `--update' or `--concatenate' operation.
2718 Notice that multi-volume support is a GNU extension and the archives
2719 created in this mode should be read only using GNU `tar'. If you
2720 absolutely have to process such archives using a third-party `tar'
2721 implementation, read *note Split Recovery::.
2723 ---------- Footnotes ----------
2725 (1) If you run GNU `tar' under a different locale, the translation
2726 to the locale's language will be used.
2728 (2) *Note --restrict::, for more information about this option.
2731 File: tar.info, Node: Tape Files, Next: Tarcat, Prev: Multi-Volume Archives, Up: Using Multiple Tapes
2736 _(This message will disappear, once this node revised.)_
2738 To give the archive a name which will be recorded in it, use the
2739 `--label=VOLUME-LABEL' (`-V VOLUME-LABEL') option. This will write a
2740 special block identifying VOLUME-LABEL as the name of the archive to
2741 the front of the archive which will be displayed when the archive is
2742 listed with `--list'. If you are creating a multi-volume archive with
2743 `--multi-volume' (*note Using Multiple Tapes::), then the volume label
2744 will have `Volume NNN' appended to the name you give, where NNN is the
2745 number of the volume of the archive. If you use the
2746 `--label=VOLUME-LABEL' option when reading an archive, it checks to
2747 make sure the label on the tape matches the one you gave. *Note
2750 When `tar' writes an archive to tape, it creates a single tape file.
2751 If multiple archives are written to the same tape, one after the other,
2752 they each get written as separate tape files. When extracting, it is
2753 necessary to position the tape at the right place before running `tar'.
2754 To do this, use the `mt' command. For more information on the `mt'
2755 command and on the organization of tapes into a sequence of tape files,
2758 People seem to often do:
2760 --label="SOME-PREFIX `date +SOME-FORMAT`"
2762 or such, for pushing a common date in all volumes or an archive set.
2765 File: tar.info, Node: Tarcat, Prev: Tape Files, Up: Using Multiple Tapes
2767 9.6.3 Concatenate Volumes into a Single Archive
2768 -----------------------------------------------
2770 Sometimes it is necessary to convert existing GNU `tar' multi-volume
2771 archive to a single `tar' archive. Simply concatenating all volumes
2772 into one will not work, since each volume carries an additional
2773 information at the beginning. GNU `tar' is shipped with the shell
2774 script `tarcat' designed for this purpose.
2776 The script takes a list of files comprising a multi-volume archive
2777 and creates the resulting archive at the standard output. For example:
2779 tarcat vol.1 vol.2 vol.3 | tar tf -
2781 The script implements a simple heuristics to determine the format of
2782 the first volume file and to decide how to process the rest of the
2783 files. However, it makes no attempt to verify whether the files are
2784 given in order or even if they are valid `tar' archives. It uses `dd'
2785 and does not filter its standard error, so you will usually see lots of
2789 File: tar.info, Node: label, Next: verify, Prev: Using Multiple Tapes, Up: Media
2791 9.7 Including a Label in the Archive
2792 ====================================
2794 To avoid problems caused by misplaced paper labels on the archive
2795 media, you can include a "label" entry -- an archive member which
2796 contains the name of the archive -- in the archive itself. Use the
2797 `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') option(1) in conjunction
2798 with the `--create' operation to include a label entry in the archive
2799 as it is being created.
2801 `--label=ARCHIVE-LABEL'
2803 Includes an "archive-label" at the beginning of the archive when
2804 the archive is being created, when used in conjunction with the
2805 `--create' operation. Checks to make sure the archive label
2806 matches the one specified (when used in conjunction with any other
2809 If you create an archive using both `--label=ARCHIVE-LABEL' (`-V
2810 ARCHIVE-LABEL') and `--multi-volume' (`-M'), each volume of the archive
2811 will have an archive label of the form `ARCHIVE-LABEL Volume N', where
2812 N is 1 for the first volume, 2 for the next, and so on. *Note Using
2813 Multiple Tapes::, for information on creating multiple volume archives.
2815 The volume label will be displayed by `--list' along with the file
2816 contents. If verbose display is requested, it will also be explicitly
2817 marked as in the example below:
2819 $ tar --verbose --list --file=iamanarchive
2820 V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header--
2821 -rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename
2823 However, `--list' option will cause listing entire contents of the
2824 archive, which may be undesirable (for example, if the archive is
2825 stored on a tape). You can request checking only the volume label by
2826 specifying `--test-label' option. This option reads only the first
2827 block of an archive, so it can be used with slow storage devices. For
2830 $ tar --test-label --file=iamanarchive
2833 If `--test-label' is used with one or more command line arguments,
2834 `tar' compares the volume label with each argument. It exits with code
2835 0 if a match is found, and with code 1 otherwise(2). No output is
2836 displayed, unless you also used the `--verbose' option. For example:
2838 $ tar --test-label --file=iamanarchive 'iamalabel'
2840 $ tar --test-label --file=iamanarchive 'alabel'
2843 When used with the `--verbose' option, `tar' prints the actual
2844 volume label (if any), and a verbose diagnostics in case of a mismatch:
2846 $ tar --test-label --verbose --file=iamanarchive 'iamalabel'
2849 $ tar --test-label --verbose --file=iamanarchive 'alabel'
2851 tar: Archive label mismatch
2854 If you request any operation, other than `--create', along with
2855 using `--label' option, `tar' will first check if the archive label
2856 matches the one specified and will refuse to proceed if it does not.
2857 Use this as a safety precaution to avoid accidentally overwriting
2858 existing archives. For example, if you wish to add files to `archive',
2859 presumably labeled with string `My volume', you will get:
2861 $ tar -rf archive --label 'My volume' .
2862 tar: Archive not labeled to match 'My volume'
2864 in case its label does not match. This will work even if `archive' is
2867 Similarly, `tar' will refuse to list or extract the archive if its
2868 label doesn't match the ARCHIVE-LABEL specified. In those cases,
2869 ARCHIVE-LABEL argument is interpreted as a globbing-style pattern which
2870 must match the actual magnetic volume label. *Note exclude::, for a
2871 precise description of how match is attempted(3). If the switch
2872 `--multi-volume' (`-M') is being used, the volume label matcher will
2873 also suffix ARCHIVE-LABEL by ` Volume [1-9]*' if the initial match
2874 fails, before giving up. Since the volume numbering is automatically
2875 added in labels at creation time, it sounded logical to equally help
2876 the user taking care of it when the archive is being read.
2878 You can also use `--label' to get a common information on all tapes
2879 of a series. For having this information different in each series
2880 created through a single script used on a regular basis, just manage to
2881 get some date string as part of the label. For example:
2883 $ tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"
2884 $ tar --create --file=/dev/tape --multi-volume \
2885 --label="Daily backup for `date +%Y-%m-%d`"
2887 Some more notes about volume labels:
2889 * Each label has its own date and time, which corresponds to the
2890 time when GNU `tar' initially attempted to write it, often soon
2891 after the operator launches `tar' or types the carriage return
2892 telling that the next tape is ready.
2894 * Comparing date labels to get an idea of tape throughput is
2895 unreliable. It gives correct results only if the delays for
2896 rewinding tapes and the operator switching them were negligible,
2897 which is usually not the case.
2899 ---------- Footnotes ----------
2901 (1) Until version 1.10, that option was called `--volume', but is
2902 not available under that name anymore.
2904 (2) Note that GNU `tar' versions up to 1.23 indicated mismatch with
2905 an exit code 2 and printed a spurious diagnostics on stderr.
2907 (3) Previous versions of `tar' used full regular expression
2908 matching, or before that, only exact string matching, instead of
2909 wildcard matchers. We decided for the sake of simplicity to use a
2910 uniform matching device through `tar'.
2913 File: tar.info, Node: verify, Next: Write Protection, Prev: label, Up: Media
2915 9.8 Verifying Data as It is Stored
2916 ==================================
2920 Attempt to verify the archive after writing.
2922 This option causes `tar' to verify the archive after writing it.
2923 Each volume is checked after it is written, and any discrepancies are
2924 recorded on the standard error output.
2926 Verification requires that the archive be on a back-space-able
2927 medium. This means pipes, some cartridge tape drives, and some other
2928 devices cannot be verified.
2930 You can insure the accuracy of an archive by comparing files in the
2931 system with archive members. `tar' can compare an archive to the file
2932 system as the archive is being written, to verify a write operation, or
2933 can compare a previously written archive, to insure that it is up to
2936 To check for discrepancies in an archive immediately after it is
2937 written, use the `--verify' (`-W') option in conjunction with the
2938 `--create' operation. When this option is specified, `tar' checks
2939 archive members against their counterparts in the file system, and
2940 reports discrepancies on the standard error.
2942 To verify an archive, you must be able to read it from before the end
2943 of the last written entry. This option is useful for detecting data
2944 errors on some tapes. Archives written to pipes, some cartridge tape
2945 drives, and some other devices cannot be verified.
2947 One can explicitly compare an already made archive with the file
2948 system by using the `--compare' (`--diff', `-d') option, instead of
2949 using the more automatic `--verify' option. *Note compare::.
2951 Note that these two options have a slightly different intent. The
2952 `--compare' option checks how identical are the logical contents of some
2953 archive with what is on your disks, while the `--verify' option is
2954 really for checking if the physical contents agree and if the recording
2955 media itself is of dependable quality. So, for the `--verify'
2956 operation, `tar' tries to defeat all in-memory cache pertaining to the
2957 archive, while it lets the speed optimization undisturbed for the
2958 `--compare' option. If you nevertheless use `--compare' for media
2959 verification, you may have to defeat the in-memory cache yourself,
2960 maybe by opening and reclosing the door latch of your recording unit,
2961 forcing some doubt in your operating system about the fact this is
2962 really the same volume as the one just written or read.
2964 The `--verify' option would not be necessary if drivers were indeed
2965 able to detect dependably all write failures. This sometimes require
2966 many magnetic heads, some able to read after the writes occurred. One
2967 would not say that drivers unable to detect all cases are necessarily
2968 flawed, as long as programming is concerned.
2970 The `--verify' (`-W') option will not work in conjunction with the
2971 `--multi-volume' (`-M') option or the `--append' (`-r'), `--update'
2972 (`-u') and `--delete' operations. *Note Operations::, for more
2973 information on these operations.
2975 Also, since `tar' normally strips leading `/' from file names (*note
2976 absolute::), a command like `tar --verify -cf /tmp/foo.tar /etc' will
2977 work as desired only if the working directory is `/', as `tar' uses the
2978 archive's relative member names (e.g., `etc/motd') when verifying the
2982 File: tar.info, Node: Write Protection, Prev: verify, Up: Media
2984 9.9 Write Protection
2985 ====================
2987 Almost all tapes and diskettes, and in a few rare cases, even disks can
2988 be "write protected", to protect data on them from being changed. Once
2989 an archive is written, you should write protect the media to prevent
2990 the archive from being accidentally overwritten or deleted. (This will
2991 protect the archive from being changed with a tape or floppy drive--it
2992 will not protect it from magnet fields or other physical hazards.)
2994 The write protection device itself is usually an integral part of the
2995 physical media, and can be a two position (write enabled/write
2996 disabled) switch, a notch which can be popped out or covered, a ring
2997 which can be removed from the center of a tape reel, or some other
3001 File: tar.info, Node: Reliability and security, Next: Changes, Prev: Media, Up: Top
3003 10 Reliability and Security
3004 ***************************
3006 The `tar' command reads and writes files as any other application does,
3007 and is subject to the usual caveats about reliability and security.
3008 This section contains some commonsense advice on the topic.
3016 File: tar.info, Node: Reliability, Next: Security, Up: Reliability and security
3021 Ideally, when `tar' is creating an archive, it reads from a file system
3022 that is not being modified, and encounters no errors or inconsistencies
3023 while reading and writing. If this is the case, the archive should
3024 faithfully reflect what was read. Similarly, when extracting from an
3025 archive, ideally `tar' ideally encounters no errors and the extracted
3026 files faithfully reflect what was in the archive.
3028 However, when reading or writing real-world file systems, several
3029 things can go wrong; these include permissions problems, corruption of
3030 data, and race conditions.
3034 * Permissions problems::
3035 * Data corruption and repair::
3039 File: tar.info, Node: Permissions problems, Next: Data corruption and repair, Up: Reliability
3041 10.1.1 Permissions Problems
3042 ---------------------------
3044 If `tar' encounters errors while reading or writing files, it normally
3045 reports an error and exits with nonzero status. The work it does may
3046 therefore be incomplete. For example, when creating an archive, if
3047 `tar' cannot read a file then it cannot copy the file into the archive.
3050 File: tar.info, Node: Data corruption and repair, Next: Race conditions, Prev: Permissions problems, Up: Reliability
3052 10.1.2 Data Corruption and Repair
3053 ---------------------------------
3055 If an archive becomes corrupted by an I/O error, this may corrupt the
3056 data in an extracted file. Worse, it may corrupt the file's metadata,
3057 which may cause later parts of the archive to become misinterpreted.
3058 An tar-format archive contains a checksum that most likely will detect
3059 errors in the metadata, but it will not detect errors in the data.
3061 If data corruption is a concern, you can compute and check your own
3062 checksums of an archive by using other programs, such as `cksum'.
3064 When attempting to recover from a read error or data corruption in an
3065 archive, you may need to skip past the questionable data and read the
3066 rest of the archive. This requires some expertise in the archive
3067 format and in other software tools.
3070 File: tar.info, Node: Race conditions, Prev: Data corruption and repair, Up: Reliability
3072 10.1.3 Race conditions
3073 ----------------------
3075 If some other process is modifying the file system while `tar' is
3076 reading or writing files, the result may well be inconsistent due to
3077 race conditions. For example, if another process creates some files in
3078 a directory while `tar' is creating an archive containing the
3079 directory's files, `tar' may see some of the files but not others, or
3080 it may see a file that is in the process of being created. The
3081 resulting archive may not be a snapshot of the file system at any point
3082 in time. If an application such as a database system depends on an
3083 accurate snapshot, restoring from the `tar' archive of a live file
3084 system may therefore break that consistency and may break the
3085 application. The simplest way to avoid the consistency issues is to
3086 avoid making other changes to the file system while tar is reading it
3089 When creating an archive, several options are available to avoid race
3090 conditions. Some hosts have a way of snapshotting a file system, or of
3091 temporarily suspending all changes to a file system, by (say)
3092 suspending the only virtual machine that can modify a file system; if
3093 you use these facilities and have `tar -c' read from a snapshot when
3094 creating an archive, you can avoid inconsistency problems. More
3095 drastically, before starting `tar' you could suspend or shut down all
3096 processes other than `tar' that have access to the file system, or you
3097 could unmount the file system and then mount it read-only.
3099 When extracting from an archive, one approach to avoid race
3100 conditions is to create a directory that no other process can write to,
3101 and extract into that.
3104 File: tar.info, Node: Security, Prev: Reliability, Up: Reliability and security
3109 In some cases `tar' may be used in an adversarial situation, where an
3110 untrusted user is attempting to gain information about or modify
3111 otherwise-inaccessible files. Dealing with untrusted data (that is,
3112 data generated by an untrusted user) typically requires extra care,
3113 because even the smallest mistake in the use of `tar' is more likely to
3114 be exploited by an adversary than by a race condition.
3120 * Live untrusted data::
3121 * Security rules of thumb::
3124 File: tar.info, Node: Privacy, Next: Integrity, Up: Security
3129 Standard privacy concerns apply when using `tar'. For example, suppose
3130 you are archiving your home directory into a file
3131 `/archive/myhome.tar'. Any secret information in your home directory,
3132 such as your SSH secret keys, are copied faithfully into the archive.
3133 Therefore, if your home directory contains any file that should not be
3134 read by some other user, the archive itself should be not be readable
3135 by that user. And even if the archive's data are inaccessible to
3136 untrusted users, its metadata (such as size or last-modified date) may
3137 reveal some information about your home directory; if the metadata are
3138 intended to be private, the archive's parent directory should also be
3139 inaccessible to untrusted users.
3141 One precaution is to create `/archive' so that it is not accessible
3142 to any user, unless that user also has permission to access all the
3143 files in your home directory.
3145 Similarly, when extracting from an archive, take care that the
3146 permissions of the extracted files are not more generous than what you
3147 want. Even if the archive itself is readable only to you, files
3148 extracted from it have their own permissions that may differ.
3151 File: tar.info, Node: Integrity, Next: Live untrusted data, Prev: Privacy, Up: Security
3156 When creating archives, take care that they are not writable by a
3157 untrusted user; otherwise, that user could modify the archive, and when
3158 you later extract from the archive you will get incorrect data.
3160 When `tar' extracts from an archive, by default it writes into files
3161 relative to the working directory. If the archive was generated by an
3162 untrusted user, that user therefore can write into any file under the
3163 working directory. If the working directory contains a symbolic link
3164 to another directory, the untrusted user can also write into any file
3165 under the referenced directory. When extracting from an untrusted
3166 archive, it is therefore good practice to create an empty directory and
3167 run `tar' in that directory.
3169 When extracting from two or more untrusted archives, each one should
3170 be extracted independently, into different empty directories.
3171 Otherwise, the first archive could create a symbolic link into an area
3172 outside the working directory, and the second one could follow the link
3173 and overwrite data that is not under the working directory. For
3174 example, when restoring from a series of incremental dumps, the
3175 archives should have been created by a trusted process, as otherwise
3176 the incremental restores might alter data outside the working directory.
3178 If you use the `--absolute-names' (`-P') option when extracting,
3179 `tar' respects any file names in the archive, even file names that
3180 begin with `/' or contain `..'. As this lets the archive overwrite any
3181 file in your system that you can write, the `--absolute-names' (`-P')
3182 option should be used only for trusted archives.
3184 Conversely, with the `--keep-old-files' (`-k') and
3185 `--skip-old-files' options, `tar' refuses to replace existing files
3186 when extracting. The difference between the two options is that the
3187 former treats existing files as errors whereas the latter just silently
3190 Finally, with the `--no-overwrite-dir' option, `tar' refuses to
3191 replace the permissions or ownership of already-existing directories.
3192 These options may help when extracting from untrusted archives.
3195 File: tar.info, Node: Live untrusted data, Next: Security rules of thumb, Prev: Integrity, Up: Security
3197 10.2.3 Dealing with Live Untrusted Data
3198 ---------------------------------------
3200 Extra care is required when creating from or extracting into a file
3201 system that is accessible to untrusted users. For example, superusers
3202 who invoke `tar' must be wary about its actions being hijacked by an
3203 adversary who is reading or writing the file system at the same time
3204 that `tar' is operating.
3206 When creating an archive from a live file system, `tar' is
3207 vulnerable to denial-of-service attacks. For example, an adversarial
3208 user could create the illusion of an indefinitely-deep directory
3209 hierarchy `d/e/f/g/...' by creating directories one step ahead of
3210 `tar', or the illusion of an indefinitely-long file by creating a
3211 sparse file but arranging for blocks to be allocated just before `tar'
3212 reads them. There is no easy way for `tar' to distinguish these
3213 scenarios from legitimate uses, so you may need to monitor `tar', just
3214 as you'd need to monitor any other system service, to detect such
3217 While a superuser is extracting from an archive into a live file
3218 system, an untrusted user might replace a directory with a symbolic
3219 link, in hopes that `tar' will follow the symbolic link and extract
3220 data into files that the untrusted user does not have access to. Even
3221 if the archive was generated by the superuser, it may contain a file
3222 such as `d/etc/passwd' that the untrusted user earlier created in order
3223 to break in; if the untrusted user replaces the directory `d/etc' with
3224 a symbolic link to `/etc' while `tar' is running, `tar' will overwrite
3225 `/etc/passwd'. This attack can be prevented by extracting into a
3226 directory that is inaccessible to untrusted users.
3228 Similar attacks via symbolic links are also possible when creating an
3229 archive, if the untrusted user can modify an ancestor of a top-level
3230 argument of `tar'. For example, an untrusted user that can modify
3231 `/home/eve' can hijack a running instance of `tar -cf -
3232 /home/eve/Documents/yesterday' by replacing `/home/eve/Documents' with
3233 a symbolic link to some other location. Attacks like these can be
3234 prevented by making sure that untrusted users cannot modify any files
3235 that are top-level arguments to `tar', or any ancestor directories of
3239 File: tar.info, Node: Security rules of thumb, Prev: Live untrusted data, Up: Security
3241 10.2.4 Security Rules of Thumb
3242 ------------------------------
3244 This section briefly summarizes rules of thumb for avoiding security
3247 * Protect archives at least as much as you protect any of the files
3250 * Extract from an untrusted archive only into an otherwise-empty
3251 directory. This directory and its parent should be accessible
3252 only to trusted users. For example:
3255 $ mkdir -m go-rwx dir
3257 $ tar -xvf /archives/got-it-off-the-net.tar.gz
3259 As a corollary, do not do an incremental restore from an untrusted
3262 * Do not let untrusted users access files extracted from untrusted
3263 archives without checking first for problems such as setuid
3266 * Do not let untrusted users modify directories that are ancestors of
3267 top-level arguments of `tar'. For example, while you are
3268 executing `tar -cf /archive/u-home.tar /u/home', do not let an
3269 untrusted user modify `/', `/archive', or `/u'.
3271 * Pay attention to the diagnostics and exit status of `tar'.
3273 * When archiving live file systems, monitor running instances of
3274 `tar' to detect denial-of-service attacks.
3276 * Avoid unusual options such as `--absolute-names' (`-P'),
3277 `--dereference' (`-h'), `--overwrite', `--recursive-unlink', and
3278 `--remove-files' unless you understand their security implications.
3282 File: tar.info, Node: Changes, Next: Configuring Help Summary, Prev: Reliability and security, Up: Top
3287 This appendix lists some important user-visible changes between version
3288 GNU `tar' 1.27 and previous versions. An up-to-date version of this
3289 document is available at the GNU `tar' documentation page
3290 (http://www.gnu.org/software/tar/manual/changes.html).
3292 Use of globbing patterns when listing and extracting.
3293 Previous versions of GNU tar assumed shell-style globbing when
3294 extracting from or listing an archive. For example:
3296 $ tar xf foo.tar '*.c'
3298 would extract all files whose names end in `.c'. This behavior
3299 was not documented and was incompatible with traditional tar
3300 implementations. Therefore, starting from version 1.15.91, GNU tar
3301 no longer uses globbing by default. For example, the above
3302 invocation is now interpreted as a request to extract from the
3303 archive the file named `*.c'.
3305 To facilitate transition to the new behavior for those users who
3306 got used to the previous incorrect one, `tar' will print a warning
3307 if it finds out that a requested member was not found in the
3308 archive and its name looks like a globbing pattern. For example:
3310 $ tar xf foo.tar '*.c'
3311 tar: Pattern matching characters used in file names. Please,
3312 tar: use --wildcards to enable pattern matching, or --no-wildcards to
3313 tar: suppress this warning.
3314 tar: *.c: Not found in archive
3315 tar: Error exit delayed from previous errors
3317 To treat member names as globbing patterns, use the `--wildcards'
3318 option. If you want to tar to mimic the behavior of versions
3319 prior to 1.15.91, add this option to your `TAR_OPTIONS' variable.
3321 *Note wildcards::, for the detailed discussion of the use of
3322 globbing patterns by GNU `tar'.
3324 Use of short option `-o'.
3325 Earlier versions of GNU `tar' understood `-o' command line option
3326 as a synonym for `--old-archive'.
3328 GNU `tar' starting from version 1.13.90 understands this option as
3329 a synonym for `--no-same-owner'. This is compatible with UNIX98
3330 `tar' implementations.
3332 However, to facilitate transition, `-o' option retains its old
3333 semantics when it is used with one of archive-creation commands.
3334 Users are encouraged to use `--format=oldgnu' instead.
3336 It is especially important, since versions of GNU Automake up to
3337 and including 1.8.4 invoke tar with this option to produce
3338 distribution tarballs. *Note v7: Formats, for the detailed
3339 discussion of this issue and its implications.
3341 *Note tar-formats: (automake)Options, for a description on how to
3342 use various archive formats with `automake'.
3344 Future versions of GNU `tar' will understand `-o' only as a
3345 synonym for `--no-same-owner'.
3347 Use of short option `-l'
3348 Earlier versions of GNU `tar' understood `-l' option as a synonym
3349 for `--one-file-system'. Since such usage contradicted to UNIX98
3350 specification and harmed compatibility with other implementations,
3351 it was declared deprecated in version 1.14. However, to
3352 facilitate transition to its new semantics, it was supported by
3353 versions 1.15 and 1.15.90. The present use of `-l' as a short
3354 variant of `--check-links' was introduced in version 1.15.91.
3356 Use of options `--portability' and `--old-archive'
3357 These options are deprecated. Please use `--format=v7' instead.
3359 Use of option `--posix'
3360 This option is deprecated. Please use `--format=posix' instead.
3363 File: tar.info, Node: Configuring Help Summary, Next: Fixing Snapshot Files, Prev: Changes, Up: Top
3365 Appendix B Configuring Help Summary
3366 ***********************************
3368 Running `tar --help' displays the short `tar' option summary (*note
3369 help::). This summary is organized by "groups" of semantically close
3370 options. The options within each group are printed in the following
3371 order: a short option, eventually followed by a list of corresponding
3372 long option names, followed by a short description of the option. For
3373 example, here is an excerpt from the actual `tar --help' output:
3375 Main operation mode:
3377 -A, --catenate, --concatenate append tar files to an archive
3378 -c, --create create a new archive
3379 -d, --diff, --compare find differences between archive and
3381 --delete delete from the archive
3383 The exact visual representation of the help output is configurable
3384 via `ARGP_HELP_FMT' environment variable. The value of this variable is
3385 a comma-separated list of "format variable" assignments. There are two
3386 kinds of format variables. An "offset variable" keeps the offset of
3387 some part of help output text from the leftmost column on the screen. A
3388 "boolean" variable is a flag that toggles some output feature on or
3389 off. Depending on the type of the corresponding variable, there are two
3390 kinds of assignments:
3393 The assignment to an offset variable has the following syntax:
3397 where VARIABLE is the variable name, and VALUE is a numeric value
3398 to be assigned to the variable.
3401 To assign `true' value to a variable, simply put this variable
3402 name. To assign `false' value, prefix the variable name with
3405 # Assign `true' value:
3407 # Assign `false' value:
3410 Following variables are declared:
3412 -- Help Output: boolean dup-args
3413 If true, arguments for an option are shown with both short and long
3414 options, even when a given option has both forms, for example:
3416 -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
3418 If false, then if an option has both short and long forms, the
3419 argument is only shown with the long one, for example:
3421 -f, --file=ARCHIVE use archive file or device ARCHIVE
3423 and a message indicating that the argument is applicable to both
3424 forms is printed below the options. This message can be disabled
3425 using `dup-args-note' (see below).
3427 The default is false.
3429 -- Help Output: boolean dup-args-note
3430 If this variable is true, which is the default, the following
3431 notice is displayed at the end of the help output:
3433 Mandatory or optional arguments to long options are also
3434 mandatory or optional for any corresponding short options.
3436 Setting `no-dup-args-note' inhibits this message. Normally, only
3437 one of variables `dup-args' or `dup-args-note' should be set.
3439 -- Help Output: offset short-opt-col
3440 Column in which short options start. Default is 2.
3442 $ tar --help|grep ARCHIVE
3443 -f, --file=ARCHIVE use archive file or device ARCHIVE
3444 $ ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE
3445 -f, --file=ARCHIVE use archive file or device ARCHIVE
3447 -- Help Output: offset long-opt-col
3448 Column in which long options start. Default is 6. For example:
3450 $ tar --help|grep ARCHIVE
3451 -f, --file=ARCHIVE use archive file or device ARCHIVE
3452 $ ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE
3453 -f, --file=ARCHIVE use archive file or device ARCHIVE
3455 -- Help Output: offset doc-opt-col
3456 Column in which "doc options" start. A doc option isn't actually
3457 an option, but rather an arbitrary piece of documentation that is
3458 displayed in much the same manner as the options. For example, in
3459 the description of `--format' option:
3461 -H, --format=FORMAT create archive of the given format.
3463 FORMAT is one of the following:
3465 gnu GNU tar 1.13.x format
3466 oldgnu GNU format as per tar <= 1.12
3467 pax POSIX 1003.1-2001 (pax) format
3469 ustar POSIX 1003.1-1988 (ustar) format
3470 v7 old V7 tar format
3472 the format names are doc options. Thus, if you set
3473 `ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output
3474 will look as follows:
3476 -H, --format=FORMAT create archive of the given format.
3478 FORMAT is one of the following:
3480 gnu GNU tar 1.13.x format
3481 oldgnu GNU format as per tar <= 1.12
3482 pax POSIX 1003.1-2001 (pax) format
3484 ustar POSIX 1003.1-1988 (ustar) format
3485 v7 old V7 tar format
3487 -- Help Output: offset opt-doc-col
3488 Column in which option description starts. Default is 29.
3490 $ tar --help|grep ARCHIVE
3491 -f, --file=ARCHIVE use archive file or device ARCHIVE
3492 $ ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE
3493 -f, --file=ARCHIVE use archive file or device ARCHIVE
3494 $ ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE
3496 use archive file or device ARCHIVE
3498 Notice, that the description starts on a separate line if
3499 `opt-doc-col' value is too small.
3501 -- Help Output: offset header-col
3502 Column in which "group headers" are printed. A group header is a
3503 descriptive text preceding an option group. For example, in the
3506 Main operation mode:
3508 -A, --catenate, --concatenate append tar files to
3510 -c, --create create a new archive
3511 `Main operation mode:' is the group header.
3513 The default value is 1.
3515 -- Help Output: offset usage-indent
3516 Indentation of wrapped usage lines. Affects `--usage' output.
3519 -- Help Output: offset rmargin
3520 Right margin of the text output. Used for wrapping.
3523 File: tar.info, Node: Fixing Snapshot Files, Next: Tar Internals, Prev: Configuring Help Summary, Up: Top
3525 Appendix C Fixing Snapshot Files
3526 ********************************
3528 Various situations can cause device numbers to change: upgrading your
3529 kernel version, reconfiguring your hardware, loading kernel modules in a
3530 different order, using virtual volumes that are assembled dynamically
3531 (such as with LVM or RAID), hot-plugging drives (e.g. external USB or
3532 Firewire drives), etc. In the majority of cases this change is
3533 unnoticed by the users. However, it influences `tar' incremental
3534 backups: the device number is stored in tar snapshot files (*note
3535 Snapshot Files::) and is used to determine whether the file has changed
3536 since the last backup. If the device numbers change for some reason,
3537 by default the next backup you run will be a full backup.
3539 To minimize the impact in these cases, GNU `tar' comes with the
3540 `tar-snapshot-edit' utility for inspecting and updating device numbers
3541 in snapshot files. (The utility, written by Dustin J. Mitchell, is
3542 also available from the GNU `tar' home page
3543 (http://www.gnu.org/software/tar/utils/tar-snapshot-edit.html).)
3545 To obtain a summary of the device numbers found in the snapshot
3548 $ tar-snapshot-edit SNAPFILE
3550 where SNAPFILE is the name of the snapshot file (you can supply as many
3551 files as you wish in a single command line). You can then compare the
3552 numbers across snapshot files, or against those currently in use on the
3553 live filesystem (using `ls -l' or `stat').
3555 Assuming the device numbers have indeed changed, it's often possible
3556 to simply tell GNU `tar' to ignore the device number when processing the
3557 incremental snapshot files for these backups, using the
3558 `--no-check-device' option (*note device numbers::).
3560 Alternatively, you can use the `tar-edit-snapshot' script's `-r'
3561 option to update all occurrences of the given device number in the
3562 snapshot file(s). It takes a single argument of the form
3563 `OLDDEV-NEWDEV', where OLDDEV is the device number used in the
3564 snapshot file, and NEWDEV is the corresponding new device number. Both
3565 numbers may be specified in hex (e.g., `0xfe01'), decimal (e.g.,
3566 `65025'), or as a major:minor number pair (e.g., `254:1'). To change
3567 several device numbers at once, specify them in a single
3568 comma-separated list, as in `-r 0x3060-0x4500,0x307-0x4600'.
3570 Before updating the snapshot file, it is a good idea to create a
3571 backup copy of it. This is accomplished by `-b' option. The name of
3572 the backup file is obtained by appending `~' to the original file name.
3575 $ tar-snapshot-edit root_snap.0 boot_snap.0
3577 Detected snapshot file version: 2
3579 Device 0x0000 occurs 1 times.
3580 Device 0x0003 occurs 1 times.
3581 Device 0x0005 occurs 1 times.
3582 Device 0x0013 occurs 1 times.
3583 Device 0x6801 occurs 1 times.
3584 Device 0x6803 occurs 6626 times.
3585 Device 0xfb00 occurs 1 times.
3588 Detected snapshot file version: 2
3590 Device 0x6801 occurs 3 times.
3591 $ tar-snapshot-edit -b -r 0x6801-0x6901,0x6803-0x6903 root_snap.0 boot_snap.0
3593 Detected snapshot file version: 2
3595 Updated 6627 records.
3598 Detected snapshot file version: 2
3603 File: tar.info, Node: Tar Internals, Next: Genfile, Prev: Fixing Snapshot Files, Up: Top
3605 Appendix D Tar Internals
3606 ************************
3610 * Standard:: Basic Tar Format
3611 * Extensions:: GNU Extensions to the Archive Format
3612 * Sparse Formats:: Storing Sparse Files
3617 File: tar.info, Node: Standard, Next: Extensions, Up: Tar Internals
3622 _(This message will disappear, once this node revised.)_
3624 While an archive may contain many files, the archive itself is a single
3625 ordinary file. Like any other file, an archive file can be written to
3626 a storage device such as a tape or disk, sent through a pipe or over a
3627 network, saved on the active file system, or even stored in another
3628 archive. An archive file is not easy to read or manipulate without
3629 using the `tar' utility or Tar mode in GNU Emacs.
3631 Physically, an archive consists of a series of file entries
3632 terminated by an end-of-archive entry, which consists of two 512 blocks
3633 of zero bytes. A file entry usually describes one of the files in the
3634 archive (an "archive member"), and consists of a file header and the
3635 contents of the file. File headers contain file names and statistics,
3636 checksum information which `tar' uses to detect file corruption, and
3637 information about file types.
3639 Archives are permitted to have more than one member with the same
3640 member name. One way this situation can occur is if more than one
3641 version of a file has been stored in the archive. For information
3642 about adding new versions of a file to an archive, see *note update::.
3644 In addition to entries describing archive members, an archive may
3645 contain entries which `tar' itself uses to store information. *Note
3646 label::, for an example of such an archive entry.
3648 A `tar' archive file contains a series of blocks. Each block
3649 contains `BLOCKSIZE' bytes. Although this format may be thought of as
3650 being on magnetic tape, other media are often used.
3652 Each file archived is represented by a header block which describes
3653 the file, followed by zero or more blocks which give the contents of
3654 the file. At the end of the archive file there are two 512-byte blocks
3655 filled with binary zeros as an end-of-file marker. A reasonable system
3656 should write such end-of-file marker at the end of an archive, but must
3657 not assume that such a block exists when reading an archive. In
3658 particular GNU `tar' always issues a warning if it does not encounter
3661 The blocks may be "blocked" for physical I/O operations. Each
3662 record of N blocks (where N is set by the `--blocking-factor=512-SIZE'
3663 (`-b 512-SIZE') option to `tar') is written with a single `write ()'
3664 operation. On magnetic tapes, the result of such a write is a single
3665 record. When writing an archive, the last record of blocks should be
3666 written at the full size, with blocks after the zero block containing
3667 all zeros. When reading an archive, a reasonable system should
3668 properly handle an archive whose last record is shorter than the rest,
3669 or which contains garbage records after a zero block.
3671 The header block is defined in C as follows. In the GNU `tar'
3672 distribution, this is part of file `src/tar.h':
3675 /* tar Header Block, from POSIX 1003.1-1990. */
3681 char name[100]; /* 0 */
3682 char mode[8]; /* 100 */
3683 char uid[8]; /* 108 */
3684 char gid[8]; /* 116 */
3685 char size[12]; /* 124 */
3686 char mtime[12]; /* 136 */
3687 char chksum[8]; /* 148 */
3688 char typeflag; /* 156 */
3689 char linkname[100]; /* 157 */
3690 char magic[6]; /* 257 */
3691 char version[2]; /* 263 */
3692 char uname[32]; /* 265 */
3693 char gname[32]; /* 297 */
3694 char devmajor[8]; /* 329 */
3695 char devminor[8]; /* 337 */
3696 char prefix[155]; /* 345 */
3700 #define TMAGIC "ustar" /* ustar and a null */
3702 #define TVERSION "00" /* 00 and no null */
3705 /* Values used in typeflag field. */
3706 #define REGTYPE '0' /* regular file */
3707 #define AREGTYPE '\0' /* regular file */
3708 #define LNKTYPE '1' /* link */
3709 #define SYMTYPE '2' /* reserved */
3710 #define CHRTYPE '3' /* character special */
3711 #define BLKTYPE '4' /* block special */
3712 #define DIRTYPE '5' /* directory */
3713 #define FIFOTYPE '6' /* FIFO special */
3714 #define CONTTYPE '7' /* reserved */
3716 #define XHDTYPE 'x' /* Extended header referring to the
3717 next file in the archive */
3718 #define XGLTYPE 'g' /* Global extended header */
3720 /* Bits used in the mode field, values in octal. */
3721 #define TSUID 04000 /* set UID on execution */
3722 #define TSGID 02000 /* set GID on execution */
3723 #define TSVTX 01000 /* reserved */
3724 /* file permissions */
3725 #define TUREAD 00400 /* read by owner */
3726 #define TUWRITE 00200 /* write by owner */
3727 #define TUEXEC 00100 /* execute/search by owner */
3728 #define TGREAD 00040 /* read by group */
3729 #define TGWRITE 00020 /* write by group */
3730 #define TGEXEC 00010 /* execute/search by group */
3731 #define TOREAD 00004 /* read by other */
3732 #define TOWRITE 00002 /* write by other */
3733 #define TOEXEC 00001 /* execute/search by other */
3735 /* tar Header Block, GNU extensions. */
3737 /* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for
3738 contiguous files, so maybe disobeying the "reserved" comment in POSIX
3739 header description. I suspect these were meant to be used this way, and
3740 should not have really been "reserved" in the published standards. */
3742 /* *BEWARE* *BEWARE* *BEWARE* that the following information is still
3743 boiling, and may change. Even if the OLDGNU format description should be
3744 accurate, the so-called GNU format is not yet fully decided. It is
3745 surely meant to use only extensions allowed by POSIX, but the sketch
3746 below repeats some ugliness from the OLDGNU format, which should rather
3747 go away. Sparse files should be saved in such a way that they do *not*
3748 require two passes at archive creation time. Huge files get some POSIX
3749 fields to overflow, alternate solutions have to be sought for this. */
3751 /* Descriptor for a single file hole. */
3755 char offset[12]; /* 0 */
3756 char numbytes[12]; /* 12 */
3760 /* Sparse files are not supported in POSIX ustar format. For sparse files
3761 with a POSIX header, a GNU extra header is provided which holds overall
3762 sparse information and a few sparse descriptors. When an old GNU header
3763 replaces both the POSIX header and the GNU extra header, it holds some
3764 sparse descriptors too. Whether POSIX or not, if more sparse descriptors
3765 are still needed, they are put into as many successive sparse headers as
3766 necessary. The following constants tell how many sparse descriptors fit
3767 in each kind of header able to hold them. */
3769 #define SPARSES_IN_EXTRA_HEADER 16
3770 #define SPARSES_IN_OLDGNU_HEADER 4
3771 #define SPARSES_IN_SPARSE_HEADER 21
3773 /* Extension header for sparse files, used immediately after the GNU extra
3774 header, and used only if all sparse information cannot fit into that
3775 extra header. There might even be many such extension headers, one after
3776 the other, until all sparse information has been recorded. */
3778 struct sparse_header
3780 struct sparse sp[SPARSES_IN_SPARSE_HEADER];
3782 char isextended; /* 504 */
3786 /* The old GNU format header conflicts with POSIX format in such a way that
3787 POSIX archives may fool old GNU tar's, and POSIX tar's might well be
3788 fooled by old GNU tar archives. An old GNU format header uses the space
3789 used by the prefix field in a POSIX header, and cumulates information
3790 normally found in a GNU extra header. With an old GNU tar header, we
3791 never see any POSIX header nor GNU extra header. Supplementary sparse
3792 headers are allowed, however. */
3794 struct oldgnu_header
3796 char unused_pad1[345]; /* 0 */
3797 char atime[12]; /* 345 Incr. archive: atime of the file */
3798 char ctime[12]; /* 357 Incr. archive: ctime of the file */
3799 char offset[12]; /* 369 Multivolume archive: the offset of
3800 the start of this volume */
3801 char longnames[4]; /* 381 Not used */
3802 char unused_pad2; /* 385 */
3803 struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
3805 char isextended; /* 482 Sparse file: Extension sparse header
3807 char realsize[12]; /* 483 Sparse file: Real size*/
3811 /* OLDGNU_MAGIC uses both magic and version fields, which are contiguous.
3812 Found in an archive, it indicates an old GNU header format, which will be
3813 hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are
3814 valid, though the header is not truly POSIX conforming. */
3815 #define OLDGNU_MAGIC "ustar " /* 7 chars and a null */
3817 /* The standards committee allows only capital A through capital Z for
3818 user-defined expansion. Other letters in use include:
3820 'A' Solaris Access Control List
3821 'E' Solaris Extended Attribute File
3822 'I' Inode only, as in 'star'
3823 'N' Obsolete GNU tar, for file names that do not fit into the main header.
3824 'X' POSIX 1003.1-2001 eXtended (VU version) */
3826 /* This is a dir entry that contains the names of files that were in the
3827 dir at the time the dump was made. */
3828 #define GNUTYPE_DUMPDIR 'D'
3830 /* Identifies the *next* file on the tape as having a long linkname. */
3831 #define GNUTYPE_LONGLINK 'K'
3833 /* Identifies the *next* file on the tape as having a long name. */
3834 #define GNUTYPE_LONGNAME 'L'
3836 /* This is the continuation of a file that began on another volume. */
3837 #define GNUTYPE_MULTIVOL 'M'
3839 /* This is for sparse files. */
3840 #define GNUTYPE_SPARSE 'S'
3842 /* This file is a tape/volume header. Ignore it on extraction. */
3843 #define GNUTYPE_VOLHDR 'V'
3845 /* Solaris extended header */
3846 #define SOLARIS_XHDTYPE 'X'
3848 /* Jo"rg Schilling star header */
3852 char name[100]; /* 0 */
3853 char mode[8]; /* 100 */
3854 char uid[8]; /* 108 */
3855 char gid[8]; /* 116 */
3856 char size[12]; /* 124 */
3857 char mtime[12]; /* 136 */
3858 char chksum[8]; /* 148 */
3859 char typeflag; /* 156 */
3860 char linkname[100]; /* 157 */
3861 char magic[6]; /* 257 */
3862 char version[2]; /* 263 */
3863 char uname[32]; /* 265 */
3864 char gname[32]; /* 297 */
3865 char devmajor[8]; /* 329 */
3866 char devminor[8]; /* 337 */
3867 char prefix[131]; /* 345 */
3868 char atime[12]; /* 476 */
3869 char ctime[12]; /* 488 */
3873 #define SPARSES_IN_STAR_HEADER 4
3874 #define SPARSES_IN_STAR_EXT_HEADER 21
3876 struct star_in_header
3878 char fill[345]; /* 0 Everything that is before t_prefix */
3879 char prefix[1]; /* 345 t_name prefix */
3880 char fill2; /* 346 */
3881 char fill3[8]; /* 347 */
3882 char isextended; /* 355 */
3883 struct sparse sp[SPARSES_IN_STAR_HEADER]; /* 356 */
3884 char realsize[12]; /* 452 Actual size of the file */
3885 char offset[12]; /* 464 Offset of multivolume contents */
3886 char atime[12]; /* 476 */
3887 char ctime[12]; /* 488 */
3888 char mfill[8]; /* 500 */
3889 char xmagic[4]; /* 508 "tar" */
3892 struct star_ext_header
3894 struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
3898 All characters in header blocks are represented by using 8-bit
3899 characters in the local variant of ASCII. Each field within the
3900 structure is contiguous; that is, there is no padding used within the
3901 structure. Each character on the archive medium is stored contiguously.
3903 Bytes representing the contents of files (after the header block of
3904 each file) are not translated in any way and are not constrained to
3905 represent characters in any character set. The `tar' format does not
3906 distinguish text files from binary files, and no translation of file
3907 contents is performed.
3909 The `name', `linkname', `magic', `uname', and `gname' are
3910 null-terminated character strings. All other fields are zero-filled
3911 octal numbers in ASCII. Each numeric field of width W contains W minus
3912 1 digits, and a null.
3914 The `name' field is the file name of the file, with directory names
3915 (if any) preceding the file name, separated by slashes.
3917 The `mode' field provides nine bits specifying file permissions and
3918 three bits to specify the Set UID, Set GID, and Save Text ("sticky")
3919 modes. Values for these bits are defined above. When special
3920 permissions are required to create a file with a given mode, and the
3921 user restoring files from the archive does not hold such permissions,
3922 the mode bit(s) specifying those special permissions are ignored.
3923 Modes which are not supported by the operating system restoring files
3924 from the archive will be ignored. Unsupported modes should be faked up
3925 when creating or updating an archive; e.g., the group permission could
3926 be copied from the _other_ permission.
3928 The `uid' and `gid' fields are the numeric user and group ID of the
3929 file owners, respectively. If the operating system does not support
3930 numeric user or group IDs, these fields should be ignored.
3932 The `size' field is the size of the file in bytes; linked files are
3933 archived with this field specified as zero.
3935 The `mtime' field is the data modification time of the file at the
3936 time it was archived. It is the ASCII representation of the octal
3937 value of the last time the file's contents were modified, represented
3938 as an integer number of seconds since January 1, 1970, 00:00
3939 Coordinated Universal Time.
3941 The `chksum' field is the ASCII representation of the octal value of
3942 the simple sum of all bytes in the header block. Each 8-bit byte in
3943 the header is added to an unsigned integer, initialized to zero, the
3944 precision of which shall be no less than seventeen bits. When
3945 calculating the checksum, the `chksum' field is treated as if it were
3948 The `typeflag' field specifies the type of file archived. If a
3949 particular implementation does not recognize or permit the specified
3950 type, the file will be extracted as if it were a regular file. As this
3951 action occurs, `tar' issues a warning to the standard error.
3953 The `atime' and `ctime' fields are used in making incremental
3954 backups; they store, respectively, the particular file's access and
3955 status change times.
3957 The `offset' is used by the `--multi-volume' (`-M') option, when
3958 making a multi-volume archive. The offset is number of bytes into the
3959 file that we need to restart at to continue the file on the next tape,
3960 i.e., where we store the location that a continued file is continued at.
3962 The following fields were added to deal with sparse files. A file
3963 is "sparse" if it takes in unallocated blocks which end up being
3964 represented as zeros, i.e., no useful data. A test to see if a file is
3965 sparse is to look at the number blocks allocated for it versus the
3966 number of characters in the file; if there are fewer blocks allocated
3967 for the file than would normally be allocated for a file of that size,
3968 then the file is sparse. This is the method `tar' uses to detect a
3969 sparse file, and once such a file is detected, it is treated
3970 differently from non-sparse files.
3972 Sparse files are often `dbm' files, or other database-type files
3973 which have data at some points and emptiness in the greater part of the
3974 file. Such files can appear to be very large when an `ls -l' is done
3975 on them, when in truth, there may be a very small amount of important
3976 data contained in the file. It is thus undesirable to have `tar' think
3977 that it must back up this entire file, as great quantities of room are
3978 wasted on empty blocks, which can lead to running out of room on a tape
3979 far earlier than is necessary. Thus, sparse files are dealt with so
3980 that these empty blocks are not written to the tape. Instead, what is
3981 written to the tape is a description, of sorts, of the sparse file:
3982 where the holes are, how big the holes are, and how much data is found
3983 at the end of the hole. This way, the file takes up potentially far
3984 less room on the tape, and when the file is extracted later on, it will
3985 look exactly the way it looked beforehand. The following is a
3986 description of the fields used to handle a sparse file:
3988 The `sp' is an array of `struct sparse'. Each `struct sparse'
3989 contains two 12-character strings which represent an offset into the
3990 file and a number of bytes to be written at that offset. The offset is
3991 absolute, and not relative to the offset in preceding array element.
3993 The header can hold four of these `struct sparse' at the moment; if
3994 more are needed, they are not stored in the header.
3996 The `isextended' flag is set when an `extended_header' is needed to
3997 deal with a file. Note that this means that this flag can only be set
3998 when dealing with a sparse file, and it is only set in the event that
3999 the description of the file will not fit in the allotted room for
4000 sparse structures in the header. In other words, an extended_header is
4003 The `extended_header' structure is used for sparse files which need
4004 more sparse structures than can fit in the header. The header can fit
4005 4 such structures; if more are needed, the flag `isextended' gets set
4006 and the next block is an `extended_header'.
4008 Each `extended_header' structure contains an array of 21 sparse
4009 structures, along with a similar `isextended' flag that the header had.
4010 There can be an indeterminate number of such `extended_header's to
4011 describe a sparse file.
4015 These flags represent a regular file. In order to be compatible
4016 with older versions of `tar', a `typeflag' value of `AREGTYPE'
4017 should be silently recognized as a regular file. New archives
4018 should be created using `REGTYPE'. Also, for backward
4019 compatibility, `tar' treats a regular file whose name ends with a
4020 slash as a directory.
4023 This flag represents a file linked to another file, of any type,
4024 previously archived. Such files are identified in Unix by each
4025 file having the same device and inode number. The linked-to name
4026 is specified in the `linkname' field with a trailing null.
4029 This represents a symbolic link to another file. The linked-to
4030 name is specified in the `linkname' field with a trailing null.
4034 These represent character special files and block special files
4035 respectively. In this case the `devmajor' and `devminor' fields
4036 will contain the major and minor device numbers respectively.
4037 Operating systems may map the device specifications to their own
4038 local specification, or may ignore the entry.
4041 This flag specifies a directory or sub-directory. The directory
4042 name in the `name' field should end with a slash. On systems where
4043 disk allocation is performed on a directory basis, the `size' field
4044 will contain the maximum number of bytes (which may be rounded to
4045 the nearest disk block allocation unit) which the directory may
4046 hold. A `size' field of zero indicates no such limiting. Systems
4047 which do not support limiting in this manner should ignore the
4051 This specifies a FIFO special file. Note that the archiving of a
4052 FIFO file archives the existence of this file and not its contents.
4055 This specifies a contiguous file, which is the same as a normal
4056 file except that, in operating systems which support it, all its
4057 space is allocated contiguously on the disk. Operating systems
4058 which do not allow contiguous allocation should silently treat this
4059 type as a normal file.
4062 These are reserved for custom implementations. Some of these are
4063 used in the GNU modified format, as described below.
4066 Other values are reserved for specification in future revisions of
4067 the P1003 standard, and should not be used by any `tar' program.
4069 The `magic' field indicates that this archive was output in the
4070 P1003 archive format. If this field contains `TMAGIC', the `uname' and
4071 `gname' fields will contain the ASCII representation of the owner and
4072 group of the file respectively. If found, the user and group IDs are
4073 used rather than the values in the `uid' and `gid' fields.
4075 For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990,
4076 pages 169-173 (section 10.1) for `Archive/Interchange File Format'; and
4077 IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
4078 (section E.4.48) for `pax - Portable archive interchange'.
4081 File: tar.info, Node: Extensions, Next: Sparse Formats, Prev: Standard, Up: Tar Internals
4083 GNU Extensions to the Archive Format
4084 ====================================
4086 _(This message will disappear, once this node revised.)_
4088 The GNU format uses additional file types to describe new types of
4089 files in an archive. These are listed below.
4093 This represents a directory and a list of files created by the
4094 `--incremental' (`-G') option. The `size' field gives the total
4095 size of the associated list of files. Each file name is preceded
4096 by either a `Y' (the file should be in this archive) or an `N'.
4097 (The file is a directory, or is not stored in the archive.) Each
4098 file name is terminated by a null. There is an additional null
4099 after the last file name.
4103 This represents a file continued from another volume of a
4104 multi-volume archive created with the `--multi-volume' (`-M')
4105 option. The original type of the file is not given here. The
4106 `size' field gives the maximum size of this piece of the file
4107 (assuming the volume does not end before the file is written out).
4108 The `offset' field gives the offset from the beginning of the file
4109 where this part of the file begins. Thus `size' plus `offset'
4110 should equal the original size of the file.
4114 This flag indicates that we are dealing with a sparse file. Note
4115 that archiving a sparse file requires special operations to find
4116 holes in the file, which mark the positions of these holes, along
4117 with the number of bytes of data to be found after the hole.
4121 This file type is used to mark the volume header that was given
4122 with the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') option when
4123 the archive was created. The `name' field contains the `name'
4124 given after the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL')
4125 option. The `size' field is zero. Only the first file in each
4126 volume of an archive should have this type.
4129 You may have trouble reading a GNU format archive on a non-GNU
4130 system if the options `--incremental' (`-G'), `--multi-volume' (`-M'),
4131 `--sparse' (`-S'), or `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') were
4132 used when writing the archive. In general, if `tar' does not use the
4133 GNU-added fields of the header, other versions of `tar' should be able
4134 to read the archive. Otherwise, the `tar' program will give an error,
4135 the most likely one being a checksum error.
4138 File: tar.info, Node: Sparse Formats, Next: Snapshot Files, Prev: Extensions, Up: Tar Internals
4140 Storing Sparse Files
4141 ====================
4143 The notion of sparse file, and the ways of handling it from the point
4144 of view of GNU `tar' user have been described in detail in *note
4145 sparse::. This chapter describes the internal format GNU `tar' uses to
4148 The support for sparse files in GNU `tar' has a long history. The
4149 earliest version featuring this support that I was able to find was
4150 1.09, released in November, 1990. The format introduced back then is
4151 called "old GNU" sparse format and in spite of the fact that its design
4152 contained many flaws, it was the only format GNU `tar' supported until
4153 version 1.14 (May, 2004), which introduced initial support for sparse
4154 archives in PAX archives (*note posix::). This format was not free
4155 from design flaws, either and it was subsequently improved in versions
4156 1.15.2 (November, 2005) and 1.15.92 (June, 2006).
4158 In addition to GNU sparse format, GNU `tar' is able to read and
4159 extract sparse files archived by `star'.
4161 The following subsections describe each format in detail.
4166 * PAX 0:: PAX Format, Versions 0.0 and 0.1
4167 * PAX 1:: PAX Format, Version 1.0
4170 File: tar.info, Node: Old GNU Format, Next: PAX 0, Up: Sparse Formats
4172 D.0.1 Old GNU Format
4173 --------------------
4175 The format introduced in November 1990 (v. 1.09) was designed on top of
4176 standard `ustar' headers in such an unfortunate way that some of its
4177 fields overwrote fields required by POSIX.
4179 An old GNU sparse header is designated by type `S'
4180 (`GNUTYPE_SPARSE') and has the following layout:
4182 Offset Size Name Data type Contents
4183 ----------------------------------------------------------------------------
4185 345 12 atime Number `atime' of the file.
4186 357 12 ctime Number `ctime' of the file .
4187 369 12 offset Number For multivolume archives:
4188 the offset of the start of
4192 386 96 sp `sparse_header'(4 entries) File map.
4193 482 1 isextended Bool `1' if an extension sparse
4196 483 12 realsize Number Real size of the file.
4198 Each of `sparse_header' object at offset 386 describes a single data
4199 chunk. It has the following structure:
4201 Offset Size Data type Contents
4202 ---------------------------------------------------------------------------
4203 0 12 Number Offset of the beginning of the chunk.
4204 12 12 Number Size of the chunk.
4206 If the member contains more than four chunks, the `isextended' field
4207 of the header has the value `1' and the main header is followed by one
4208 or more "extension headers". Each such header has the following
4211 Offset Size Name Data type Contents
4212 ----------------------------------------------------------------------------
4213 0 21 sp `sparse_header' (21 entries) File map.
4214 504 1 isextended Bool `1' if an extension sparse
4215 header follows, or `0'
4218 A header with `isextended=0' ends the map.
4221 File: tar.info, Node: PAX 0, Next: PAX 1, Prev: Old GNU Format, Up: Sparse Formats
4223 D.0.2 PAX Format, Versions 0.0 and 0.1
4224 --------------------------------------
4226 There are two formats available in this branch. The version `0.0' is
4227 the initial version of sparse format used by `tar' versions
4228 1.14-1.15.1. The sparse file map is kept in extended (`x') PAX header
4232 Real size of the stored file;
4234 `GNU.sparse.numblocks'
4235 Number of blocks in the sparse map;
4238 Offset of the data block;
4240 `GNU.sparse.numbytes'
4241 Size of the data block.
4243 The latter two variables repeat for each data block, so the overall
4244 structure is like this:
4246 GNU.sparse.size=SIZE
4247 GNU.sparse.numblocks=NUMBLOCKS
4248 repeat NUMBLOCKS times
4249 GNU.sparse.offset=OFFSET
4250 GNU.sparse.numbytes=NUMBYTES
4253 This format presented the following two problems:
4255 1. Whereas the POSIX specification allows a variable to appear
4256 multiple times in a header, it requires that only the last
4257 occurrence be meaningful. Thus, multiple occurrences of
4258 `GNU.sparse.offset' and `GNU.sparse.numbytes' are conflicting with
4261 2. Attempting to extract such archives using a third-party's `tar'
4262 results in extraction of sparse files in _condensed form_. If the
4263 `tar' implementation in question does not support POSIX format, it
4264 will also extract a file containing extension header attributes.
4265 This file can be used to expand the file to its original state.
4266 However, posix-aware `tar's will usually ignore the unknown
4267 variables, which makes restoring the file more difficult. *Note
4268 Extraction of sparse members in v.0.0 format: extracting sparse
4269 v.0.x, for the detailed description of how to restore such members
4270 using non-GNU `tar's.
4272 GNU `tar' 1.15.2 introduced sparse format version `0.1', which
4273 attempted to solve these problems. As its predecessor, this format
4274 stores sparse map in the extended POSIX header. It retains
4275 `GNU.sparse.size' and `GNU.sparse.numblocks' variables, but instead of
4276 `GNU.sparse.offset'/`GNU.sparse.numbytes' pairs it uses a single
4280 Map of non-null data chunks. It is a string consisting of
4281 comma-separated values "OFFSET,SIZE[,OFFSET-1,SIZE-1...]"
4283 To address the 2nd problem, the `name' field in `ustar' is replaced
4284 with a special name, constructed using the following pattern:
4286 %d/GNUSparseFile.%p/%f
4288 The real name of the sparse file is stored in the variable
4289 `GNU.sparse.name'. Thus, those `tar' implementations that are not
4290 aware of GNU extensions will at least extract the files into separate
4291 directories, giving the user a possibility to expand it afterwards.
4292 *Note Extraction of sparse members in v.0.1 format: extracting sparse
4293 v.0.x, for the detailed description of how to restore such members
4294 using non-GNU `tar's.
4296 The resulting `GNU.sparse.map' string can be _very_ long. Although
4297 POSIX does not impose any limit on the length of a `x' header variable,
4298 this possibly can confuse some `tar's.
4301 File: tar.info, Node: PAX 1, Prev: PAX 0, Up: Sparse Formats
4303 D.0.3 PAX Format, Version 1.0
4304 -----------------------------
4306 The version `1.0' of sparse format was introduced with GNU `tar'
4307 1.15.92. Its main objective was to make the resulting file extractable
4308 with little effort even by non-posix aware `tar' implementations.
4309 Starting from this version, the extended header preceding a sparse
4310 member always contains the following variables that identify the format
4319 The `name' field in `ustar' header contains a special name,
4320 constructed using the following pattern:
4322 %d/GNUSparseFile.%p/%f
4324 The real name of the sparse file is stored in the variable
4325 `GNU.sparse.name'. The real size of the file is stored in the variable
4326 `GNU.sparse.realsize'.
4328 The sparse map itself is stored in the file data block, preceding
4329 the actual file data. It consists of a series of octal numbers of
4330 arbitrary length, delimited by newlines. The map is padded with nulls
4331 to the nearest block boundary.
4333 The first number gives the number of entries in the map. Following
4334 are map entries, each one consisting of two numbers giving the offset
4335 and size of the data block it describes.
4337 The format is designed in such a way that non-posix aware `tar's and
4338 `tar's not supporting `GNU.sparse.*' keywords will extract each sparse
4339 file in its condensed form with the file map prepended and will place it
4340 into a separate directory. Then, using a simple program it would be
4341 possible to expand the file to its original form even without GNU `tar'.
4342 *Note Sparse Recovery::, for the detailed information on how to extract
4343 sparse members without GNU `tar'.
4346 File: tar.info, Node: Snapshot Files, Next: Dumpdir, Prev: Sparse Formats, Up: Tar Internals
4348 Format of the Incremental Snapshot Files
4349 ========================================
4351 A "snapshot file" (or "directory file") is created during incremental
4352 backups (*note Incremental Dumps::). It contains the status of the
4353 file system at the time of the dump and is used to determine which
4354 files were modified since the last backup.
4356 GNU `tar' version 1.27 supports three snapshot file formats. The
4357 first format, called "format 0", is the one used by GNU `tar' versions
4358 up to and including 1.15.1. The second format, called "format 1" is an
4359 extended version of this format, that contains more metadata and allows
4360 for further extensions. It was used by alpha release version 1.15.90.
4361 For alpha version 1.15.91 and stable releases version 1.16 up through
4362 1.27, the "format 2" is used.
4364 GNU `tar' is able to read all three formats, but will create
4365 snapshots only in format 2.
4367 This appendix describes all three formats in detail.
4369 0. `Format 0' snapshot file begins with a line containing a decimal
4370 number that represents a UNIX timestamp of the beginning of the
4371 last archivation. This line is followed by directory metadata
4372 descriptions, one per line. Each description has the following
4380 A single plus character (`+'), if this directory is located on
4381 an NFS-mounted partition, otherwise empty.
4383 (That is, for non-NFS directories, the first character on the
4384 description line contains the start of the DEV field.)
4387 Device number of the directory;
4390 I-node number of the directory;
4393 Name of the directory. Any special characters (white-space,
4394 backslashes, etc.) are quoted.
4396 1. `Format 1' snapshot file begins with a line specifying the
4397 format of the file. This line has the following structure:
4399 `GNU tar-'TAR-VERSION`-'INCR-FORMAT-VERSION
4401 where TAR-VERSION is the version number of GNU `tar'
4402 implementation that created this snapshot, and INCR-FORMAT-VERSION
4403 is the version number of the snapshot format (in this case `1').
4405 Next line contains two decimal numbers, representing the time of
4406 the last backup. First number is the number of seconds, the second
4407 one is the number of nanoseconds, since the beginning of the epoch.
4409 Lines that follow contain directory metadata, one line per
4410 directory. Each line is formatted as follows:
4412 [NFS]MTIME-SEC MTIME-NSEC DEV INODE NAME
4414 where MTIME-SEC and MTIME-NSEC represent last modification time of
4415 this directory with nanosecond precision; NFS, DEV, INODE and NAME
4416 have the same meaning as with `format 0'.
4418 2. `Format 2' snapshot file begins with a format identifier, as
4419 described for version 1, e.g.:
4423 This line is followed by newline. Rest of file consists of
4424 records, separated by null (ASCII 0) characters. Thus, in contrast
4425 to the previous formats, format 2 snapshot is a binary file.
4427 First two records are decimal integers, representing the time of
4428 the last backup. First number is the number of seconds, the
4429 second one is the number of nanoseconds, since the beginning of the
4430 epoch. These are followed by arbitrary number of directory
4433 Each "directory record" contains a set of metadata describing a
4434 particular directory. Parts of a directory record are delimited
4435 with ASCII 0 characters. The following table describes each part.
4436 The "Number" type in this table stands for a decimal integer in
4437 ASCII notation. (Negative values are preceeded with a "-"
4438 character, while positive values have no leading punctuation.)
4440 Field Type Description
4441 ----------------------------------------------------------------------
4442 nfs Character `1' if the directory is located on an
4443 NFS-mounted partition, or `0' otherwise;
4444 timestamp_sec Number Modification time, seconds;
4445 timestamp_nsec Number Modification time, nanoseconds;
4446 dev Number Device number;
4447 ino Number I-node number;
4448 name String Directory name; in contrast to the
4449 previous versions it is not quoted;
4450 contents Dumpdir Contents of the directory; *Note
4451 Dumpdir::, for a description of its
4455 Dumpdirs stored in snapshot files contain only records of types
4458 The specific range of values allowed in each of the "Number" fields
4459 depends on the underlying C datatypes as determined when `tar' is
4460 compiled. To see the specific ranges allowed for a particular
4461 `tar' binary, you can use the `--show-snapshot-field-ranges'
4464 $ tar --show-shapshot-field-ranges
4465 This tar's snapshot file field ranges are
4466 (field name => [ min, max ]):
4469 timestamp_sec => [ -9223372036854775808, 9223372036854775807 ],
4470 timestamp_nsec => [ 0, 999999999 ],
4471 dev => [ 0, 18446744073709551615 ],
4472 ino => [ 0, 18446744073709551615 ],
4474 (This example is from a GNU/Linux x86_64 system.)
4478 File: tar.info, Node: Dumpdir, Prev: Snapshot Files, Up: Tar Internals
4483 Incremental archives keep information about contents of each dumped
4484 directory in special data blocks called "dumpdirs".
4486 Dumpdir is a sequence of entries of the following form:
4490 where C is one of the "control codes" described below, FILENAME is the
4491 name of the file C operates upon, and `\0' represents a nul character
4492 (ASCII 0). The white space characters were added for readability, real
4493 dumpdirs do not contain them.
4495 Each dumpdir ends with a single nul character.
4497 The following table describes control codes and their meanings:
4500 FILENAME is contained in the archive.
4503 FILENAME was present in the directory at the time the archive was
4504 made, yet it was not dumped to the archive, because it had not
4505 changed since the last backup.
4508 FILENAME is a directory.
4511 This code requests renaming of the FILENAME to the name specified
4512 with the `T' command, that immediately follows it.
4515 Specify target file name for `R' command (see below).
4518 Specify "temporary directory" name for a rename operation (see
4521 Codes `Y', `N' and `D' require FILENAME argument to be a relative
4522 file name to the directory this dumpdir describes, whereas codes `R',
4523 `T' and `X' require their argument to be an absolute file name.
4525 The three codes `R', `T' and `X' specify a "renaming operation". In
4526 the simplest case it is:
4528 R`source'\0T`dest'\0
4530 which means "rename file `source' to file `dest'".
4532 However, there are cases that require using a "temporary directory".
4533 For example, consider the following scenario:
4535 1. Previous run dumped a directory `foo' which contained the
4536 following three directories:
4542 2. They were renamed _cyclically_, so that:
4548 3. New incremental dump was made.
4550 This case cannot be handled by three successive renames, since
4551 renaming `a' to `b' will destroy the existing directory. To correctly
4552 process it, GNU `tar' needs a temporary directory, so it creates the
4553 following dumpdir (newlines have been added for readability):
4561 The first command, `Xfoo\0', instructs the extractor to create a
4562 temporary directory in the directory `foo'. Second command,
4563 `Rfoo/aT\0', says "rename file `foo/a' to the temporary directory that
4564 has just been created" (empty file name after a command means use
4565 temporary directory). Third and fourth commands work as usual, and,
4566 finally, the last command, `R\0Tfoo/a\0' tells tar to rename the
4567 temporary directory to `foo/a'.
4569 The exact placement of a dumpdir in the archive depends on the
4570 archive format (*note Formats::):
4574 In PAX archives, dumpdir is stored in the extended header of the
4575 corresponding directory, in variable `GNU.dumpdir'.
4577 * GNU and old GNU archives
4579 These formats implement special header type `D', which is similar
4580 to ustar header `5' (directory), except that it precedes a data
4581 block containing the dumpdir.
4584 File: tar.info, Node: Genfile, Next: Free Software Needs Free Documentation, Prev: Tar Internals, Up: Top
4589 This appendix describes `genfile', an auxiliary program used in the GNU
4590 tar testsuite. If you are not interested in developing GNU tar, skip
4593 Initially, `genfile' was used to generate data files for the
4594 testsuite, hence its name. However, new operation modes were being
4595 implemented as the testsuite grew more sophisticated, and now `genfile'
4596 is a multi-purpose instrument.
4598 There are three basic operation modes:
4601 This is the default mode. In this mode, `genfile' generates data
4605 In this mode `genfile' displays status of specified files.
4607 Synchronous Execution.
4608 In this mode `genfile' executes the given program with
4609 `--checkpoint' option and executes a set of actions when specified
4610 checkpoints are reached.
4614 * Generate Mode:: File Generation Mode.
4615 * Status Mode:: File Status Mode.
4616 * Exec Mode:: Synchronous Execution mode.
4619 File: tar.info, Node: Generate Mode, Next: Status Mode, Up: Genfile
4624 In this mode `genfile' creates a data file for the test suite. The size
4625 of the file is given with the `--length' (`-l') option. By default the
4626 file contents is written to the standard output, this can be changed
4627 using `--file' (`-f') command line option. Thus, the following two
4628 commands are equivalent:
4630 genfile --length 100 > outfile
4631 genfile --length 100 --file outfile
4633 If `--length' is not given, `genfile' will generate an empty
4636 The command line option `--seek=N' istructs `genfile' to skip the
4637 given number of bytes (N) in the output file before writing to it. It
4638 is similar to the `seek=N' of the `dd' utility.
4640 You can instruct `genfile' to create several files at one go, by
4641 giving it `--files-from' (`-T') option followed by a name of file
4642 containing a list of file names. Using dash (`-') instead of the file
4643 name causes `genfile' to read file list from the standard input. For
4646 # Read file names from file `file.list'
4647 genfile --files-from file.list
4648 # Read file names from standard input
4649 genfile --files-from -
4651 The list file is supposed to contain one file name per line. To use
4652 file lists separated by ASCII NUL character, use `--null' (`-0')
4653 command line option:
4655 genfile --null --files-from file.list
4657 The default data pattern for filling the generated file consists of
4658 first 256 letters of ASCII code, repeated enough times to fill the
4659 entire file. This behavior can be changed with `--pattern' option. This
4660 option takes a mandatory argument, specifying pattern name to use.
4661 Currently two patterns are implemented:
4664 The default pattern as described above.
4667 Fills the file with zeroes.
4669 If no file name was given, the program exits with the code `0'.
4670 Otherwise, it exits with `0' only if it was able to create a file of
4671 the specified length.
4673 Special option `--sparse' (`-s') instructs `genfile' to create a
4674 sparse file. Sparse files consist of "data fragments", separated by
4675 "holes" or blocks of zeros. On many operating systems, actual disk
4676 storage is not allocated for holes, but they are counted in the length
4677 of the file. To create a sparse file, `genfile' should know where to
4678 put data fragments, and what data to use to fill them. So, when
4679 `--sparse' is given the rest of the command line specifies a so-called
4682 The file map consists of any number of "fragment descriptors". Each
4683 descriptor is composed of two values: a number, specifying fragment
4684 offset from the end of the previous fragment or, for the very first
4685 fragment, from the beginning of the file, and "contents string", i.e.,
4686 a string of characters, specifying the pattern to fill the fragment
4687 with. File offset can be suffixed with the following quantifiers:
4691 The number is expressed in kilobytes.
4695 The number is expressed in megabytes.
4699 The number is expressed in gigabytes.
4701 For each letter in contents string `genfile' will generate a "block"
4702 of data, filled with this letter and will write it to the fragment. The
4703 size of block is given by `--block-size' option. It defaults to 512.
4704 Thus, if the string consists of N characters, the resulting file
4705 fragment will contain `N*BLOCK-SIZE' of data.
4707 Last fragment descriptor can have only file offset part. In this
4708 case `genfile' will create a hole at the end of the file up to the
4711 For example, consider the following invocation:
4713 genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K
4715 It will create 3101184-bytes long file of the following structure:
4717 Offset Length Contents
4718 0 4*512=2048 Four 512-byte blocks, filled
4719 with letters `A', `B', `C' and
4721 2048 1046528 Zero bytes
4722 1050624 5*512=2560 Five blocks, filled with letters
4723 `E', `F', `G', `H', `I'.
4724 1053184 2048000 Zero bytes
4726 The exit code of `genfile --status' command is `0' only if created
4727 file is actually sparse.
4730 File: tar.info, Node: Status Mode, Next: Exec Mode, Prev: Generate Mode, Up: Genfile
4735 In status mode, `genfile' prints file system status for each file
4736 specified in the command line. This mode is toggled by `--stat' (`-S')
4737 command line option. An optional argument to this option specifies
4738 output "format": a comma-separated list of `struct stat' fields to be
4739 displayed. This list can contain following identifiers:
4746 Device number in decimal.
4754 File mode in octal. Optional NUMBER specifies octal mask to be
4755 applied to the mode before outputting. For example, `--stat
4756 mode.777' will preserve lower nine bits of it. Notice, that you
4757 can use any punctuation character in place of `.'.
4761 Number of hard links.
4773 File size in decimal.
4777 The size in bytes of each file block.
4781 Number of blocks allocated.
4785 Time of last access.
4789 Time of last modification
4793 Time of last status change
4796 A boolean value indicating whether the file is `sparse'.
4798 Modification times are displayed in UTC as UNIX timestamps, unless
4799 suffixed with `H' (for "human-readable"), as in `ctimeH', in which case
4800 usual `tar tv' output format is used.
4802 The default output format is: `name,dev,ino,mode,
4803 nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime'.
4805 For example, the following command will display file names and
4806 corresponding times of last access for each file in the current working
4809 genfile --stat=name,atime *
4812 File: tar.info, Node: Exec Mode, Prev: Status Mode, Up: Genfile
4817 This mode is designed for testing the behavior of `paxutils' commands
4818 when some of the files change during archiving. It is an experimental
4821 The `Exec Mode' is toggled by `--run' command line option (or its
4822 alias `-r'). The non-optional arguments to `getopt' give the command
4823 line to be executed. Normally, it should contain at least the
4824 `--checkpoint' option.
4826 A set of options is provided for defining checkpoint values and
4827 actions to be executed upon reaching them. Checkpoint values are
4828 introduced with the `--checkpoint' command line option. Argument to
4829 this option is the number of checkpoint in decimal.
4831 Any number of "actions" may be specified after a checkpoint.
4832 Available actions are
4836 Truncate FILE to the size specified by previous `--length' option
4837 (or 0, if it is not given).
4840 Append data to FILE. The size of data and its pattern are given by
4841 previous `--length' and `pattern' options.
4844 Update the access and modification times of FILE. These timestamps
4845 are changed to the current time, unless `--date' option was given,
4846 in which case they are changed to the specified time. Argument to
4847 `--date' option is a date specification in an almost arbitrary
4848 format (*note Date input formats::).
4851 Execute given shell command.
4856 Option `--verbose' instructs `genfile' to print on standard output
4857 notifications about checkpoints being executed and to verbosely
4858 describe exit status of the command.
4860 While the command is being executed its standard output remains
4861 connected to descriptor 1. All messages it prints to file descriptor 2,
4862 except checkpoint notifications, are forwarded to standard error.
4864 `Genfile' exits with the exit status of the executed command.
4866 For compatibility with previous `genfile' versions, the `--run'
4867 option takes an optional argument. If used this way, its argument
4868 supplies the command line to be executed. There should be no
4869 non-optional arguments in the `genfile' command line.
4871 The actual command line is constructed by inserting the
4872 `--checkpoint' option between the command name and its first argument
4873 (if any). Due to this, the argument to `--run' may not use traditional
4874 `tar' option syntax, i.e., the following is wrong:
4877 genfile --run='tar cf foo bar'
4879 Use the following syntax instead:
4881 genfile --run='tar -cf foo bar' ACTIONS...
4883 The above command line is equivalent to
4885 genfile ACTIONS... -- tar -cf foo bar
4887 Notice, that the use of compatibility mode is deprecated.
4890 File: tar.info, Node: Free Software Needs Free Documentation, Next: GNU Free Documentation License, Prev: Genfile, Up: Top
4892 Appendix F Free Software Needs Free Documentation
4893 *************************************************
4895 The biggest deficiency in the free software community today is not in
4896 the software--it is the lack of good free documentation that we can
4897 include with the free software. Many of our most important programs do
4898 not come with free reference manuals and free introductory texts.
4899 Documentation is an essential part of any software package; when an
4900 important free software package does not come with a free manual and a
4901 free tutorial, that is a major gap. We have many such gaps today.
4903 Consider Perl, for instance. The tutorial manuals that people
4904 normally use are non-free. How did this come about? Because the
4905 authors of those manuals published them with restrictive terms--no
4906 copying, no modification, source files not available--which exclude
4907 them from the free software world.
4909 That wasn't the first time this sort of thing happened, and it was
4910 far from the last. Many times we have heard a GNU user eagerly
4911 describe a manual that he is writing, his intended contribution to the
4912 community, only to learn that he had ruined everything by signing a
4913 publication contract to make it non-free.
4915 Free documentation, like free software, is a matter of freedom, not
4916 price. The problem with the non-free manual is not that publishers
4917 charge a price for printed copies--that in itself is fine. (The Free
4918 Software Foundation sells printed copies of manuals, too.) The problem
4919 is the restrictions on the use of the manual. Free manuals are
4920 available in source code form, and give you permission to copy and
4921 modify. Non-free manuals do not allow this.
4923 The criteria of freedom for a free manual are roughly the same as for
4924 free software. Redistribution (including the normal kinds of
4925 commercial redistribution) must be permitted, so that the manual can
4926 accompany every copy of the program, both on-line and on paper.
4928 Permission for modification of the technical content is crucial too.
4929 When people modify the software, adding or changing features, if they
4930 are conscientious they will change the manual too--so they can provide
4931 accurate and clear documentation for the modified program. A manual
4932 that leaves you no choice but to write a new manual to document a
4933 changed version of the program is not really available to our community.
4935 Some kinds of limits on the way modification is handled are
4936 acceptable. For example, requirements to preserve the original
4937 author's copyright notice, the distribution terms, or the list of
4938 authors, are ok. It is also no problem to require modified versions to
4939 include notice that they were modified. Even entire sections that may
4940 not be deleted or changed are acceptable, as long as they deal with
4941 nontechnical topics (like this one). These kinds of restrictions are
4942 acceptable because they don't obstruct the community's normal use of
4945 However, it must be possible to modify all the _technical_ content
4946 of the manual, and then distribute the result in all the usual media,
4947 through all the usual channels. Otherwise, the restrictions obstruct
4948 the use of the manual, it is not free, and we need another manual to
4951 Please spread the word about this issue. Our community continues to
4952 lose manuals to proprietary publishing. If we spread the word that
4953 free software needs free reference manuals and free tutorials, perhaps
4954 the next person who wants to contribute by writing documentation will
4955 realize, before it is too late, that only free manuals contribute to
4956 the free software community.
4958 If you are writing documentation, please insist on publishing it
4959 under the GNU Free Documentation License or another free documentation
4960 license. Remember that this decision requires your approval--you don't
4961 have to let the publisher decide. Some commercial publishers will use
4962 a free license if you insist, but they will not propose the option; it
4963 is up to you to raise the issue and say firmly that this is what you
4964 want. If the publisher you are dealing with refuses, please try other
4965 publishers. If you're not sure whether a proposed license is free,
4966 write to <licensing@gnu.org>.
4968 You can encourage commercial publishers to sell more free, copylefted
4969 manuals and tutorials by buying them, and particularly by buying copies
4970 from the publishers that paid for their writing or for major
4971 improvements. Meanwhile, try to avoid buying non-free documentation at
4972 all. Check the distribution terms of a manual before you buy it, and
4973 insist that whoever seeks your business must respect your freedom.
4974 Check the history of the book, and try reward the publishers that have
4975 paid or pay the authors to work on it.
4977 The Free Software Foundation maintains a list of free documentation
4978 published by other publishers, at
4979 `http://www.fsf.org/doc/other-free-books.html'.
4982 File: tar.info, Node: GNU Free Documentation License, Next: Index of Command Line Options, Prev: Free Software Needs Free Documentation, Up: Top
4984 Appendix G GNU Free Documentation License
4985 *****************************************
4987 Version 1.3, 3 November 2008
4989 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
4992 Everyone is permitted to copy and distribute verbatim copies
4993 of this license document, but changing it is not allowed.
4997 The purpose of this License is to make a manual, textbook, or other
4998 functional and useful document "free" in the sense of freedom: to
4999 assure everyone the effective freedom to copy and redistribute it,
5000 with or without modifying it, either commercially or
5001 noncommercially. Secondarily, this License preserves for the
5002 author and publisher a way to get credit for their work, while not
5003 being considered responsible for modifications made by others.
5005 This License is a kind of "copyleft", which means that derivative
5006 works of the document must themselves be free in the same sense.
5007 It complements the GNU General Public License, which is a copyleft
5008 license designed for free software.
5010 We have designed this License in order to use it for manuals for
5011 free software, because free software needs free documentation: a
5012 free program should come with manuals providing the same freedoms
5013 that the software does. But this License is not limited to
5014 software manuals; it can be used for any textual work, regardless
5015 of subject matter or whether it is published as a printed book.
5016 We recommend this License principally for works whose purpose is
5017 instruction or reference.
5019 1. APPLICABILITY AND DEFINITIONS
5021 This License applies to any manual or other work, in any medium,
5022 that contains a notice placed by the copyright holder saying it
5023 can be distributed under the terms of this License. Such a notice
5024 grants a world-wide, royalty-free license, unlimited in duration,
5025 to use that work under the conditions stated herein. The
5026 "Document", below, refers to any such manual or work. Any member
5027 of the public is a licensee, and is addressed as "you". You
5028 accept the license if you copy, modify or distribute the work in a
5029 way requiring permission under copyright law.
5031 A "Modified Version" of the Document means any work containing the
5032 Document or a portion of it, either copied verbatim, or with
5033 modifications and/or translated into another language.
5035 A "Secondary Section" is a named appendix or a front-matter section
5036 of the Document that deals exclusively with the relationship of the
5037 publishers or authors of the Document to the Document's overall
5038 subject (or to related matters) and contains nothing that could
5039 fall directly within that overall subject. (Thus, if the Document
5040 is in part a textbook of mathematics, a Secondary Section may not
5041 explain any mathematics.) The relationship could be a matter of
5042 historical connection with the subject or with related matters, or
5043 of legal, commercial, philosophical, ethical or political position
5046 The "Invariant Sections" are certain Secondary Sections whose
5047 titles are designated, as being those of Invariant Sections, in
5048 the notice that says that the Document is released under this
5049 License. If a section does not fit the above definition of
5050 Secondary then it is not allowed to be designated as Invariant.
5051 The Document may contain zero Invariant Sections. If the Document
5052 does not identify any Invariant Sections then there are none.
5054 The "Cover Texts" are certain short passages of text that are
5055 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
5056 that says that the Document is released under this License. A
5057 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
5058 be at most 25 words.
5060 A "Transparent" copy of the Document means a machine-readable copy,
5061 represented in a format whose specification is available to the
5062 general public, that is suitable for revising the document
5063 straightforwardly with generic text editors or (for images
5064 composed of pixels) generic paint programs or (for drawings) some
5065 widely available drawing editor, and that is suitable for input to
5066 text formatters or for automatic translation to a variety of
5067 formats suitable for input to text formatters. A copy made in an
5068 otherwise Transparent file format whose markup, or absence of
5069 markup, has been arranged to thwart or discourage subsequent
5070 modification by readers is not Transparent. An image format is
5071 not Transparent if used for any substantial amount of text. A
5072 copy that is not "Transparent" is called "Opaque".
5074 Examples of suitable formats for Transparent copies include plain
5075 ASCII without markup, Texinfo input format, LaTeX input format,
5076 SGML or XML using a publicly available DTD, and
5077 standard-conforming simple HTML, PostScript or PDF designed for
5078 human modification. Examples of transparent image formats include
5079 PNG, XCF and JPG. Opaque formats include proprietary formats that
5080 can be read and edited only by proprietary word processors, SGML or
5081 XML for which the DTD and/or processing tools are not generally
5082 available, and the machine-generated HTML, PostScript or PDF
5083 produced by some word processors for output purposes only.
5085 The "Title Page" means, for a printed book, the title page itself,
5086 plus such following pages as are needed to hold, legibly, the
5087 material this License requires to appear in the title page. For
5088 works in formats which do not have any title page as such, "Title
5089 Page" means the text near the most prominent appearance of the
5090 work's title, preceding the beginning of the body of the text.
5092 The "publisher" means any person or entity that distributes copies
5093 of the Document to the public.
5095 A section "Entitled XYZ" means a named subunit of the Document
5096 whose title either is precisely XYZ or contains XYZ in parentheses
5097 following text that translates XYZ in another language. (Here XYZ
5098 stands for a specific section name mentioned below, such as
5099 "Acknowledgements", "Dedications", "Endorsements", or "History".)
5100 To "Preserve the Title" of such a section when you modify the
5101 Document means that it remains a section "Entitled XYZ" according
5104 The Document may include Warranty Disclaimers next to the notice
5105 which states that this License applies to the Document. These
5106 Warranty Disclaimers are considered to be included by reference in
5107 this License, but only as regards disclaiming warranties: any other
5108 implication that these Warranty Disclaimers may have is void and
5109 has no effect on the meaning of this License.
5113 You may copy and distribute the Document in any medium, either
5114 commercially or noncommercially, provided that this License, the
5115 copyright notices, and the license notice saying this License
5116 applies to the Document are reproduced in all copies, and that you
5117 add no other conditions whatsoever to those of this License. You
5118 may not use technical measures to obstruct or control the reading
5119 or further copying of the copies you make or distribute. However,
5120 you may accept compensation in exchange for copies. If you
5121 distribute a large enough number of copies you must also follow
5122 the conditions in section 3.
5124 You may also lend copies, under the same conditions stated above,
5125 and you may publicly display copies.
5127 3. COPYING IN QUANTITY
5129 If you publish printed copies (or copies in media that commonly
5130 have printed covers) of the Document, numbering more than 100, and
5131 the Document's license notice requires Cover Texts, you must
5132 enclose the copies in covers that carry, clearly and legibly, all
5133 these Cover Texts: Front-Cover Texts on the front cover, and
5134 Back-Cover Texts on the back cover. Both covers must also clearly
5135 and legibly identify you as the publisher of these copies. The
5136 front cover must present the full title with all words of the
5137 title equally prominent and visible. You may add other material
5138 on the covers in addition. Copying with changes limited to the
5139 covers, as long as they preserve the title of the Document and
5140 satisfy these conditions, can be treated as verbatim copying in
5143 If the required texts for either cover are too voluminous to fit
5144 legibly, you should put the first ones listed (as many as fit
5145 reasonably) on the actual cover, and continue the rest onto
5148 If you publish or distribute Opaque copies of the Document
5149 numbering more than 100, you must either include a
5150 machine-readable Transparent copy along with each Opaque copy, or
5151 state in or with each Opaque copy a computer-network location from
5152 which the general network-using public has access to download
5153 using public-standard network protocols a complete Transparent
5154 copy of the Document, free of added material. If you use the
5155 latter option, you must take reasonably prudent steps, when you
5156 begin distribution of Opaque copies in quantity, to ensure that
5157 this Transparent copy will remain thus accessible at the stated
5158 location until at least one year after the last time you
5159 distribute an Opaque copy (directly or through your agents or
5160 retailers) of that edition to the public.
5162 It is requested, but not required, that you contact the authors of
5163 the Document well before redistributing any large number of
5164 copies, to give them a chance to provide you with an updated
5165 version of the Document.
5169 You may copy and distribute a Modified Version of the Document
5170 under the conditions of sections 2 and 3 above, provided that you
5171 release the Modified Version under precisely this License, with
5172 the Modified Version filling the role of the Document, thus
5173 licensing distribution and modification of the Modified Version to
5174 whoever possesses a copy of it. In addition, you must do these
5175 things in the Modified Version:
5177 A. Use in the Title Page (and on the covers, if any) a title
5178 distinct from that of the Document, and from those of
5179 previous versions (which should, if there were any, be listed
5180 in the History section of the Document). You may use the
5181 same title as a previous version if the original publisher of
5182 that version gives permission.
5184 B. List on the Title Page, as authors, one or more persons or
5185 entities responsible for authorship of the modifications in
5186 the Modified Version, together with at least five of the
5187 principal authors of the Document (all of its principal
5188 authors, if it has fewer than five), unless they release you
5189 from this requirement.
5191 C. State on the Title page the name of the publisher of the
5192 Modified Version, as the publisher.
5194 D. Preserve all the copyright notices of the Document.
5196 E. Add an appropriate copyright notice for your modifications
5197 adjacent to the other copyright notices.
5199 F. Include, immediately after the copyright notices, a license
5200 notice giving the public permission to use the Modified
5201 Version under the terms of this License, in the form shown in
5204 G. Preserve in that license notice the full lists of Invariant
5205 Sections and required Cover Texts given in the Document's
5208 H. Include an unaltered copy of this License.
5210 I. Preserve the section Entitled "History", Preserve its Title,
5211 and add to it an item stating at least the title, year, new
5212 authors, and publisher of the Modified Version as given on
5213 the Title Page. If there is no section Entitled "History" in
5214 the Document, create one stating the title, year, authors,
5215 and publisher of the Document as given on its Title Page,
5216 then add an item describing the Modified Version as stated in
5217 the previous sentence.
5219 J. Preserve the network location, if any, given in the Document
5220 for public access to a Transparent copy of the Document, and
5221 likewise the network locations given in the Document for
5222 previous versions it was based on. These may be placed in
5223 the "History" section. You may omit a network location for a
5224 work that was published at least four years before the
5225 Document itself, or if the original publisher of the version
5226 it refers to gives permission.
5228 K. For any section Entitled "Acknowledgements" or "Dedications",
5229 Preserve the Title of the section, and preserve in the
5230 section all the substance and tone of each of the contributor
5231 acknowledgements and/or dedications given therein.
5233 L. Preserve all the Invariant Sections of the Document,
5234 unaltered in their text and in their titles. Section numbers
5235 or the equivalent are not considered part of the section
5238 M. Delete any section Entitled "Endorsements". Such a section
5239 may not be included in the Modified Version.
5241 N. Do not retitle any existing section to be Entitled
5242 "Endorsements" or to conflict in title with any Invariant
5245 O. Preserve any Warranty Disclaimers.
5247 If the Modified Version includes new front-matter sections or
5248 appendices that qualify as Secondary Sections and contain no
5249 material copied from the Document, you may at your option
5250 designate some or all of these sections as invariant. To do this,
5251 add their titles to the list of Invariant Sections in the Modified
5252 Version's license notice. These titles must be distinct from any
5253 other section titles.
5255 You may add a section Entitled "Endorsements", provided it contains
5256 nothing but endorsements of your Modified Version by various
5257 parties--for example, statements of peer review or that the text
5258 has been approved by an organization as the authoritative
5259 definition of a standard.
5261 You may add a passage of up to five words as a Front-Cover Text,
5262 and a passage of up to 25 words as a Back-Cover Text, to the end
5263 of the list of Cover Texts in the Modified Version. Only one
5264 passage of Front-Cover Text and one of Back-Cover Text may be
5265 added by (or through arrangements made by) any one entity. If the
5266 Document already includes a cover text for the same cover,
5267 previously added by you or by arrangement made by the same entity
5268 you are acting on behalf of, you may not add another; but you may
5269 replace the old one, on explicit permission from the previous
5270 publisher that added the old one.
5272 The author(s) and publisher(s) of the Document do not by this
5273 License give permission to use their names for publicity for or to
5274 assert or imply endorsement of any Modified Version.
5276 5. COMBINING DOCUMENTS
5278 You may combine the Document with other documents released under
5279 this License, under the terms defined in section 4 above for
5280 modified versions, provided that you include in the combination
5281 all of the Invariant Sections of all of the original documents,
5282 unmodified, and list them all as Invariant Sections of your
5283 combined work in its license notice, and that you preserve all
5284 their Warranty Disclaimers.
5286 The combined work need only contain one copy of this License, and
5287 multiple identical Invariant Sections may be replaced with a single
5288 copy. If there are multiple Invariant Sections with the same name
5289 but different contents, make the title of each such section unique
5290 by adding at the end of it, in parentheses, the name of the
5291 original author or publisher of that section if known, or else a
5292 unique number. Make the same adjustment to the section titles in
5293 the list of Invariant Sections in the license notice of the
5296 In the combination, you must combine any sections Entitled
5297 "History" in the various original documents, forming one section
5298 Entitled "History"; likewise combine any sections Entitled
5299 "Acknowledgements", and any sections Entitled "Dedications". You
5300 must delete all sections Entitled "Endorsements."
5302 6. COLLECTIONS OF DOCUMENTS
5304 You may make a collection consisting of the Document and other
5305 documents released under this License, and replace the individual
5306 copies of this License in the various documents with a single copy
5307 that is included in the collection, provided that you follow the
5308 rules of this License for verbatim copying of each of the
5309 documents in all other respects.
5311 You may extract a single document from such a collection, and
5312 distribute it individually under this License, provided you insert
5313 a copy of this License into the extracted document, and follow
5314 this License in all other respects regarding verbatim copying of
5317 7. AGGREGATION WITH INDEPENDENT WORKS
5319 A compilation of the Document or its derivatives with other
5320 separate and independent documents or works, in or on a volume of
5321 a storage or distribution medium, is called an "aggregate" if the
5322 copyright resulting from the compilation is not used to limit the
5323 legal rights of the compilation's users beyond what the individual
5324 works permit. When the Document is included in an aggregate, this
5325 License does not apply to the other works in the aggregate which
5326 are not themselves derivative works of the Document.
5328 If the Cover Text requirement of section 3 is applicable to these
5329 copies of the Document, then if the Document is less than one half
5330 of the entire aggregate, the Document's Cover Texts may be placed
5331 on covers that bracket the Document within the aggregate, or the
5332 electronic equivalent of covers if the Document is in electronic
5333 form. Otherwise they must appear on printed covers that bracket
5334 the whole aggregate.
5338 Translation is considered a kind of modification, so you may
5339 distribute translations of the Document under the terms of section
5340 4. Replacing Invariant Sections with translations requires special
5341 permission from their copyright holders, but you may include
5342 translations of some or all Invariant Sections in addition to the
5343 original versions of these Invariant Sections. You may include a
5344 translation of this License, and all the license notices in the
5345 Document, and any Warranty Disclaimers, provided that you also
5346 include the original English version of this License and the
5347 original versions of those notices and disclaimers. In case of a
5348 disagreement between the translation and the original version of
5349 this License or a notice or disclaimer, the original version will
5352 If a section in the Document is Entitled "Acknowledgements",
5353 "Dedications", or "History", the requirement (section 4) to
5354 Preserve its Title (section 1) will typically require changing the
5359 You may not copy, modify, sublicense, or distribute the Document
5360 except as expressly provided under this License. Any attempt
5361 otherwise to copy, modify, sublicense, or distribute it is void,
5362 and will automatically terminate your rights under this License.
5364 However, if you cease all violation of this License, then your
5365 license from a particular copyright holder is reinstated (a)
5366 provisionally, unless and until the copyright holder explicitly
5367 and finally terminates your license, and (b) permanently, if the
5368 copyright holder fails to notify you of the violation by some
5369 reasonable means prior to 60 days after the cessation.
5371 Moreover, your license from a particular copyright holder is
5372 reinstated permanently if the copyright holder notifies you of the
5373 violation by some reasonable means, this is the first time you have
5374 received notice of violation of this License (for any work) from
5375 that copyright holder, and you cure the violation prior to 30 days
5376 after your receipt of the notice.
5378 Termination of your rights under this section does not terminate
5379 the licenses of parties who have received copies or rights from
5380 you under this License. If your rights have been terminated and
5381 not permanently reinstated, receipt of a copy of some or all of
5382 the same material does not give you any rights to use it.
5384 10. FUTURE REVISIONS OF THIS LICENSE
5386 The Free Software Foundation may publish new, revised versions of
5387 the GNU Free Documentation License from time to time. Such new
5388 versions will be similar in spirit to the present version, but may
5389 differ in detail to address new problems or concerns. See
5390 `http://www.gnu.org/copyleft/'.
5392 Each version of the License is given a distinguishing version
5393 number. If the Document specifies that a particular numbered
5394 version of this License "or any later version" applies to it, you
5395 have the option of following the terms and conditions either of
5396 that specified version or of any later version that has been
5397 published (not as a draft) by the Free Software Foundation. If
5398 the Document does not specify a version number of this License,
5399 you may choose any version ever published (not as a draft) by the
5400 Free Software Foundation. If the Document specifies that a proxy
5401 can decide which future versions of this License can be used, that
5402 proxy's public statement of acceptance of a version permanently
5403 authorizes you to choose that version for the Document.
5407 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
5408 World Wide Web server that publishes copyrightable works and also
5409 provides prominent facilities for anybody to edit those works. A
5410 public wiki that anybody can edit is an example of such a server.
5411 A "Massive Multiauthor Collaboration" (or "MMC") contained in the
5412 site means any set of copyrightable works thus published on the MMC
5415 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
5416 license published by Creative Commons Corporation, a not-for-profit
5417 corporation with a principal place of business in San Francisco,
5418 California, as well as future copyleft versions of that license
5419 published by that same organization.
5421 "Incorporate" means to publish or republish a Document, in whole or
5422 in part, as part of another Document.
5424 An MMC is "eligible for relicensing" if it is licensed under this
5425 License, and if all works that were first published under this
5426 License somewhere other than this MMC, and subsequently
5427 incorporated in whole or in part into the MMC, (1) had no cover
5428 texts or invariant sections, and (2) were thus incorporated prior
5429 to November 1, 2008.
5431 The operator of an MMC Site may republish an MMC contained in the
5432 site under CC-BY-SA on the same site at any time before August 1,
5433 2009, provided the MMC is eligible for relicensing.
5436 ADDENDUM: How to use this License for your documents
5437 ====================================================
5439 To use this License in a document you have written, include a copy of
5440 the License in the document and put the following copyright and license
5441 notices just after the title page:
5443 Copyright (C) YEAR YOUR NAME.
5444 Permission is granted to copy, distribute and/or modify this document
5445 under the terms of the GNU Free Documentation License, Version 1.3
5446 or any later version published by the Free Software Foundation;
5447 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
5448 Texts. A copy of the license is included in the section entitled ``GNU
5449 Free Documentation License''.
5451 If you have Invariant Sections, Front-Cover Texts and Back-Cover
5452 Texts, replace the "with...Texts." line with this:
5454 with the Invariant Sections being LIST THEIR TITLES, with
5455 the Front-Cover Texts being LIST, and with the Back-Cover Texts
5458 If you have Invariant Sections without Cover Texts, or some other
5459 combination of the three, merge those two alternatives to suit the
5462 If your document contains nontrivial examples of program code, we
5463 recommend releasing these examples in parallel under your choice of
5464 free software license, such as the GNU General Public License, to
5465 permit their use in free software.
5468 File: tar.info, Node: Index of Command Line Options, Next: Index, Prev: GNU Free Documentation License, Up: Top
5470 Appendix H Index of Command Line Options
5471 ****************************************
5473 This appendix contains an index of all GNU `tar' long command line
5474 options. The options are listed without the preceding double-dash. For
5475 a cross-reference of short command line options, see *note Short Option
5481 * --keep-directory-symlink, summary: Option Summary. (line 359)
5482 * absolute-names: absolute. (line 10)
5483 * absolute-names, summary: Option Summary. (line 6)
5484 * add-file: files. (line 60)
5485 * after-date: after. (line 24)
5486 * after-date, summary: Option Summary. (line 13)
5487 * anchored: controlling pattern-matching.
5489 * anchored, summary: Option Summary. (line 16)
5490 * append <1>: appending files. (line 6)
5491 * append: append. (line 6)
5492 * append, summary: Operation Summary. (line 6)
5493 * atime-preserve: Attributes. (line 10)
5494 * atime-preserve, summary: Option Summary. (line 20)
5495 * auto-compress: gzip. (line 155)
5496 * auto-compress, summary: Option Summary. (line 66)
5497 * backup: backup. (line 41)
5498 * backup, summary: Option Summary. (line 72)
5499 * block-number: verbose. (line 115)
5500 * block-number, summary: Option Summary. (line 77)
5501 * blocking-factor: Blocking Factor. (line 8)
5502 * blocking-factor, summary: Option Summary. (line 83)
5503 * bzip2, summary: Option Summary. (line 88)
5504 * catenate: concatenate. (line 6)
5505 * catenate, summary: Operation Summary. (line 10)
5506 * check-device, described: Incremental Dumps. (line 108)
5507 * check-device, summary: Option Summary. (line 93)
5508 * check-links, described: hard links. (line 31)
5509 * check-links, summary: Option Summary. (line 144)
5510 * checkpoint: checkpoints. (line 6)
5511 * checkpoint, defined: checkpoints. (line 13)
5512 * checkpoint, summary: Option Summary. (line 98)
5513 * checkpoint-action: checkpoints. (line 6)
5514 * checkpoint-action, defined: checkpoints. (line 22)
5515 * checkpoint-action, summary: Option Summary. (line 106)
5516 * compare: compare. (line 6)
5517 * compare, summary: Operation Summary. (line 14)
5518 * compress: gzip. (line 113)
5519 * compress, summary: Option Summary. (line 153)
5520 * concatenate: concatenate. (line 6)
5521 * concatenate, summary: Operation Summary. (line 20)
5522 * confirmation, summary: Option Summary. (line 160)
5523 * create, additional options: create options. (line 6)
5524 * create, complementary notes: Basic tar. (line 11)
5525 * create, introduced: Creating the archive.
5527 * create, summary: Operation Summary. (line 25)
5528 * create, using with --verbose: create verbose. (line 6)
5529 * create, using with --verify: verify. (line 24)
5530 * delay-directory-restore: Directory Modification Times and Permissions.
5532 * delay-directory-restore, summary: Option Summary. (line 163)
5533 * delete: delete. (line 6)
5534 * delete, summary: Operation Summary. (line 29)
5535 * delete, using before -append: append. (line 47)
5536 * dereference: dereference. (line 6)
5537 * dereference, summary: Option Summary. (line 168)
5538 * diff, summary: Operation Summary. (line 33)
5539 * directory: directory. (line 11)
5540 * directory, summary: Option Summary. (line 174)
5541 * exclude: exclude. (line 6)
5542 * exclude, potential problems with: problems with exclude.
5544 * exclude, summary: Option Summary. (line 181)
5545 * exclude-backups: exclude. (line 82)
5546 * exclude-backups, summary: Option Summary. (line 185)
5547 * exclude-caches: exclude. (line 105)
5548 * exclude-caches, summary: Option Summary. (line 193)
5549 * exclude-caches-all: exclude. (line 113)
5550 * exclude-caches-all, summary: Option Summary. (line 206)
5551 * exclude-caches-under: exclude. (line 109)
5552 * exclude-caches-under, summary: Option Summary. (line 200)
5553 * exclude-from: exclude. (line 6)
5554 * exclude-from, summary: Option Summary. (line 188)
5555 * exclude-tag: exclude. (line 122)
5556 * exclude-tag, summary: Option Summary. (line 210)
5557 * exclude-tag-all: exclude. (line 130)
5558 * exclude-tag-all, summary: Option Summary. (line 220)
5559 * exclude-tag-under: exclude. (line 126)
5560 * exclude-tag-under, summary: Option Summary. (line 215)
5561 * exclude-vcs: exclude. (line 37)
5562 * exclude-vcs, summary: Option Summary. (line 224)
5563 * extract: extract. (line 6)
5564 * extract, additional options: extract options. (line 6)
5565 * extract, complementary notes: Basic tar. (line 48)
5566 * extract, summary: Operation Summary. (line 37)
5567 * extract, using with --listed-incremental: Incremental Dumps.
5569 * file: file. (line 6)
5570 * file, short description: file. (line 15)
5571 * file, summary: Option Summary. (line 230)
5572 * file, tutorial: file tutorial. (line 6)
5573 * files-from: files. (line 14)
5574 * files-from, summary: Option Summary. (line 236)
5575 * force-local, short description: Device. (line 70)
5576 * force-local, summary: Option Summary. (line 242)
5577 * format, summary: Option Summary. (line 247)
5578 * full-time, summary: Option Summary. (line 272)
5579 * get, summary: Operation Summary. (line 42)
5580 * group: override. (line 88)
5581 * group, summary: Option Summary. (line 290)
5582 * gunzip, summary: Option Summary. (line 298)
5583 * gzip: gzip. (line 91)
5584 * gzip, summary: Option Summary. (line 298)
5585 * hard-dereference, described: hard links. (line 59)
5586 * hard-dereference, summary: Option Summary. (line 306)
5587 * help: help tutorial. (line 6)
5588 * help, introduction: help. (line 26)
5589 * help, summary: Option Summary. (line 312)
5590 * ignore-case: controlling pattern-matching.
5592 * ignore-case, summary: Option Summary. (line 317)
5593 * ignore-command-error: Writing to an External Program.
5595 * ignore-command-error, summary: Option Summary. (line 321)
5596 * ignore-failed-read: Ignore Failed Read. (line 7)
5597 * ignore-failed-read, summary: Option Summary. (line 325)
5598 * ignore-zeros: Ignore Zeros. (line 6)
5599 * ignore-zeros, short description: Blocking Factor. (line 156)
5600 * ignore-zeros, summary: Option Summary. (line 329)
5601 * incremental, summary: Option Summary. (line 334)
5602 * incremental, using with --list: Incremental Dumps. (line 186)
5603 * index-file, summary: Option Summary. (line 341)
5604 * info-script: Multi-Volume Archives.
5606 * info-script, short description: Device. (line 122)
5607 * info-script, summary: Option Summary. (line 344)
5608 * interactive: interactive. (line 14)
5609 * interactive, summary: Option Summary. (line 352)
5610 * keep-newer-files: Keep Newer Files. (line 6)
5611 * keep-newer-files, summary: Option Summary. (line 372)
5612 * keep-old-files: Keep Old Files. (line 9)
5613 * keep-old-files, introduced: Dealing with Old Files.
5615 * keep-old-files, summary: Option Summary. (line 376)
5616 * label <1>: label. (line 6)
5617 * label: Tape Files. (line 6)
5618 * label, summary: Option Summary. (line 384)
5619 * level, described: Incremental Dumps. (line 76)
5620 * level, summary: Option Summary. (line 391)
5621 * list: list. (line 6)
5622 * list, summary: Operation Summary. (line 46)
5623 * list, using with --incremental: Incremental Dumps. (line 186)
5624 * list, using with --listed-incremental: Incremental Dumps. (line 186)
5625 * list, using with --verbose: list. (line 30)
5626 * list, using with file name arguments: list. (line 68)
5627 * listed-incremental, described: Incremental Dumps. (line 14)
5628 * listed-incremental, summary: Option Summary. (line 401)
5629 * listed-incremental, using with --extract: Incremental Dumps.
5631 * listed-incremental, using with --list: Incremental Dumps. (line 186)
5632 * lzip: gzip. (line 104)
5633 * lzip, summary: Option Summary. (line 409)
5634 * lzma: gzip. (line 107)
5635 * lzma, summary: Option Summary. (line 413)
5636 * lzop: gzip. (line 110)
5637 * mode: override. (line 14)
5638 * mode, summary: Option Summary. (line 421)
5639 * mtime: override. (line 29)
5640 * mtime, summary: Option Summary. (line 427)
5641 * multi-volume: Multi-Volume Archives.
5643 * multi-volume, short description: Device. (line 88)
5644 * multi-volume, summary: Option Summary. (line 436)
5645 * new-volume-script: Multi-Volume Archives.
5647 * new-volume-script, short description: Device. (line 122)
5648 * new-volume-script, summary: Option Summary. (line 344)
5649 * newer: after. (line 24)
5650 * newer, summary: Option Summary. (line 444)
5651 * newer-mtime: after. (line 35)
5652 * newer-mtime, summary: Option Summary. (line 452)
5653 * no-anchored: controlling pattern-matching.
5655 * no-anchored, summary: Option Summary. (line 457)
5656 * no-auto-compress, summary: Option Summary. (line 461)
5657 * no-check-device, described: Incremental Dumps. (line 104)
5658 * no-check-device, summary: Option Summary. (line 465)
5659 * no-delay-directory-restore: Directory Modification Times and Permissions.
5661 * no-delay-directory-restore, summary: Option Summary. (line 470)
5662 * no-ignore-case: controlling pattern-matching.
5664 * no-ignore-case, summary: Option Summary. (line 476)
5665 * no-ignore-command-error: Writing to an External Program.
5667 * no-ignore-command-error, summary: Option Summary. (line 479)
5668 * no-null, described: nul. (line 15)
5669 * no-null, summary: Option Summary. (line 483)
5670 * no-overwrite-dir, summary: Option Summary. (line 488)
5671 * no-quote-chars, summary: Option Summary. (line 492)
5672 * no-recursion: recurse. (line 11)
5673 * no-recursion, summary: Option Summary. (line 497)
5674 * no-same-owner: Attributes. (line 63)
5675 * no-same-owner, summary: Option Summary. (line 501)
5676 * no-same-permissions, summary: Option Summary. (line 507)
5677 * no-seek, summary: Option Summary. (line 512)
5678 * no-unquote: Selecting Archive Members.
5680 * no-unquote, summary: Option Summary. (line 517)
5681 * no-wildcards: controlling pattern-matching.
5683 * no-wildcards, summary: Option Summary. (line 521)
5684 * no-wildcards-match-slash: controlling pattern-matching.
5686 * no-wildcards-match-slash, summary: Option Summary. (line 524)
5687 * null, described: nul. (line 11)
5688 * null, summary: Option Summary. (line 527)
5689 * numeric-owner: Attributes. (line 69)
5690 * numeric-owner, summary: Option Summary. (line 533)
5691 * occurrence, described: append. (line 34)
5692 * occurrence, summary: Option Summary. (line 550)
5693 * old-archive, summary: Option Summary. (line 564)
5694 * one-file-system: one. (line 14)
5695 * one-file-system, summary: Option Summary. (line 567)
5696 * overwrite: Overwrite Old Files. (line 6)
5697 * overwrite, introduced: Dealing with Old Files.
5699 * overwrite, summary: Option Summary. (line 572)
5700 * overwrite-dir: Overwrite Old Files. (line 28)
5701 * overwrite-dir, introduced: Dealing with Old Files.
5703 * overwrite-dir, summary: Option Summary. (line 576)
5704 * owner: override. (line 57)
5705 * owner, summary: Option Summary. (line 580)
5706 * pax-option: PAX keywords. (line 6)
5707 * pax-option, summary: Option Summary. (line 588)
5708 * portability, summary: Option Summary. (line 594)
5709 * posix, summary: Option Summary. (line 598)
5710 * preserve: Attributes. (line 122)
5711 * preserve, summary: Option Summary. (line 601)
5712 * preserve-order: Same Order. (line 6)
5713 * preserve-order, summary: Option Summary. (line 605)
5714 * preserve-permissions: Setting Access Permissions.
5716 * preserve-permissions, short description: Attributes. (line 109)
5717 * preserve-permissions, summary: Option Summary. (line 608)
5718 * quote-chars, summary: Option Summary. (line 618)
5719 * quoting-style: quoting styles. (line 38)
5720 * quoting-style, summary: Option Summary. (line 622)
5721 * read-full-records <1>: read full records. (line 6)
5722 * read-full-records: Reading. (line 6)
5723 * read-full-records, short description: Blocking Factor. (line 172)
5724 * read-full-records, summary: Option Summary. (line 629)
5725 * record-size, summary: Option Summary. (line 634)
5726 * recursion: recurse. (line 22)
5727 * recursion, summary: Option Summary. (line 641)
5728 * recursive-unlink: Recursive Unlink. (line 6)
5729 * recursive-unlink, summary: Option Summary. (line 645)
5730 * remove-files: remove files. (line 6)
5731 * remove-files, summary: Option Summary. (line 650)
5732 * restrict, summary: Option Summary. (line 654)
5733 * rmt-command, summary: Option Summary. (line 659)
5734 * rsh-command: Device. (line 73)
5735 * rsh-command, summary: Option Summary. (line 663)
5736 * same-order: Same Order. (line 6)
5737 * same-order, summary: Option Summary. (line 667)
5738 * same-owner: Attributes. (line 44)
5739 * same-owner, summary: Option Summary. (line 675)
5740 * same-permissions: Setting Access Permissions.
5742 * same-permissions, short description: Attributes. (line 109)
5743 * same-permissions, summary: Option Summary. (line 608)
5744 * seek, summary: Option Summary. (line 684)
5745 * show-defaults: defaults. (line 6)
5746 * show-defaults, summary: Option Summary. (line 693)
5747 * show-omitted-dirs: verbose. (line 107)
5748 * show-omitted-dirs, summary: Option Summary. (line 705)
5749 * show-snapshot-field-ranges: Snapshot Files. (line 113)
5750 * show-snapshot-field-ranges, summary: Option Summary. (line 709)
5751 * show-stored-names: list. (line 60)
5752 * show-stored-names, summary: Option Summary. (line 714)
5753 * show-transformed-names: transform. (line 45)
5754 * show-transformed-names, summary: Option Summary. (line 714)
5755 * skip-old-files, introduced: Dealing with Old Files.
5757 * skip-old-files, summary: Option Summary. (line 722)
5758 * sparse: sparse. (line 22)
5759 * sparse, summary: Option Summary. (line 734)
5760 * sparse-version: sparse. (line 57)
5761 * sparse-version, summary: Option Summary. (line 739)
5762 * starting-file: Starting File. (line 6)
5763 * starting-file, summary: Option Summary. (line 744)
5764 * strip-components: transform. (line 25)
5765 * strip-components, summary: Option Summary. (line 750)
5766 * suffix: backup. (line 68)
5767 * suffix, summary: Option Summary. (line 759)
5768 * tape-length: Multi-Volume Archives.
5770 * tape-length, short description: Device. (line 96)
5771 * tape-length, summary: Option Summary. (line 763)
5772 * test-label: label. (line 35)
5773 * test-label, summary: Option Summary. (line 772)
5774 * to-command: Writing to an External Program.
5776 * to-command, summary: Option Summary. (line 776)
5777 * to-stdout: Writing to Standard Output.
5779 * to-stdout, summary: Option Summary. (line 780)
5780 * totals: verbose. (line 46)
5781 * totals, summary: Option Summary. (line 785)
5782 * touch <1>: Attributes. (line 33)
5783 * touch: Data Modification Times.
5785 * touch, summary: Option Summary. (line 790)
5786 * transform: transform. (line 74)
5787 * transform, summary: Option Summary. (line 796)
5788 * uncompress: gzip. (line 113)
5789 * uncompress, summary: Option Summary. (line 153)
5790 * ungzip: gzip. (line 91)
5791 * ungzip, summary: Option Summary. (line 298)
5792 * unlink-first: Unlink First. (line 6)
5793 * unlink-first, introduced: Dealing with Old Files.
5795 * unlink-first, summary: Option Summary. (line 816)
5796 * unquote: Selecting Archive Members.
5798 * unquote, summary: Option Summary. (line 822)
5799 * update <1>: how to update. (line 6)
5800 * update: update. (line 6)
5801 * update, summary: Operation Summary. (line 50)
5802 * usage: help. (line 53)
5803 * use-compress-program: gzip. (line 177)
5804 * use-compress-program, summary: Option Summary. (line 826)
5805 * utc, summary: Option Summary. (line 831)
5806 * verbose: verbose. (line 18)
5807 * verbose, introduced: verbose tutorial. (line 6)
5808 * verbose, summary: Option Summary. (line 835)
5809 * verbose, using with --create: create verbose. (line 6)
5810 * verbose, using with --list: list. (line 30)
5811 * verify, short description: verify. (line 8)
5812 * verify, summary: Option Summary. (line 842)
5813 * verify, using with --create: verify. (line 24)
5814 * version: help. (line 6)
5815 * version, summary: Option Summary. (line 847)
5816 * volno-file: Multi-Volume Archives.
5818 * volno-file, summary: Option Summary. (line 852)
5819 * warning, explained: warnings. (line 12)
5820 * warning, summary: Option Summary. (line 857)
5821 * wildcards: controlling pattern-matching.
5823 * wildcards, summary: Option Summary. (line 862)
5824 * wildcards-match-slash: controlling pattern-matching.
5826 * wildcards-match-slash, summary: Option Summary. (line 866)
5827 * xform: transform. (line 74)
5828 * xform, summary: Option Summary. (line 796)
5829 * xz: gzip. (line 96)
5830 * xz, summary: Option Summary. (line 869)