diff options
Diffstat (limited to 'doc/tar.info-2')
| -rw-r--r-- | doc/tar.info-2 | 7007 |
1 files changed, 7007 insertions, 0 deletions
diff --git a/doc/tar.info-2 b/doc/tar.info-2 new file mode 100644 index 0000000..9dc6a87 --- /dev/null +++ b/doc/tar.info-2 @@ -0,0 +1,7007 @@ +This is tar.info, produced by makeinfo version 5.9.93 from tar.texi. + +This manual is for GNU 'tar' (version 1.29, 14 April 2016), which +creates and extracts files from archives. + + Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2016 Free Software +Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with the Invariant Sections being "GNU General Public + License", with the Front-Cover Texts being "A GNU Manual", and with + the Back-Cover Texts as in (a) below. A copy of the license is + included in the section entitled "GNU Free Documentation License". + + (a) The FSF's Back-Cover Text is: "You have the freedom to copy and + modify this GNU manual." +INFO-DIR-SECTION Archiving +START-INFO-DIR-ENTRY +* Tar: (tar). Making tape (or disk) archives. +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* tar: (tar)tar invocation. Invoking GNU 'tar'. +END-INFO-DIR-ENTRY + + +File: tar.info, Node: one, Prev: recurse, Up: Choosing + +6.10 Crossing File System Boundaries +==================================== + +'tar' will normally automatically cross file system boundaries in order +to archive files which are part of a directory tree. You can change +this behavior by running 'tar' and specifying '--one-file-system'. This +option only affects files that are archived because they are in a +directory that is being archived; 'tar' will still archive files +explicitly named on the command line or through '--files-from', +regardless of where they reside. + +'--one-file-system' + Prevents 'tar' from crossing file system boundaries when archiving. + Use in conjunction with any write operation. + + The '--one-file-system' option causes 'tar' to modify its normal +behavior in archiving the contents of directories. If a file in a +directory is not on the same file system as the directory itself, then +'tar' will not archive that file. If the file is a directory itself, +'tar' will not archive anything beneath it; in other words, 'tar' will +not cross mount points. + + This option is useful for making full or incremental archival backups +of a file system. If this option is used in conjunction with +'--verbose' ('-v'), files that are excluded are mentioned by name on the +standard error. + +* Menu: + +* directory:: Changing Directory +* absolute:: Absolute File Names + + +File: tar.info, Node: directory, Next: absolute, Up: one + +6.10.1 Changing the Working Directory +------------------------------------- + +To change the working directory in the middle of a list of file names, +either on the command line or in a file specified using '--files-from' +('-T'), use '--directory' ('-C'). This will change the working +directory to the specified directory after that point in the list. + +'--directory=DIRECTORY' +'-C DIRECTORY' + Changes the working directory in the middle of a command line. + + For example, + + $ tar -c -f jams.tar grape prune -C food cherry + +will place the files 'grape' and 'prune' from the current directory into +the archive 'jams.tar', followed by the file 'cherry' from the directory +'food'. This option is especially useful when you have several widely +separated files that you want to store in the same archive. + + Note that the file 'cherry' is recorded in the archive under the +precise name 'cherry', _not_ 'food/cherry'. Thus, the archive will +contain three files that all appear to have come from the same +directory; if the archive is extracted with plain 'tar --extract', all +three files will be written in the current directory. + + Contrast this with the command, + + $ tar -c -f jams.tar grape prune -C food red/cherry + +which records the third file in the archive under the name 'red/cherry' +so that, if the archive is extracted using 'tar --extract', the third +file will be written in a subdirectory named 'red'. + + You can use the '--directory' option to make the archive independent +of the original name of the directory holding the files. The following +command places the files '/etc/passwd', '/etc/hosts', and '/lib/libc.a' +into the archive 'foo.tar': + + $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a + +However, the names of the archive members will be exactly what they were +on the command line: 'passwd', 'hosts', and 'libc.a'. They will not +appear to be related by file name to the original directories where +those files were located. + + Note that '--directory' options are interpreted consecutively. If +'--directory' specifies a relative file name, it is interpreted relative +to the then current directory, which might not be the same as the +original current working directory of 'tar', due to a previous +'--directory' option. + + When using '--files-from' (*note files::), you can put various 'tar' +options (including '-C') in the file list. Notice, however, that in +this case the option and its argument may not be separated by +whitespace. If you use short option, its argument must either follow +the option letter immediately, without any intervening whitespace, or +occupy the next line. Otherwise, if you use long option, separate its +argument by an equal sign. + + For instance, the file list for the above example will be: + + -C/etc + passwd + hosts + --directory=/lib + libc.a + +To use it, you would invoke 'tar' as follows: + + $ tar -c -f foo.tar --files-from list + + The interpretation of options in file lists is disabled by +'--verbatim-files-from' and '--null' options. + + +File: tar.info, Node: absolute, Prev: directory, Up: one + +6.10.2 Absolute File Names +-------------------------- + +By default, GNU 'tar' drops a leading '/' on input or output, and +complains about file names containing a '..' component. There is an +option that turns off this behavior: + +'--absolute-names' +'-P' + Do not strip leading slashes from file names, and permit file names + containing a '..' file name component. + + When 'tar' extracts archive members from an archive, it strips any +leading slashes ('/') from the member name. This causes absolute member +names in the archive to be treated as relative file names. This allows +you to have such members extracted wherever you want, instead of being +restricted to extracting the member in the exact directory named in the +archive. For example, if the archive member has the name '/etc/passwd', +'tar' will extract it as if the name were really 'etc/passwd'. + + File names containing '..' can cause problems when extracting, so +'tar' normally warns you about such files when creating an archive, and +rejects attempts to extracts such files. + + Other 'tar' programs do not do this. As a result, if you create an +archive whose member names start with a slash, they will be difficult +for other people with a non-GNU 'tar' program to use. Therefore, GNU +'tar' also strips leading slashes from member names when putting members +into the archive. For example, if you ask 'tar' to add the file +'/bin/ls' to an archive, it will do so, but the member name will be +'bin/ls'(1). + + Symbolic links containing '..' or leading '/' can also cause problems +when extracting, so 'tar' normally extracts them last; it may create +empty files as placeholders during extraction. + + If you use the '--absolute-names' ('-P') option, 'tar' will do none +of these transformations. + + To archive or extract files relative to the root directory, specify +the '--absolute-names' ('-P') option. + + Normally, 'tar' acts on files relative to the working +directory--ignoring superior directory names when archiving, and +ignoring leading slashes when extracting. + + When you specify '--absolute-names' ('-P'), 'tar' stores file names +including all superior directory names, and preserves leading slashes. +If you only invoked 'tar' from the root directory you would never need +the '--absolute-names' option, but using this option may be more +convenient than switching to root. + +'--absolute-names' + Preserves full file names (including superior directory names) when + archiving and extracting files. + + 'tar' prints out a message about removing the '/' from file names. +This message appears once per GNU 'tar' invocation. It represents +something which ought to be told; ignoring what it means can cause very +serious surprises, later. + + Some people, nevertheless, do not want to see this message. Wanting +to play really dangerously, one may of course redirect 'tar' standard +error to the sink. For example, under 'sh': + + $ tar -c -f archive.tar /home 2> /dev/null + +Another solution, both nicer and simpler, would be to change to the '/' +directory first, and then avoid absolute notation. For example: + + $ tar -c -f archive.tar -C / home + + *Note Integrity::, for some of the security-related implications of +using this option. + + ---------- Footnotes ---------- + + (1) A side effect of this is that when '--create' is used with +'--verbose' the resulting output is not, generally speaking, the same as +the one you'd get running 'tar --list' command. This may be important +if you use some scripts for comparing both outputs. *Note listing +member and file names::, for the information on how to handle this case. + + +File: tar.info, Node: Date input formats, Next: Formats, Prev: Choosing, Up: Top + +7 Date input formats +******************** + +First, a quote: + + Our units of temporal measurement, from seconds on up to months, + are so complicated, asymmetrical and disjunctive so as to make + coherent mental reckoning in time all but impossible. Indeed, had + some tyrannical god contrived to enslave our minds to time, to make + it all but impossible for us to escape subjection to sodden + routines and unpleasant surprises, he could hardly have done better + than handing down our present system. It is like a set of + trapezoidal building blocks, with no vertical or horizontal + surfaces, like a language in which the simplest thought demands + ornate constructions, useless particles and lengthy + circumlocutions. Unlike the more successful patterns of language + and science, which enable us to face experience boldly or at least + level-headedly, our system of temporal calculation silently and + persistently encourages our terror of time. + + ... It is as though architects had to measure length in feet, width + in meters and height in ells; as though basic instruction manuals + demanded a knowledge of five different languages. It is no wonder + then that we often look into our own immediate past or future, last + Tuesday or a week from Sunday, with feelings of helpless confusion. + ... + + --Robert Grudin, 'Time and the Art of Living'. + + This section describes the textual date representations that GNU +programs accept. These are the strings you, as a user, can supply as +arguments to the various programs. The C interface (via the +'parse_datetime' function) is not described here. + +* Menu: + +* General date syntax:: Common rules. +* Calendar date items:: 19 Dec 1994. +* Time of day items:: 9:20pm. +* Time zone items:: EST, PDT, UTC, ... +* Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500. +* Day of week items:: Monday and others. +* Relative items in date strings:: next tuesday, 2 years ago. +* Pure numbers in date strings:: 19931219, 1440. +* Seconds since the Epoch:: @1078100502. +* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". +* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al. + + +File: tar.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats + +7.1 General date syntax +======================= + +A "date" is a string, possibly empty, containing many items separated by +whitespace. The whitespace may be omitted when no ambiguity arises. +The empty string means the beginning of today (i.e., midnight). Order +of the items is immaterial. A date string may contain many flavors of +items: + + * calendar date items + * time of day items + * time zone items + * combined date and time of day items + * day of the week items + * relative items + * pure numbers. + +We describe each of these item types in turn, below. + + A few ordinal numbers may be written out in words in some contexts. +This is most useful for specifying day of the week items or relative +items (see below). Among the most commonly used ordinal numbers, the +word 'last' stands for -1, 'this' stands for 0, and 'first' and 'next' +both stand for 1. Because the word 'second' stands for the unit of time +there is no way to write the ordinal number 2, but for convenience +'third' stands for 3, 'fourth' for 4, 'fifth' for 5, 'sixth' for 6, +'seventh' for 7, 'eighth' for 8, 'ninth' for 9, 'tenth' for 10, +'eleventh' for 11 and 'twelfth' for 12. + + When a month is written this way, it is still considered to be +written numerically, instead of being "spelled in full"; this changes +the allowed strings. + + In the current implementation, only English is supported for words +and abbreviations like 'AM', 'DST', 'EST', 'first', 'January', 'Sunday', +'tomorrow', and 'year'. + + The output of the 'date' command is not always acceptable as a date +string, not only because of the language problem, but also because there +is no standard meaning for time zone items like 'IST'. When using +'date' to generate a date string intended to be parsed later, specify a +date format that is independent of language and that does not use time +zone items other than 'UTC' and 'Z'. Here are some ways to do this: + + $ LC_ALL=C TZ=UTC0 date + Mon Mar 1 00:21:42 UTC 2004 + $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' + 2004-03-01 00:21:42Z + $ date --rfc-3339=ns # --rfc-3339 is a GNU extension. + 2004-02-29 16:21:42.692722128-08:00 + $ date --rfc-2822 # a GNU extension + Sun, 29 Feb 2004 16:21:42 -0800 + $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. + 2004-02-29 16:21:42 -0800 + $ date +'@%s.%N' # %s and %N are GNU extensions. + @1078100502.692722128 + + Alphabetic case is completely ignored in dates. Comments may be +introduced between round parentheses, as long as included parentheses +are properly nested. Hyphens not followed by a digit are currently +ignored. Leading zeros on numbers are ignored. + + Invalid dates like '2005-02-29' or times like '24:00' are rejected. +In the typical case of a host that does not support leap seconds, a time +like '23:59:60' is rejected even if it corresponds to a valid leap +second. + + +File: tar.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats + +7.2 Calendar date items +======================= + +A "calendar date item" specifies a day of the year. It is specified +differently, depending on whether the month is specified numerically or +literally. All these strings specify the same calendar date: + + 1972-09-24 # ISO 8601. + 72-9-24 # Assume 19xx for 69 through 99, + # 20xx for 00 through 68. + 72-09-24 # Leading zeros are ignored. + 9/24/72 # Common U.S. writing. + 24 September 1972 + 24 Sept 72 # September has a special abbreviation. + 24 Sep 72 # Three-letter abbreviations always allowed. + Sep 24, 1972 + 24-sep-72 + 24sep72 + + The year can also be omitted. In this case, the last specified year +is used, or the current year if none. For example: + + 9/24 + sep 24 + + Here are the rules. + + For numeric months, the ISO 8601 format 'YEAR-MONTH-DAY' is allowed, +where YEAR is any positive number, MONTH is a number between 01 and 12, +and DAY is a number between 01 and 31. A leading zero must be present +if a number is less than ten. If YEAR is 68 or smaller, then 2000 is +added to it; otherwise, if YEAR is less than 100, then 1900 is added to +it. The construct 'MONTH/DAY/YEAR', popular in the United States, is +accepted. Also 'MONTH/DAY', omitting the year. + + Literal months may be spelled out in full: 'January', 'February', +'March', 'April', 'May', 'June', 'July', 'August', 'September', +'October', 'November' or 'December'. Literal months may be abbreviated +to their first three letters, possibly followed by an abbreviating dot. +It is also permitted to write 'Sept' instead of 'September'. + + When months are written literally, the calendar date may be given as +any of the following: + + DAY MONTH YEAR + DAY MONTH + MONTH DAY YEAR + DAY-MONTH-YEAR + + Or, omitting the year: + + MONTH DAY + + +File: tar.info, Node: Time of day items, Next: Time zone items, Prev: Calendar date items, Up: Date input formats + +7.3 Time of day items +===================== + +A "time of day item" in date strings specifies the time on a given day. +Here are some examples, all of which represent the same time: + + 20:02:00.000000 + 20:02 + 8:02pm + 20:02-0500 # In EST (U.S. Eastern Standard Time). + + More generally, the time of day may be given as 'HOUR:MINUTE:SECOND', +where HOUR is a number between 0 and 23, MINUTE is a number between 0 +and 59, and SECOND is a number between 0 and 59 possibly followed by '.' +or ',' and a fraction containing one or more digits. Alternatively, +':SECOND' can be omitted, in which case it is taken to be zero. On the +rare hosts that support leap seconds, SECOND may be 60. + + If the time is followed by 'am' or 'pm' (or 'a.m.' or 'p.m.'), HOUR +is restricted to run from 1 to 12, and ':MINUTE' may be omitted (taken +to be zero). 'am' indicates the first half of the day, 'pm' indicates +the second half of the day. In this notation, 12 is the predecessor of +1: midnight is '12am' while noon is '12pm'. (This is the zero-oriented +interpretation of '12am' and '12pm', as opposed to the old tradition +derived from Latin which uses '12m' for noon and '12pm' for midnight.) + + The time may alternatively be followed by a time zone correction, +expressed as 'SHHMM', where S is '+' or '-', HH is a number of zone +hours and MM is a number of zone minutes. The zone minutes term, MM, +may be omitted, in which case the one- or two-digit correction is +interpreted as a number of hours. You can also separate HH from MM with +a colon. When a time zone correction is given this way, it forces +interpretation of the time relative to Coordinated Universal Time (UTC), +overriding any previous specification for the time zone or the local +time zone. For example, '+0530' and '+05:30' both stand for the time +zone 5.5 hours ahead of UTC (e.g., India). This is the best way to +specify a time zone correction by fractional parts of an hour. The +maximum zone correction is 24 hours. + + Either 'am'/'pm' or a time zone correction may be specified, but not +both. + + +File: tar.info, Node: Time zone items, Next: Combined date and time of day items, Prev: Time of day items, Up: Date input formats + +7.4 Time zone items +=================== + +A "time zone item" specifies an international time zone, indicated by a +small set of letters, e.g., 'UTC' or 'Z' for Coordinated Universal Time. +Any included periods are ignored. By following a non-daylight-saving +time zone by the string 'DST' in a separate word (that is, separated by +some white space), the corresponding daylight saving time zone may be +specified. Alternatively, a non-daylight-saving time zone can be +followed by a time zone correction, to add the two values. This is +normally done only for 'UTC'; for example, 'UTC+05:30' is equivalent to +'+05:30'. + + Time zone items other than 'UTC' and 'Z' are obsolescent and are not +recommended, because they are ambiguous; for example, 'EST' has a +different meaning in Australia than in the United States. Instead, it's +better to use unambiguous numeric time zone corrections like '-0500', as +described in the previous section. + + If neither a time zone item nor a time zone correction is supplied, +time stamps are interpreted using the rules of the default time zone +(*note Specifying time zone rules::). + + +File: tar.info, Node: Combined date and time of day items, Next: Day of week items, Prev: Time zone items, Up: Date input formats + +7.5 Combined date and time of day items +======================================= + +The ISO 8601 date and time of day extended format consists of an ISO +8601 date, a 'T' character separator, and an ISO 8601 time of day. This +format is also recognized if the 'T' is replaced by a space. + + In this format, the time of day should use 24-hour notation. +Fractional seconds are allowed, with either comma or period preceding +the fraction. ISO 8601 fractional minutes and hours are not supported. +Typically, hosts support nanosecond timestamp resolution; excess +precision is silently discarded. + + Here are some examples: + + 2012-09-24T20:02:00.052-0500 + 2012-12-31T23:59:59,999999999+1100 + 1970-01-01 00:00Z + + +File: tar.info, Node: Day of week items, Next: Relative items in date strings, Prev: Combined date and time of day items, Up: Date input formats + +7.6 Day of week items +===================== + +The explicit mention of a day of the week will forward the date (only if +necessary) to reach that day of the week in the future. + + Days of the week may be spelled out in full: 'Sunday', 'Monday', +'Tuesday', 'Wednesday', 'Thursday', 'Friday' or 'Saturday'. Days may be +abbreviated to their first three letters, optionally followed by a +period. The special abbreviations 'Tues' for 'Tuesday', 'Wednes' for +'Wednesday' and 'Thur' or 'Thurs' for 'Thursday' are also allowed. + + A number may precede a day of the week item to move forward +supplementary weeks. It is best used in expression like 'third monday'. +In this context, 'last DAY' or 'next DAY' is also acceptable; they move +one week before or after the day that DAY by itself would represent. + + A comma following a day of the week item is ignored. + + +File: tar.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats + +7.7 Relative items in date strings +================================== + +"Relative items" adjust a date (or the current date if none) forward or +backward. The effects of relative items accumulate. Here are some +examples: + + 1 year + 1 year ago + 3 years + 2 days + + The unit of time displacement may be selected by the string 'year' or +'month' for moving by whole years or months. These are fuzzy units, as +years and months are not all of equal duration. More precise units are +'fortnight' which is worth 14 days, 'week' worth 7 days, 'day' worth 24 +hours, 'hour' worth 60 minutes, 'minute' or 'min' worth 60 seconds, and +'second' or 'sec' worth one second. An 's' suffix on these units is +accepted and ignored. + + The unit of time may be preceded by a multiplier, given as an +optionally signed number. Unsigned numbers are taken as positively +signed. No number at all implies 1 for a multiplier. Following a +relative item by the string 'ago' is equivalent to preceding the unit by +a multiplier with value -1. + + The string 'tomorrow' is worth one day in the future (equivalent to +'day'), the string 'yesterday' is worth one day in the past (equivalent +to 'day ago'). + + The strings 'now' or 'today' are relative items corresponding to +zero-valued time displacement, these strings come from the fact a +zero-valued time displacement represents the current time when not +otherwise changed by previous items. They may be used to stress other +items, like in '12:00 today'. The string 'this' also has the meaning of +a zero-valued time displacement, but is preferred in date strings like +'this thursday'. + + When a relative item causes the resulting date to cross a boundary +where the clocks were adjusted, typically for daylight saving time, the +resulting date and time are adjusted accordingly. + + The fuzz in units can cause problems with relative items. For +example, '2003-07-31 -1 month' might evaluate to 2003-07-01, because +2003-06-31 is an invalid date. To determine the previous month more +reliably, you can ask for the month before the 15th of the current +month. For example: + + $ date -R + Thu, 31 Jul 2003 13:02:39 -0700 + $ date --date='-1 month' +'Last month was %B?' + Last month was July? + $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' + Last month was June! + + Also, take care when manipulating dates around clock changes such as +daylight saving leaps. In a few cases these have added or subtracted as +much as 24 hours from the clock, so it is often wise to adopt universal +time by setting the 'TZ' environment variable to 'UTC0' before embarking +on calendrical calculations. + + +File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats + +7.8 Pure numbers in date strings +================================ + +The precise interpretation of a pure decimal number depends on the +context in the date string. + + If the decimal number is of the form YYYYMMDD and no other calendar +date item (*note Calendar date items::) appears before it in the date +string, then YYYY is read as the year, MM as the month number and DD as +the day of the month, for the specified calendar date. + + If the decimal number is of the form HHMM and no other time of day +item appears before it in the date string, then HH is read as the hour +of the day and MM as the minute of the hour, for the specified time of +day. MM can also be omitted. + + If both a calendar date and a time of day appear to the left of a +number in the date string, but no relative item, then the number +overrides the year. + + +File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats + +7.9 Seconds since the Epoch +=========================== + +If you precede a number with '@', it represents an internal time stamp +as a count of seconds. The number can contain an internal decimal point +(either '.' or ','); any excess precision not supported by the internal +representation is truncated toward minus infinity. Such a number cannot +be combined with any other date item, as it specifies a complete time +stamp. + + Internally, computer times are represented as a count of seconds +since an epoch--a well-defined point of time. On GNU and POSIX systems, +the epoch is 1970-01-01 00:00:00 UTC, so '@0' represents this time, '@1' +represents 1970-01-01 00:00:01 UTC, and so forth. GNU and most other +POSIX-compliant systems support such times as an extension to POSIX, +using negative counts, so that '@-1' represents 1969-12-31 23:59:59 UTC. + + Traditional Unix systems count seconds with 32-bit two's-complement +integers and can represent times from 1901-12-13 20:45:52 through +2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of +seconds with nanosecond subcounts, and can represent all the times in +the known lifetime of the universe to a resolution of 1 nanosecond. + + On most hosts, these counts ignore the presence of leap seconds. For +example, on most hosts '@915148799' represents 1998-12-31 23:59:59 UTC, +'@915148800' represents 1999-01-01 00:00:00 UTC, and there is no way to +represent the intervening leap second 1998-12-31 23:59:60 UTC. + + +File: tar.info, Node: Specifying time zone rules, Next: Authors of parse_datetime, Prev: Seconds since the Epoch, Up: Date input formats + +7.10 Specifying time zone rules +=============================== + +Normally, dates are interpreted using the rules of the current time +zone, which in turn are specified by the 'TZ' environment variable, or +by a system default if 'TZ' is not set. To specify a different set of +default time zone rules that apply just to one date, start the date with +a string of the form 'TZ="RULE"'. The two quote characters ('"') must +be present in the date, and any quotes or backslashes within RULE must +be escaped by a backslash. + + For example, with the GNU 'date' command you can answer the question +"What time is it in New York when a Paris clock shows 6:30am on October +31, 2004?" by using a date beginning with 'TZ="Europe/Paris"' as shown +in the following shell transcript: + + $ export TZ="America/New_York" + $ date --date='TZ="Europe/Paris" 2004-10-31 06:30' + Sun Oct 31 01:30:00 EDT 2004 + + In this example, the '--date' operand begins with its own 'TZ' +setting, so the rest of that operand is processed according to +'Europe/Paris' rules, treating the string '2004-10-31 06:30' as if it +were in Paris. However, since the output of the 'date' command is +processed according to the overall time zone rules, it uses New York +time. (Paris was normally six hours ahead of New York in 2004, but this +example refers to a brief Halloween period when the gap was five hours.) + + A 'TZ' value is a rule that typically names a location in the 'tz' +database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of +location names appears in the TWiki Date and Time Gateway +(http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a +colon before a location name in a 'TZ' setting, e.g., +'TZ=":America/New_York"'. + + The 'tz' database includes a wide variety of locations ranging from +'Arctic/Longyearbyen' to 'Antarctica/South_Pole', but if you are at sea +and have your own private time zone, or if you are using a non-GNU host +that does not support the 'tz' database, you may need to use a POSIX +rule instead. Simple POSIX rules like 'UTC0' specify a time zone +without daylight saving time; other rules can specify simple daylight +saving regimes. *Note Specifying the Time Zone with 'TZ': (libc)TZ +Variable. + + +File: tar.info, Node: Authors of parse_datetime, Prev: Specifying time zone rules, Up: Date input formats + +7.11 Authors of 'parse_datetime' +================================ + +'parse_datetime' started life as 'getdate', as originally implemented by +Steven M. Bellovin (<smb@research.att.com>) while at the University of +North Carolina at Chapel Hill. The code was later tweaked by a couple +of people on Usenet, then completely overhauled by Rich $alz +(<rsalz@bbn.com>) and Jim Berets (<jberets@bbn.com>) in August, 1990. +Various revisions for the GNU system were made by David MacKenzie, Jim +Meyering, Paul Eggert and others, including renaming it to 'get_date' to +avoid a conflict with the alternative Posix function 'getdate', and a +later rename to 'parse_datetime'. The Posix function 'getdate' can +parse more locale-specific dates using 'strptime', but relies on an +environment variable and external file, and lacks the thread-safety of +'parse_datetime'. + + This chapter was originally produced by Franc,ois Pinard +(<pinard@iro.umontreal.ca>) from the 'parse_datetime.y' source code, and +then edited by K. Berry (<kb@cs.umb.edu>). + + +File: tar.info, Node: Formats, Next: Media, Prev: Date input formats, Up: Top + +8 Controlling the Archive Format +******************************** + +Due to historical reasons, there are several formats of tar archives. +All of them are based on the same principles, but have some subtle +differences that often make them incompatible with each other. + + GNU tar is able to create and handle archives in a variety of +formats. The most frequently used formats are (in alphabetical order): + +gnu + Format used by GNU 'tar' versions up to 1.13.25. This format + derived from an early POSIX standard, adding some improvements such + as sparse file handling and incremental archives. Unfortunately + these features were implemented in a way incompatible with other + archive formats. + + Archives in 'gnu' format are able to hold file names of unlimited + length. + +oldgnu + Format used by GNU 'tar' of versions prior to 1.12. + +v7 + Archive format, compatible with the V7 implementation of tar. This + format imposes a number of limitations. The most important of them + are: + + 1. The maximum length of a file name is limited to 99 characters. + 2. The maximum length of a symbolic link is limited to 99 + characters. + 3. It is impossible to store special files (block and character + devices, fifos etc.) + 4. Maximum value of user or group ID is limited to 2097151 + (7777777 octal) + 5. V7 archives do not contain symbolic ownership information + (user and group name of the file owner). + + This format has traditionally been used by Automake when producing + Makefiles. This practice will change in the future, in the + meantime, however this means that projects containing file names + more than 99 characters long will not be able to use GNU 'tar' 1.29 + and Automake prior to 1.9. + +ustar + Archive format defined by POSIX.1-1988 specification. It stores + symbolic ownership information. It is also able to store special + files. However, it imposes several restrictions as well: + + 1. The maximum length of a file name is limited to 256 + characters, provided that the file name can be split at a + directory separator in two parts, first of them being at most + 155 bytes long. So, in most cases the maximum file name + length will be shorter than 256 characters. + 2. The maximum length of a symbolic link name is limited to 100 + characters. + 3. Maximum size of a file the archive is able to accommodate is + 8GB + 4. Maximum value of UID/GID is 2097151. + 5. Maximum number of bits in device major and minor numbers is + 21. + +star + Format used by Jo"rg Schilling 'star' implementation. GNU 'tar' is + able to read 'star' archives but currently does not produce them. + +posix + Archive format defined by POSIX.1-2001 specification. This is the + most flexible and feature-rich format. It does not impose any + restrictions on file sizes or file name lengths. This format is + quite recent, so not all tar implementations are able to handle it + properly. However, this format is designed in such a way that any + tar implementation able to read 'ustar' archives will be able to + read most 'posix' archives as well, with the only exception that + any additional information (such as long file names etc.) will in + such case be extracted as plain text files along with the files it + refers to. + + This archive format will be the default format for future versions + of GNU 'tar'. + + The following table summarizes the limitations of each of these +formats: + +Format UID File Size File Name Devn +-------------------------------------------------------------------- +gnu 1.8e19 Unlimited Unlimited 63 +oldgnu 1.8e19 Unlimited Unlimited 63 +v7 2097151 8GB 99 n/a +ustar 2097151 8GB 256 21 +posix Unlimited Unlimited Unlimited Unlimited + + The default format for GNU 'tar' is defined at compilation time. You +may check it by running 'tar --help', and examining the last lines of +its output. Usually, GNU 'tar' is configured to create archives in +'gnu' format, however, future version will switch to 'posix'. + +* Menu: + +* Compression:: Using Less Space through Compression +* Attributes:: Handling File Attributes +* Portability:: Making 'tar' Archives More Portable +* cpio:: Comparison of 'tar' and 'cpio' + + +File: tar.info, Node: Compression, Next: Attributes, Up: Formats + +8.1 Using Less Space through Compression +======================================== + +* Menu: + +* gzip:: Creating and Reading Compressed Archives +* sparse:: Archiving Sparse Files + + +File: tar.info, Node: gzip, Next: sparse, Up: Compression + +8.1.1 Creating and Reading Compressed Archives +---------------------------------------------- + +GNU 'tar' is able to create and read compressed archives. It supports a +wide variety of compression programs, namely: 'gzip', 'bzip2', 'lzip', +'lzma', 'lzop', 'xz' and traditional 'compress'. The latter is +supported mostly for backward compatibility, and we recommend against +using it, because it is by far less effective than the other compression +programs(1). + + Creating a compressed archive is simple: you just specify a +"compression option" along with the usual archive creation commands. +The compression option is '-z' ('--gzip') to create a 'gzip' compressed +archive, '-j' ('--bzip2') to create a 'bzip2' compressed archive, +'--lzip' to create an lzip compressed archive, '-J' ('--xz') to create +an XZ archive, '--lzma' to create an LZMA compressed archive, '--lzop' +to create an LSOP archive, and '-Z' ('--compress') to use 'compress' +program. For example: + + $ tar czf archive.tar.gz . + + You can also let GNU 'tar' select the compression program based on +the suffix of the archive file name. This is done using +'--auto-compress' ('-a') command line option. For example, the +following invocation will use 'bzip2' for compression: + + $ tar caf archive.tar.bz2 . + +whereas the following one will use 'lzma': + + $ tar caf archive.tar.lzma . + + For a complete list of file name suffixes recognized by GNU 'tar', +see *note auto-compress::. + + Reading compressed archive is even simpler: you don't need to specify +any additional options as GNU 'tar' recognizes its format automatically. +Thus, the following commands will list and extract the archive created +in previous example: + + # List the compressed archive + $ tar tf archive.tar.gz + # Extract the compressed archive + $ tar xf archive.tar.gz + + The format recognition algorithm is based on "signatures", a special +byte sequences in the beginning of file, that are specific for certain +compression formats. If this approach fails, 'tar' falls back to using +archive name suffix to determine its format (*note auto-compress::, for +a list of recognized suffixes). + + Some compression programs are able to handle different compression +formats. GNU 'tar' uses this, if the principal decompressor for the +given format is not available. For example, if 'compress' is not +installed, 'tar' will try to use 'gzip'. As of version 1.29 the +following alternatives are tried(2): + +Format Main decompressor Alternatives +--------------------------------------------------------------------- +compress compress gzip +lzma lzma xz +bzip2 bzip2 lbzip2 + + The only case when you have to specify a decompression option while +reading the archive is when reading from a pipe or from a tape drive +that does not support random access. However, in this case GNU 'tar' +will indicate which option you should use. For example: + + $ cat archive.tar.gz | tar tf - + tar: Archive is compressed. Use -z option + tar: Error is not recoverable: exiting now + + If you see such diagnostics, just add the suggested option to the +invocation of GNU 'tar': + + $ cat archive.tar.gz | tar tzf - + + Notice also, that there are several restrictions on operations on +compressed archives. First of all, compressed archives cannot be +modified, i.e., you cannot update ('--update', alias '-u') them or +delete ('--delete') members from them or add ('--append', alias '-r') +members to them. Likewise, you cannot append another 'tar' archive to a +compressed archive using '--concatenate' ('-A'). Secondly, multi-volume +archives cannot be compressed. + + The following options allow to select a particular compressor +program: + +'-z' +'--gzip' +'--ungzip' + Filter the archive through 'gzip'. + +'-J' +'--xz' + Filter the archive through 'xz'. + +'-j' +'--bzip2' + Filter the archive through 'bzip2'. + +'--lzip' + Filter the archive through 'lzip'. + +'--lzma' + Filter the archive through 'lzma'. + +'--lzop' + Filter the archive through 'lzop'. + +'-Z' +'--compress' +'--uncompress' + Filter the archive through 'compress'. + + When any of these options is given, GNU 'tar' searches the compressor +binary in the current path and invokes it. The name of the compressor +program is specified at compilation time using a corresponding +'--with-COMPNAME' option to 'configure', e.g. '--with-bzip2' to select +a specific 'bzip2' binary. *Note lbzip2::, for a detailed discussion. + + The output produced by 'tar --help' shows the actual compressor names +along with each of these options. + + You can use any of these options on physical devices (tape drives, +etc.) and remote files as well as on normal files; data to or from such +devices or remote files is reblocked by another copy of the 'tar' +program to enforce the specified (or default) record size. The default +compression parameters are used. You can override them by using the +'-I' option (see below), e.g.: + + $ tar -cf archive.tar.gz -I 'gzip -9 -n' subdir + +A more traditional way to do this is to use a pipe: + + $ tar cf - subdir | gzip -9 -n > archive.tar.gz + + Compressed archives are easily corrupted, because compressed files +have little redundancy. The adaptive nature of the compression scheme +means that the compression tables are implicitly spread all over the +archive. If you lose a few blocks, the dynamic construction of the +compression tables becomes unsynchronized, and there is little chance +that you could recover later in the archive. + + Other compression options provide better control over creating +compressed archives. These are: + +'--auto-compress' +'-a' + Select a compression program to use by the archive file name + suffix. The following suffixes are recognized: + + Suffix Compression program + ------------------------------------------------------------------- + '.gz' 'gzip' + '.tgz' 'gzip' + '.taz' 'gzip' + '.Z' 'compress' + '.taZ' 'compress' + '.bz2' 'bzip2' + '.tz2' 'bzip2' + '.tbz2' 'bzip2' + '.tbz' 'bzip2' + '.lz' 'lzip' + '.lzma' 'lzma' + '.tlz' 'lzma' + '.lzo' 'lzop' + '.xz' 'xz' + +'--use-compress-program=COMMAND' +'-I=COMMAND' + Use external compression program COMMAND. Use this option if you + want to specify options for the compression program, or if you are + not happy with the compression program associated with the suffix + at compile time, or if you have a compression program that GNU + 'tar' does not support. The COMMAND argument is a valid command + invocation, as you would type it at the command line prompt, with + any additional options as needed. Enclose it in quotes if it + contains white space (*note Running External Commands: external.). + + The COMMAND should follow two conventions: + + First, when invoked without additional options, it should read data + from standard input, compress it and output it on standard output. + + Secondly, if invoked with the additional '-d' option, it should do + exactly the opposite, i.e., read the compressed data from the + standard input and produce uncompressed data on the standard + output. + + The latter requirement means that you must not use the '-d' option + as a part of the COMMAND itself. + + The '--use-compress-program' option, in particular, lets you +implement your own filters, not necessarily dealing with +compression/decompression. For example, suppose you wish to implement +PGP encryption on top of compression, using 'gpg' (*note gpg: +(gpg)Top.). The following script does that: + + #! /bin/sh + case $1 in + -d) gpg --decrypt - | gzip -d -c;; + '') gzip -c | gpg -s;; + *) echo "Unknown option $1">&2; exit 1;; + esac + + Suppose you name it 'gpgz' and save it somewhere in your 'PATH'. +Then the following command will create a compressed archive signed with +your private key: + + $ tar -cf foo.tar.gpgz -Igpgz . + +Likewise, the command below will list its contents: + + $ tar -tf foo.tar.gpgz -Igpgz . + +* Menu: + +* lbzip2:: Using lbzip2 with GNU 'tar'. + + ---------- Footnotes ---------- + + (1) It also had patent problems in the past. + + (2) To verbosely trace the decompressor selection, use the +'--warning=decompress-program' option (*note decompress-program: +warnings.). + + +File: tar.info, Node: lbzip2, Up: gzip + +8.1.1.1 Using lbzip2 with GNU 'tar'. +.................................... + +'Lbzip2' is a multithreaded utility for handling 'bzip2' compression, +written by Laszlo Ersek. It makes use of multiple processors to speed +up its operation and in general works considerably faster than 'bzip2'. +For a detailed description of 'lbzip2' see +<http://freshmeat.net/projects/lbzip2> and lbzip2: parallel bzip2 +utility +(http://www.linuxinsight.com/lbzip2-parallel-bzip2-utility.html). + + Recent versions of 'lbzip2' are mostly command line compatible with +'bzip2', which makes it possible to automatically invoke it via the +'--bzip2' GNU 'tar' command line option. To do so, GNU 'tar' must be +configured with the '--with-bzip2' command line option, like this: + + $ ./configure --with-bzip2=lbzip2 [OTHER-OPTIONS] + + Once configured and compiled this way, 'tar --help' will show the +following: + + $ tar --help | grep -- --bzip2 + -j, --bzip2 filter the archive through lbzip2 + +which means that running 'tar --bzip2' will invoke 'lbzip2'. + + +File: tar.info, Node: sparse, Prev: gzip, Up: Compression + +8.1.2 Archiving Sparse Files +---------------------------- + +Files in the file system occasionally have "holes". A "hole" in a file +is a section of the file's contents which was never written. The +contents of a hole reads as all zeros. On many operating systems, +actual disk storage is not allocated for holes, but they are counted in +the length of the file. If you archive such a file, 'tar' could create +an archive longer than the original. To have 'tar' attempt to recognize +the holes in a file, use '--sparse' ('-S'). When you use this option, +then, for any file using less disk space than would be expected from its +length, 'tar' searches the file for holes. It then records in the +archive for the file where the holes (consecutive stretches of zeros) +are, and only archives the "real contents" of the file. On extraction +(using '--sparse' is not needed on extraction) any such files have also +holes created wherever the holes were found. Thus, if you use +'--sparse', 'tar' archives won't take more space than the original. + + GNU 'tar' uses two methods for detecting holes in sparse files. +These methods are described later in this subsection. + +'-S' +'--sparse' + This option instructs 'tar' to test each file for sparseness before + attempting to archive it. If the file is found to be sparse it is + treated specially, thus allowing to decrease the amount of space + used by its image in the archive. + + This option is meaningful only when creating or updating archives. + It has no effect on extraction. + + Consider using '--sparse' when performing file system backups, to +avoid archiving the expanded forms of files stored sparsely in the +system. + + Even if your system has no sparse files currently, some may be +created in the future. If you use '--sparse' while making file system +backups as a matter of course, you can be assured the archive will never +take more space on the media than the files take on disk (otherwise, +archiving a disk filled with sparse files might take hundreds of tapes). +*Note Incremental Dumps::. + + However, be aware that '--sparse' option may present a serious +drawback. Namely, in order to determine the positions of holes in a +file 'tar' may have to read it before trying to archive it, so in total +the file may be read *twice*. This may happen when your OS or your FS +does not support "SEEK_HOLE/SEEK_DATA" feature in "lseek" (See +'--hole-detection', below). + + When using 'POSIX' archive format, GNU 'tar' is able to store sparse +files using in three distinct ways, called "sparse formats". A sparse +format is identified by its "number", consisting, as usual of two +decimal numbers, delimited by a dot. By default, format '1.0' is used. +If, for some reason, you wish to use an earlier format, you can select +it using '--sparse-version' option. + +'--sparse-version=VERSION' + Select the format to store sparse files in. Valid VERSION values + are: '0.0', '0.1' and '1.0'. *Note Sparse Formats::, for a + detailed description of each format. + + Using '--sparse-format' option implies '--sparse'. + +'--hole-detection=METHOD' + Enforce concrete hole detection method. Before the real contents + of sparse file are stored, 'tar' needs to gather knowledge about + file sparseness. This is because it needs to have the file's map + of holes stored into tar header before it starts archiving the file + contents. Currently, two methods of hole detection are + implemented: + + * '--hole-detection=seek' Seeking the file for data and holes. + It uses enhancement of the 'lseek' system call ('SEEK_HOLE' + and 'SEEK_DATA') which is able to reuse file system knowledge + about sparse file contents - so the detection is usually very + fast. To use this feature, your file system and operating + system must support it. At the time of this writing (2015) + this feature, in spite of not being accepted by POSIX, is + fairly widely supported by different operating systems. + + * '--hole-detection=raw' Reading byte-by-byte the whole sparse + file before the archiving. This method detects holes like + consecutive stretches of zeroes. Comparing to the previous + method, it is usually much slower, although more portable. + + When no '--hole-detection' option is given, 'tar' uses the 'seek', if +supported by the operating system. + + Using '--hole-detection' option implies '--sparse'. + + +File: tar.info, Node: Attributes, Next: Portability, Prev: Compression, Up: Formats + +8.2 Handling File Attributes +============================ + +When 'tar' reads files, it updates their access times. To avoid this, +use the '--atime-preserve[=METHOD]' option, which can either reset the +access time retroactively or avoid changing it in the first place. + +'--atime-preserve' +'--atime-preserve=replace' +'--atime-preserve=system' + Preserve the access times of files that are read. This works only + for files that you own, unless you have superuser privileges. + + '--atime-preserve=replace' works on most systems, but it also + restores the data modification time and updates the status change + time. Hence it doesn't interact with incremental dumps nicely + (*note Incremental Dumps::), and it can set access or data + modification times incorrectly if other programs access the file + while 'tar' is running. + + '--atime-preserve=system' avoids changing the access time in the + first place, if the operating system supports this. Unfortunately, + this may or may not work on any given operating system or file + system. If 'tar' knows for sure it won't work, it complains right + away. + + Currently '--atime-preserve' with no operand defaults to + '--atime-preserve=replace', but this is intended to change to + '--atime-preserve=system' when the latter is better-supported. + +'-m' +'--touch' + Do not extract data modification time. + + When this option is used, 'tar' leaves the data modification times + of the files it extracts as the times when the files were + extracted, instead of setting it to the times recorded in the + archive. + + This option is meaningless with '--list' ('-t'). + +'--same-owner' + Create extracted files with the same ownership they have in the + archive. + + This is the default behavior for the superuser, so this option is + meaningful only for non-root users, when 'tar' is executed on those + systems able to give files away. This is considered as a security + flaw by many people, at least because it makes quite difficult to + correctly account users for the disk space they occupy. Also, the + 'suid' or 'sgid' attributes of files are easily and silently lost + when files are given away. + + When writing an archive, 'tar' writes the user ID and user name + separately. If it can't find a user name (because the user ID is + not in '/etc/passwd'), then it does not write one. When restoring, + it tries to look the name (if one was written) up in '/etc/passwd'. + If it fails, then it uses the user ID stored in the archive + instead. + +'--no-same-owner' +'-o' + Do not attempt to restore ownership when extracting. This is the + default behavior for ordinary users, so this option has an effect + only for the superuser. + +'--numeric-owner' + The '--numeric-owner' option allows (ANSI) archives to be written + without user/group name information or such information to be + ignored when extracting. It effectively disables the generation + and/or use of user/group name information. This option forces + extraction using the numeric ids from the archive, ignoring the + names. + + This is useful in certain circumstances, when restoring a backup + from an emergency floppy with different passwd/group files for + example. It is otherwise impossible to extract files with the + right ownerships if the password file in use during the extraction + does not match the one belonging to the file system(s) being + extracted. This occurs, for example, if you are restoring your + files after a major crash and had booted from an emergency floppy + with no password file or put your disk into another machine to do + the restore. + + The numeric ids are _always_ saved into 'tar' archives. The + identifying names are added at create time when provided by the + system, unless '--format=oldgnu' is used. Numeric ids could be + used when moving archives between a collection of machines using a + centralized management for attribution of numeric ids to users and + groups. This is often made through using the NIS capabilities. + + When making a 'tar' file for distribution to other sites, it is + sometimes cleaner to use a single owner for all files in the + distribution, and nicer to specify the write permission bits of the + files as stored in the archive independently of their actual value + on the file system. The way to prepare a clean distribution is + usually to have some Makefile rule creating a directory, copying + all needed files in that directory, then setting ownership and + permissions as wanted (there are a lot of possible schemes), and + only then making a 'tar' archive out of this directory, before + cleaning everything out. Of course, we could add a lot of options + to GNU 'tar' for fine tuning permissions and ownership. This is + not the good way, I think. GNU 'tar' is already crowded with + options and moreover, the approach just explained gives you a great + deal of control already. + +'-p' +'--same-permissions' +'--preserve-permissions' + Extract all protection information. + + This option causes 'tar' to set the modes (access permissions) of + extracted files exactly as recorded in the archive. If this option + is not used, the current 'umask' setting limits the permissions on + extracted files. This option is by default enabled when 'tar' is + executed by a superuser. + + This option is meaningless with '--list' ('-t'). + + +File: tar.info, Node: Portability, Next: cpio, Prev: Attributes, Up: Formats + +8.3 Making 'tar' Archives More Portable +======================================= + +Creating a 'tar' archive on a particular system that is meant to be +useful later on many other machines and with other versions of 'tar' is +more challenging than you might think. 'tar' archive formats have been +evolving since the first versions of Unix. Many such formats are +around, and are not always compatible with each other. This section +discusses a few problems, and gives some advice about making 'tar' +archives more portable. + + One golden rule is simplicity. For example, limit your 'tar' +archives to contain only regular files and directories, avoiding other +kind of special files. Do not attempt to save sparse files or +contiguous files as such. Let's discuss a few more problems, in turn. + +* Menu: + +* Portable Names:: Portable Names +* dereference:: Symbolic Links +* hard links:: Hard Links +* old:: Old V7 Archives +* ustar:: Ustar Archives +* gnu:: GNU and old GNU format archives. +* posix:: POSIX archives +* Checksumming:: Checksumming Problems +* Large or Negative Values:: Large files, negative time stamps, etc. +* Other Tars:: How to Extract GNU-Specific Data Using + Other 'tar' Implementations + + +File: tar.info, Node: Portable Names, Next: dereference, Up: Portability + +8.3.1 Portable Names +-------------------- + +Use portable file and member names. A name is portable if it contains +only ASCII letters and digits, '/', '.', '_', and '-'; it cannot be +empty, start with '-' or '//', or contain '/-'. Avoid deep directory +nesting. For portability to old Unix hosts, limit your file name +components to 14 characters or less. + + If you intend to have your 'tar' archives to be read under MSDOS, you +should not rely on case distinction for file names, and you might use +the GNU 'doschk' program for helping you further diagnosing illegal +MSDOS names, which are even more limited than System V's. + + +File: tar.info, Node: dereference, Next: hard links, Prev: Portable Names, Up: Portability + +8.3.2 Symbolic Links +-------------------- + +Normally, when 'tar' archives a symbolic link, it writes a block to the +archive naming the target of the link. In that way, the 'tar' archive +is a faithful record of the file system contents. When '--dereference' +('-h') is used with '--create' ('-c'), 'tar' archives the files symbolic +links point to, instead of the links themselves. + + When creating portable archives, use '--dereference' ('-h'): some +systems do not support symbolic links, and moreover, your distribution +might be unusable if it contains unresolved symbolic links. + + When reading from an archive, the '--dereference' ('-h') option +causes 'tar' to follow an already-existing symbolic link when 'tar' +writes or reads a file named in the archive. Ordinarily, 'tar' does not +follow such a link, though it may remove the link before writing a new +file. *Note Dealing with Old Files::. + + The '--dereference' option is unsafe if an untrusted user can modify +directories while 'tar' is running. *Note Security::. + + +File: tar.info, Node: hard links, Next: old, Prev: dereference, Up: Portability + +8.3.3 Hard Links +---------------- + +Normally, when 'tar' archives a hard link, it writes a block to the +archive naming the target of the link (a '1' type block). In that way, +the actual file contents is stored in file only once. For example, +consider the following two files: + + $ ls -l + -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one + -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden + + Here, 'jeden' is a link to 'one'. When archiving this directory with +a verbose level 2, you will get an output similar to the following: + + $ tar cvvf ../archive.tar . + drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./ + -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden + hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden + + The last line shows that, instead of storing two copies of the file, +'tar' stored it only once, under the name 'jeden', and stored file 'one' +as a hard link to this file. + + It may be important to know that all hard links to the given file are +stored in the archive. For example, this may be necessary for exact +reproduction of the file system. The following option does that: + +'--check-links' +'-l' + Check the number of links dumped for each processed file. If this + number does not match the total number of hard links for the file, + print a warning message. + + For example, trying to archive only file 'jeden' with this option +produces the following diagnostics: + + $ tar -c -f ../archive.tar -l jeden + tar: Missing links to 'jeden'. + + Although creating special records for hard links helps keep a +faithful record of the file system contents and makes archives more +compact, it may present some difficulties when extracting individual +members from the archive. For example, trying to extract file 'one' +from the archive created in previous examples produces, in the absence +of file 'jeden': + + $ tar xf archive.tar ./one + tar: ./one: Cannot hard link to './jeden': No such file or directory + tar: Error exit delayed from previous errors + + The reason for this behavior is that 'tar' cannot seek back in the +archive to the previous member (in this case, 'one'), to extract it(1). +If you wish to avoid such problems at the cost of a bigger archive, use +the following option: + +'--hard-dereference' + Dereference hard links and store the files they refer to. + + For example, trying this option on our two sample files, we get two +copies in the archive, each of which can then be extracted independently +of the other: + + $ tar -c -vv -f ../archive.tar --hard-dereference . + drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./ + -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden + -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one + + ---------- Footnotes ---------- + + (1) There are plans to fix this in future releases. + + +File: tar.info, Node: old, Next: ustar, Prev: hard links, Up: Portability + +8.3.4 Old V7 Archives +--------------------- + +Certain old versions of 'tar' cannot handle additional information +recorded by newer 'tar' programs. To create an archive in V7 format +(not ANSI), which can be read by these old versions, specify the +'--format=v7' option in conjunction with the '--create' ('-c') ('tar' +also accepts '--portability' or '--old-archive' for this option). When +you specify it, 'tar' leaves out information about directories, pipes, +fifos, contiguous files, and device files, and specifies file ownership +by group and user IDs instead of group and user names. + + When updating an archive, do not use '--format=v7' unless the archive +was created using this option. + + In most cases, a _new_ format archive can be read by an _old_ 'tar' +program without serious trouble, so this option should seldom be needed. +On the other hand, most modern 'tar's are able to read old format +archives, so it might be safer for you to always use '--format=v7' for +your distributions. Notice, however, that 'ustar' format is a better +alternative, as it is free from many of 'v7''s drawbacks. + + +File: tar.info, Node: ustar, Next: gnu, Prev: old, Up: Portability + +8.3.5 Ustar Archive Format +-------------------------- + +The archive format defined by the POSIX.1-1988 specification is called +'ustar'. Although it is more flexible than the V7 format, it still has +many restrictions (*note ustar: Formats, for the detailed description of +'ustar' format). Along with V7 format, 'ustar' format is a good choice +for archives intended to be read with other implementations of 'tar'. + + To create an archive in 'ustar' format, use the '--format=ustar' +option in conjunction with '--create' ('-c'). + + +File: tar.info, Node: gnu, Next: posix, Prev: ustar, Up: Portability + +8.3.6 GNU and old GNU 'tar' format +---------------------------------- + +GNU 'tar' was based on an early draft of the POSIX 1003.1 'ustar' +standard. GNU extensions to 'tar', such as the support for file names +longer than 100 characters, use portions of the 'tar' header record +which were specified in that POSIX draft as unused. Subsequent changes +in POSIX have allocated the same parts of the header record for other +purposes. As a result, GNU 'tar' format is incompatible with the +current POSIX specification, and with 'tar' programs that follow it. + + In the majority of cases, 'tar' will be configured to create this +format by default. This will change in future releases, since we plan +to make 'POSIX' format the default. + + To force creation a GNU 'tar' archive, use option '--format=gnu'. + + +File: tar.info, Node: posix, Next: Checksumming, Prev: gnu, Up: Portability + +8.3.7 GNU 'tar' and POSIX 'tar' +------------------------------- + +Starting from version 1.14 GNU 'tar' features full support for +POSIX.1-2001 archives. + + A POSIX conformant archive will be created if 'tar' was given +'--format=posix' ('--format=pax') option. No special option is required +to read and extract from a POSIX archive. + +* Menu: + +* PAX keywords:: Controlling Extended Header Keywords. + + +File: tar.info, Node: PAX keywords, Up: posix + +8.3.7.1 Controlling Extended Header Keywords +............................................ + +'--pax-option=KEYWORD-LIST' + Handle keywords in PAX extended headers. This option is equivalent + to '-o' option of the 'pax' utility. + + KEYWORD-LIST is a comma-separated list of keyword options, each +keyword option taking one of the following forms: + +'delete=PATTERN' + When used with one of archive-creation commands, this option + instructs 'tar' to omit from extended header records that it + produces any keywords matching the string PATTERN. + + When used in extract or list mode, this option instructs tar to + ignore any keywords matching the given PATTERN in the extended + header records. In both cases, matching is performed using the + pattern matching notation described in POSIX 1003.2, 3.13 (*note + wildcards::). For example: + + --pax-option delete=security.* + + would suppress security-related information. + +'exthdr.name=STRING' + + This keyword allows user control over the name that is written into + the ustar header blocks for the extended headers. The name is + obtained from STRING after making the following substitutions: + + Meta-character Replaced By + ------------------------------------------------------------ + %d The directory name of the file, + equivalent to the result of the + 'dirname' utility on the translated + file name. + %f The name of the file with the + directory information stripped, + equivalent to the result of the + 'basename' utility on the translated + file name. + %p The process ID of the 'tar' process. + %% A '%' character. + + Any other '%' characters in STRING produce undefined results. + + If no option 'exthdr.name=string' is specified, 'tar' will use the + following default value: + + %d/PaxHeaders.%p/%f + +'exthdr.mtime=VALUE' + + This keyword defines the value of the 'mtime' field that is written + into the ustar header blocks for the extended headers. By default, + the 'mtime' field is set to the modification time of the archive + member described by that extended header (or to the value of the + '--mtime' option, if supplied). + +'globexthdr.name=STRING' + This keyword allows user control over the name that is written into + the ustar header blocks for global extended header records. The + name is obtained from the contents of STRING, after making the + following substitutions: + + Meta-character Replaced By + ------------------------------------------------------------ + %n An integer that represents the + sequence number of the global extended + header record in the archive, starting + at 1. + %p The process ID of the 'tar' process. + %% A '%' character. + + Any other '%' characters in STRING produce undefined results. + + If no option 'globexthdr.name=string' is specified, 'tar' will use + the following default value: + + $TMPDIR/GlobalHead.%p.%n + + where '$TMPDIR' represents the value of the TMPDIR environment + variable. If TMPDIR is not set, 'tar' uses '/tmp'. + +'globexthdr.mtime=VALUE' + + This keyword defines the value of the 'mtime' field that is written + into the ustar header blocks for the global extended headers. By + default, the 'mtime' field is set to the time when 'tar' was + invoked. + +'KEYWORD=VALUE' + When used with one of archive-creation commands, these + keyword/value pairs will be included at the beginning of the + archive in a global extended header record. When used with one of + archive-reading commands, 'tar' will behave as if it has + encountered these keyword/value pairs at the beginning of the + archive in a global extended header record. + +'KEYWORD:=VALUE' + When used with one of archive-creation commands, these + keyword/value pairs will be included as records at the beginning of + an extended header for each file. This is effectively equivalent + to KEYWORD=VALUE form except that it creates no global extended + header records. + + When used with one of archive-reading commands, 'tar' will behave + as if these keyword/value pairs were included as records at the end + of each extended header; thus, they will override any global or + file-specific extended header record keywords of the same names. + For example, in the command: + + tar --format=posix --create \ + --file archive --pax-option gname:=user . + + the group name will be forced to a new value for all files stored + in the archive. + + In any of the forms described above, the VALUE may be a string +enclosed in curly braces. In that case, the string between the braces +is understood either as a textual time representation, as described in +*note Date input formats::, or a name of the existing file, starting +with '/' or '.'. In the latter case, the modification time of that file +is used. + + For example, to set all modification times to the current date, you +use the following option: + + --pax-option='mtime:={now}' + + Note quoting of the option's argument. + + As another example, here is the option that ensures that any two +archives created using it, will be binary equivalent if they have the +same contents: + + --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0 + +If you extract files from such an archive and recreate the archive from +them, you will also need to eliminate changes due to ctime, as shown in +examples below: + + --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,ctime:=0 + +or + + --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,delete=ctime + + +File: tar.info, Node: Checksumming, Next: Large or Negative Values, Prev: posix, Up: Portability + +8.3.8 Checksumming Problems +--------------------------- + +SunOS and HP-UX 'tar' fail to accept archives created using GNU 'tar' +and containing non-ASCII file names, that is, file names having +characters with the eighth bit set, because they use signed checksums, +while GNU 'tar' uses unsigned checksums while creating archives, as per +POSIX standards. On reading, GNU 'tar' computes both checksums and +accepts either of them. It is somewhat worrying that a lot of people +may go around doing backup of their files using faulty (or at least +non-standard) software, not learning about it until it's time to restore +their missing files with an incompatible file extractor, or vice versa. + + GNU 'tar' computes checksums both ways, and accepts either of them on +read, so GNU tar can read Sun tapes even with their wrong checksums. +GNU 'tar' produces the standard checksum, however, raising +incompatibilities with Sun. That is to say, GNU 'tar' has not been +modified to _produce_ incorrect archives to be read by buggy 'tar''s. +I've been told that more recent Sun 'tar' now read standard archives, so +maybe Sun did a similar patch, after all? + + The story seems to be that when Sun first imported 'tar' sources on +their system, they recompiled it without realizing that the checksums +were computed differently, because of a change in the default signing of +'char''s in their compiler. So they started computing checksums +wrongly. When they later realized their mistake, they merely decided to +stay compatible with it, and with themselves afterwards. Presumably, +but I do not really know, HP-UX has chosen their 'tar' archives to be +compatible with Sun's. The current standards do not favor Sun 'tar' +format. In any case, it now falls on the shoulders of SunOS and HP-UX +users to get a 'tar' able to read the good archives they receive. + + +File: tar.info, Node: Large or Negative Values, Next: Other Tars, Prev: Checksumming, Up: Portability + +8.3.9 Large or Negative Values +------------------------------ + + _(This message will disappear, once this node revised.)_ + + The above sections suggest to use 'oldest possible' archive format if +in doubt. However, sometimes it is not possible. If you attempt to +archive a file whose metadata cannot be represented using required +format, GNU 'tar' will print error message and ignore such a file. You +will than have to switch to a format that is able to handle such values. +The format summary table (*note Formats::) will help you to do so. + + In particular, when trying to archive files larger than 8GB or with +timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16 +12:56:31 UTC, you will have to chose between GNU and POSIX archive +formats. When considering which format to choose, bear in mind that the +GNU format uses two's-complement base-256 notation to store values that +do not fit into standard ustar range. Such archives can generally be +read only by a GNU 'tar' implementation. Moreover, they sometimes +cannot be correctly restored on another hosts even by GNU 'tar'. For +example, using two's complement representation for negative time stamps +that assumes a signed 32-bit 'time_t' generates archives that are not +portable to hosts with differing 'time_t' representations. + + On the other hand, POSIX archives, generally speaking, can be +extracted by any tar implementation that understands older ustar format. +The only exception are files larger than 8GB. + + +File: tar.info, Node: Other Tars, Prev: Large or Negative Values, Up: Portability + +8.3.10 How to Extract GNU-Specific Data Using Other 'tar' Implementations +------------------------------------------------------------------------- + +In previous sections you became acquainted with various quirks necessary +to make your archives portable. Sometimes you may need to extract +archives containing GNU-specific members using some third-party 'tar' +implementation or an older version of GNU 'tar'. Of course your best +bet is to have GNU 'tar' installed, but if it is for some reason +impossible, this section will explain how to cope without it. + + When we speak about "GNU-specific" members we mean two classes of +them: members split between the volumes of a multi-volume archive and +sparse members. You will be able to always recover such members if the +archive is in PAX format. In addition split members can be recovered +from archives in old GNU format. The following subsections describe the +required procedures in detail. + +* Menu: + +* Split Recovery:: Members Split Between Volumes +* Sparse Recovery:: Sparse Members + + +File: tar.info, Node: Split Recovery, Next: Sparse Recovery, Up: Other Tars + +8.3.10.1 Extracting Members Split Between Volumes +................................................. + +If a member is split between several volumes of an old GNU format +archive most third party 'tar' implementation will fail to extract it. +To extract it, use 'tarcat' program (*note Tarcat::). This program is +available from GNU 'tar' home page +(http://www.gnu.org/software/tar/utils/tarcat.html). It concatenates +several archive volumes into a single valid archive. For example, if +you have three volumes named from 'vol-1.tar' to 'vol-3.tar', you can do +the following to extract them using a third-party 'tar': + + $ tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf - + + You could use this approach for most (although not all) PAX format +archives as well. However, extracting split members from a PAX archive +is a much easier task, because PAX volumes are constructed in such a way +that each part of a split member is extracted to a different file by +'tar' implementations that are not aware of GNU extensions. More +specifically, the very first part retains its original name, and all +subsequent parts are named using the pattern: + + %d/GNUFileParts.%p/%f.%n + +where symbols preceded by '%' are "macro characters" that have the +following meaning: + +Meta-character Replaced By +------------------------------------------------------------ +%d The directory name of the file, + equivalent to the result of the + 'dirname' utility on its full name. +%f The file name of the file, equivalent + to the result of the 'basename' + utility on its full name. +%p The process ID of the 'tar' process + that created the archive. +%n Ordinal number of this particular + part. + + For example, if the file 'var/longfile' was split during archive +creation between three volumes, and the creator 'tar' process had +process ID '27962', then the member names will be: + + var/longfile + var/GNUFileParts.27962/longfile.1 + var/GNUFileParts.27962/longfile.2 + + When you extract your archive using a third-party 'tar', these files +will be created on your disk, and the only thing you will need to do to +restore your file in its original form is concatenate them in the proper +order, for example: + + $ cd var + $ cat GNUFileParts.27962/longfile.1 \ + GNUFileParts.27962/longfile.2 >> longfile + $ rm -f GNUFileParts.27962 + + Notice, that if the 'tar' implementation you use supports PAX format +archives, it will probably emit warnings about unknown keywords during +extraction. They will look like this: + + Tar file too small + Unknown extended header keyword 'GNU.volume.filename' ignored. + Unknown extended header keyword 'GNU.volume.size' ignored. + Unknown extended header keyword 'GNU.volume.offset' ignored. + +You can safely ignore these warnings. + + If your 'tar' implementation is not PAX-aware, you will get more +warnings and more files generated on your disk, e.g.: + + $ tar xf vol-1.tar + var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as + normal file + Unexpected EOF in archive + $ tar xf vol-2.tar + tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file + GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type + 'x', extracted as normal file + + Ignore these warnings. The 'PaxHeaders.*' directories created will +contain files with "extended header keywords" describing the extracted +files. You can delete them, unless they describe sparse members. Read +further to learn more about them. + + +File: tar.info, Node: Sparse Recovery, Prev: Split Recovery, Up: Other Tars + +8.3.10.2 Extracting Sparse Members +.................................. + +Any 'tar' implementation will be able to extract sparse members from a +PAX archive. However, the extracted files will be "condensed", i.e., +any zero blocks will be removed from them. When we restore such a +condensed file to its original form, by adding zero blocks (or "holes") +back to their original locations, we call this process "expanding" a +compressed sparse file. + + To expand a file, you will need a simple auxiliary program called +'xsparse'. It is available in source form from GNU 'tar' home page +(http://www.gnu.org/software/tar/utils/xsparse.html). + + Let's begin with archive members in "sparse format version 1.0"(1), +which are the easiest to expand. The condensed file will contain both +file map and file data, so no additional data will be needed to restore +it. If the original file name was 'DIR/NAME', then the condensed file +will be named 'DIR/GNUSparseFile.N/NAME', where N is a decimal +number(2). + + To expand a version 1.0 file, run 'xsparse' as follows: + + $ xsparse cond-file + +where 'cond-file' is the name of the condensed file. The utility will +deduce the name for the resulting expanded file using the following +algorithm: + + 1. If 'cond-file' does not contain any directories, '../cond-file' + will be used; + + 2. If 'cond-file' has the form 'DIR/T/NAME', where both T and NAME are + simple names, with no '/' characters in them, the output file name + will be 'DIR/NAME'. + + 3. Otherwise, if 'cond-file' has the form 'DIR/NAME', the output file + name will be 'NAME'. + + In the unlikely case when this algorithm does not suit your needs, +you can explicitly specify output file name as a second argument to the +command: + + $ xsparse cond-file out-file + + It is often a good idea to run 'xsparse' in "dry run" mode first. In +this mode, the command does not actually expand the file, but verbosely +lists all actions it would be taking to do so. The dry run mode is +enabled by '-n' command line argument: + + $ xsparse -n /home/gray/GNUSparseFile.6058/sparsefile + Reading v.1.0 sparse map + Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to + '/home/gray/sparsefile' + Finished dry run + + To actually expand the file, you would run: + + $ xsparse /home/gray/GNUSparseFile.6058/sparsefile + +The program behaves the same way all UNIX utilities do: it will keep +quiet unless it has something important to tell you (e.g. an error +condition or something). If you wish it to produce verbose output, +similar to that from the dry run mode, use '-v' option: + + $ xsparse -v /home/gray/GNUSparseFile.6058/sparsefile + Reading v.1.0 sparse map + Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to + '/home/gray/sparsefile' + Done + + Additionally, if your 'tar' implementation has extracted the +"extended headers" for this file, you can instruct 'xstar' to use them +in order to verify the integrity of the expanded file. The option '-x' +sets the name of the extended header file to use. Continuing our +example: + + $ xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \ + /home/gray/GNUSparseFile.6058/sparsefile + Reading extended header file + Found variable GNU.sparse.major = 1 + Found variable GNU.sparse.minor = 0 + Found variable GNU.sparse.name = sparsefile + Found variable GNU.sparse.realsize = 217481216 + Reading v.1.0 sparse map + Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to + '/home/gray/sparsefile' + Done + + An "extended header" is a special 'tar' archive header that precedes +an archive member and contains a set of "variables", describing the +member properties that cannot be stored in the standard 'ustar' header. +While optional for expanding sparse version 1.0 members, the use of +extended headers is mandatory when expanding sparse members in older +sparse formats: v.0.0 and v.0.1 (The sparse formats are described in +detail in *note Sparse Formats::.) So, for these formats, the question +is: how to obtain extended headers from the archive? + + If you use a 'tar' implementation that does not support PAX format, +extended headers for each member will be extracted as a separate file. +If we represent the member name as 'DIR/NAME', then the extended header +file will be named 'DIR/PaxHeaders.N/NAME', where N is an integer +number. + + Things become more difficult if your 'tar' implementation does +support PAX headers, because in this case you will have to manually +extract the headers. We recommend the following algorithm: + + 1. Consult the documentation of your 'tar' implementation for an + option that prints "block numbers" along with the archive listing + (analogous to GNU 'tar''s '-R' option). For example, 'star' has + '-block-number'. + + 2. Obtain verbose listing using the 'block number' option, and find + block numbers of the sparse member in question and the member + immediately following it. For example, running 'star' on our + archive we obtain: + + $ star -t -v -block-number -f arc.tar + ... + star: Unknown extended header keyword 'GNU.sparse.size' ignored. + star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored. + star: Unknown extended header keyword 'GNU.sparse.name' ignored. + star: Unknown extended header keyword 'GNU.sparse.map' ignored. + block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile + block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README + ... + + (as usual, ignore the warnings about unknown keywords.) + + 3. Let SIZE be the size of the sparse member, BS be its block number + and BN be the block number of the next member. Compute: + + N = BS - BN - SIZE/512 - 2 + + This number gives the size of the extended header part in tar + "blocks". In our example, this formula gives: '897 - 56 - 425984 / + 512 - 2 = 7'. + + 4. Use 'dd' to extract the headers: + + dd if=ARCHIVE of=HNAME bs=512 skip=BS count=N + + where ARCHIVE is the archive name, HNAME is a name of the file to + store the extended header in, BS and N are computed in previous + steps. + + In our example, this command will be + + $ dd if=arc.tar of=xhdr bs=512 skip=56 count=7 + + Finally, you can expand the condensed file, using the obtained +header: + + $ xsparse -v -x xhdr GNUSparseFile.6058/sparsefile + Reading extended header file + Found variable GNU.sparse.size = 217481216 + Found variable GNU.sparse.numblocks = 208 + Found variable GNU.sparse.name = sparsefile + Found variable GNU.sparse.map = 0,2048,1050624,2048,... + Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile' + Done + + ---------- Footnotes ---------- + + (1) *Note PAX 1::. + + (2) Technically speaking, N is a "process ID" of the 'tar' process +which created the archive (*note PAX keywords::). + + +File: tar.info, Node: cpio, Prev: Portability, Up: Formats + +8.4 Comparison of 'tar' and 'cpio' +================================== + + _(This message will disappear, once this node revised.)_ + + The 'cpio' archive formats, like 'tar', do have maximum file name +lengths. The binary and old ASCII formats have a maximum file length of +256, and the new ASCII and CRC ASCII formats have a max file length of +1024. GNU 'cpio' can read and write archives with arbitrary file name +lengths, but other 'cpio' implementations may crash unexplainedly trying +to read them. + + 'tar' handles symbolic links in the form in which it comes in BSD; +'cpio' doesn't handle symbolic links in the form in which it comes in +System V prior to SVR4, and some vendors may have added symlinks to +their system without enhancing 'cpio' to know about them. Others may +have enhanced it in a way other than the way I did it at Sun, and which +was adopted by AT&T (and which is, I think, also present in the 'cpio' +that Berkeley picked up from AT&T and put into a later BSD release--I +think I gave them my changes). + + (SVR4 does some funny stuff with 'tar'; basically, its 'cpio' can +handle 'tar' format input, and write it on output, and it probably +handles symbolic links. They may not have bothered doing anything to +enhance 'tar' as a result.) + + 'cpio' handles special files; traditional 'tar' doesn't. + + 'tar' comes with V7, System III, System V, and BSD source; 'cpio' +comes only with System III, System V, and later BSD (4.3-tahoe and +later). + + 'tar''s way of handling multiple hard links to a file can handle file +systems that support 32-bit i-numbers (e.g., the BSD file system); +'cpio's way requires you to play some games (in its "binary" format, +i-numbers are only 16 bits, and in its "portable ASCII" format, they're +18 bits--it would have to play games with the "file system ID" field of +the header to make sure that the file system ID/i-number pairs of +different files were always different), and I don't know which 'cpio's, +if any, play those games. Those that don't might get confused and think +two files are the same file when they're not, and make hard links +between them. + + 'tar's way of handling multiple hard links to a file places only one +copy of the link on the tape, but the name attached to that copy is the +_only_ one you can use to retrieve the file; 'cpio's way puts one copy +for every link, but you can retrieve it using any of the names. + + What type of check sum (if any) is used, and how is this + calculated. + + See the attached manual pages for 'tar' and 'cpio' format. 'tar' +uses a checksum which is the sum of all the bytes in the 'tar' header +for a file; 'cpio' uses no checksum. + + If anyone knows why 'cpio' was made when 'tar' was present at the + unix scene, + + It wasn't. 'cpio' first showed up in PWB/UNIX 1.0; no +generally-available version of UNIX had 'tar' at the time. I don't know +whether any version that was generally available _within AT&T_ had +'tar', or, if so, whether the people within AT&T who did 'cpio' knew +about it. + + On restore, if there is a corruption on a tape 'tar' will stop at +that point, while 'cpio' will skip over it and try to restore the rest +of the files. + + The main difference is just in the command syntax and header format. + + 'tar' is a little more tape-oriented in that everything is blocked to +start on a record boundary. + + Is there any differences between the ability to recover crashed + archives between the two of them. (Is there any chance of + recovering crashed archives at all.) + + Theoretically it should be easier under 'tar' since the blocking lets +you find a header with some variation of 'dd skip=NN'. However, modern +'cpio''s and variations have an option to just search for the next file +header after an error with a reasonable chance of resyncing. However, +lots of tape driver software won't allow you to continue past a media +error which should be the only reason for getting out of sync unless a +file changed sizes while you were writing the archive. + + If anyone knows why 'cpio' was made when 'tar' was present at the + unix scene, please tell me about this too. + + Probably because it is more media efficient (by not blocking +everything and using only the space needed for the headers where 'tar' +always uses 512 bytes per file header) and it knows how to archive +special files. + + You might want to look at the freely available alternatives. The +major ones are 'afio', GNU 'tar', and 'pax', each of which have their +own extensions with some backwards compatibility. + + Sparse files were 'tar'red as sparse files (which you can easily +test, because the resulting archive gets smaller, and GNU 'cpio' can no +longer read it). + + +File: tar.info, Node: Media, Next: Reliability and security, Prev: Formats, Up: Top + +9 Tapes and Other Archive Media +******************************* + + _(This message will disappear, once this node revised.)_ + + A few special cases about tape handling warrant more detailed +description. These special cases are discussed below. + + Many complexities surround the use of 'tar' on tape drives. Since +the creation and manipulation of archives located on magnetic tape was +the original purpose of 'tar', it contains many features making such +manipulation easier. + + Archives are usually written on dismountable media--tape cartridges, +mag tapes, or floppy disks. + + The amount of data a tape or disk holds depends not only on its size, +but also on how it is formatted. A 2400 foot long reel of mag tape +holds 40 megabytes of data when formatted at 1600 bits per inch. The +physically smaller EXABYTE tape cartridge holds 2.3 gigabytes. + + Magnetic media are re-usable--once the archive on a tape is no longer +needed, the archive can be erased and the tape or disk used over. Media +quality does deteriorate with use, however. Most tapes or disks should +be discarded when they begin to produce data errors. EXABYTE tape +cartridges should be discarded when they generate an "error count" +(number of non-usable bits) of more than 10k. + + Magnetic media are written and erased using magnetic fields, and +should be protected from such fields to avoid damage to stored data. +Sticking a floppy disk to a filing cabinet using a magnet is probably +not a good idea. + +* Menu: + +* Device:: Device selection and switching +* Remote Tape Server:: +* Common Problems and Solutions:: +* Blocking:: Blocking +* Many:: Many archives on one tape +* Using Multiple Tapes:: Using Multiple Tapes +* label:: Including a Label in the Archive +* verify:: +* Write Protection:: + + +File: tar.info, Node: Device, Next: Remote Tape Server, Up: Media + +9.1 Device Selection and Switching +================================== + + _(This message will disappear, once this node revised.)_ + +'-f [HOSTNAME:]FILE' +'--file=[HOSTNAME:]FILE' + Use archive file or device FILE on HOSTNAME. + + This option is used to specify the file name of the archive 'tar' +works on. + + If the file name is '-', 'tar' reads the archive from standard input +(when listing or extracting), or writes it to standard output (when +creating). If the '-' file name is given when updating an archive, +'tar' will read the original archive from its standard input, and will +write the entire new archive to its standard output. + + If the file name contains a ':', it is interpreted as 'hostname:file +name'. If the HOSTNAME contains an "at" sign ('@'), it is treated as +'user@hostname:file name'. In either case, 'tar' will invoke the +command 'rsh' (or 'remsh') to start up an '/usr/libexec/rmt' on the +remote machine. If you give an alternate login name, it will be given +to the 'rsh'. Naturally, the remote machine must have an executable +'/usr/libexec/rmt'. This program is free software from the University +of California, and a copy of the source code can be found with the +sources for 'tar'; it's compiled and installed by default. The exact +path to this utility is determined when configuring the package. It is +'PREFIX/libexec/rmt', where PREFIX stands for your installation prefix. +This location may also be overridden at runtime by using the +'--rmt-command=COMMAND' option (*Note --rmt-command: Option Summary, for +detailed description of this option. *Note Remote Tape Server::, for +the description of 'rmt' command). + + If this option is not given, but the environment variable 'TAPE' is +set, its value is used; otherwise, old versions of 'tar' used a default +archive name (which was picked when 'tar' was compiled). The default is +normally set up to be the "first" tape drive or other transportable I/O +medium on the system. + + Starting with version 1.11.5, GNU 'tar' uses standard input and +standard output as the default device, and I will not try anymore +supporting automatic device detection at installation time. This was +failing really in too many cases, it was hopeless. This is now +completely left to the installer to override standard input and standard +output for default device, if this seems preferable. Further, I think +_most_ actual usages of 'tar' are done with pipes or disks, not really +tapes, cartridges or diskettes. + + Some users think that using standard input and output is running +after trouble. This could lead to a nasty surprise on your screen if +you forget to specify an output file name--especially if you are going +through a network or terminal server capable of buffering large amounts +of output. We had so many bug reports in that area of configuring +default tapes automatically, and so many contradicting requests, that we +finally consider the problem to be portably intractable. We could of +course use something like '/dev/tape' as a default, but this is _also_ +running after various kind of trouble, going from hung processes to +accidental destruction of real tapes. After having seen all this mess, +using standard input and output as a default really sounds like the only +clean choice left, and a very useful one too. + + GNU 'tar' reads and writes archive in records, I suspect this is the +main reason why block devices are preferred over character devices. +Most probably, block devices are more efficient too. The installer +could also check for 'DEFTAPE' in '<sys/mtio.h>'. + +'--force-local' + Archive file is local even if it contains a colon. + +'--rsh-command=COMMAND' + Use remote COMMAND instead of 'rsh'. This option exists so that + people who use something other than the standard 'rsh' (e.g., a + Kerberized 'rsh') can access a remote device. + + When this command is not used, the shell command found when the + 'tar' program was installed is used instead. This is the first + found of '/usr/ucb/rsh', '/usr/bin/remsh', '/usr/bin/rsh', + '/usr/bsd/rsh' or '/usr/bin/nsh'. The installer may have + overridden this by defining the environment variable 'RSH' _at + installation time_. + +'-[0-7][lmh]' + Specify drive and density. + +'-M' +'--multi-volume' + Create/list/extract multi-volume archive. + + This option causes 'tar' to write a "multi-volume" archive--one + that may be larger than will fit on the medium used to hold it. + *Note Multi-Volume Archives::. + +'-L NUM' +'--tape-length=SIZE[SUF]' + Change tape after writing SIZE units of data. Unless SUF is given, + SIZE is treated as kilobytes, i.e. 'SIZE x 1024' bytes. The + following suffixes alter this behavior: + + Suffix Units Byte Equivalent + ------------------------------------------------------------- + b Blocks SIZE x 512 + B Kilobytes SIZE x 1024 + c Bytes SIZE + G Gigabytes SIZE x 1024^3 + K Kilobytes SIZE x 1024 + k Kilobytes SIZE x 1024 + M Megabytes SIZE x 1024^2 + P Petabytes SIZE x 1024^5 + T Terabytes SIZE x 1024^4 + w Words SIZE x 2 + + Table 9.1: Size Suffixes + + This option might be useful when your tape drivers do not properly + detect end of physical tapes. By being slightly conservative on + the maximum tape length, you might avoid the problem entirely. + +'-F COMMAND' +'--info-script=COMMAND' +'--new-volume-script=COMMAND' + Execute COMMAND at end of each tape. This implies '--multi-volume' + ('-M'). *Note info-script::, for a detailed description of this + option. + + +File: tar.info, Node: Remote Tape Server, Next: Common Problems and Solutions, Prev: Device, Up: Media + +9.2 Remote Tape Server +====================== + +In order to access the tape drive on a remote machine, 'tar' uses the +remote tape server written at the University of California at Berkeley. +The remote tape server must be installed as 'PREFIX/libexec/rmt' on any +machine whose tape drive you want to use. 'tar' calls 'rmt' by running +an 'rsh' or 'remsh' to the remote machine, optionally using a different +login name if one is supplied. + + A copy of the source for the remote tape server is provided. Its +source code can be freely distributed. It is compiled and installed by +default. + + Unless you use the '--absolute-names' ('-P') option, GNU 'tar' will +not allow you to create an archive that contains absolute file names (a +file name beginning with '/'). If you try, 'tar' will automatically +remove the leading '/' from the file names it stores in the archive. It +will also type a warning message telling you what it is doing. + + When reading an archive that was created with a different 'tar' +program, GNU 'tar' automatically extracts entries in the archive which +have absolute file names as if the file names were not absolute. This +is an important feature. A visitor here once gave a 'tar' tape to an +operator to restore; the operator used Sun 'tar' instead of GNU 'tar', +and the result was that it replaced large portions of our '/bin' and +friends with versions from the tape; needless to say, we were unhappy +about having to recover the file system from backup tapes. + + For example, if the archive contained a file '/usr/bin/computoy', GNU +'tar' would extract the file to 'usr/bin/computoy', relative to the +current directory. If you want to extract the files in an archive to +the same absolute names that they had when the archive was created, you +should do a 'cd /' before extracting the files from the archive, or you +should either use the '--absolute-names' option, or use the command 'tar +-C / ...'. + + Some versions of Unix (Ultrix 3.1 is known to have this problem), can +claim that a short write near the end of a tape succeeded, when it +actually failed. This will result in the -M option not working +correctly. The best workaround at the moment is to use a significantly +larger blocking factor than the default 20. + + In order to update an archive, 'tar' must be able to backspace the +archive in order to reread or rewrite a record that was just read (or +written). This is currently possible only on two kinds of files: normal +disk files (or any other file that can be backspaced with 'lseek'), and +industry-standard 9-track magnetic tape (or any other kind of tape that +can be backspaced with the 'MTIOCTOP' 'ioctl'). + + This means that the '--append', '--concatenate', and '--delete' +commands will not work on any other kind of file. Some media simply +cannot be backspaced, which means these commands and options will never +be able to work on them. These non-backspacing media include pipes and +cartridge tape drives. + + Some other media can be backspaced, and 'tar' will work on them once +'tar' is modified to do so. + + Archives created with the '--multi-volume', '--label', and +'--incremental' ('-G') options may not be readable by other version of +'tar'. In particular, restoring a file that was split over a volume +boundary will require some careful work with 'dd', if it can be done at +all. Other versions of 'tar' may also create an empty file whose name +is that of the volume header. Some versions of 'tar' may create normal +files instead of directories archived with the '--incremental' ('-G') +option. + + +File: tar.info, Node: Common Problems and Solutions, Next: Blocking, Prev: Remote Tape Server, Up: Media + +9.3 Some Common Problems and their Solutions +============================================ + +errors from system: +permission denied +no such file or directory +not owner + +errors from 'tar': +directory checksum error +header format error + +errors from media/system: +i/o error +device busy + + +File: tar.info, Node: Blocking, Next: Many, Prev: Common Problems and Solutions, Up: Media + +9.4 Blocking +============ + +"Block" and "record" terminology is rather confused, and it is also +confusing to the expert reader. On the other hand, readers who are new +to the field have a fresh mind, and they may safely skip the next two +paragraphs, as the remainder of this manual uses those two terms in a +quite consistent way. + + John Gilmore, the writer of the public domain 'tar' from which GNU +'tar' was originally derived, wrote (June 1995): + + The nomenclature of tape drives comes from IBM, where I believe + they were invented for the IBM 650 or so. On IBM mainframes, what + is recorded on tape are tape blocks. The logical organization of + data is into records. There are various ways of putting records + into blocks, including 'F' (fixed sized records), 'V' (variable + sized records), 'FB' (fixed blocked: fixed size records, N to a + block), 'VB' (variable size records, N to a block), 'VSB' (variable + spanned blocked: variable sized records that can occupy more than + one block), etc. The 'JCL' 'DD RECFORM=' parameter specified this + to the operating system. + + The Unix man page on 'tar' was totally confused about this. When I + wrote 'PD TAR', I used the historically correct terminology ('tar' + writes data records, which are grouped into blocks). It appears + that the bogus terminology made it into POSIX (no surprise here), + and now Franc,ois has migrated that terminology back into the + source code too. + + The term "physical block" means the basic transfer chunk from or to a +device, after which reading or writing may stop without anything being +lost. In this manual, the term "block" usually refers to a disk +physical block, _assuming_ that each disk block is 512 bytes in length. +It is true that some disk devices have different physical blocks, but +'tar' ignore these differences in its own format, which is meant to be +portable, so a 'tar' block is always 512 bytes in length, and "block" +always mean a 'tar' block. The term "logical block" often represents +the basic chunk of allocation of many disk blocks as a single entity, +which the operating system treats somewhat atomically; this concept is +only barely used in GNU 'tar'. + + The term "physical record" is another way to speak of a physical +block, those two terms are somewhat interchangeable. In this manual, +the term "record" usually refers to a tape physical block, _assuming_ +that the 'tar' archive is kept on magnetic tape. It is true that +archives may be put on disk or used with pipes, but nevertheless, 'tar' +tries to read and write the archive one "record" at a time, whatever the +medium in use. One record is made up of an integral number of blocks, +and this operation of putting many disk blocks into a single tape block +is called "reblocking", or more simply, "blocking". The term "logical +record" refers to the logical organization of many characters into +something meaningful to the application. The term "unit record" +describes a small set of characters which are transmitted whole to or by +the application, and often refers to a line of text. Those two last +terms are unrelated to what we call a "record" in GNU 'tar'. + + When writing to tapes, 'tar' writes the contents of the archive in +chunks known as "records". To change the default blocking factor, use +the '--blocking-factor=512-SIZE' ('-b 512-SIZE') option. Each record +will then be composed of 512-SIZE blocks. (Each 'tar' block is 512 +bytes. *Note Standard::.) Each file written to the archive uses at +least one full record. As a result, using a larger record size can +result in more wasted space for small files. On the other hand, a +larger record size can often be read and written much more efficiently. + + Further complicating the problem is that some tape drives ignore the +blocking entirely. For these, a larger record size can still improve +performance (because the software layers above the tape drive still +honor the blocking), but not as dramatically as on tape drives that +honor blocking. + + When reading an archive, 'tar' can usually figure out the record size +on itself. When this is the case, and a non-standard record size was +used when the archive was created, 'tar' will print a message about a +non-standard blocking factor, and then operate normally(1). On some +tape devices, however, 'tar' cannot figure out the record size itself. +On most of those, you can specify a blocking factor (with +'--blocking-factor') larger than the actual blocking factor, and then +use the '--read-full-records' ('-B') option. (If you specify a blocking +factor with '--blocking-factor' and don't use the '--read-full-records' +option, then 'tar' will not attempt to figure out the recording size +itself.) On some devices, you must always specify the record size +exactly with '--blocking-factor' when reading, because 'tar' cannot +figure it out. In any case, use '--list' ('-t') before doing any +extractions to see whether 'tar' is reading the archive correctly. + + 'tar' blocks are all fixed size (512 bytes), and its scheme for +putting them into records is to put a whole number of them (one or more) +into each record. 'tar' records are all the same size; at the end of +the file there's a block containing all zeros, which is how you tell +that the remainder of the last record(s) are garbage. + + In a standard 'tar' file (no options), the block size is 512 and the +record size is 10240, for a blocking factor of 20. What the +'--blocking-factor' option does is sets the blocking factor, changing +the record size while leaving the block size at 512 bytes. 20 was fine +for ancient 800 or 1600 bpi reel-to-reel tape drives; most tape drives +these days prefer much bigger records in order to stream and not waste +tape. When writing tapes for myself, some tend to use a factor of the +order of 2048, say, giving a record size of around one megabyte. + + If you use a blocking factor larger than 20, older 'tar' programs +might not be able to read the archive, so we recommend this as a limit +to use in practice. GNU 'tar', however, will support arbitrarily large +record sizes, limited only by the amount of virtual memory or the +physical characteristics of the tape device. + +* Menu: + +* Format Variations:: Format Variations +* Blocking Factor:: The Blocking Factor of an Archive + + ---------- Footnotes ---------- + + (1) If this message is not needed, you can turn it off using the +'--warning=no-record-size' option. + + +File: tar.info, Node: Format Variations, Next: Blocking Factor, Up: Blocking + +9.4.1 Format Variations +----------------------- + + _(This message will disappear, once this node revised.)_ + + Format parameters specify how an archive is written on the archive +media. The best choice of format parameters will vary depending on the +type and number of files being archived, and on the media used to store +the archive. + + To specify format parameters when accessing or creating an archive, +you can use the options described in the following sections. If you do +not specify any format parameters, 'tar' uses default parameters. You +cannot modify a compressed archive. If you create an archive with the +'--blocking-factor' option specified (*note Blocking Factor::), you must +specify that blocking-factor when operating on the archive. *Note +Formats::, for other examples of format parameter considerations. + + +File: tar.info, Node: Blocking Factor, Prev: Format Variations, Up: Blocking + +9.4.2 The Blocking Factor of an Archive +--------------------------------------- + + _(This message will disappear, once this node revised.)_ + + The data in an archive is grouped into blocks, which are 512 bytes. +Blocks are read and written in whole number multiples called "records". +The number of blocks in a record (i.e., the size of a record in units of +512 bytes) is called the "blocking factor". The +'--blocking-factor=512-SIZE' ('-b 512-SIZE') option specifies the +blocking factor of an archive. The default blocking factor is typically +20 (i.e., 10240 bytes), but can be specified at installation. To find +out the blocking factor of an existing archive, use 'tar --list +--file=ARCHIVE-NAME'. This may not work on some devices. + + Records are separated by gaps, which waste space on the archive +media. If you are archiving on magnetic tape, using a larger blocking +factor (and therefore larger records) provides faster throughput and +allows you to fit more data on a tape (because there are fewer gaps). +If you are archiving on cartridge, a very large blocking factor (say 126 +or more) greatly increases performance. A smaller blocking factor, on +the other hand, may be useful when archiving small files, to avoid +archiving lots of nulls as 'tar' fills out the archive to the end of the +record. In general, the ideal record size depends on the size of the +inter-record gaps on the tape you are using, and the average size of the +files you are archiving. *Note create::, for information on writing +archives. + + Archives with blocking factors larger than 20 cannot be read by very +old versions of 'tar', or by some newer versions of 'tar' running on old +machines with small address spaces. With GNU 'tar', the blocking factor +of an archive is limited only by the maximum record size of the device +containing the archive, or by the amount of available virtual memory. + + Also, on some systems, not using adequate blocking factors, as +sometimes imposed by the device drivers, may yield unexpected +diagnostics. For example, this has been reported: + + Cannot write to /dev/dlt: Invalid argument + +In such cases, it sometimes happen that the 'tar' bundled by the system +is aware of block size idiosyncrasies, while GNU 'tar' requires an +explicit specification for the block size, which it cannot guess. This +yields some people to consider GNU 'tar' is misbehaving, because by +comparison, 'the bundle 'tar' works OK'. Adding '-b 256', for example, +might resolve the problem. + + If you use a non-default blocking factor when you create an archive, +you must specify the same blocking factor when you modify that archive. +Some archive devices will also require you to specify the blocking +factor when reading that archive, however this is not typically the +case. Usually, you can use '--list' ('-t') without specifying a +blocking factor--'tar' reports a non-default record size and then lists +the archive members as it would normally. To extract files from an +archive with a non-standard blocking factor (particularly if you're not +sure what the blocking factor is), you can usually use the +'--read-full-records' ('-B') option while specifying a blocking factor +larger then the blocking factor of the archive (i.e., 'tar --extract +--read-full-records --blocking-factor=300'). *Note list::, for more +information on the '--list' ('-t') operation. *Note Reading::, for a +more detailed explanation of that option. + +'--blocking-factor=NUMBER' +'-b NUMBER' + Specifies the blocking factor of an archive. Can be used with any + operation, but is usually not necessary with '--list' ('-t'). + + Device blocking + +'-b BLOCKS' +'--blocking-factor=BLOCKS' + Set record size to BLOCKS*512 bytes. + + This option is used to specify a "blocking factor" for the archive. + When reading or writing the archive, 'tar', will do reads and + writes of the archive in records of BLOCK*512 bytes. This is true + even when the archive is compressed. Some devices requires that + all write operations be a multiple of a certain size, and so, 'tar' + pads the archive out to the next record boundary. + + The default blocking factor is set when 'tar' is compiled, and is + typically 20. Blocking factors larger than 20 cannot be read by + very old versions of 'tar', or by some newer versions of 'tar' + running on old machines with small address spaces. + + With a magnetic tape, larger records give faster throughput and fit + more data on a tape (because there are fewer inter-record gaps). + If the archive is in a disk file or a pipe, you may want to specify + a smaller blocking factor, since a large one will result in a large + number of null bytes at the end of the archive. + + When writing cartridge or other streaming tapes, a much larger + blocking factor (say 126 or more) will greatly increase + performance. However, you must specify the same blocking factor + when reading or updating the archive. + + Apparently, Exabyte drives have a physical block size of 8K bytes. + If we choose our blocksize as a multiple of 8k bytes, then the + problem seems to disappear. Id est, we are using block size of 112 + right now, and we haven't had the problem since we switched... + + With GNU 'tar' the blocking factor is limited only by the maximum + record size of the device containing the archive, or by the amount + of available virtual memory. + + However, deblocking or reblocking is virtually avoided in a special + case which often occurs in practice, but which requires all the + following conditions to be simultaneously true: + * the archive is subject to a compression option, + * the archive is not handled through standard input or output, + nor redirected nor piped, + * the archive is directly handled to a local disk, instead of + any special device, + * '--blocking-factor' is not explicitly specified on the 'tar' + invocation. + + If the output goes directly to a local disk, and not through + stdout, then the last write is not extended to a full record size. + Otherwise, reblocking occurs. Here are a few other remarks on this + topic: + + * 'gzip' will complain about trailing garbage if asked to + uncompress a compressed archive on tape, there is an option to + turn the message off, but it breaks the regularity of simply + having to use 'PROG -d' for decompression. It would be nice + if gzip was silently ignoring any number of trailing zeros. + I'll ask Jean-loup Gailly, by sending a copy of this message + to him. + + * 'compress' does not show this problem, but as Jean-loup + pointed out to Michael, 'compress -d' silently adds garbage + after the result of decompression, which tar ignores because + it already recognized its end-of-file indicator. So this bug + may be safely ignored. + + * 'gzip -d -q' will be silent about the trailing zeros indeed, + but will still return an exit status of 2 which tar reports in + turn. 'tar' might ignore the exit status returned, but I hate + doing that, as it weakens the protection 'tar' offers users + against other possible problems at decompression time. If + 'gzip' was silently skipping trailing zeros _and_ also + avoiding setting the exit status in this innocuous case, that + would solve this situation. + + * 'tar' should become more solid at not stopping to read a pipe + at the first null block encountered. This inelegantly breaks + the pipe. 'tar' should rather drain the pipe out before + exiting itself. + +'-i' +'--ignore-zeros' + Ignore blocks of zeros in archive (means EOF). + + The '--ignore-zeros' ('-i') option causes 'tar' to ignore blocks of + zeros in the archive. Normally a block of zeros indicates the end + of the archive, but when reading a damaged archive, or one which + was created by concatenating several archives together, this option + allows 'tar' to read the entire archive. This option is not on by + default because many versions of 'tar' write garbage after the + zeroed blocks. + + Note that this option causes 'tar' to read to the end of the + archive file, which may sometimes avoid problems when multiple + files are stored on a single physical tape. + +'-B' +'--read-full-records' + Reblock as we read (for reading 4.2BSD pipes). + + If '--read-full-records' is used, 'tar' will not panic if an + attempt to read a record from the archive does not return a full + record. Instead, 'tar' will keep reading until it has obtained a + full record. + + This option is turned on by default when 'tar' is reading an + archive from standard input, or from a remote machine. This is + because on BSD Unix systems, a read of a pipe will return however + much happens to be in the pipe, even if it is less than 'tar' + requested. If this option was not used, 'tar' would fail as soon + as it read an incomplete record from the pipe. + + This option is also useful with the commands for updating an + archive. + + Tape blocking + + When handling various tapes or cartridges, you have to take care of +selecting a proper blocking, that is, the number of disk blocks you put +together as a single tape block on the tape, without intervening tape +gaps. A "tape gap" is a small landing area on the tape with no +information on it, used for decelerating the tape to a full stop, and +for later regaining the reading or writing speed. When the tape driver +starts reading a record, the record has to be read whole without +stopping, as a tape gap is needed to stop the tape motion without losing +information. + + Using higher blocking (putting more disk blocks per tape block) will +use the tape more efficiently as there will be less tape gaps. But +reading such tapes may be more difficult for the system, as more memory +will be required to receive at once the whole record. Further, if there +is a reading error on a huge record, this is less likely that the system +will succeed in recovering the information. So, blocking should not be +too low, nor it should be too high. 'tar' uses by default a blocking of +20 for historical reasons, and it does not really matter when reading or +writing to disk. Current tape technology would easily accommodate +higher blockings. Sun recommends a blocking of 126 for Exabytes and 96 +for DATs. We were told that for some DLT drives, the blocking should be +a multiple of 4Kb, preferably 64Kb ('-b 128') or 256 for decent +performance. Other manufacturers may use different recommendations for +the same tapes. This might also depends of the buffering techniques +used inside modern tape controllers. Some imposes a minimum blocking, +or a maximum blocking. Others request blocking to be some exponent of +two. + + So, there is no fixed rule for blocking. But blocking at read time +should ideally be the same as blocking used at write time. At one place +I know, with a wide variety of equipment, they found it best to use a +blocking of 32 to guarantee that their tapes are fully interchangeable. + + I was also told that, for recycled tapes, prior erasure (by the same +drive unit that will be used to create the archives) sometimes lowers +the error rates observed at rewriting time. + + I might also use '--number-blocks' instead of '--block-number', so +'--block' will then expand to '--blocking-factor' unambiguously. + + +File: tar.info, Node: Many, Next: Using Multiple Tapes, Prev: Blocking, Up: Media + +9.5 Many Archives on One Tape +============================= + +Most tape devices have two entries in the '/dev' directory, or entries +that come in pairs, which differ only in the minor number for this +device. Let's take for example '/dev/tape', which often points to the +only or usual tape device of a given system. There might be a +corresponding '/dev/nrtape' or '/dev/ntape'. The simpler name is the +_rewinding_ version of the device, while the name having 'nr' in it is +the _no rewinding_ version of the same device. + + A rewinding tape device will bring back the tape to its beginning +point automatically when this device is opened or closed. Since 'tar' +opens the archive file before using it and closes it afterwards, this +means that a simple: + + $ tar cf /dev/tape DIRECTORY + +will reposition the tape to its beginning both prior and after saving +DIRECTORY contents to it, thus erasing prior tape contents and making it +so that any subsequent write operation will destroy what has just been +saved. + + So, a rewinding device is normally meant to hold one and only one +file. If you want to put more than one 'tar' archive on a given tape, +you will need to avoid using the rewinding version of the tape device. +You will also have to pay special attention to tape positioning. Errors +in positioning may overwrite the valuable data already on your tape. +Many people, burnt by past experiences, will only use rewinding devices +and limit themselves to one file per tape, precisely to avoid the risk +of such errors. Be fully aware that writing at the wrong position on a +tape loses all information past this point and most probably until the +end of the tape, and this destroyed information _cannot_ be recovered. + + To save DIRECTORY-1 as a first archive at the beginning of a tape, +and leave that tape ready for a second archive, you should use: + + $ mt -f /dev/nrtape rewind + $ tar cf /dev/nrtape DIRECTORY-1 + + "Tape marks" are special magnetic patterns written on the tape media, +which are later recognizable by the reading hardware. These marks are +used after each file, when there are many on a single tape. An empty +file (that is to say, two tape marks in a row) signal the logical end of +the tape, after which no file exist. Usually, non-rewinding tape device +drivers will react to the close request issued by 'tar' by first writing +two tape marks after your archive, and by backspacing over one of these. +So, if you remove the tape at that time from the tape drive, it is +properly terminated. But if you write another file at the current +position, the second tape mark will be erased by the new information, +leaving only one tape mark between files. + + So, you may now save DIRECTORY-2 as a second archive after the first +on the same tape by issuing the command: + + $ tar cf /dev/nrtape DIRECTORY-2 + +and so on for all the archives you want to put on the same tape. + + Another usual case is that you do not write all the archives the same +day, and you need to remove and store the tape between two archive +sessions. In general, you must remember how many files are already +saved on your tape. Suppose your tape already has 16 files on it, and +that you are ready to write the 17th. You have to take care of skipping +the first 16 tape marks before saving DIRECTORY-17, say, by using these +commands: + + $ mt -f /dev/nrtape rewind + $ mt -f /dev/nrtape fsf 16 + $ tar cf /dev/nrtape DIRECTORY-17 + + In all the previous examples, we put aside blocking considerations, +but you should do the proper things for that as well. *Note Blocking::. + +* Menu: + +* Tape Positioning:: Tape Positions and Tape Marks +* mt:: The 'mt' Utility + + +File: tar.info, Node: Tape Positioning, Next: mt, Up: Many + +9.5.1 Tape Positions and Tape Marks +----------------------------------- + + _(This message will disappear, once this node revised.)_ + + Just as archives can store more than one file from the file system, +tapes can store more than one archive file. To keep track of where +archive files (or any other type of file stored on tape) begin and end, +tape archive devices write magnetic "tape marks" on the archive media. +Tape drives write one tape mark between files, two at the end of all the +file entries. + + If you think of data as a series of records "rrrr"'s, and tape marks +as "*"'s, a tape might look like the following: + + rrrr*rrrrrr*rrrrr*rr*rrrrr**------------------------- + + Tape devices read and write tapes using a read/write "tape head"--a +physical part of the device which can only access one point on the tape +at a time. When you use 'tar' to read or write archive data from a tape +device, the device will begin reading or writing from wherever on the +tape the tape head happens to be, regardless of which archive or what +part of the archive the tape head is on. Before writing an archive, you +should make sure that no data on the tape will be overwritten (unless it +is no longer needed). Before reading an archive, you should make sure +the tape head is at the beginning of the archive you want to read. You +can do it manually via 'mt' utility (*note mt::). The 'restore' script +does that automatically (*note Scripted Restoration::). + + If you want to add new archive file entries to a tape, you should +advance the tape to the end of the existing file entries, backspace over +the last tape mark, and write the new archive file. If you were to add +two archives to the example above, the tape might look like the +following: + + rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- + + +File: tar.info, Node: mt, Prev: Tape Positioning, Up: Many + +9.5.2 The 'mt' Utility +---------------------- + + _(This message will disappear, once this node revised.)_ + + *Note Blocking Factor::. + + You can use the 'mt' utility to advance or rewind a tape past a +specified number of archive files on the tape. This will allow you to +move to the beginning of an archive before extracting or reading it, or +to the end of all the archives before writing a new one. + + The syntax of the 'mt' command is: + + mt [-f TAPENAME] OPERATION [NUMBER] + + where TAPENAME is the name of the tape device, NUMBER is the number +of times an operation is performed (with a default of one), and +OPERATION is one of the following: + +'eof' +'weof' + Writes NUMBER tape marks at the current position on the tape. + +'fsf' + Moves tape position forward NUMBER files. + +'bsf' + Moves tape position back NUMBER files. + +'rewind' + Rewinds the tape. (Ignores NUMBER.) + +'offline' +'rewoff1' + Rewinds the tape and takes the tape device off-line. (Ignores + NUMBER.) + +'status' + Prints status information about the tape unit. + + If you don't specify a TAPENAME, 'mt' uses the environment variable +'TAPE'; if 'TAPE' is not set, 'mt' will use the default device specified +in your 'sys/mtio.h' file ('DEFTAPE' variable). If this is not defined, +the program will display a descriptive error message and exit with code +1. + + 'mt' returns a 0 exit status when the operation(s) were successful, 1 +if the command was unrecognized, and 2 if an operation failed. + + +File: tar.info, Node: Using Multiple Tapes, Next: label, Prev: Many, Up: Media + +9.6 Using Multiple Tapes +======================== + +Often you might want to write a large archive, one larger than will fit +on the actual tape you are using. In such a case, you can run multiple +'tar' commands, but this can be inconvenient, particularly if you are +using options like '--exclude=PATTERN' or dumping entire file systems. +Therefore, 'tar' provides a special mode for creating multi-volume +archives. + + "Multi-volume" archive is a single 'tar' archive, stored on several +media volumes of fixed size. Although in this section we will often +call 'volume' a "tape", there is absolutely no requirement for +multi-volume archives to be stored on tapes. Instead, they can use +whatever media type the user finds convenient, they can even be located +on files. + + When creating a multi-volume archive, GNU 'tar' continues to fill +current volume until it runs out of space, then it switches to next +volume (usually the operator is queried to replace the tape on this +point), and continues working on the new volume. This operation +continues until all requested files are dumped. If GNU 'tar' detects +end of media while dumping a file, such a file is archived in split +form. Some very big files can even be split across several volumes. + + Each volume is itself a valid GNU 'tar' archive, so it can be read +without any special options. Consequently any file member residing +entirely on one volume can be extracted or otherwise operated upon +without needing the other volume. Sure enough, to extract a split +member you would need all volumes its parts reside on. + + Multi-volume archives suffer from several limitations. In +particular, they cannot be compressed. + + GNU 'tar' is able to create multi-volume archives of two formats +(*note Formats::): 'GNU' and 'POSIX'. + +* Menu: + +* Multi-Volume Archives:: Archives Longer than One Tape or Disk +* Tape Files:: Tape Files +* Tarcat:: Concatenate Volumes into a Single Archive + + +File: tar.info, Node: Multi-Volume Archives, Next: Tape Files, Up: Using Multiple Tapes + +9.6.1 Archives Longer than One Tape or Disk +------------------------------------------- + +To create an archive that is larger than will fit on a single unit of +the media, use the '--multi-volume' ('-M') option in conjunction with +the '--create' option (*note create::). A "multi-volume" archive can be +manipulated like any other archive (provided the '--multi-volume' option +is specified), but is stored on more than one tape or file. + + When you specify '--multi-volume', 'tar' does not report an error +when it comes to the end of an archive volume (when reading), or the end +of the media (when writing). Instead, it prompts you to load a new +storage volume. If the archive is on a magnetic tape, you should change +tapes when you see the prompt; if the archive is on a floppy disk, you +should change disks; etc. + +'--multi-volume' +'-M' + Creates a multi-volume archive, when used in conjunction with + '--create' ('-c'). To perform any other operation on a + multi-volume archive, specify '--multi-volume' in conjunction with + that operation. For example: + + $ tar --create --multi-volume --file=/dev/tape FILES + + The method 'tar' uses to detect end of tape is not perfect, and fails +on some operating systems or on some devices. If 'tar' cannot detect +the end of the tape itself, you can use '--tape-length' option to inform +it about the capacity of the tape: + +'--tape-length=SIZE[SUF]' +'-L SIZE[SUF]' + Set maximum length of a volume. The SUF, if given, specifies units + in which SIZE is expressed, e.g. '2M' mean 2 megabytes (*note + Table 9.1: size-suffixes, for a list of allowed size suffixes). + Without SUF, units of 1024 bytes (kilobyte) are assumed. + + This option selects '--multi-volume' automatically. For example: + + $ tar --create --tape-length=41943040 --file=/dev/tape FILES + + or, which is equivalent: + + $ tar --create --tape-length=4G --file=/dev/tape FILES + + When GNU 'tar' comes to the end of a storage media, it asks you to +change the volume. The built-in prompt for POSIX locale is(1): + + Prepare volume #N for 'ARCHIVE' and hit return: + +where N is the ordinal number of the volume to be created and ARCHIVE is +archive file or device name. + + When prompting for a new tape, 'tar' accepts any of the following +responses: + +'?' + Request 'tar' to explain possible responses. +'q' + Request 'tar' to exit immediately. +'n FILE-NAME' + Request 'tar' to write the next volume on the file FILE-NAME. +'!' + Request 'tar' to run a subshell. This option can be disabled by + giving '--restrict' command line option to 'tar'(2). +'y' + Request 'tar' to begin writing the next volume. + + (You should only type 'y' after you have changed the tape; otherwise +'tar' will write over the volume it just finished.) + + The volume number used by 'tar' in its tape-changing prompt can be +changed; if you give the '--volno-file=FILE-OF-NUMBER' option, then +FILE-OF-NUMBER should be an non-existing file to be created, or else, a +file already containing a decimal number. That number will be used as +the volume number of the first volume written. When 'tar' is finished, +it will rewrite the file with the now-current volume number. (This does +not change the volume number written on a tape label, as per *note +label::, it _only_ affects the number used in the prompt.) + + If you want more elaborate behavior than this, you can write a +special "new volume script", that will be responsible for changing the +volume, and instruct 'tar' to use it instead of its normal prompting +procedure: + +'--info-script=COMMAND' +'--new-volume-script=COMMAND' +'-F COMMAND' + Specify the command to invoke when switching volumes. The COMMAND + can be used to eject cassettes, or to broadcast messages such as + 'Someone please come change my tape' when performing unattended + backups. + + The COMMAND can contain additional options, if such are needed. +*Note Running External Commands: external, for a detailed discussion of +the way GNU 'tar' runs external commands. It inherits 'tar''s shell +environment. Additional data is passed to it via the following +environment variables: + +'TAR_VERSION' + GNU 'tar' version number. + +'TAR_ARCHIVE' + The name of the archive 'tar' is processing. + +'TAR_BLOCKING_FACTOR' + Current blocking factor (*note Blocking::). + +'TAR_VOLUME' + Ordinal number of the volume 'tar' is about to start. + +'TAR_SUBCOMMAND' + A short option describing the operation 'tar' is executing. *Note + Operations::, for a complete list of subcommand options. + +'TAR_FORMAT' + Format of the archive being processed. *Note Formats::, for a + complete list of archive format names. + +'TAR_FD' + File descriptor which can be used to communicate the new volume + name to 'tar'. + + These variables can be used in the COMMAND itself, provided that they +are properly quoted to prevent them from being expanded by the shell +that invokes 'tar'. + + The volume script can instruct 'tar' to use new archive name, by +writing in to file descriptor '$TAR_FD' (see below for an example). + + If the info script fails, 'tar' exits; otherwise, it begins writing +the next volume. + + If you want 'tar' to cycle through a series of files or tape drives, +there are three approaches to choose from. First of all, you can give +'tar' multiple '--file' options. In this case the specified files will +be used, in sequence, as the successive volumes of the archive. Only +when the first one in the sequence needs to be used again will 'tar' +prompt for a tape change (or run the info script). For example, suppose +someone has two tape drives on a system named '/dev/tape0' and +'/dev/tape1'. For having GNU 'tar' to switch to the second drive when +it needs to write the second tape, and then back to the first tape, +etc., just do either of: + + $ tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 FILES + $ tar -cM -f /dev/tape0 -f /dev/tape1 FILES + + The second method is to use the 'n' response to the tape-change +prompt. + + Finally, the most flexible approach is to use a volume script, that +writes new archive name to the file descriptor '$TAR_FD'. For example, +the following volume script will create a series of archive files, named +'ARCHIVE-VOL', where ARCHIVE is the name of the archive being created +(as given by '--file' option) and VOL is the ordinal number of the +archive being created: + + #! /bin/bash + # For this script it's advisable to use a shell, such as Bash, + # that supports a TAR_FD value greater than 9. + + echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE. + + name=`expr $TAR_ARCHIVE : '\(.*\)-.*'` + case $TAR_SUBCOMMAND in + -c) ;; + -d|-x|-t) test -r ${name:-$TAR_ARCHIVE}-$TAR_VOLUME || exit 1 + ;; + *) exit 1 + esac + + echo ${name:-$TAR_ARCHIVE}-$TAR_VOLUME >&$TAR_FD + + The same script can be used while listing, comparing or extracting +from the created archive. For example: + + # Create a multi-volume archive: + $ tar -c -L1024 -f archive.tar -F new-volume . + # Extract from the created archive: + $ tar -x -f archive.tar -F new-volume . + +Notice, that the first command had to use '-L' option, since otherwise +GNU 'tar' will end up writing everything to file 'archive.tar'. + + You can read each individual volume of a multi-volume archive as if +it were an archive by itself. For example, to list the contents of one +volume, use '--list', without '--multi-volume' specified. To extract an +archive member from one volume (assuming it is described that volume), +use '--extract', again without '--multi-volume'. + + If an archive member is split across volumes (i.e., its entry begins +on one volume of the media and ends on another), you need to specify +'--multi-volume' to extract it successfully. In this case, you should +load the volume where the archive member starts, and use 'tar --extract +--multi-volume'--'tar' will prompt for later volumes as it needs them. +*Note extracting archives::, for more information about extracting +archives. + + Multi-volume archives can be modified like any other archive. To add +files to a multi-volume archive, you need to only mount the last volume +of the archive media (and new volumes, if needed). For all other +operations, you need to use the entire archive. + + If a multi-volume archive was labeled using '--label=ARCHIVE-LABEL' +(*note label::) when it was created, 'tar' will not automatically label +volumes which are added later. To label subsequent volumes, specify +'--label=ARCHIVE-LABEL' again in conjunction with the '--append', +'--update' or '--concatenate' operation. + + Notice that multi-volume support is a GNU extension and the archives +created in this mode should be read only using GNU 'tar'. If you +absolutely have to process such archives using a third-party 'tar' +implementation, read *note Split Recovery::. + + ---------- Footnotes ---------- + + (1) If you run GNU 'tar' under a different locale, the translation to +the locale's language will be used. + + (2) *Note --restrict::, for more information about this option. + + +File: tar.info, Node: Tape Files, Next: Tarcat, Prev: Multi-Volume Archives, Up: Using Multiple Tapes + +9.6.2 Tape Files +---------------- + + _(This message will disappear, once this node revised.)_ + + To give the archive a name which will be recorded in it, use the +'--label=VOLUME-LABEL' ('-V VOLUME-LABEL') option. This will write a +special block identifying VOLUME-LABEL as the name of the archive to the +front of the archive which will be displayed when the archive is listed +with '--list'. If you are creating a multi-volume archive with +'--multi-volume' (*note Using Multiple Tapes::), then the volume label +will have 'Volume NNN' appended to the name you give, where NNN is the +number of the volume of the archive. If you use the +'--label=VOLUME-LABEL' option when reading an archive, it checks to make +sure the label on the tape matches the one you gave. *Note label::. + + When 'tar' writes an archive to tape, it creates a single tape file. +If multiple archives are written to the same tape, one after the other, +they each get written as separate tape files. When extracting, it is +necessary to position the tape at the right place before running 'tar'. +To do this, use the 'mt' command. For more information on the 'mt' +command and on the organization of tapes into a sequence of tape files, +see *note mt::. + + People seem to often do: + + --label="SOME-PREFIX `date +SOME-FORMAT`" + + or such, for pushing a common date in all volumes or an archive set. + + +File: tar.info, Node: Tarcat, Prev: Tape Files, Up: Using Multiple Tapes + +9.6.3 Concatenate Volumes into a Single Archive +----------------------------------------------- + +Sometimes it is necessary to convert existing GNU 'tar' multi-volume +archive to a single 'tar' archive. Simply concatenating all volumes +into one will not work, since each volume carries an additional +information at the beginning. GNU 'tar' is shipped with the shell +script 'tarcat' designed for this purpose. + + The script takes a list of files comprising a multi-volume archive +and creates the resulting archive at the standard output. For example: + + tarcat vol.1 vol.2 vol.3 | tar tf - + + The script implements a simple heuristics to determine the format of +the first volume file and to decide how to process the rest of the +files. However, it makes no attempt to verify whether the files are +given in order or even if they are valid 'tar' archives. It uses 'dd' +and does not filter its standard error, so you will usually see lots of +spurious messages. + + +File: tar.info, Node: label, Next: verify, Prev: Using Multiple Tapes, Up: Media + +9.7 Including a Label in the Archive +==================================== + +To avoid problems caused by misplaced paper labels on the archive media, +you can include a "label" entry -- an archive member which contains the +name of the archive -- in the archive itself. Use the +'--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') option(1) in conjunction +with the '--create' operation to include a label entry in the archive as +it is being created. + +'--label=ARCHIVE-LABEL' +'-V ARCHIVE-LABEL' + Includes an "archive-label" at the beginning of the archive when + the archive is being created, when used in conjunction with the + '--create' operation. Checks to make sure the archive label + matches the one specified (when used in conjunction with any other + operation). + + If you create an archive using both '--label=ARCHIVE-LABEL' ('-V +ARCHIVE-LABEL') and '--multi-volume' ('-M'), each volume of the archive +will have an archive label of the form 'ARCHIVE-LABEL Volume N', where N +is 1 for the first volume, 2 for the next, and so on. *Note Using +Multiple Tapes::, for information on creating multiple volume archives. + + The volume label will be displayed by '--list' along with the file +contents. If verbose display is requested, it will also be explicitly +marked as in the example below: + + $ tar --verbose --list --file=iamanarchive + V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header-- + -rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename + + However, '--list' option will cause listing entire contents of the +archive, which may be undesirable (for example, if the archive is stored +on a tape). You can request checking only the volume label by +specifying '--test-label' option. This option reads only the first +block of an archive, so it can be used with slow storage devices. For +example: + + $ tar --test-label --file=iamanarchive + iamalabel + + If '--test-label' is used with one or more command line arguments, +'tar' compares the volume label with each argument. It exits with code +0 if a match is found, and with code 1 otherwise(2). No output is +displayed, unless you also used the '--verbose' option. For example: + + $ tar --test-label --file=iamanarchive 'iamalabel' + => 0 + $ tar --test-label --file=iamanarchive 'alabel' + => 1 + + When used with the '--verbose' option, 'tar' prints the actual volume +label (if any), and a verbose diagnostics in case of a mismatch: + + $ tar --test-label --verbose --file=iamanarchive 'iamalabel' + iamalabel + => 0 + $ tar --test-label --verbose --file=iamanarchive 'alabel' + iamalabel + tar: Archive label mismatch + => 1 + + If you request any operation, other than '--create', along with using +'--label' option, 'tar' will first check if the archive label matches +the one specified and will refuse to proceed if it does not. Use this +as a safety precaution to avoid accidentally overwriting existing +archives. For example, if you wish to add files to 'archive', +presumably labeled with string 'My volume', you will get: + + $ tar -rf archive --label 'My volume' . + tar: Archive not labeled to match 'My volume' + +in case its label does not match. This will work even if 'archive' is +not labeled at all. + + Similarly, 'tar' will refuse to list or extract the archive if its +label doesn't match the ARCHIVE-LABEL specified. In those cases, +ARCHIVE-LABEL argument is interpreted as a globbing-style pattern which +must match the actual magnetic volume label. *Note exclude::, for a +precise description of how match is attempted(3). If the switch +'--multi-volume' ('-M') is being used, the volume label matcher will +also suffix ARCHIVE-LABEL by ' Volume [1-9]*' if the initial match +fails, before giving up. Since the volume numbering is automatically +added in labels at creation time, it sounded logical to equally help the +user taking care of it when the archive is being read. + + You can also use '--label' to get a common information on all tapes +of a series. For having this information different in each series +created through a single script used on a regular basis, just manage to +get some date string as part of the label. For example: + + $ tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`" + $ tar --create --file=/dev/tape --multi-volume \ + --label="Daily backup for `date +%Y-%m-%d`" + + Some more notes about volume labels: + + * Each label has its own date and time, which corresponds to the time + when GNU 'tar' initially attempted to write it, often soon after + the operator launches 'tar' or types the carriage return telling + that the next tape is ready. + + * Comparing date labels to get an idea of tape throughput is + unreliable. It gives correct results only if the delays for + rewinding tapes and the operator switching them were negligible, + which is usually not the case. + + ---------- Footnotes ---------- + + (1) Until version 1.10, that option was called '--volume', but is not +available under that name anymore. + + (2) Note that GNU 'tar' versions up to 1.23 indicated mismatch with +an exit code 2 and printed a spurious diagnostics on stderr. + + (3) Previous versions of 'tar' used full regular expression matching, +or before that, only exact string matching, instead of wildcard +matchers. We decided for the sake of simplicity to use a uniform +matching device through 'tar'. + + +File: tar.info, Node: verify, Next: Write Protection, Prev: label, Up: Media + +9.8 Verifying Data as It is Stored +================================== + +'-W' +'--verify' + Attempt to verify the archive after writing. + + This option causes 'tar' to verify the archive after writing it. +Each volume is checked after it is written, and any discrepancies are +recorded on the standard error output. + + Verification requires that the archive be on a back-space-able +medium. This means pipes, some cartridge tape drives, and some other +devices cannot be verified. + + You can insure the accuracy of an archive by comparing files in the +system with archive members. 'tar' can compare an archive to the file +system as the archive is being written, to verify a write operation, or +can compare a previously written archive, to insure that it is up to +date. + + To check for discrepancies in an archive immediately after it is +written, use the '--verify' ('-W') option in conjunction with the +'--create' operation. When this option is specified, 'tar' checks +archive members against their counterparts in the file system, and +reports discrepancies on the standard error. + + To verify an archive, you must be able to read it from before the end +of the last written entry. This option is useful for detecting data +errors on some tapes. Archives written to pipes, some cartridge tape +drives, and some other devices cannot be verified. + + One can explicitly compare an already made archive with the file +system by using the '--compare' ('--diff', '-d') option, instead of +using the more automatic '--verify' option. *Note compare::. + + Note that these two options have a slightly different intent. The +'--compare' option checks how identical are the logical contents of some +archive with what is on your disks, while the '--verify' option is +really for checking if the physical contents agree and if the recording +media itself is of dependable quality. So, for the '--verify' +operation, 'tar' tries to defeat all in-memory cache pertaining to the +archive, while it lets the speed optimization undisturbed for the +'--compare' option. If you nevertheless use '--compare' for media +verification, you may have to defeat the in-memory cache yourself, maybe +by opening and reclosing the door latch of your recording unit, forcing +some doubt in your operating system about the fact this is really the +same volume as the one just written or read. + + The '--verify' option would not be necessary if drivers were indeed +able to detect dependably all write failures. This sometimes require +many magnetic heads, some able to read after the writes occurred. One +would not say that drivers unable to detect all cases are necessarily +flawed, as long as programming is concerned. + + The '--verify' ('-W') option will not work in conjunction with the +'--multi-volume' ('-M') option or the '--append' ('-r'), '--update' +('-u') and '--delete' operations. *Note Operations::, for more +information on these operations. + + Also, since 'tar' normally strips leading '/' from file names (*note +absolute::), a command like 'tar --verify -cf /tmp/foo.tar /etc' will +work as desired only if the working directory is '/', as 'tar' uses the +archive's relative member names (e.g., 'etc/motd') when verifying the +archive. + + +File: tar.info, Node: Write Protection, Prev: verify, Up: Media + +9.9 Write Protection +==================== + +Almost all tapes and diskettes, and in a few rare cases, even disks can +be "write protected", to protect data on them from being changed. Once +an archive is written, you should write protect the media to prevent the +archive from being accidentally overwritten or deleted. (This will +protect the archive from being changed with a tape or floppy drive--it +will not protect it from magnet fields or other physical hazards.) + + The write protection device itself is usually an integral part of the +physical media, and can be a two position (write enabled/write disabled) +switch, a notch which can be popped out or covered, a ring which can be +removed from the center of a tape reel, or some other changeable +feature. + + +File: tar.info, Node: Reliability and security, Next: Changes, Prev: Media, Up: Top + +10 Reliability and Security +*************************** + +The 'tar' command reads and writes files as any other application does, +and is subject to the usual caveats about reliability and security. +This section contains some commonsense advice on the topic. + +* Menu: + +* Reliability:: +* Security:: + + +File: tar.info, Node: Reliability, Next: Security, Up: Reliability and security + +10.1 Reliability +================ + +Ideally, when 'tar' is creating an archive, it reads from a file system +that is not being modified, and encounters no errors or inconsistencies +while reading and writing. If this is the case, the archive should +faithfully reflect what was read. Similarly, when extracting from an +archive, ideally 'tar' ideally encounters no errors and the extracted +files faithfully reflect what was in the archive. + + However, when reading or writing real-world file systems, several +things can go wrong; these include permissions problems, corruption of +data, and race conditions. + +* Menu: + +* Permissions problems:: +* Data corruption and repair:: +* Race conditions:: + + +File: tar.info, Node: Permissions problems, Next: Data corruption and repair, Up: Reliability + +10.1.1 Permissions Problems +--------------------------- + +If 'tar' encounters errors while reading or writing files, it normally +reports an error and exits with nonzero status. The work it does may +therefore be incomplete. For example, when creating an archive, if +'tar' cannot read a file then it cannot copy the file into the archive. + + +File: tar.info, Node: Data corruption and repair, Next: Race conditions, Prev: Permissions problems, Up: Reliability + +10.1.2 Data Corruption and Repair +--------------------------------- + +If an archive becomes corrupted by an I/O error, this may corrupt the +data in an extracted file. Worse, it may corrupt the file's metadata, +which may cause later parts of the archive to become misinterpreted. An +tar-format archive contains a checksum that most likely will detect +errors in the metadata, but it will not detect errors in the data. + + If data corruption is a concern, you can compute and check your own +checksums of an archive by using other programs, such as 'cksum'. + + When attempting to recover from a read error or data corruption in an +archive, you may need to skip past the questionable data and read the +rest of the archive. This requires some expertise in the archive format +and in other software tools. + + +File: tar.info, Node: Race conditions, Prev: Data corruption and repair, Up: Reliability + +10.1.3 Race conditions +---------------------- + +If some other process is modifying the file system while 'tar' is +reading or writing files, the result may well be inconsistent due to +race conditions. For example, if another process creates some files in +a directory while 'tar' is creating an archive containing the +directory's files, 'tar' may see some of the files but not others, or it +may see a file that is in the process of being created. The resulting +archive may not be a snapshot of the file system at any point in time. +If an application such as a database system depends on an accurate +snapshot, restoring from the 'tar' archive of a live file system may +therefore break that consistency and may break the application. The +simplest way to avoid the consistency issues is to avoid making other +changes to the file system while tar is reading it or writing it. + + When creating an archive, several options are available to avoid race +conditions. Some hosts have a way of snapshotting a file system, or of +temporarily suspending all changes to a file system, by (say) suspending +the only virtual machine that can modify a file system; if you use these +facilities and have 'tar -c' read from a snapshot when creating an +archive, you can avoid inconsistency problems. More drastically, before +starting 'tar' you could suspend or shut down all processes other than +'tar' that have access to the file system, or you could unmount the file +system and then mount it read-only. + + When extracting from an archive, one approach to avoid race +conditions is to create a directory that no other process can write to, +and extract into that. + + +File: tar.info, Node: Security, Prev: Reliability, Up: Reliability and security + +10.2 Security +============= + +In some cases 'tar' may be used in an adversarial situation, where an +untrusted user is attempting to gain information about or modify +otherwise-inaccessible files. Dealing with untrusted data (that is, +data generated by an untrusted user) typically requires extra care, +because even the smallest mistake in the use of 'tar' is more likely to +be exploited by an adversary than by a race condition. + +* Menu: + +* Privacy:: +* Integrity:: +* Live untrusted data:: +* Security rules of thumb:: + + +File: tar.info, Node: Privacy, Next: Integrity, Up: Security + +10.2.1 Privacy +-------------- + +Standard privacy concerns apply when using 'tar'. For example, suppose +you are archiving your home directory into a file '/archive/myhome.tar'. +Any secret information in your home directory, such as your SSH secret +keys, are copied faithfully into the archive. Therefore, if your home +directory contains any file that should not be read by some other user, +the archive itself should be not be readable by that user. And even if +the archive's data are inaccessible to untrusted users, its metadata +(such as size or last-modified date) may reveal some information about +your home directory; if the metadata are intended to be private, the +archive's parent directory should also be inaccessible to untrusted +users. + + One precaution is to create '/archive' so that it is not accessible +to any user, unless that user also has permission to access all the +files in your home directory. + + Similarly, when extracting from an archive, take care that the +permissions of the extracted files are not more generous than what you +want. Even if the archive itself is readable only to you, files +extracted from it have their own permissions that may differ. + + +File: tar.info, Node: Integrity, Next: Live untrusted data, Prev: Privacy, Up: Security + +10.2.2 Integrity +---------------- + +When creating archives, take care that they are not writable by a +untrusted user; otherwise, that user could modify the archive, and when +you later extract from the archive you will get incorrect data. + + When 'tar' extracts from an archive, by default it writes into files +relative to the working directory. If the archive was generated by an +untrusted user, that user therefore can write into any file under the +working directory. If the working directory contains a symbolic link to +another directory, the untrusted user can also write into any file under +the referenced directory. When extracting from an untrusted archive, it +is therefore good practice to create an empty directory and run 'tar' in +that directory. + + When extracting from two or more untrusted archives, each one should +be extracted independently, into different empty directories. +Otherwise, the first archive could create a symbolic link into an area +outside the working directory, and the second one could follow the link +and overwrite data that is not under the working directory. For +example, when restoring from a series of incremental dumps, the archives +should have been created by a trusted process, as otherwise the +incremental restores might alter data outside the working directory. + + If you use the '--absolute-names' ('-P') option when extracting, +'tar' respects any file names in the archive, even file names that begin +with '/' or contain '..'. As this lets the archive overwrite any file +in your system that you can write, the '--absolute-names' ('-P') option +should be used only for trusted archives. + + Conversely, with the '--keep-old-files' ('-k') and '--skip-old-files' +options, 'tar' refuses to replace existing files when extracting. The +difference between the two options is that the former treats existing +files as errors whereas the latter just silently ignores them. + + Finally, with the '--no-overwrite-dir' option, 'tar' refuses to +replace the permissions or ownership of already-existing directories. +These options may help when extracting from untrusted archives. + + +File: tar.info, Node: Live untrusted data, Next: Security rules of thumb, Prev: Integrity, Up: Security + +10.2.3 Dealing with Live Untrusted Data +--------------------------------------- + +Extra care is required when creating from or extracting into a file +system that is accessible to untrusted users. For example, superusers +who invoke 'tar' must be wary about its actions being hijacked by an +adversary who is reading or writing the file system at the same time +that 'tar' is operating. + + When creating an archive from a live file system, 'tar' is vulnerable +to denial-of-service attacks. For example, an adversarial user could +create the illusion of an indefinitely-deep directory hierarchy +'d/e/f/g/...' by creating directories one step ahead of 'tar', or the +illusion of an indefinitely-long file by creating a sparse file but +arranging for blocks to be allocated just before 'tar' reads them. +There is no easy way for 'tar' to distinguish these scenarios from +legitimate uses, so you may need to monitor 'tar', just as you'd need to +monitor any other system service, to detect such attacks. + + While a superuser is extracting from an archive into a live file +system, an untrusted user might replace a directory with a symbolic +link, in hopes that 'tar' will follow the symbolic link and extract data +into files that the untrusted user does not have access to. Even if the +archive was generated by the superuser, it may contain a file such as +'d/etc/passwd' that the untrusted user earlier created in order to break +in; if the untrusted user replaces the directory 'd/etc' with a symbolic +link to '/etc' while 'tar' is running, 'tar' will overwrite +'/etc/passwd'. This attack can be prevented by extracting into a +directory that is inaccessible to untrusted users. + + Similar attacks via symbolic links are also possible when creating an +archive, if the untrusted user can modify an ancestor of a top-level +argument of 'tar'. For example, an untrusted user that can modify +'/home/eve' can hijack a running instance of 'tar -cf - +/home/eve/Documents/yesterday' by replacing '/home/eve/Documents' with a +symbolic link to some other location. Attacks like these can be +prevented by making sure that untrusted users cannot modify any files +that are top-level arguments to 'tar', or any ancestor directories of +these files. + + +File: tar.info, Node: Security rules of thumb, Prev: Live untrusted data, Up: Security + +10.2.4 Security Rules of Thumb +------------------------------ + +This section briefly summarizes rules of thumb for avoiding security +pitfalls. + + * Protect archives at least as much as you protect any of the files + being archived. + + * Extract from an untrusted archive only into an otherwise-empty + directory. This directory and its parent should be accessible only + to trusted users. For example: + + $ chmod go-rwx . + $ mkdir -m go-rwx dir + $ cd dir + $ tar -xvf /archives/got-it-off-the-net.tar.gz + + As a corollary, do not do an incremental restore from an untrusted + archive. + + * Do not let untrusted users access files extracted from untrusted + archives without checking first for problems such as setuid + programs. + + * Do not let untrusted users modify directories that are ancestors of + top-level arguments of 'tar'. For example, while you are executing + 'tar -cf /archive/u-home.tar /u/home', do not let an untrusted user + modify '/', '/archive', or '/u'. + + * Pay attention to the diagnostics and exit status of 'tar'. + + * When archiving live file systems, monitor running instances of + 'tar' to detect denial-of-service attacks. + + * Avoid unusual options such as '--absolute-names' ('-P'), + '--dereference' ('-h'), '--overwrite', '--recursive-unlink', and + '--remove-files' unless you understand their security implications. + + +File: tar.info, Node: Changes, Next: Configuring Help Summary, Prev: Reliability and security, Up: Top + +Appendix A Changes +****************** + +This appendix lists some important user-visible changes between version +GNU 'tar' 1.29 and previous versions. An up-to-date version of this +document is available at the GNU 'tar' documentation page +(http://www.gnu.org/software/tar/manual/changes.html). + +Use of globbing patterns when listing and extracting. + + Previous versions of GNU tar assumed shell-style globbing when + extracting from or listing an archive. For example: + + $ tar xf foo.tar '*.c' + + would extract all files whose names end in '.c'. This behavior was + not documented and was incompatible with traditional tar + implementations. Therefore, starting from version 1.15.91, GNU tar + no longer uses globbing by default. For example, the above + invocation is now interpreted as a request to extract from the + archive the file named '*.c'. + + To facilitate transition to the new behavior for those users who + got used to the previous incorrect one, 'tar' will print a warning + if it finds out that a requested member was not found in the + archive and its name looks like a globbing pattern. For example: + + $ tar xf foo.tar '*.c' + tar: Pattern matching characters used in file names. Please, + tar: use --wildcards to enable pattern matching, or --no-wildcards to + tar: suppress this warning. + tar: *.c: Not found in archive + tar: Error exit delayed from previous errors + + To treat member names as globbing patterns, use the '--wildcards' + option. If you want to tar to mimic the behavior of versions prior + to 1.15.91, add this option to your 'TAR_OPTIONS' variable. + + *Note wildcards::, for the detailed discussion of the use of + globbing patterns by GNU 'tar'. + +Use of short option '-o'. + + Earlier versions of GNU 'tar' understood '-o' command line option + as a synonym for '--old-archive'. + + GNU 'tar' starting from version 1.13.90 understands this option as + a synonym for '--no-same-owner'. This is compatible with UNIX98 + 'tar' implementations. + + However, to facilitate transition, '-o' option retains its old + semantics when it is used with one of archive-creation commands. + Users are encouraged to use '--format=oldgnu' instead. + + It is especially important, since versions of GNU Automake up to + and including 1.8.4 invoke tar with this option to produce + distribution tarballs. *Note v7: Formats, for the detailed + discussion of this issue and its implications. + + *Note tar-formats: (automake)Options, for a description on how to + use various archive formats with 'automake'. + + Future versions of GNU 'tar' will understand '-o' only as a synonym + for '--no-same-owner'. + +Use of short option '-l' + + Earlier versions of GNU 'tar' understood '-l' option as a synonym + for '--one-file-system'. Since such usage contradicted to UNIX98 + specification and harmed compatibility with other implementations, + it was declared deprecated in version 1.14. However, to facilitate + transition to its new semantics, it was supported by versions 1.15 + and 1.15.90. The present use of '-l' as a short variant of + '--check-links' was introduced in version 1.15.91. + +Use of options '--portability' and '--old-archive' + + These options are deprecated. Please use '--format=v7' instead. + +Use of option '--posix' + + This option is deprecated. Please use '--format=posix' instead. + + +File: tar.info, Node: Configuring Help Summary, Next: Fixing Snapshot Files, Prev: Changes, Up: Top + +Appendix B Configuring Help Summary +*********************************** + +Running 'tar --help' displays the short 'tar' option summary (*note +help::). This summary is organized by "groups" of semantically close +options. The options within each group are printed in the following +order: a short option, eventually followed by a list of corresponding +long option names, followed by a short description of the option. For +example, here is an excerpt from the actual 'tar --help' output: + + Main operation mode: + + -A, --catenate, --concatenate append tar files to an archive + -c, --create create a new archive + -d, --diff, --compare find differences between archive and + file system + --delete delete from the archive + + The exact visual representation of the help output is configurable +via 'ARGP_HELP_FMT' environment variable. The value of this variable is +a comma-separated list of "format variable" assignments. There are two +kinds of format variables. An "offset variable" keeps the offset of +some part of help output text from the leftmost column on the screen. A +"boolean" variable is a flag that toggles some output feature on or off. +Depending on the type of the corresponding variable, there are two kinds +of assignments: + +Offset assignment + + The assignment to an offset variable has the following syntax: + + VARIABLE=VALUE + + where VARIABLE is the variable name, and VALUE is a numeric value + to be assigned to the variable. + +Boolean assignment + + To assign 'true' value to a variable, simply put this variable + name. To assign 'false' value, prefix the variable name with + 'no-'. For example: + + # Assign true value: + dup-args + # Assign false value: + no-dup-args + + Following variables are declared: + + -- Help Output: boolean dup-args + If true, arguments for an option are shown with both short and long + options, even when a given option has both forms, for example: + + -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE + + If false, then if an option has both short and long forms, the + argument is only shown with the long one, for example: + + -f, --file=ARCHIVE use archive file or device ARCHIVE + + and a message indicating that the argument is applicable to both + forms is printed below the options. This message can be disabled + using 'dup-args-note' (see below). + + The default is false. + + -- Help Output: boolean dup-args-note + If this variable is true, which is the default, the following + notice is displayed at the end of the help output: + + Mandatory or optional arguments to long options are also + mandatory or optional for any corresponding short options. + + Setting 'no-dup-args-note' inhibits this message. Normally, only + one of variables 'dup-args' or 'dup-args-note' should be set. + + -- Help Output: offset short-opt-col + Column in which short options start. Default is 2. + + $ tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + $ ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + + -- Help Output: offset long-opt-col + Column in which long options start. Default is 6. For example: + + $ tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + $ ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + + -- Help Output: offset doc-opt-col + Column in which "doc options" start. A doc option isn't actually + an option, but rather an arbitrary piece of documentation that is + displayed in much the same manner as the options. For example, in + the description of '--format' option: + + -H, --format=FORMAT create archive of the given format. + + FORMAT is one of the following: + + gnu GNU tar 1.13.x format + oldgnu GNU format as per tar <= 1.12 + pax POSIX 1003.1-2001 (pax) format + posix same as pax + ustar POSIX 1003.1-1988 (ustar) format + v7 old V7 tar format + + the format names are doc options. Thus, if you set + 'ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output + will look as follows: + + -H, --format=FORMAT create archive of the given format. + + FORMAT is one of the following: + + gnu GNU tar 1.13.x format + oldgnu GNU format as per tar <= 1.12 + pax POSIX 1003.1-2001 (pax) format + posix same as pax + ustar POSIX 1003.1-1988 (ustar) format + v7 old V7 tar format + + -- Help Output: offset opt-doc-col + Column in which option description starts. Default is 29. + + $ tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + $ ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE + -f, --file=ARCHIVE use archive file or device ARCHIVE + $ ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE + -f, --file=ARCHIVE + use archive file or device ARCHIVE + + Notice, that the description starts on a separate line if + 'opt-doc-col' value is too small. + + -- Help Output: offset header-col + Column in which "group headers" are printed. A group header is a + descriptive text preceding an option group. For example, in the + following text: + + Main operation mode: + + -A, --catenate, --concatenate append tar files to + an archive + -c, --create create a new archive + 'Main operation mode:' is the group header. + + The default value is 1. + + -- Help Output: offset usage-indent + Indentation of wrapped usage lines. Affects '--usage' output. + Default is 12. + + -- Help Output: offset rmargin + Right margin of the text output. Used for wrapping. + + +File: tar.info, Node: Fixing Snapshot Files, Next: Tar Internals, Prev: Configuring Help Summary, Up: Top + +Appendix C Fixing Snapshot Files +******************************** + +Various situations can cause device numbers to change: upgrading your +kernel version, reconfiguring your hardware, loading kernel modules in a +different order, using virtual volumes that are assembled dynamically +(such as with LVM or RAID), hot-plugging drives (e.g. external USB or +Firewire drives), etc. In the majority of cases this change is +unnoticed by the users. However, it influences 'tar' incremental +backups: the device number is stored in tar snapshot files (*note +Snapshot Files::) and is used to determine whether the file has changed +since the last backup. If the device numbers change for some reason, by +default the next backup you run will be a full backup. + + To minimize the impact in these cases, GNU 'tar' comes with the +'tar-snapshot-edit' utility for inspecting and updating device numbers +in snapshot files. (The utility, written by Dustin J. Mitchell, is also +available from the GNU 'tar' home page +(http://www.gnu.org/software/tar/utils/tar-snapshot-edit.html).) + + To obtain a summary of the device numbers found in the snapshot file, +run + + $ tar-snapshot-edit SNAPFILE + +where SNAPFILE is the name of the snapshot file (you can supply as many +files as you wish in a single command line). You can then compare the +numbers across snapshot files, or against those currently in use on the +live filesystem (using 'ls -l' or 'stat'). + + Assuming the device numbers have indeed changed, it's often possible +to simply tell GNU 'tar' to ignore the device number when processing the +incremental snapshot files for these backups, using the +'--no-check-device' option (*note device numbers::). + + Alternatively, you can use the 'tar-edit-snapshot' script's '-r' +option to update all occurrences of the given device number in the +snapshot file(s). It takes a single argument of the form +'OLDDEV-NEWDEV', where OLDDEV is the device number used in the snapshot +file, and NEWDEV is the corresponding new device number. Both numbers +may be specified in hex (e.g., '0xfe01'), decimal (e.g., '65025'), or as +a major:minor number pair (e.g., '254:1'). To change several device +numbers at once, specify them in a single comma-separated list, as in +'-r 0x3060-0x4500,0x307-0x4600'. + + Before updating the snapshot file, it is a good idea to create a +backup copy of it. This is accomplished by '-b' option. The name of +the backup file is obtained by appending '~' to the original file name. + + An example session: + $ tar-snapshot-edit root_snap.0 boot_snap.0 + File: root_snap.0 + Detected snapshot file version: 2 + + Device 0x0000 occurs 1 times. + Device 0x0003 occurs 1 times. + Device 0x0005 occurs 1 times. + Device 0x0013 occurs 1 times. + Device 0x6801 occurs 1 times. + Device 0x6803 occurs 6626 times. + Device 0xfb00 occurs 1 times. + + File: boot_snap.0 + Detected snapshot file version: 2 + + Device 0x6801 occurs 3 times. + $ tar-snapshot-edit -b -r 0x6801-0x6901,0x6803-0x6903 root_snap.0 boot_snap.0 + File: root_snap.0 + Detected snapshot file version: 2 + + Updated 6627 records. + + File: boot_snap.0 + Detected snapshot file version: 2 + + Updated 3 records. + + +File: tar.info, Node: Tar Internals, Next: Genfile, Prev: Fixing Snapshot Files, Up: Top + +Appendix D Tar Internals +************************ + +* Menu: + +* Standard:: Basic Tar Format +* Extensions:: GNU Extensions to the Archive Format +* Sparse Formats:: Storing Sparse Files +* Snapshot Files:: +* Dumpdir:: + + +File: tar.info, Node: Standard, Next: Extensions, Up: Tar Internals + +Basic Tar Format +================ + + _(This message will disappear, once this node revised.)_ + + While an archive may contain many files, the archive itself is a +single ordinary file. Like any other file, an archive file can be +written to a storage device such as a tape or disk, sent through a pipe +or over a network, saved on the active file system, or even stored in +another archive. An archive file is not easy to read or manipulate +without using the 'tar' utility or Tar mode in GNU Emacs. + + Physically, an archive consists of a series of file entries +terminated by an end-of-archive entry, which consists of two 512 blocks +of zero bytes. A file entry usually describes one of the files in the +archive (an "archive member"), and consists of a file header and the +contents of the file. File headers contain file names and statistics, +checksum information which 'tar' uses to detect file corruption, and +information about file types. + + Archives are permitted to have more than one member with the same +member name. One way this situation can occur is if more than one +version of a file has been stored in the archive. For information about +adding new versions of a file to an archive, see *note update::. + + In addition to entries describing archive members, an archive may +contain entries which 'tar' itself uses to store information. *Note +label::, for an example of such an archive entry. + + A 'tar' archive file contains a series of blocks. Each block +contains 'BLOCKSIZE' bytes. Although this format may be thought of as +being on magnetic tape, other media are often used. + + Each file archived is represented by a header block which describes +the file, followed by zero or more blocks which give the contents of the +file. At the end of the archive file there are two 512-byte blocks +filled with binary zeros as an end-of-file marker. A reasonable system +should write such end-of-file marker at the end of an archive, but must +not assume that such a block exists when reading an archive. In +particular GNU 'tar' always issues a warning if it does not encounter +it. + + The blocks may be "blocked" for physical I/O operations. Each record +of N blocks (where N is set by the '--blocking-factor=512-SIZE' ('-b +512-SIZE') option to 'tar') is written with a single 'write ()' +operation. On magnetic tapes, the result of such a write is a single +record. When writing an archive, the last record of blocks should be +written at the full size, with blocks after the zero block containing +all zeros. When reading an archive, a reasonable system should properly +handle an archive whose last record is shorter than the rest, or which +contains garbage records after a zero block. + + The header block is defined in C as follows. In the GNU 'tar' +distribution, this is part of file 'src/tar.h': + + + /* tar Header Block, from POSIX 1003.1-1990. */ + + /* POSIX header. */ + + struct posix_header + { /* byte offset */ + char name[100]; /* 0 */ + char mode[8]; /* 100 */ + char uid[8]; /* 108 */ + char gid[8]; /* 116 */ + char size[12]; /* 124 */ + char mtime[12]; /* 136 */ + char chksum[8]; /* 148 */ + char typeflag; /* 156 */ + char linkname[100]; /* 157 */ + char magic[6]; /* 257 */ + char version[2]; /* 263 */ + char uname[32]; /* 265 */ + char gname[32]; /* 297 */ + char devmajor[8]; /* 329 */ + char devminor[8]; /* 337 */ + char prefix[155]; /* 345 */ + /* 500 */ + }; + + #define TMAGIC "ustar" /* ustar and a null */ + #define TMAGLEN 6 + #define TVERSION "00" /* 00 and no null */ + #define TVERSLEN 2 + + /* Values used in typeflag field. */ + #define REGTYPE '0' /* regular file */ + #define AREGTYPE '\0' /* regular file */ + #define LNKTYPE '1' /* link */ + #define SYMTYPE '2' /* reserved */ + #define CHRTYPE '3' /* character special */ + #define BLKTYPE '4' /* block special */ + #define DIRTYPE '5' /* directory */ + #define FIFOTYPE '6' /* FIFO special */ + #define CONTTYPE '7' /* reserved */ + + #define XHDTYPE 'x' /* Extended header referring to the + next file in the archive */ + #define XGLTYPE 'g' /* Global extended header */ + + /* Bits used in the mode field, values in octal. */ + #define TSUID 04000 /* set UID on execution */ + #define TSGID 02000 /* set GID on execution */ + #define TSVTX 01000 /* reserved */ + /* file permissions */ + #define TUREAD 00400 /* read by owner */ + #define TUWRITE 00200 /* write by owner */ + #define TUEXEC 00100 /* execute/search by owner */ + #define TGREAD 00040 /* read by group */ + #define TGWRITE 00020 /* write by group */ + #define TGEXEC 00010 /* execute/search by group */ + #define TOREAD 00004 /* read by other */ + #define TOWRITE 00002 /* write by other */ + #define TOEXEC 00001 /* execute/search by other */ + + /* tar Header Block, GNU extensions. */ + + /* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for + contiguous files, so maybe disobeying the "reserved" comment in POSIX + header description. I suspect these were meant to be used this way, and + should not have really been "reserved" in the published standards. */ + + /* *BEWARE* *BEWARE* *BEWARE* that the following information is still + boiling, and may change. Even if the OLDGNU format description should be + accurate, the so-called GNU format is not yet fully decided. It is + surely meant to use only extensions allowed by POSIX, but the sketch + below repeats some ugliness from the OLDGNU format, which should rather + go away. Sparse files should be saved in such a way that they do *not* + require two passes at archive creation time. Huge files get some POSIX + fields to overflow, alternate solutions have to be sought for this. */ + + /* Descriptor for a single file hole. */ + + struct sparse + { /* byte offset */ + char offset[12]; /* 0 */ + char numbytes[12]; /* 12 */ + /* 24 */ + }; + + /* Sparse files are not supported in POSIX ustar format. For sparse files + with a POSIX header, a GNU extra header is provided which holds overall + sparse information and a few sparse descriptors. When an old GNU header + replaces both the POSIX header and the GNU extra header, it holds some + sparse descriptors too. Whether POSIX or not, if more sparse descriptors + are still needed, they are put into as many successive sparse headers as + necessary. The following constants tell how many sparse descriptors fit + in each kind of header able to hold them. */ + + #define SPARSES_IN_EXTRA_HEADER 16 + #define SPARSES_IN_OLDGNU_HEADER 4 + #define SPARSES_IN_SPARSE_HEADER 21 + + /* Extension header for sparse files, used immediately after the GNU extra + header, and used only if all sparse information cannot fit into that + extra header. There might even be many such extension headers, one after + the other, until all sparse information has been recorded. */ + + struct sparse_header + { /* byte offset */ + struct sparse sp[SPARSES_IN_SPARSE_HEADER]; + /* 0 */ + char isextended; /* 504 */ + /* 505 */ + }; + + /* The old GNU format header conflicts with POSIX format in such a way that + POSIX archives may fool old GNU tar's, and POSIX tar's might well be + fooled by old GNU tar archives. An old GNU format header uses the space + used by the prefix field in a POSIX header, and cumulates information + normally found in a GNU extra header. With an old GNU tar header, we + never see any POSIX header nor GNU extra header. Supplementary sparse + headers are allowed, however. */ + + struct oldgnu_header + { /* byte offset */ + char unused_pad1[345]; /* 0 */ + char atime[12]; /* 345 Incr. archive: atime of the file */ + char ctime[12]; /* 357 Incr. archive: ctime of the file */ + char offset[12]; /* 369 Multivolume archive: the offset of + the start of this volume */ + char longnames[4]; /* 381 Not used */ + char unused_pad2; /* 385 */ + struct sparse sp[SPARSES_IN_OLDGNU_HEADER]; + /* 386 */ + char isextended; /* 482 Sparse file: Extension sparse header + follows */ + char realsize[12]; /* 483 Sparse file: Real size*/ + /* 495 */ + }; + + /* OLDGNU_MAGIC uses both magic and version fields, which are contiguous. + Found in an archive, it indicates an old GNU header format, which will be + hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are + valid, though the header is not truly POSIX conforming. */ + #define OLDGNU_MAGIC "ustar " /* 7 chars and a null */ + + /* The standards committee allows only capital A through capital Z for + user-defined expansion. Other letters in use include: + + 'A' Solaris Access Control List + 'E' Solaris Extended Attribute File + 'I' Inode only, as in 'star' + 'N' Obsolete GNU tar, for file names that do not fit into the main header. + 'X' POSIX 1003.1-2001 eXtended (VU version) */ + + /* This is a dir entry that contains the names of files that were in the + dir at the time the dump was made. */ + #define GNUTYPE_DUMPDIR 'D' + + /* Identifies the *next* file on the tape as having a long linkname. */ + #define GNUTYPE_LONGLINK 'K' + + /* Identifies the *next* file on the tape as having a long name. */ + #define GNUTYPE_LONGNAME 'L' + + /* This is the continuation of a file that began on another volume. */ + #define GNUTYPE_MULTIVOL 'M' + + /* This is for sparse files. */ + #define GNUTYPE_SPARSE 'S' + + /* This file is a tape/volume header. Ignore it on extraction. */ + #define GNUTYPE_VOLHDR 'V' + + /* Solaris extended header */ + #define SOLARIS_XHDTYPE 'X' + + /* Jo"rg Schilling star header */ + + struct star_header + { /* byte offset */ + char name[100]; /* 0 */ + char mode[8]; /* 100 */ + char uid[8]; /* 108 */ + char gid[8]; /* 116 */ + char size[12]; /* 124 */ + char mtime[12]; /* 136 */ + char chksum[8]; /* 148 */ + char typeflag; /* 156 */ + char linkname[100]; /* 157 */ + char magic[6]; /* 257 */ + char version[2]; /* 263 */ + char uname[32]; /* 265 */ + char gname[32]; /* 297 */ + char devmajor[8]; /* 329 */ + char devminor[8]; /* 337 */ + char prefix[131]; /* 345 */ + char atime[12]; /* 476 */ + char ctime[12]; /* 488 */ + /* 500 */ + }; + + #define SPARSES_IN_STAR_HEADER 4 + #define SPARSES_IN_STAR_EXT_HEADER 21 + + struct star_in_header + { + char fill[345]; /* 0 Everything that is before t_prefix */ + char prefix[1]; /* 345 t_name prefix */ + char fill2; /* 346 */ + char fill3[8]; /* 347 */ + char isextended; /* 355 */ + struct sparse sp[SPARSES_IN_STAR_HEADER]; /* 356 */ + char realsize[12]; /* 452 Actual size of the file */ + char offset[12]; /* 464 Offset of multivolume contents */ + char atime[12]; /* 476 */ + char ctime[12]; /* 488 */ + char mfill[8]; /* 500 */ + char xmagic[4]; /* 508 "tar" */ + }; + + struct star_ext_header + { + struct sparse sp[SPARSES_IN_STAR_EXT_HEADER]; + char isextended; + }; + + + All characters in header blocks are represented by using 8-bit +characters in the local variant of ASCII. Each field within the +structure is contiguous; that is, there is no padding used within the +structure. Each character on the archive medium is stored contiguously. + + Bytes representing the contents of files (after the header block of +each file) are not translated in any way and are not constrained to +represent characters in any character set. The 'tar' format does not +distinguish text files from binary files, and no translation of file +contents is performed. + + The 'name', 'linkname', 'magic', 'uname', and 'gname' are +null-terminated character strings. All other fields are zero-filled +octal numbers in ASCII. Each numeric field of width W contains W minus 1 +digits, and a null. + + The 'name' field is the file name of the file, with directory names +(if any) preceding the file name, separated by slashes. + + The 'mode' field provides nine bits specifying file permissions and +three bits to specify the Set UID, Set GID, and Save Text ("sticky") +modes. Values for these bits are defined above. When special +permissions are required to create a file with a given mode, and the +user restoring files from the archive does not hold such permissions, +the mode bit(s) specifying those special permissions are ignored. Modes +which are not supported by the operating system restoring files from the +archive will be ignored. Unsupported modes should be faked up when +creating or updating an archive; e.g., the group permission could be +copied from the _other_ permission. + + The 'uid' and 'gid' fields are the numeric user and group ID of the +file owners, respectively. If the operating system does not support +numeric user or group IDs, these fields should be ignored. + + The 'size' field is the size of the file in bytes; linked files are +archived with this field specified as zero. + + The 'mtime' field is the data modification time of the file at the +time it was archived. It is the ASCII representation of the octal value +of the last time the file's contents were modified, represented as an +integer number of seconds since January 1, 1970, 00:00 Coordinated +Universal Time. + + The 'chksum' field is the ASCII representation of the octal value of +the simple sum of all bytes in the header block. Each 8-bit byte in the +header is added to an unsigned integer, initialized to zero, the +precision of which shall be no less than seventeen bits. When +calculating the checksum, the 'chksum' field is treated as if it were +all blanks. + + The 'typeflag' field specifies the type of file archived. If a +particular implementation does not recognize or permit the specified +type, the file will be extracted as if it were a regular file. As this +action occurs, 'tar' issues a warning to the standard error. + + The 'atime' and 'ctime' fields are used in making incremental +backups; they store, respectively, the particular file's access and +status change times. + + The 'offset' is used by the '--multi-volume' ('-M') option, when +making a multi-volume archive. The offset is number of bytes into the +file that we need to restart at to continue the file on the next tape, +i.e., where we store the location that a continued file is continued at. + + The following fields were added to deal with sparse files. A file is +"sparse" if it takes in unallocated blocks which end up being +represented as zeros, i.e., no useful data. A test to see if a file is +sparse is to look at the number blocks allocated for it versus the +number of characters in the file; if there are fewer blocks allocated +for the file than would normally be allocated for a file of that size, +then the file is sparse. This is the method 'tar' uses to detect a +sparse file, and once such a file is detected, it is treated differently +from non-sparse files. + + Sparse files are often 'dbm' files, or other database-type files +which have data at some points and emptiness in the greater part of the +file. Such files can appear to be very large when an 'ls -l' is done on +them, when in truth, there may be a very small amount of important data +contained in the file. It is thus undesirable to have 'tar' think that +it must back up this entire file, as great quantities of room are wasted +on empty blocks, which can lead to running out of room on a tape far +earlier than is necessary. Thus, sparse files are dealt with so that +these empty blocks are not written to the tape. Instead, what is +written to the tape is a description, of sorts, of the sparse file: +where the holes are, how big the holes are, and how much data is found +at the end of the hole. This way, the file takes up potentially far +less room on the tape, and when the file is extracted later on, it will +look exactly the way it looked beforehand. The following is a +description of the fields used to handle a sparse file: + + The 'sp' is an array of 'struct sparse'. Each 'struct sparse' +contains two 12-character strings which represent an offset into the +file and a number of bytes to be written at that offset. The offset is +absolute, and not relative to the offset in preceding array element. + + The header can hold four of these 'struct sparse' at the moment; if +more are needed, they are not stored in the header. + + The 'isextended' flag is set when an 'extended_header' is needed to +deal with a file. Note that this means that this flag can only be set +when dealing with a sparse file, and it is only set in the event that +the description of the file will not fit in the allotted room for sparse +structures in the header. In other words, an extended_header is needed. + + The 'extended_header' structure is used for sparse files which need +more sparse structures than can fit in the header. The header can fit 4 +such structures; if more are needed, the flag 'isextended' gets set and +the next block is an 'extended_header'. + + Each 'extended_header' structure contains an array of 21 sparse +structures, along with a similar 'isextended' flag that the header had. +There can be an indeterminate number of such 'extended_header's to +describe a sparse file. + +'REGTYPE' +'AREGTYPE' + These flags represent a regular file. In order to be compatible + with older versions of 'tar', a 'typeflag' value of 'AREGTYPE' + should be silently recognized as a regular file. New archives + should be created using 'REGTYPE'. Also, for backward + compatibility, 'tar' treats a regular file whose name ends with a + slash as a directory. + +'LNKTYPE' + This flag represents a file linked to another file, of any type, + previously archived. Such files are identified in Unix by each + file having the same device and inode number. The linked-to name + is specified in the 'linkname' field with a trailing null. + +'SYMTYPE' + This represents a symbolic link to another file. The linked-to + name is specified in the 'linkname' field with a trailing null. + +'CHRTYPE' +'BLKTYPE' + These represent character special files and block special files + respectively. In this case the 'devmajor' and 'devminor' fields + will contain the major and minor device numbers respectively. + Operating systems may map the device specifications to their own + local specification, or may ignore the entry. + +'DIRTYPE' + This flag specifies a directory or sub-directory. The directory + name in the 'name' field should end with a slash. On systems where + disk allocation is performed on a directory basis, the 'size' field + will contain the maximum number of bytes (which may be rounded to + the nearest disk block allocation unit) which the directory may + hold. A 'size' field of zero indicates no such limiting. Systems + which do not support limiting in this manner should ignore the + 'size' field. + +'FIFOTYPE' + This specifies a FIFO special file. Note that the archiving of a + FIFO file archives the existence of this file and not its contents. + +'CONTTYPE' + This specifies a contiguous file, which is the same as a normal + file except that, in operating systems which support it, all its + space is allocated contiguously on the disk. Operating systems + which do not allow contiguous allocation should silently treat this + type as a normal file. + +'A' ... 'Z' + These are reserved for custom implementations. Some of these are + used in the GNU modified format, as described below. + + Other values are reserved for specification in future revisions of +the P1003 standard, and should not be used by any 'tar' program. + + The 'magic' field indicates that this archive was output in the P1003 +archive format. If this field contains 'TMAGIC', the 'uname' and +'gname' fields will contain the ASCII representation of the owner and +group of the file respectively. If found, the user and group IDs are +used rather than the values in the 'uid' and 'gid' fields. + + For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, +pages 169-173 (section 10.1) for 'Archive/Interchange File Format'; and +IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940 +(section E.4.48) for 'pax - Portable archive interchange'. + + +File: tar.info, Node: Extensions, Next: Sparse Formats, Prev: Standard, Up: Tar Internals + +GNU Extensions to the Archive Format +==================================== + + _(This message will disappear, once this node revised.)_ + + The GNU format uses additional file types to describe new types of +files in an archive. These are listed below. + +'GNUTYPE_DUMPDIR' +''D'' + This represents a directory and a list of files created by the + '--incremental' ('-G') option. The 'size' field gives the total + size of the associated list of files. Each file name is preceded + by either a 'Y' (the file should be in this archive) or an 'N'. + (The file is a directory, or is not stored in the archive.) Each + file name is terminated by a null. There is an additional null + after the last file name. + +'GNUTYPE_MULTIVOL' +''M'' + This represents a file continued from another volume of a + multi-volume archive created with the '--multi-volume' ('-M') + option. The original type of the file is not given here. The + 'size' field gives the maximum size of this piece of the file + (assuming the volume does not end before the file is written out). + The 'offset' field gives the offset from the beginning of the file + where this part of the file begins. Thus 'size' plus 'offset' + should equal the original size of the file. + +'GNUTYPE_SPARSE' +''S'' + This flag indicates that we are dealing with a sparse file. Note + that archiving a sparse file requires special operations to find + holes in the file, which mark the positions of these holes, along + with the number of bytes of data to be found after the hole. + +'GNUTYPE_VOLHDR' +''V'' + This file type is used to mark the volume header that was given + with the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') option when + the archive was created. The 'name' field contains the 'name' + given after the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') + option. The 'size' field is zero. Only the first file in each + volume of an archive should have this type. + + You may have trouble reading a GNU format archive on a non-GNU system +if the options '--incremental' ('-G'), '--multi-volume' ('-M'), +'--sparse' ('-S'), or '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') were +used when writing the archive. In general, if 'tar' does not use the +GNU-added fields of the header, other versions of 'tar' should be able +to read the archive. Otherwise, the 'tar' program will give an error, +the most likely one being a checksum error. + + +File: tar.info, Node: Sparse Formats, Next: Snapshot Files, Prev: Extensions, Up: Tar Internals + +Storing Sparse Files +==================== + +The notion of sparse file, and the ways of handling it from the point of +view of GNU 'tar' user have been described in detail in *note sparse::. +This chapter describes the internal format GNU 'tar' uses to store such +files. + + The support for sparse files in GNU 'tar' has a long history. The +earliest version featuring this support that I was able to find was +1.09, released in November, 1990. The format introduced back then is +called "old GNU" sparse format and in spite of the fact that its design +contained many flaws, it was the only format GNU 'tar' supported until +version 1.14 (May, 2004), which introduced initial support for sparse +archives in PAX archives (*note posix::). This format was not free from +design flaws, either and it was subsequently improved in versions 1.15.2 +(November, 2005) and 1.15.92 (June, 2006). + + In addition to GNU sparse format, GNU 'tar' is able to read and +extract sparse files archived by 'star'. + + The following subsections describe each format in detail. + +* Menu: + +* Old GNU Format:: +* PAX 0:: PAX Format, Versions 0.0 and 0.1 +* PAX 1:: PAX Format, Version 1.0 + + +File: tar.info, Node: Old GNU Format, Next: PAX 0, Up: Sparse Formats + +Old GNU Format +-------------- + +The format introduced in November 1990 (v. 1.09) was designed on top of +standard 'ustar' headers in such an unfortunate way that some of its +fields overwrote fields required by POSIX. + + An old GNU sparse header is designated by type 'S' ('GNUTYPE_SPARSE') +and has the following layout: + +Offset Size Name Data type Contents +---------------------------------------------------------------------------- +0 345 N/A Not used. +345 12 atime Number 'atime' of the file. +357 12 ctime Number 'ctime' of the file . +369 12 offset Number For multivolume archives: + the offset of the start of + this volume. +381 4 N/A Not used. +385 1 N/A Not used. +386 96 sp 'sparse_header'(4 entries) File map. +482 1 isextended Bool '1' if an extension sparse + header follows, '0' + otherwise. +483 12 realsize Number Real size of the file. + + Each of 'sparse_header' object at offset 386 describes a single data +chunk. It has the following structure: + +Offset Size Data type Contents +--------------------------------------------------------------------------- +0 12 Number Offset of the beginning of the chunk. +12 12 Number Size of the chunk. + + If the member contains more than four chunks, the 'isextended' field +of the header has the value '1' and the main header is followed by one +or more "extension headers". Each such header has the following +structure: + +Offset Size Name Data type Contents +---------------------------------------------------------------------------- +0 21 sp 'sparse_header'(21 entries) File map. +504 1 isextended Bool '1' if an extension sparse + header follows, or '0' + otherwise. + + A header with 'isextended=0' ends the map. + + +File: tar.info, Node: PAX 0, Next: PAX 1, Prev: Old GNU Format, Up: Sparse Formats + +PAX Format, Versions 0.0 and 0.1 +-------------------------------- + +There are two formats available in this branch. The version '0.0' is +the initial version of sparse format used by 'tar' versions 1.14-1.15.1. +The sparse file map is kept in extended ('x') PAX header variables: + +'GNU.sparse.size' + Real size of the stored file; + +'GNU.sparse.numblocks' + Number of blocks in the sparse map; + +'GNU.sparse.offset' + Offset of the data block; + +'GNU.sparse.numbytes' + Size of the data block. + + The latter two variables repeat for each data block, so the overall +structure is like this: + + GNU.sparse.size=SIZE + GNU.sparse.numblocks=NUMBLOCKS + repeat NUMBLOCKS times + GNU.sparse.offset=OFFSET + GNU.sparse.numbytes=NUMBYTES + end repeat + + This format presented the following two problems: + + 1. Whereas the POSIX specification allows a variable to appear + multiple times in a header, it requires that only the last + occurrence be meaningful. Thus, multiple occurrences of + 'GNU.sparse.offset' and 'GNU.sparse.numbytes' are conflicting with + the POSIX specs. + + 2. Attempting to extract such archives using a third-party's 'tar' + results in extraction of sparse files in _condensed form_. If the + 'tar' implementation in question does not support POSIX format, it + will also extract a file containing extension header attributes. + This file can be used to expand the file to its original state. + However, posix-aware 'tar's will usually ignore the unknown + variables, which makes restoring the file more difficult. *Note + Extraction of sparse members in v.0.0 format: extracting sparse + v.0.x, for the detailed description of how to restore such members + using non-GNU 'tar's. + + GNU 'tar' 1.15.2 introduced sparse format version '0.1', which +attempted to solve these problems. As its predecessor, this format +stores sparse map in the extended POSIX header. It retains +'GNU.sparse.size' and 'GNU.sparse.numblocks' variables, but instead of +'GNU.sparse.offset'/'GNU.sparse.numbytes' pairs it uses a single +variable: + +'GNU.sparse.map' + Map of non-null data chunks. It is a string consisting of + comma-separated values "OFFSET,SIZE[,OFFSET-1,SIZE-1...]" + + To address the 2nd problem, the 'name' field in 'ustar' is replaced +with a special name, constructed using the following pattern: + + %d/GNUSparseFile.%p/%f + + The real name of the sparse file is stored in the variable +'GNU.sparse.name'. Thus, those 'tar' implementations that are not aware +of GNU extensions will at least extract the files into separate +directories, giving the user a possibility to expand it afterwards. +*Note Extraction of sparse members in v.0.1 format: extracting sparse +v.0.x, for the detailed description of how to restore such members using +non-GNU 'tar's. + + The resulting 'GNU.sparse.map' string can be _very_ long. Although +POSIX does not impose any limit on the length of a 'x' header variable, +this possibly can confuse some 'tar's. + + +File: tar.info, Node: PAX 1, Prev: PAX 0, Up: Sparse Formats + +PAX Format, Version 1.0 +----------------------- + +The version '1.0' of sparse format was introduced with GNU 'tar' +1.15.92. Its main objective was to make the resulting file extractable +with little effort even by non-posix aware 'tar' implementations. +Starting from this version, the extended header preceding a sparse +member always contains the following variables that identify the format +being used: + +'GNU.sparse.major' + Major version + +'GNU.sparse.minor' + Minor version + + The 'name' field in 'ustar' header contains a special name, +constructed using the following pattern: + + %d/GNUSparseFile.%p/%f + + The real name of the sparse file is stored in the variable +'GNU.sparse.name'. The real size of the file is stored in the variable +'GNU.sparse.realsize'. + + The sparse map itself is stored in the file data block, preceding the +actual file data. It consists of a series of octal numbers of arbitrary +length, delimited by newlines. The map is padded with nulls to the +nearest block boundary. + + The first number gives the number of entries in the map. Following +are map entries, each one consisting of two numbers giving the offset +and size of the data block it describes. + + The format is designed in such a way that non-posix aware 'tar's and +'tar's not supporting 'GNU.sparse.*' keywords will extract each sparse +file in its condensed form with the file map prepended and will place it +into a separate directory. Then, using a simple program it would be +possible to expand the file to its original form even without GNU 'tar'. +*Note Sparse Recovery::, for the detailed information on how to extract +sparse members without GNU 'tar'. + + +File: tar.info, Node: Snapshot Files, Next: Dumpdir, Prev: Sparse Formats, Up: Tar Internals + +Format of the Incremental Snapshot Files +======================================== + +A "snapshot file" (or "directory file") is created during incremental +backups (*note Incremental Dumps::). It contains the status of the file +system at the time of the dump and is used to determine which files were +modified since the last backup. + + GNU 'tar' version 1.29 supports three snapshot file formats. The +first format, called "format 0", is the one used by GNU 'tar' versions +up to and including 1.15.1. The second format, called "format 1" is an +extended version of this format, that contains more metadata and allows +for further extensions. It was used by alpha release version 1.15.90. +For alpha version 1.15.91 and stable releases version 1.16 up through +1.29, the "format 2" is used. + + GNU 'tar' is able to read all three formats, but will create +snapshots only in format 2. + + This appendix describes all three formats in detail. + + 0. 'Format 0' snapshot file begins with a line containing a decimal + number that represents a UNIX timestamp of the beginning of the + last archivation. This line is followed by directory metadata + descriptions, one per line. Each description has the following + format: + + [NFS]DEV INODE NAME + + where: + + NFS + A single plus character ('+'), if this directory is located on + an NFS-mounted partition, otherwise empty. + + (That is, for non-NFS directories, the first character on the + description line contains the start of the DEV field.) + + DEV + Device number of the directory; + + INODE + I-node number of the directory; + + NAME + Name of the directory. Any special characters (white-space, + backslashes, etc.) are quoted. + + 1. 'Format 1' snapshot file begins with a line specifying the format + of the file. This line has the following structure: + + 'GNU tar-'TAR-VERSION'-'INCR-FORMAT-VERSION + + where TAR-VERSION is the version number of GNU 'tar' implementation + that created this snapshot, and INCR-FORMAT-VERSION is the version + number of the snapshot format (in this case '1'). + + Next line contains two decimal numbers, representing the time of + the last backup. First number is the number of seconds, the second + one is the number of nanoseconds, since the beginning of the epoch. + + Lines that follow contain directory metadata, one line per + directory. Each line is formatted as follows: + + [NFS]MTIME-SEC MTIME-NSEC DEV INODE NAME + + where MTIME-SEC and MTIME-NSEC represent last modification time of + this directory with nanosecond precision; NFS, DEV, INODE and NAME + have the same meaning as with 'format 0'. + + 2. 'Format 2' snapshot file begins with a format identifier, as + described for version 1, e.g.: + + GNU tar-1.29-2 + + This line is followed by newline. Rest of file consists of + records, separated by null (ASCII 0) characters. Thus, in contrast + to the previous formats, format 2 snapshot is a binary file. + + First two records are decimal integers, representing the time of + the last backup. First number is the number of seconds, the second + one is the number of nanoseconds, since the beginning of the epoch. + These are followed by arbitrary number of directory records. + + Each "directory record" contains a set of metadata describing a + particular directory. Parts of a directory record are delimited + with ASCII 0 characters. The following table describes each part. + The "Number" type in this table stands for a decimal integer in + ASCII notation. (Negative values are preceded with a "-" + character, while positive values have no leading punctuation.) + + Field Type Description + --------------------------------------------------------------------------- + nfs Character '1' if the directory is located on an + NFS-mounted partition, or '0' otherwise; + timestamp_sec Number Modification time, seconds; + timestamp_nsec Number Modification time, nanoseconds; + dev Number Device number; + ino Number I-node number; + name String Directory name; in contrast to the + previous versions it is not quoted; + contents Dumpdir Contents of the directory; + *Note Dumpdir::, for a description of its + format. + + Dumpdirs stored in snapshot files contain only records of types + 'Y', 'N' and 'D'. + + The specific range of values allowed in each of the "Number" fields + depends on the underlying C datatypes as determined when 'tar' is + compiled. To see the specific ranges allowed for a particular + 'tar' binary, you can use the '--show-snapshot-field-ranges' + option: + + $ tar --show-shapshot-field-ranges + This tar's snapshot file field ranges are + (field name => [ min, max ]): + + nfs => [ 0, 1 ], + timestamp_sec => [ -9223372036854775808, 9223372036854775807 ], + timestamp_nsec => [ 0, 999999999 ], + dev => [ 0, 18446744073709551615 ], + ino => [ 0, 18446744073709551615 ], + + (This example is from a GNU/Linux x86_64 system.) + + +File: tar.info, Node: Dumpdir, Prev: Snapshot Files, Up: Tar Internals + +Dumpdir +======= + +Incremental archives keep information about contents of each dumped +directory in special data blocks called "dumpdirs". + + Dumpdir is a sequence of entries of the following form: + + C FILENAME \0 + +where C is one of the "control codes" described below, FILENAME is the +name of the file C operates upon, and '\0' represents a nul character +(ASCII 0). The white space characters were added for readability, real +dumpdirs do not contain them. + + Each dumpdir ends with a single nul character. + + The following table describes control codes and their meanings: + +'Y' + FILENAME is contained in the archive. + +'N' + FILENAME was present in the directory at the time the archive was + made, yet it was not dumped to the archive, because it had not + changed since the last backup. + +'D' + FILENAME is a directory. + +'R' + This code requests renaming of the FILENAME to the name specified + with the 'T' command, that immediately follows it. + +'T' + Specify target file name for 'R' command (see below). + +'X' + Specify "temporary directory" name for a rename operation (see + below). + + Codes 'Y', 'N' and 'D' require FILENAME argument to be a relative +file name to the directory this dumpdir describes, whereas codes 'R', +'T' and 'X' require their argument to be an absolute file name. + + The three codes 'R', 'T' and 'X' specify a "renaming operation". In +the simplest case it is: + + Rsource\0Tdest\0 + +which means "rename file 'source' to file 'dest'". + + However, there are cases that require using a "temporary directory". +For example, consider the following scenario: + + 1. Previous run dumped a directory 'foo' which contained the following + three directories: + + a + b + c + + 2. They were renamed _cyclically_, so that: + + a became b + b became c + c became a + + 3. New incremental dump was made. + + This case cannot be handled by three successive renames, since +renaming 'a' to 'b' will destroy the existing directory. To correctly +process it, GNU 'tar' needs a temporary directory, so it creates the +following dumpdir (newlines have been added for readability): + + Xfoo\0 + Rfoo/a\0T\0 + Rfoo/b\0Tfoo/c\0 + Rfoo/c\0Tfoo/a\0 + R\0Tfoo/a\0 + + The first command, 'Xfoo\0', instructs the extractor to create a +temporary directory in the directory 'foo'. Second command, +'Rfoo/aT\0', says "rename file 'foo/a' to the temporary directory that +has just been created" (empty file name after a command means use +temporary directory). Third and fourth commands work as usual, and, +finally, the last command, 'R\0Tfoo/a\0' tells tar to rename the +temporary directory to 'foo/a'. + + The exact placement of a dumpdir in the archive depends on the +archive format (*note Formats::): + + * PAX archives + + In PAX archives, dumpdir is stored in the extended header of the + corresponding directory, in variable 'GNU.dumpdir'. + + * GNU and old GNU archives + + These formats implement special header type 'D', which is similar + to ustar header '5' (directory), except that it precedes a data + block containing the dumpdir. + + +File: tar.info, Node: Genfile, Next: Free Software Needs Free Documentation, Prev: Tar Internals, Up: Top + +Appendix E Genfile +****************** + +This appendix describes 'genfile', an auxiliary program used in the GNU +tar testsuite. If you are not interested in developing GNU tar, skip +this appendix. + + Initially, 'genfile' was used to generate data files for the +testsuite, hence its name. However, new operation modes were being +implemented as the testsuite grew more sophisticated, and now 'genfile' +is a multi-purpose instrument. + + There are three basic operation modes: + +File Generation + This is the default mode. In this mode, 'genfile' generates data + files. + +File Status + In this mode 'genfile' displays status of specified files. + +Synchronous Execution. + In this mode 'genfile' executes the given program with + '--checkpoint' option and executes a set of actions when specified + checkpoints are reached. + +* Menu: + +* Generate Mode:: File Generation Mode. +* Status Mode:: File Status Mode. +* Exec Mode:: Synchronous Execution mode. + + +File: tar.info, Node: Generate Mode, Next: Status Mode, Up: Genfile + +E.1 Generate Mode +================= + +In this mode 'genfile' creates a data file for the test suite. The size +of the file is given with the '--length' ('-l') option. By default the +file contents is written to the standard output, this can be changed +using '--file' ('-f') command line option. Thus, the following two +commands are equivalent: + + genfile --length 100 > outfile + genfile --length 100 --file outfile + + If '--length' is not given, 'genfile' will generate an empty +(zero-length) file. + + The command line option '--seek=N' istructs 'genfile' to skip the +given number of bytes (N) in the output file before writing to it. It +is similar to the 'seek=N' of the 'dd' utility. + + You can instruct 'genfile' to create several files at one go, by +giving it '--files-from' ('-T') option followed by a name of file +containing a list of file names. Using dash ('-') instead of the file +name causes 'genfile' to read file list from the standard input. For +example: + + # Read file names from file file.list + genfile --files-from file.list + # Read file names from standard input + genfile --files-from - + + The list file is supposed to contain one file name per line. To use +file lists separated by ASCII NUL character, use '--null' ('-0') command +line option: + + genfile --null --files-from file.list + + The default data pattern for filling the generated file consists of +first 256 letters of ASCII code, repeated enough times to fill the +entire file. This behavior can be changed with '--pattern' option. +This option takes a mandatory argument, specifying pattern name to use. +Currently two patterns are implemented: + +'--pattern=default' + The default pattern as described above. + +'--pattern=zero' + Fills the file with zeroes. + + If no file name was given, the program exits with the code '0'. +Otherwise, it exits with '0' only if it was able to create a file of the +specified length. + + Special option '--sparse' ('-s') instructs 'genfile' to create a +sparse file. Sparse files consist of "data fragments", separated by +"holes" or blocks of zeros. On many operating systems, actual disk +storage is not allocated for holes, but they are counted in the length +of the file. To create a sparse file, 'genfile' should know where to +put data fragments, and what data to use to fill them. So, when +'--sparse' is given the rest of the command line specifies a so-called +"file map". + + The file map consists of any number of "fragment descriptors". Each +descriptor is composed of two values: a number, specifying fragment +offset from the end of the previous fragment or, for the very first +fragment, from the beginning of the file, and "contents string", that +specifies the pattern to fill the fragment with. File offset can be +suffixed with the following quantifiers: + +'k' +'K' + The number is expressed in kilobytes. +'m' +'M' + The number is expressed in megabytes. +'g' +'G' + The number is expressed in gigabytes. + + Contents string can be either a fragment size or a pattern. Fragment +size is a decimal number, prefixed with an equals sign. It can be +suffixed with a quantifier, as discussed above. If fragment size is +given, the fragment of that size will be filled with the currently +selected pattern (*note -pattern: Generate Mode.) and written to the +file. + + A pattern is a string of arbitrary ASCII characters. For each of +them, 'genfile' will generate a "block" of data, filled with that +character and will write it to the fragment. The size of block is given +by '--block-size' option. It defaults to 512. Thus, if pattern +consists of N characters, the resulting file fragment will contain +'N*BLOCK-SIZE' bytes of data. + + The last fragment descriptor can have only file offset part. In this +case 'genfile' will create a hole at the end of the file up to the given +offset. + + A dash appearing as a fragment descriptor instructs 'genfile' to read +file map from the standard input. Each line of input should consist of +fragment offset and contents string, separated by any amount of +whitespace. + + For example, consider the following invocation: + + genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K + +It will create 3101184-bytes long file of the following structure: + +Offset Length Contents +0 4*512=2048 Four 512-byte blocks, filled + with letters 'A', 'B', 'C' and + 'D'. +2048 1046528 Zero bytes +1050624 5*512=2560 Five blocks, filled with + letters 'E', 'F', 'G', 'H', + 'I'. +1053184 2048000 Zero bytes + + The exit code of 'genfile --sparse' command is '0' only if created +file is actually sparse. If it is not, the appropriate error message is +displayed and the command exists with code '1'. The '--quite' ('-q') +option suppresses this behavior. If '--quite' is given, 'genfile +--sparse' exits with code '0' if it was able to create the file, whether +the resulting file is sparse or not. + + +File: tar.info, Node: Status Mode, Next: Exec Mode, Prev: Generate Mode, Up: Genfile + +E.2 Status Mode +=============== + +In status mode, 'genfile' prints file system status for each file +specified in the command line. This mode is toggled by '--stat' ('-S') +command line option. An optional argument to this option specifies +output "format": a comma-separated list of 'struct stat' fields to be +displayed. This list can contain following identifiers: + +name + The file name. + +dev +st_dev + Device number in decimal. + +ino +st_ino + Inode number. + +mode[.NUMBER] +st_mode[.NUMBER] + + File mode in octal. Optional NUMBER specifies octal mask to be + applied to the mode before outputting. For example, '--stat + mode.777' will preserve lower nine bits of it. Notice, that you + can use any punctuation character in place of '.'. + +nlink +st_nlink + Number of hard links. + +uid +st_uid + User ID of owner. + +gid +st_gid + Group ID of owner. + +size +st_size + File size in decimal. + +blksize +st_blksize + The size in bytes of each file block. + +blocks +st_blocks + Number of blocks allocated. + +atime +st_atime + Time of last access. + +mtime +st_mtime + Time of last modification + +ctime +st_ctime + Time of last status change + +sparse + A boolean value indicating whether the file is 'sparse'. + + Modification times are displayed in UTC as UNIX timestamps, unless +suffixed with 'H' (for "human-readable"), as in 'ctimeH', in which case +usual 'tar tv' output format is used. + + The default output format is: 'name,dev,ino,mode, +nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime'. + + For example, the following command will display file names and +corresponding times of last access for each file in the current working +directory: + + genfile --stat=name,atime * + + +File: tar.info, Node: Exec Mode, Prev: Status Mode, Up: Genfile + +E.3 Exec Mode +============= + +This mode is designed for testing the behavior of 'paxutils' commands +when some of the files change during archiving. It is an experimental +mode. + + The 'Exec Mode' is toggled by '--run' command line option (or its +alias '-r'). The non-optional arguments to 'getopt' give the command +line to be executed. Normally, it should contain at least the +'--checkpoint' option. + + A set of options is provided for defining checkpoint values and +actions to be executed upon reaching them. Checkpoint values are +introduced with the '--checkpoint' command line option. Argument to +this option is the number of checkpoint in decimal. + + Any number of "actions" may be specified after a checkpoint. +Available actions are + +'--cut FILE' +'--truncate FILE' + Truncate FILE to the size specified by previous '--length' option + (or 0, if it is not given). + +'--append FILE' + Append data to FILE. The size of data and its pattern are given by + previous '--length' and 'pattern' options. + +'--touch FILE' + Update the access and modification times of FILE. These timestamps + are changed to the current time, unless '--date' option was given, + in which case they are changed to the specified time. Argument to + '--date' option is a date specification in an almost arbitrary + format (*note Date input formats::). + +'--exec COMMAND' + Execute given shell command. + +'--unlink FILE' + Unlink the FILE. + + Option '--verbose' instructs 'genfile' to print on standard output +notifications about checkpoints being executed and to verbosely describe +exit status of the command. + + While the command is being executed its standard output remains +connected to descriptor 1. All messages it prints to file descriptor 2, +except checkpoint notifications, are forwarded to standard error. + + 'Genfile' exits with the exit status of the executed command. + + For compatibility with previous 'genfile' versions, the '--run' +option takes an optional argument. If used this way, its argument +supplies the command line to be executed. There should be no +non-optional arguments in the 'genfile' command line. + + The actual command line is constructed by inserting the +'--checkpoint' option between the command name and its first argument +(if any). Due to this, the argument to '--run' may not use traditional +'tar' option syntax, i.e., the following is wrong: + + # Wrong! + genfile --run='tar cf foo bar' + + Use the following syntax instead: + + genfile --run='tar -cf foo bar' ACTIONS... + + The above command line is equivalent to + + genfile ACTIONS... -- tar -cf foo bar + + Notice, that the use of compatibility mode is deprecated. + + +File: tar.info, Node: Free Software Needs Free Documentation, Next: GNU Free Documentation License, Prev: Genfile, Up: Top + +Appendix F Free Software Needs Free Documentation +************************************************* + +The biggest deficiency in the free software community today is not in +the software--it is the lack of good free documentation that we can +include with the free software. Many of our most important programs do +not come with free reference manuals and free introductory texts. +Documentation is an essential part of any software package; when an +important free software package does not come with a free manual and a +free tutorial, that is a major gap. We have many such gaps today. + + Consider Perl, for instance. The tutorial manuals that people +normally use are non-free. How did this come about? Because the +authors of those manuals published them with restrictive terms--no +copying, no modification, source files not available--which exclude them +from the free software world. + + That wasn't the first time this sort of thing happened, and it was +far from the last. Many times we have heard a GNU user eagerly describe +a manual that he is writing, his intended contribution to the community, +only to learn that he had ruined everything by signing a publication +contract to make it non-free. + + Free documentation, like free software, is a matter of freedom, not +price. The problem with the non-free manual is not that publishers +charge a price for printed copies--that in itself is fine. (The Free +Software Foundation sells printed copies of manuals, too.) The problem +is the restrictions on the use of the manual. Free manuals are +available in source code form, and give you permission to copy and +modify. Non-free manuals do not allow this. + + The criteria of freedom for a free manual are roughly the same as for +free software. Redistribution (including the normal kinds of commercial +redistribution) must be permitted, so that the manual can accompany +every copy of the program, both on-line and on paper. + + Permission for modification of the technical content is crucial too. +When people modify the software, adding or changing features, if they +are conscientious they will change the manual too--so they can provide +accurate and clear documentation for the modified program. A manual +that leaves you no choice but to write a new manual to document a +changed version of the program is not really available to our community. + + Some kinds of limits on the way modification is handled are +acceptable. For example, requirements to preserve the original author's +copyright notice, the distribution terms, or the list of authors, are +ok. It is also no problem to require modified versions to include +notice that they were modified. Even entire sections that may not be +deleted or changed are acceptable, as long as they deal with +nontechnical topics (like this one). These kinds of restrictions are +acceptable because they don't obstruct the community's normal use of the +manual. + + However, it must be possible to modify all the _technical_ content of +the manual, and then distribute the result in all the usual media, +through all the usual channels. Otherwise, the restrictions obstruct +the use of the manual, it is not free, and we need another manual to +replace it. + + Please spread the word about this issue. Our community continues to +lose manuals to proprietary publishing. If we spread the word that free +software needs free reference manuals and free tutorials, perhaps the +next person who wants to contribute by writing documentation will +realize, before it is too late, that only free manuals contribute to the +free software community. + + If you are writing documentation, please insist on publishing it +under the GNU Free Documentation License or another free documentation +license. Remember that this decision requires your approval--you don't +have to let the publisher decide. Some commercial publishers will use a +free license if you insist, but they will not propose the option; it is +up to you to raise the issue and say firmly that this is what you want. +If the publisher you are dealing with refuses, please try other +publishers. If you're not sure whether a proposed license is free, +write to <licensing@gnu.org>. + + You can encourage commercial publishers to sell more free, copylefted +manuals and tutorials by buying them, and particularly by buying copies +from the publishers that paid for their writing or for major +improvements. Meanwhile, try to avoid buying non-free documentation at +all. Check the distribution terms of a manual before you buy it, and +insist that whoever seeks your business must respect your freedom. +Check the history of the book, and try reward the publishers that have +paid or pay the authors to work on it. + + The Free Software Foundation maintains a list of free documentation +published by other publishers, at +<http://www.fsf.org/doc/other-free-books.html>. + + +File: tar.info, Node: GNU Free Documentation License, Next: Index of Command Line Options, Prev: Free Software Needs Free Documentation, Up: Top + +Appendix G GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000-2002, 2007-2008, 2014, 2016 Free Software + Foundation, Inc. + <http://fsf.org/> + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + <http://www.gnu.org/copyleft/>. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: tar.info, Node: Index of Command Line Options, Next: Index, Prev: GNU Free Documentation License, Up: Top + +Appendix H Index of Command Line Options +**************************************** + +This appendix contains an index of all GNU 'tar' long command line +options. The options are listed without the preceding double-dash. For +a cross-reference of short command line options, see *note Short Option +Summary::. + + +* Menu: + +* absolute-names: absolute. (line 10) +* absolute-names, summary: Option Summary. (line 6) +* acls, summary: Option Summary. (line 14) +* add-file: files. (line 79) +* after-date: after. (line 24) +* after-date, summary: Option Summary. (line 17) +* anchored: controlling pattern-matching. + (line 78) +* anchored, summary: Option Summary. (line 21) +* append: append. (line 6) +* append <1>: appending files. (line 6) +* append, summary: Operation Summary. (line 6) +* atime-preserve: Attributes. (line 10) +* atime-preserve, summary: Option Summary. (line 25) +* auto-compress: gzip. (line 150) +* auto-compress, summary: Option Summary. (line 71) +* backup: backup. (line 41) +* backup, summary: Option Summary. (line 78) +* block-number: verbose. (line 112) +* block-number, summary: Option Summary. (line 84) +* blocking-factor: Blocking Factor. (line 8) +* blocking-factor, summary: Option Summary. (line 91) +* bzip2, summary: Option Summary. (line 97) +* catenate: concatenate. (line 6) +* catenate, summary: Operation Summary. (line 11) +* check-device, described: Incremental Dumps. (line 107) +* check-device, summary: Option Summary. (line 103) +* check-links, described: hard links. (line 31) +* check-links, summary: Option Summary. (line 155) +* checkpoint: checkpoints. (line 6) +* checkpoint, defined: checkpoints. (line 13) +* checkpoint, summary: Option Summary. (line 108) +* checkpoint-action: checkpoints. (line 6) +* checkpoint-action, defined: checkpoints. (line 22) +* checkpoint-action, summary: Option Summary. (line 117) +* clamp-mtime, summary: Option Summary. (line 172) +* compare: compare. (line 6) +* compare, summary: Operation Summary. (line 16) +* compress: gzip. (line 113) +* compress, summary: Option Summary. (line 164) +* concatenate: concatenate. (line 6) +* concatenate, summary: Operation Summary. (line 23) +* confirmation, summary: Option Summary. (line 176) +* create, additional options: create options. (line 6) +* create, complementary notes: Basic tar. (line 11) +* create, introduced: Creating the archive. + (line 6) +* create, summary: Operation Summary. (line 29) +* create, using with '--verbose': create verbose. (line 6) +* create, using with '--verify': verify. (line 24) +* delay-directory-restore: Directory Modification Times and Permissions. + (line 62) +* delay-directory-restore, summary: Option Summary. (line 180) +* delete: delete. (line 6) +* delete, summary: Operation Summary. (line 34) +* delete, using before -append: append. (line 47) +* dereference: dereference. (line 6) +* dereference, summary: Option Summary. (line 186) +* diff, summary: Operation Summary. (line 39) +* directory: directory. (line 11) +* directory, summary: Option Summary. (line 193) +* exclude: exclude. (line 6) +* exclude <1>: exclude. (line 9) +* exclude, potential problems with: problems with exclude. + (line 6) +* exclude, summary: Option Summary. (line 201) +* exclude-backups: exclude. (line 114) +* exclude-backups, summary: Option Summary. (line 206) +* exclude-caches: exclude. (line 134) +* exclude-caches, summary: Option Summary. (line 215) +* exclude-caches-all: exclude. (line 142) +* exclude-caches-all, summary: Option Summary. (line 230) +* exclude-caches-under: exclude. (line 138) +* exclude-caches-under, summary: Option Summary. (line 223) +* exclude-from: exclude. (line 6) +* exclude-from <1>: exclude. (line 20) +* exclude-from, summary: Option Summary. (line 209) +* exclude-ignore: exclude. (line 76) +* exclude-ignore, summary: Option Summary. (line 235) +* exclude-ignore-recursive: exclude. (line 81) +* exclude-ignore-recursive, summary: Option Summary. (line 240) +* exclude-tag: exclude. (line 151) +* exclude-tag, summary: Option Summary. (line 245) +* exclude-tag-all: exclude. (line 159) +* exclude-tag-all, summary: Option Summary. (line 257) +* exclude-tag-under: exclude. (line 155) +* exclude-tag-under, summary: Option Summary. (line 251) +* exclude-vcs: exclude. (line 85) +* exclude-vcs, summary: Option Summary. (line 262) +* exclude-vcs-ignores: exclude. (line 42) +* exclude-vcs-ignores, summary: Option Summary. (line 269) +* extract: extract. (line 6) +* extract, additional options: extract options. (line 6) +* extract, complementary notes: Basic tar. (line 49) +* extract, summary: Operation Summary. (line 44) +* extract, using with '--listed-incremental': Incremental Dumps. + (line 120) +* file: file. (line 6) +* file, short description: file. (line 15) +* file, summary: Option Summary. (line 277) +* file, tutorial: file tutorial. (line 6) +* files-from: files. (line 14) +* files-from, summary: Option Summary. (line 284) +* force-local, short description: Device. (line 70) +* force-local, summary: Option Summary. (line 291) +* format, summary: Option Summary. (line 297) +* full-time, summary: Option Summary. (line 322) +* get, summary: Operation Summary. (line 50) +* group: override. (line 99) +* group, summary: Option Summary. (line 340) +* group-map, summary: Option Summary. (line 350) +* gunzip, summary: Option Summary. (line 360) +* gzip: gzip. (line 91) +* gzip, summary: Option Summary. (line 360) +* hard-dereference, described: hard links. (line 59) +* hard-dereference, summary: Option Summary. (line 369) +* help: help tutorial. (line 6) +* help, introduction: help. (line 26) +* help, summary: Option Summary. (line 375) +* hole-detection: sparse. (line 66) +* hole-detection, summary: Option Summary. (line 381) +* ignore-case: controlling pattern-matching. + (line 85) +* ignore-case, summary: Option Summary. (line 386) +* ignore-command-error: Writing to an External Program. + (line 111) +* ignore-command-error, summary: Option Summary. (line 390) +* ignore-failed-read: Ignore Failed Read. (line 7) +* ignore-failed-read, summary: Option Summary. (line 394) +* ignore-zeros: Ignore Zeros. (line 6) +* ignore-zeros, short description: Blocking Factor. (line 152) +* ignore-zeros, summary: Option Summary. (line 399) +* incremental, summary: Option Summary. (line 405) +* incremental, using with '--list': Incremental Dumps. (line 185) +* index-file, summary: Option Summary. (line 413) +* info-script: Multi-Volume Archives. + (line 83) +* info-script, short description: Device. (line 121) +* info-script, summary: Option Summary. (line 417) +* interactive: interactive. (line 14) +* interactive, summary: Option Summary. (line 426) +* keep-directory-symlink, summary: Option Summary. (line 434) +* keep-newer-files: Keep Newer Files. (line 6) +* keep-newer-files, summary: Option Summary. (line 448) +* keep-old-files: Keep Old Files. (line 9) +* keep-old-files, introduced: Dealing with Old Files. + (line 16) +* keep-old-files, summary: Option Summary. (line 453) +* label: Tape Files. (line 6) +* label <1>: label. (line 6) +* label, summary: Option Summary. (line 462) +* level, described: Incremental Dumps. (line 75) +* level, summary: Option Summary. (line 470) +* list: list. (line 6) +* list, summary: Operation Summary. (line 55) +* list, using with '--incremental': Incremental Dumps. (line 185) +* list, using with '--listed-incremental': Incremental Dumps. + (line 185) +* list, using with '--verbose': list. (line 34) +* list, using with file name arguments: list. (line 25) +* listed-incremental, described: Incremental Dumps. (line 14) +* listed-incremental, summary: Option Summary. (line 480) +* listed-incremental, using with '--extract': Incremental Dumps. + (line 120) +* listed-incremental, using with '--list': Incremental Dumps. + (line 185) +* lzip: gzip. (line 104) +* lzip, summary: Option Summary. (line 489) +* lzma: gzip. (line 107) +* lzma, summary: Option Summary. (line 494) +* lzop: gzip. (line 110) +* mode: override. (line 14) +* mode, summary: Option Summary. (line 504) +* mtime: override. (line 30) +* mtime, summary: Option Summary. (line 511) +* multi-volume: Multi-Volume Archives. + (line 6) +* multi-volume, short description: Device. (line 88) +* multi-volume, summary: Option Summary. (line 526) +* new-volume-script: Multi-Volume Archives. + (line 83) +* new-volume-script, short description: Device. (line 121) +* new-volume-script, summary: Option Summary. (line 417) +* new-volume-script, summary <1>: Option Summary. (line 532) +* newer: after. (line 24) +* newer, summary: Option Summary. (line 536) +* newer-mtime: after. (line 35) +* newer-mtime, summary: Option Summary. (line 545) +* no-acls, summary: Option Summary. (line 551) +* no-anchored: controlling pattern-matching. + (line 78) +* no-anchored, summary: Option Summary. (line 555) +* no-auto-compress, summary: Option Summary. (line 559) +* no-check-device, described: Incremental Dumps. (line 103) +* no-check-device, summary: Option Summary. (line 564) +* no-delay-directory-restore: Directory Modification Times and Permissions. + (line 68) +* no-delay-directory-restore, summary: Option Summary. (line 569) +* no-ignore-case: controlling pattern-matching. + (line 85) +* no-ignore-case, summary: Option Summary. (line 575) +* no-ignore-command-error: Writing to an External Program. + (line 116) +* no-ignore-command-error, summary: Option Summary. (line 578) +* no-null, described: nul. (line 15) +* no-null, summary: Option Summary. (line 582) +* no-overwrite-dir, summary: Option Summary. (line 588) +* no-quote-chars, summary: Option Summary. (line 593) +* no-recursion: recurse. (line 11) +* no-recursion, summary: Option Summary. (line 598) +* no-same-owner: Attributes. (line 63) +* no-same-owner, summary: Option Summary. (line 603) +* no-same-permissions, summary: Option Summary. (line 610) +* no-seek, summary: Option Summary. (line 616) +* no-selinux, summary: Option Summary. (line 622) +* no-unquote: Selecting Archive Members. + (line 42) +* no-unquote, summary: Option Summary. (line 626) +* no-verbatim-files-from: files. (line 75) +* no-verbatim-files-from, summary: Option Summary. (line 630) +* no-wildcards: controlling pattern-matching. + (line 41) +* no-wildcards, summary: Option Summary. (line 644) +* no-wildcards-match-slash: controlling pattern-matching. + (line 91) +* no-wildcards-match-slash, summary: Option Summary. (line 647) +* no-xattrs, summary: Option Summary. (line 650) +* null, described: nul. (line 11) +* null, summary: Option Summary. (line 654) +* numeric-owner: Attributes. (line 69) +* numeric-owner, summary: Option Summary. (line 667) +* occurrence, described: append. (line 34) +* occurrence, summary: Option Summary. (line 685) +* old-archive, summary: Option Summary. (line 700) +* one-file-system: one. (line 14) +* one-file-system, summary: Option Summary. (line 703) +* one-top-level, summary: Option Summary. (line 708) +* overwrite: Overwrite Old Files. + (line 6) +* overwrite, introduced: Dealing with Old Files. + (line 32) +* overwrite, summary: Option Summary. (line 719) +* overwrite-dir: Overwrite Old Files. + (line 28) +* overwrite-dir, introduced: Dealing with Old Files. + (line 6) +* overwrite-dir, summary: Option Summary. (line 724) +* owner: override. (line 67) +* owner, summary: Option Summary. (line 729) +* owner-map, summary: Option Summary. (line 739) +* pax-option: PAX keywords. (line 6) +* pax-option, summary: Option Summary. (line 749) +* portability, summary: Option Summary. (line 755) +* posix, summary: Option Summary. (line 759) +* preserve-order: Same Order. (line 6) +* preserve-order, summary: Option Summary. (line 762) +* preserve-permissions: Setting Access Permissions. + (line 10) +* preserve-permissions, short description: Attributes. (line 109) +* preserve-permissions, summary: Option Summary. (line 766) +* quote-chars, summary: Option Summary. (line 777) +* quoting-style: quoting styles. (line 38) +* quoting-style, summary: Option Summary. (line 781) +* read-full-records: Reading. (line 6) +* read-full-records <1>: read full records. (line 6) +* read-full-records, short description: Blocking Factor. (line 168) +* read-full-records, summary: Option Summary. (line 788) +* record-size, summary: Option Summary. (line 794) +* recursion: recurse. (line 22) +* recursion, summary: Option Summary. (line 802) +* recursive-unlink: Recursive Unlink. (line 6) +* recursive-unlink, summary: Option Summary. (line 807) +* remove-files: remove files. (line 6) +* remove-files, summary: Option Summary. (line 812) +* restrict, summary: Option Summary. (line 817) +* rmt-command, summary: Option Summary. (line 823) +* rsh-command: Device. (line 73) +* rsh-command, summary: Option Summary. (line 828) +* same-order: Same Order. (line 6) +* same-order, summary: Option Summary. (line 833) +* same-owner: Attributes. (line 44) +* same-owner, summary: Option Summary. (line 842) +* same-permissions: Setting Access Permissions. + (line 10) +* same-permissions, short description: Attributes. (line 109) +* same-permissions, summary: Option Summary. (line 766) +* same-permissions, summary <1>: Option Summary. (line 849) +* seek, summary: Option Summary. (line 853) +* selinux, summary: Option Summary. (line 863) +* show-defaults: defaults. (line 6) +* show-defaults, summary: Option Summary. (line 867) +* show-omitted-dirs: verbose. (line 105) +* show-omitted-dirs, summary: Option Summary. (line 880) +* show-snapshot-field-ranges: Snapshot Files. (line 111) +* show-snapshot-field-ranges, summary: Option Summary. (line 885) +* show-stored-names: list. (line 68) +* show-stored-names, summary: Option Summary. (line 891) +* show-transformed-names: transform. (line 45) +* show-transformed-names, summary: Option Summary. (line 891) +* skip-old-files, introduced: Dealing with Old Files. + (line 28) +* skip-old-files, summary: Option Summary. (line 900) +* sort, summary: Option Summary. (line 913) +* sparse: sparse. (line 24) +* sparse, summary: Option Summary. (line 930) +* sparse-version: sparse. (line 59) +* sparse-version, summary: Option Summary. (line 936) +* starting-file: Starting File. (line 6) +* starting-file, summary: Option Summary. (line 942) +* strip-components: transform. (line 25) +* strip-components, summary: Option Summary. (line 949) +* suffix: backup. (line 67) +* suffix, summary: Option Summary. (line 960) +* tape-length: Multi-Volume Archives. + (line 33) +* tape-length, short description: Device. (line 96) +* tape-length, summary: Option Summary. (line 965) +* test-label: label. (line 35) +* test-label, summary: Option Summary. (line 976) +* to-command: Writing to an External Program. + (line 9) +* to-command, summary: Option Summary. (line 981) +* to-stdout: Writing to Standard Output. + (line 14) +* to-stdout, summary: Option Summary. (line 986) +* totals: verbose. (line 45) +* totals, summary: Option Summary. (line 992) +* touch: Data Modification Times. + (line 15) +* touch <1>: Attributes. (line 33) +* touch, summary: Option Summary. (line 998) +* transform: transform. (line 74) +* transform, summary: Option Summary. (line 1005) +* uncompress: gzip. (line 113) +* uncompress, summary: Option Summary. (line 164) +* uncompress, summary <1>: Option Summary. (line 1019) +* ungzip: gzip. (line 91) +* ungzip, summary: Option Summary. (line 360) +* ungzip, summary <1>: Option Summary. (line 1023) +* unlink-first: Unlink First. (line 6) +* unlink-first, introduced: Dealing with Old Files. + (line 51) +* unlink-first, summary: Option Summary. (line 1027) +* unquote: Selecting Archive Members. + (line 39) +* unquote, summary: Option Summary. (line 1033) +* update: update. (line 6) +* update <1>: how to update. (line 6) +* update, summary: Operation Summary. (line 60) +* usage: help. (line 53) +* use-compress-program: gzip. (line 172) +* use-compress-program, summary: Option Summary. (line 1037) +* utc, summary: Option Summary. (line 1043) +* verbatim-files-from: files. (line 70) +* verbatim-files-from, summary: Option Summary. (line 1048) +* verbose: verbose. (line 18) +* verbose, introduced: verbose tutorial. (line 6) +* verbose, summary: Option Summary. (line 1070) +* verbose, using with '--create': create verbose. (line 6) +* verbose, using with '--list': list. (line 34) +* verify, short description: verify. (line 8) +* verify, summary: Option Summary. (line 1078) +* verify, using with '--create': verify. (line 24) +* version: help. (line 6) +* version, summary: Option Summary. (line 1084) +* volno-file: Multi-Volume Archives. + (line 74) +* volno-file, summary: Option Summary. (line 1090) +* warning, explained: warnings. (line 12) +* warning, summary: Option Summary. (line 1096) +* wildcards: controlling pattern-matching. + (line 38) +* wildcards, summary: Option Summary. (line 1102) +* wildcards-match-slash: controlling pattern-matching. + (line 91) +* wildcards-match-slash, summary: Option Summary. (line 1106) +* xattrs, summary: Option Summary. (line 1109) +* xattrs-exclude, summary: Option Summary. (line 1113) +* xattrs-include, summary: Option Summary. (line 1117) +* xform: transform. (line 74) +* xform, summary: Option Summary. (line 1005) +* xz: gzip. (line 96) +* xz, summary: Option Summary. (line 1123) + + +File: tar.info, Node: Index, Prev: Index of Command Line Options, Up: Top + +Appendix I Index +**************** + + +* Menu: + +* '%s: Directory has been renamed from %s', warning message: warnings. + (line 96) +* '%s: Directory has been renamed', warning message: warnings. + (line 96) +* '%s: Directory is new', warning message: warnings. (line 98) +* '%s: directory is on a different device: not purging', warning message: warnings. + (line 100) +* '%s: skipping existing file', warning message: warnings. (line 62) +* -after-date and -update compared: after. (line 19) +* -newer-mtime and -update compared: after. (line 19) +* -quite, option: Generate Mode. (line 120) +* .bzrignore: exclude. (line 63) +* .cvsignore: exclude. (line 50) +* .gitignore: exclude. (line 55) +* .hgignore: exclude. (line 70) +* 'A lone zero block at', warning message: warnings. (line 33) +* abbreviations for months: Calendar date items. (line 38) +* absolute file names: absolute. (line 6) +* absolute file names <1>: Remote Tape Server. (line 17) +* Adding archives to an archive: concatenate. (line 6) +* Adding files to an Archive: appending files. (line 6) +* ADMINISTRATOR: General-Purpose Variables. + (line 6) +* Age, excluding files by: after. (line 6) +* ago in date strings: Relative items in date strings. + (line 23) +* all: warnings. (line 28) +* alone-zero-block: warnings. (line 33) +* alternative decompression programs: gzip. (line 54) +* am in date strings: Time of day items. (line 21) +* Appending files to an Archive: appending files. (line 6) +* appending files to existing archive: append. (line 6) +* Arch, excluding files: exclude. (line 85) +* archive: Definitions. (line 6) +* Archive creation: file. (line 34) +* archive member: Definitions. (line 15) +* Archive Name: file. (line 6) +* Archive, creation of: create. (line 6) +* Archives, Appending files to: appending files. (line 6) +* archives, binary equivalent: PAX keywords. (line 136) +* Archiving Directories: create dir. (line 6) +* archiving files: Top. (line 23) +* ARGP_HELP_FMT, environment variable: Configuring Help Summary. + (line 21) +* arguments to long options: Long Options. (line 31) +* arguments to old options: Old Options. (line 26) +* arguments to short options: Short Options. (line 13) +* 'Attempting extraction of symbolic links as hard links', warning message: warnings. + (line 68) +* attributes, files: Attributes. (line 6) +* authors of 'parse_datetime': Authors of parse_datetime. + (line 6) +* Avoiding recursion in directories: recurse. (line 6) +* backup options: backup. (line 6) +* backup suffix: backup. (line 67) +* backups: backup. (line 41) +* backups <1>: Backups. (line 6) +* BACKUP_DIRS: General-Purpose Variables. + (line 30) +* BACKUP_FILES: General-Purpose Variables. + (line 58) +* BACKUP_HOUR: General-Purpose Variables. + (line 10) +* bad-dumpdir: warnings. (line 102) +* basic operations: Operations. (line 6) +* Bazaar, excluding files: exclude. (line 85) +* Bazaar, ignore files: exclude. (line 37) +* beginning of time, for POSIX: Seconds since the Epoch. + (line 13) +* 'bell', checkpoint action: checkpoints. (line 106) +* Bellovin, Steven M.: Authors of parse_datetime. + (line 6) +* Berets, Jim: Authors of parse_datetime. + (line 6) +* Berry, K.: Authors of parse_datetime. + (line 19) +* binary equivalent archives, creating: PAX keywords. (line 136) +* block: Blocking. (line 6) +* Block number where error occurred: verbose. (line 112) +* BLOCKING: General-Purpose Variables. + (line 25) +* Blocking Factor: Blocking Factor. (line 6) +* blocking factor: Blocking Factor. (line 189) +* Blocks per record: Blocking Factor. (line 6) +* bug reports: Reports. (line 6) +* Bytes per record: Blocking Factor. (line 6) +* bzip2: gzip. (line 6) +* cachedir: warnings. (line 40) +* calendar date item: Calendar date items. (line 6) +* case, ignored in dates: General date syntax. (line 60) +* 'cat' vs 'concatenate': concatenate. (line 63) +* Changing directory mid-stream: directory. (line 6) +* Character class, excluding characters from: wildcards. (line 34) +* checkpoints, defined: checkpoints. (line 6) +* Choosing an archive file: file. (line 6) +* combined date and time of day item: Combined date and time of day items. + (line 6) +* comments, in dates: General date syntax. (line 60) +* compress: gzip. (line 6) +* Compressed archives: gzip. (line 6) +* 'concatenate' vs 'cat': concatenate. (line 63) +* Concatenating Archives: concatenate. (line 6) +* 'contains a cache directory tag', warning message: warnings. + (line 40) +* contiguous-cast: warnings. (line 66) +* corrupted archives: Full Dumps. (line 8) +* corrupted archives <1>: gzip. (line 140) +* Creation of the archive: create. (line 6) +* 'Current %s is newer or same age', warning message: warnings. + (line 72) +* CVS, excluding files: exclude. (line 85) +* CVS, ignore files: exclude. (line 37) +* Darcs, excluding files: exclude. (line 85) +* DAT blocking: Blocking Factor. (line 199) +* Data Modification time, excluding files by: after. (line 6) +* Data modification times of extracted files: Data Modification Times. + (line 6) +* date and time of day format, ISO 8601: Combined date and time of day items. + (line 6) +* date format, ISO 8601: Calendar date items. (line 30) +* date input formats: Date input formats. (line 6) +* day in date strings: Relative items in date strings. + (line 15) +* day in date strings <1>: Relative items in date strings. + (line 29) +* day of week item: Day of week items. (line 6) +* decompress-program: warnings. (line 76) +* Deleting files from an archive: delete. (line 6) +* Deleting from tape archives: delete. (line 17) +* dereferencing hard links: hard links. (line 6) +* Descending directories, avoiding: recurse. (line 6) +* Device numbers, changing: Fixing Snapshot Files. + (line 6) +* Device numbers, using in incremental backups: Incremental Dumps. + (line 89) +* Directories, Archiving: create dir. (line 6) +* Directories, avoiding recursion: recurse. (line 6) +* Directory, changing mid-stream: directory. (line 6) +* DIRLIST: General-Purpose Variables. + (line 53) +* displacement of dates: Relative items in date strings. + (line 6) +* doc-opt-col: Configuring Help Summary. + (line 95) +* 'door ignored', warning message: warnings. (line 45) +* 'dot', checkpoint action: checkpoints. (line 130) +* Double-checking a write operation: verify. (line 6) +* dumps, full: Full Dumps. (line 8) +* DUMP_BEGIN: User Hooks. (line 31) +* DUMP_END: User Hooks. (line 35) +* DUMP_REMIND_SCRIPT: General-Purpose Variables. + (line 112) +* dup-args: Configuring Help Summary. + (line 52) +* dup-args-note: Configuring Help Summary. + (line 69) +* 'echo', checkpoint action: checkpoints. (line 25) +* Eggert, Paul: Authors of parse_datetime. + (line 6) +* End-of-archive blocks, ignoring: Ignore Zeros. (line 6) +* End-of-archive info script: Multi-Volume Archives. + (line 83) +* entry: Naming tar Archives. (line 11) +* epoch, for POSIX: Seconds since the Epoch. + (line 13) +* Error message, block number of: verbose. (line 122) +* Exabyte blocking: Blocking Factor. (line 199) +* exclude: exclude. (line 12) +* exclude-caches: exclude. (line 122) +* exclude-from: exclude. (line 25) +* exclude-tag: exclude. (line 145) +* Excluding characters from a character class: wildcards. (line 34) +* Excluding file by age: after. (line 6) +* Excluding files by file system: exclude. (line 6) +* Excluding files by name and pattern: exclude. (line 6) +* Exec Mode, 'genfile': Exec Mode. (line 6) +* 'exec', checkpoint action: checkpoints. (line 151) +* existing backup method: backup. (line 59) +* existing-file: warnings. (line 62) +* exit status: Synopsis. (line 67) +* 'Extracting contiguous files as regular files', warning message: warnings. + (line 66) +* extracting Nth copy of the file: append. (line 34) +* extraction: Definitions. (line 22) +* Extraction: extract. (line 6) +* file archival: Top. (line 23) +* file attributes: Attributes. (line 6) +* 'file changed as we read it', warning message: warnings. (line 55) +* 'file is on a different filesystem', warning message: warnings. + (line 43) +* 'file is the archive; not dumped', warning message: warnings. + (line 51) +* 'file is the archive; not dumped', warning message <1>: warnings. + (line 51) +* 'file is unchanged; not dumped', warning message: warnings. (line 49) +* File lists separated by NUL characters: Generate Mode. (line 33) +* file name: Definitions. (line 15) +* File Name arguments, alternatives: files. (line 6) +* File name arguments, using '--list' with: list. (line 25) +* 'file name read contains nul character', warning message: warnings. + (line 31) +* file names, absolute: absolute. (line 6) +* File names, excluding files by: exclude. (line 6) +* File names, terminated by 'NUL': nul. (line 6) +* File names, using hard links: hard links. (line 6) +* File names, using symbolic links: dereference. (line 6) +* 'File removed before we read it', warning message: warnings. + (line 53) +* 'File shrank by %s bytes', warning message: warnings. (line 41) +* File system boundaries, not crossing: one. (line 6) +* file-changed: warnings. (line 55) +* file-ignored: warnings. (line 45) +* file-removed: warnings. (line 53) +* file-shrank: warnings. (line 41) +* file-unchanged: warnings. (line 49) +* FILELIST: General-Purpose Variables. + (line 69) +* filename-with-nuls: warnings. (line 31) +* 'find', using with 'tar': files. (line 6) +* 'find', using with 'tar' <1>: recurse. (line 11) +* first in date strings: General date syntax. (line 22) +* format 0, snapshot file: Snapshot Files. (line 24) +* format 1, snapshot file: Snapshot Files. (line 51) +* format 2, snapshot file: Snapshot Files. (line 73) +* Format Options: Format Variations. (line 6) +* Format Parameters: Format Variations. (line 6) +* Format, old style: old. (line 6) +* fortnight in date strings: Relative items in date strings. + (line 15) +* free documentation: Free Software Needs Free Documentation. + (line 6) +* full dumps: Full Dumps. (line 8) +* future time stamps: Large or Negative Values. + (line 6) +* general date syntax: General date syntax. (line 6) +* Generate Mode, 'genfile': Generate Mode. (line 6) +* genfile: Genfile. (line 6) +* 'genfile', create file: Generate Mode. (line 6) +* 'genfile', creating sparse files: Generate Mode. (line 55) +* 'genfile', generate mode: Generate Mode. (line 6) +* 'genfile', reading a list of file names: Generate Mode. (line 22) +* 'genfile', seeking to a given offset: Generate Mode. (line 18) +* Getting program version number: help. (line 6) +* git, excluding files: exclude. (line 85) +* Git, ignore files: exclude. (line 37) +* GNU archive format: gnu. (line 6) +* GNU.sparse.major, extended header variable: PAX 1. (line 14) +* GNU.sparse.map, extended header variable: PAX 0. (line 59) +* GNU.sparse.minor, extended header variable: PAX 1. (line 17) +* GNU.sparse.name, extended header variable: PAX 0. (line 67) +* GNU.sparse.name, extended header variable, in v.1.0: PAX 1. (line 24) +* GNU.sparse.numblocks, extended header variable: PAX 0. (line 14) +* GNU.sparse.numbytes, extended header variable: PAX 0. (line 20) +* GNU.sparse.offset, extended header variable: PAX 0. (line 17) +* GNU.sparse.realsize, extended header variable: PAX 1. (line 24) +* GNU.sparse.size, extended header variable: PAX 0. (line 10) +* gnupg, using with tar: gzip. (line 196) +* gpg, using with tar: gzip. (line 196) +* gzip: gzip. (line 6) +* hard links, dereferencing: hard links. (line 6) +* header-col: Configuring Help Summary. + (line 141) +* hole detection: sparse. (line 66) +* hook: User Hooks. (line 12) +* hour in date strings: Relative items in date strings. + (line 15) +* ignore-archive: warnings. (line 51) +* ignore-archive <1>: warnings. (line 51) +* ignore-newer: warnings. (line 72) +* Ignoring end-of-archive blocks: Ignore Zeros. (line 6) +* 'Ignoring unknown extended header keyword '%s'', warning message: warnings. + (line 74) +* 'implausibly old time stamp %s', warning message: warnings. (line 63) +* Info script: Multi-Volume Archives. + (line 83) +* Interactive operation: interactive. (line 6) +* ISO 8601 date and time of day format: Combined date and time of day items. + (line 6) +* ISO 8601 date format: Calendar date items. (line 30) +* items in date strings: General date syntax. (line 6) +* Labeling an archive: label. (line 6) +* labeling archives: Tape Files. (line 6) +* Labeling multi-volume archives: label. (line 6) +* Labels on the archive media: label. (line 6) +* language, in dates: General date syntax. (line 36) +* language, in dates <1>: General date syntax. (line 40) +* Large lists of file names on small machines: Same Order. (line 6) +* large values: Large or Negative Values. + (line 6) +* last DAY: Day of week items. (line 15) +* last in date strings: General date syntax. (line 22) +* Laszlo Ersek: lbzip2. (line 6) +* lbzip2: lbzip2. (line 6) +* leap seconds: General date syntax. (line 65) +* leap seconds <1>: Time of day items. (line 14) +* leap seconds <2>: Seconds since the Epoch. + (line 26) +* Listing all 'tar' options: help. (line 26) +* listing member and file names: list. (line 45) +* Listing volume label: label. (line 27) +* Lists of file names: files. (line 6) +* Local and remote archives: file. (line 70) +* long options: Long Options. (line 6) +* long options with mandatory arguments: Long Options. (line 31) +* long options with optional arguments: Long Options. (line 39) +* long-opt-col: Configuring Help Summary. + (line 87) +* lzip: gzip. (line 6) +* lzma: gzip. (line 6) +* lzop: gzip. (line 6) +* MacKenzie, David: Authors of parse_datetime. + (line 6) +* 'Malformed dumpdir: 'X' never used', warning message: warnings. + (line 102) +* member: Definitions. (line 15) +* member name: Definitions. (line 15) +* members, multiple: multiple. (line 6) +* Members, replacing with other members: append. (line 47) +* Mercurial, excluding files: exclude. (line 85) +* Mercurial, ignore files: exclude. (line 37) +* Meyering, Jim: Authors of parse_datetime. + (line 6) +* Middle of the archive, starting in the: Starting File. (line 11) +* midnight in date strings: Time of day items. (line 21) +* minute in date strings: Relative items in date strings. + (line 15) +* minutes, time zone correction by: Time of day items. (line 29) +* Modes of extracted files: Setting Access Permissions. + (line 6) +* Modification time, excluding files by: after. (line 6) +* Modification times of extracted files: Data Modification Times. + (line 6) +* month in date strings: Relative items in date strings. + (line 15) +* month names in date strings: Calendar date items. (line 38) +* months, written-out: General date syntax. (line 32) +* MT: General-Purpose Variables. + (line 74) +* MT_BEGIN: Magnetic Tape Control. + (line 10) +* MT_OFFLINE: Magnetic Tape Control. + (line 30) +* MT_REWIND: Magnetic Tape Control. + (line 20) +* MT_STATUS: Magnetic Tape Control. + (line 40) +* Multi-volume archives: Multi-Volume Archives. + (line 6) +* Multi-volume archives in PAX format, extracting using non-GNU tars: Split Recovery. + (line 17) +* Multi-volume archives, extracting using non-GNU tars: Split Recovery. + (line 6) +* multiple members: multiple. (line 6) +* Naming an archive: file. (line 6) +* negative time stamps: Large or Negative Values. + (line 6) +* new-directory: warnings. (line 98) +* next DAY: Day of week items. (line 15) +* next in date strings: General date syntax. (line 22) +* none: warnings. (line 29) +* noon in date strings: Time of day items. (line 21) +* now in date strings: Relative items in date strings. + (line 33) +* ntape device: Many. (line 6) +* 'NUL'-terminated file names: nul. (line 6) +* Number of blocks per record: Blocking Factor. (line 6) +* Number of bytes per record: Blocking Factor. (line 6) +* numbered backup method: backup. (line 55) +* numbers, written-out: General date syntax. (line 22) +* Obtaining help: help. (line 26) +* Obtaining total status information: verbose. (line 45) +* Old GNU archive format: gnu. (line 6) +* Old GNU sparse format: Old GNU Format. (line 6) +* old option style: Old Options. (line 6) +* old options with mandatory arguments: Old Options. (line 26) +* Old style archives: old. (line 6) +* Old style format: old. (line 6) +* opt-doc-col: Configuring Help Summary. + (line 127) +* option syntax, traditional: Old Options. (line 6) +* optional arguments to long options: Long Options. (line 39) +* optional arguments to short options: Short Options. (line 22) +* options for use with '--extract': extract options. (line 6) +* Options when reading archives: Reading. (line 6) +* Options, archive format specifying: Format Variations. (line 6) +* Options, format specifying: Format Variations. (line 6) +* options, GNU style: Long Options. (line 6) +* options, long style: Long Options. (line 6) +* options, mixing different styles: Mixing. (line 6) +* options, mnemonic names: Long Options. (line 6) +* options, old style: Old Options. (line 6) +* options, short style: Short Options. (line 6) +* options, traditional: Short Options. (line 6) +* ordinal numbers: General date syntax. (line 22) +* Overwriting old files, prevention: Dealing with Old Files. + (line 16) +* parse_datetime: Date input formats. (line 6) +* pattern, 'genfile': Generate Mode. (line 39) +* PAX archive format: posix. (line 6) +* Permissions of extracted files: Setting Access Permissions. + (line 6) +* Pinard, F.: Authors of parse_datetime. + (line 19) +* pm in date strings: Time of day items. (line 21) +* POSIX archive format: posix. (line 6) +* Progress information: verbose. (line 82) +* Protecting old files: Dealing with Old Files. + (line 36) +* pure numbers in date strings: Pure numbers in date strings. + (line 6) +* RCS, excluding files: exclude. (line 85) +* Reading file names from a file: files. (line 6) +* Reading incomplete records: Reading. (line 6) +* record: Blocking. (line 6) +* Record Size: Blocking Factor. (line 6) +* 'Record size = %lu blocks', warning message: warnings. (line 89) +* record-size: warnings. (line 89) +* Records, incomplete: Reading. (line 6) +* Recursion in directories, avoiding: recurse. (line 6) +* relative items in date strings: Relative items in date strings. + (line 6) +* Remote devices: file. (line 60) +* remote tape drive: Remote Tape Server. (line 6) +* Removing files from an archive: delete. (line 6) +* rename-directory: warnings. (line 96) +* Replacing members with other members: append. (line 47) +* reporting bugs: Reports. (line 6) +* RESTORE_BEGIN: User Hooks. (line 38) +* RESTORE_END: User Hooks. (line 41) +* Resurrecting files from an archive: extract. (line 6) +* Retrieving files from an archive: extract. (line 6) +* return status: Synopsis. (line 67) +* rmargin: Configuring Help Summary. + (line 159) +* rmt: Remote Tape Server. (line 6) +* RSH: General-Purpose Variables. + (line 78) +* RSH_COMMAND: General-Purpose Variables. + (line 83) +* Running out of space: Scarce. (line 8) +* Salz, Rich: Authors of parse_datetime. + (line 6) +* SCCS, excluding files: exclude. (line 85) +* short options: Short Options. (line 6) +* short options with mandatory arguments: Short Options. (line 13) +* short options with optional arguments: Short Options. (line 22) +* short-opt-col: Configuring Help Summary. + (line 79) +* simple backup method: backup. (line 64) +* SIMPLE_BACKUP_SUFFIX: backup. (line 67) +* 'sleep', checkpoint action: checkpoints. (line 145) +* SLEEP_MESSAGE: General-Purpose Variables. + (line 121) +* SLEEP_TIME: General-Purpose Variables. + (line 106) +* Small memory: Scarce. (line 8) +* snapshot file field ranges: Snapshot Files. (line 111) +* snapshot file, format 0: Snapshot Files. (line 24) +* snapshot file, format 1: Snapshot Files. (line 51) +* snapshot file, format 2: Snapshot Files. (line 73) +* snapshot files, editing: Fixing Snapshot Files. + (line 6) +* snapshot files, fixing device numbers: Fixing Snapshot Files. + (line 6) +* 'socket ignored', warning message: warnings. (line 45) +* Sparse Files: sparse. (line 6) +* sparse files v.0.0, extracting with non-GNU tars: Sparse Recovery. + (line 92) +* sparse files v.0.1, extracting with non-GNU tars: Sparse Recovery. + (line 92) +* sparse files v.1.0, extracting with non-GNU tars: Sparse Recovery. + (line 17) +* Sparse files, creating using 'genfile': Generate Mode. (line 55) +* sparse files, extracting with non-GNU tars: Sparse Recovery. + (line 6) +* sparse formats: Sparse Formats. (line 6) +* sparse formats, defined: sparse. (line 52) +* sparse formats, Old GNU: Old GNU Format. (line 6) +* sparse formats, v.0.0: PAX 0. (line 6) +* sparse formats, v.0.1: PAX 0. (line 51) +* sparse formats, v.1.0: PAX 1. (line 6) +* sparse versions: Sparse Formats. (line 6) +* Specifying archive members: Selecting Archive Members. + (line 6) +* Specifying files to act on: Selecting Archive Members. + (line 6) +* Standard input and output: file. (line 39) +* Standard output, writing extracted files to: Writing to Standard Output. + (line 6) +* Storing archives in compressed format: gzip. (line 6) +* SVN, excluding files: exclude. (line 85) +* Symbolic link as file name: dereference. (line 6) +* symlink-cast: warnings. (line 68) +* TAPE: file tutorial. (line 14) +* tape blocking: Blocking Factor. (line 189) +* tape marks: Many. (line 43) +* tape positioning: Many. (line 26) +* Tapes, using '--delete' and: delete. (line 17) +* TAPE_FILE: General-Purpose Variables. + (line 18) +* tar: What tar Does. (line 6) +* TAR: General-Purpose Variables. + (line 126) +* tar archive: Definitions. (line 6) +* Tar archive formats: Formats. (line 6) +* tar entry: Naming tar Archives. (line 11) +* tar file: Naming tar Archives. (line 11) +* tar to a remote device: file. (line 60) +* tar to standard input and output: file. (line 39) +* tar-snapshot-edit: Fixing Snapshot Files. + (line 17) +* tarcat: Tarcat. (line 6) +* TAR_ARCHIVE, checkpoint script environment: checkpoints. (line 167) +* TAR_ARCHIVE, info script environment variable: Multi-Volume Archives. + (line 105) +* TAR_ARCHIVE, to-command environment: Writing to an External Program. + (line 79) +* TAR_ATIME, to-command environment: Writing to an External Program. + (line 52) +* TAR_BLOCKING_FACTOR, checkpoint script environment: checkpoints. + (line 170) +* TAR_BLOCKING_FACTOR, info script environment variable: Multi-Volume Archives. + (line 108) +* TAR_BLOCKING_FACTOR, to-command environment: Writing to an External Program. + (line 82) +* TAR_CHECKPOINT, checkpoint script environment: checkpoints. (line 173) +* TAR_CTIME, to-command environment: Writing to an External Program. + (line 61) +* TAR_FD, info script environment variable: Multi-Volume Archives. + (line 122) +* TAR_FILENAME, to-command environment: Writing to an External Program. + (line 40) +* TAR_FILETYPE, to-command environment: Writing to an External Program. + (line 24) +* TAR_FORMAT, checkpoint script environment: checkpoints. (line 180) +* TAR_FORMAT, info script environment variable: Multi-Volume Archives. + (line 118) +* TAR_FORMAT, to-command environment: Writing to an External Program. + (line 88) +* TAR_GID, to-command environment: Writing to an External Program. + (line 70) +* TAR_GNAME, to-command environment: Writing to an External Program. + (line 49) +* TAR_MODE, to-command environment: Writing to an External Program. + (line 37) +* TAR_MTIME, to-command environment: Writing to an External Program. + (line 58) +* TAR_OPTIONS, environment variable: using tar options. (line 30) +* TAR_REALNAME, to-command environment: Writing to an External Program. + (line 43) +* TAR_SIZE, to-command environment: Writing to an External Program. + (line 64) +* TAR_SUBCOMMAND, checkpoint script environment: checkpoints. (line 176) +* TAR_SUBCOMMAND, info script environment variable: Multi-Volume Archives. + (line 114) +* TAR_UID, to-command environment: Writing to an External Program. + (line 67) +* TAR_UNAME, to-command environment: Writing to an External Program. + (line 46) +* TAR_VERSION, checkpoint script environment: checkpoints. (line 164) +* TAR_VERSION, info script environment variable: Multi-Volume Archives. + (line 102) +* TAR_VERSION, to-command environment: Writing to an External Program. + (line 76) +* TAR_VOLUME, info script environment variable: Multi-Volume Archives. + (line 111) +* TAR_VOLUME, to-command environment: Writing to an External Program. + (line 85) +* this in date strings: Relative items in date strings. + (line 33) +* time of day item: Time of day items. (line 6) +* 'time stamp %s is %s s in the future', warning message: warnings. + (line 63) +* time zone correction: Time of day items. (line 29) +* time zone item: General date syntax. (line 40) +* time zone item <1>: Time zone items. (line 6) +* timestamp: warnings. (line 63) +* today in date strings: Relative items in date strings. + (line 33) +* tomorrow in date strings: Relative items in date strings. + (line 29) +* 'totals', checkpoint action: checkpoints. (line 140) +* 'ttyout', checkpoint action: checkpoints. (line 111) +* TZ: Specifying time zone rules. + (line 6) +* Ultrix 3.1 and write failure: Remote Tape Server. (line 40) +* 'Unknown file type '%c', extracted as normal file', warning message: warnings. + (line 70) +* 'Unknown file type; file ignored', warning message: warnings. + (line 45) +* unknown-cast: warnings. (line 70) +* unknown-keyword: warnings. (line 74) +* unpacking: Definitions. (line 22) +* Updating an archive: update. (line 6) +* usage-indent: Configuring Help Summary. + (line 155) +* Using encrypted archives: gzip. (line 196) +* ustar archive format: ustar. (line 6) +* uuencode: Applications. (line 8) +* v7 archive format: old. (line 6) +* VCS, excluding files: exclude. (line 85) +* VCS, excluding patterns from ignore files: exclude. (line 37) +* VCS, ignore files: exclude. (line 37) +* Verbose operation: verbose. (line 18) +* Verifying a write operation: verify. (line 6) +* Verifying the currency of an archive: compare. (line 6) +* version control system, excluding files: exclude. (line 85) +* Version of the 'tar' program: help. (line 6) +* version-control Emacs variable: backup. (line 49) +* VERSION_CONTROL: backup. (line 41) +* volno file: Multi-Volume Archives. + (line 74) +* VOLNO_FILE: General-Purpose Variables. + (line 89) +* Volume label, listing: label. (line 27) +* Volume number file: Multi-Volume Archives. + (line 74) +* week in date strings: Relative items in date strings. + (line 15) +* Where is the archive?: file. (line 6) +* Working directory, specifying: directory. (line 6) +* Writing extracted files to standard output: Writing to Standard Output. + (line 6) +* Writing new archives: file. (line 34) +* xdev: warnings. (line 43) +* xdev <1>: warnings. (line 100) +* XLIST: General-Purpose Variables. + (line 95) +* xsparse: Sparse Recovery. (line 13) +* year in date strings: Relative items in date strings. + (line 15) +* yesterday in date strings: Relative items in date strings. + (line 29) + |