1 This is tar.info, produced by makeinfo version 5.9.93 from tar.texi.
3 This manual is for GNU 'tar' (version 1.29, 14 April 2016), which
4 creates and extracts files from archives.
6 Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2016 Free Software
9 Permission is granted to copy, distribute and/or modify this
10 document under the terms of the GNU Free Documentation License,
11 Version 1.3 or any later version published by the Free Software
12 Foundation; with the Invariant Sections being "GNU General Public
13 License", with the Front-Cover Texts being "A GNU Manual", and with
14 the Back-Cover Texts as in (a) below. A copy of the license is
15 included in the section entitled "GNU Free Documentation License".
17 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
18 modify this GNU manual."
19 INFO-DIR-SECTION Archiving
21 * Tar: (tar). Making tape (or disk) archives.
24 INFO-DIR-SECTION Individual utilities
26 * tar: (tar)tar invocation. Invoking GNU 'tar'.
30 File: tar.info, Node: one, Prev: recurse, Up: Choosing
32 6.10 Crossing File System Boundaries
33 ====================================
35 'tar' will normally automatically cross file system boundaries in order
36 to archive files which are part of a directory tree. You can change
37 this behavior by running 'tar' and specifying '--one-file-system'. This
38 option only affects files that are archived because they are in a
39 directory that is being archived; 'tar' will still archive files
40 explicitly named on the command line or through '--files-from',
41 regardless of where they reside.
44 Prevents 'tar' from crossing file system boundaries when archiving.
45 Use in conjunction with any write operation.
47 The '--one-file-system' option causes 'tar' to modify its normal
48 behavior in archiving the contents of directories. If a file in a
49 directory is not on the same file system as the directory itself, then
50 'tar' will not archive that file. If the file is a directory itself,
51 'tar' will not archive anything beneath it; in other words, 'tar' will
52 not cross mount points.
54 This option is useful for making full or incremental archival backups
55 of a file system. If this option is used in conjunction with
56 '--verbose' ('-v'), files that are excluded are mentioned by name on the
61 * directory:: Changing Directory
62 * absolute:: Absolute File Names
65 File: tar.info, Node: directory, Next: absolute, Up: one
67 6.10.1 Changing the Working Directory
68 -------------------------------------
70 To change the working directory in the middle of a list of file names,
71 either on the command line or in a file specified using '--files-from'
72 ('-T'), use '--directory' ('-C'). This will change the working
73 directory to the specified directory after that point in the list.
75 '--directory=DIRECTORY'
77 Changes the working directory in the middle of a command line.
81 $ tar -c -f jams.tar grape prune -C food cherry
83 will place the files 'grape' and 'prune' from the current directory into
84 the archive 'jams.tar', followed by the file 'cherry' from the directory
85 'food'. This option is especially useful when you have several widely
86 separated files that you want to store in the same archive.
88 Note that the file 'cherry' is recorded in the archive under the
89 precise name 'cherry', _not_ 'food/cherry'. Thus, the archive will
90 contain three files that all appear to have come from the same
91 directory; if the archive is extracted with plain 'tar --extract', all
92 three files will be written in the current directory.
94 Contrast this with the command,
96 $ tar -c -f jams.tar grape prune -C food red/cherry
98 which records the third file in the archive under the name 'red/cherry'
99 so that, if the archive is extracted using 'tar --extract', the third
100 file will be written in a subdirectory named 'red'.
102 You can use the '--directory' option to make the archive independent
103 of the original name of the directory holding the files. The following
104 command places the files '/etc/passwd', '/etc/hosts', and '/lib/libc.a'
105 into the archive 'foo.tar':
107 $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a
109 However, the names of the archive members will be exactly what they were
110 on the command line: 'passwd', 'hosts', and 'libc.a'. They will not
111 appear to be related by file name to the original directories where
112 those files were located.
114 Note that '--directory' options are interpreted consecutively. If
115 '--directory' specifies a relative file name, it is interpreted relative
116 to the then current directory, which might not be the same as the
117 original current working directory of 'tar', due to a previous
118 '--directory' option.
120 When using '--files-from' (*note files::), you can put various 'tar'
121 options (including '-C') in the file list. Notice, however, that in
122 this case the option and its argument may not be separated by
123 whitespace. If you use short option, its argument must either follow
124 the option letter immediately, without any intervening whitespace, or
125 occupy the next line. Otherwise, if you use long option, separate its
126 argument by an equal sign.
128 For instance, the file list for the above example will be:
136 To use it, you would invoke 'tar' as follows:
138 $ tar -c -f foo.tar --files-from list
140 The interpretation of options in file lists is disabled by
141 '--verbatim-files-from' and '--null' options.
144 File: tar.info, Node: absolute, Prev: directory, Up: one
146 6.10.2 Absolute File Names
147 --------------------------
149 By default, GNU 'tar' drops a leading '/' on input or output, and
150 complains about file names containing a '..' component. There is an
151 option that turns off this behavior:
155 Do not strip leading slashes from file names, and permit file names
156 containing a '..' file name component.
158 When 'tar' extracts archive members from an archive, it strips any
159 leading slashes ('/') from the member name. This causes absolute member
160 names in the archive to be treated as relative file names. This allows
161 you to have such members extracted wherever you want, instead of being
162 restricted to extracting the member in the exact directory named in the
163 archive. For example, if the archive member has the name '/etc/passwd',
164 'tar' will extract it as if the name were really 'etc/passwd'.
166 File names containing '..' can cause problems when extracting, so
167 'tar' normally warns you about such files when creating an archive, and
168 rejects attempts to extracts such files.
170 Other 'tar' programs do not do this. As a result, if you create an
171 archive whose member names start with a slash, they will be difficult
172 for other people with a non-GNU 'tar' program to use. Therefore, GNU
173 'tar' also strips leading slashes from member names when putting members
174 into the archive. For example, if you ask 'tar' to add the file
175 '/bin/ls' to an archive, it will do so, but the member name will be
178 Symbolic links containing '..' or leading '/' can also cause problems
179 when extracting, so 'tar' normally extracts them last; it may create
180 empty files as placeholders during extraction.
182 If you use the '--absolute-names' ('-P') option, 'tar' will do none
183 of these transformations.
185 To archive or extract files relative to the root directory, specify
186 the '--absolute-names' ('-P') option.
188 Normally, 'tar' acts on files relative to the working
189 directory--ignoring superior directory names when archiving, and
190 ignoring leading slashes when extracting.
192 When you specify '--absolute-names' ('-P'), 'tar' stores file names
193 including all superior directory names, and preserves leading slashes.
194 If you only invoked 'tar' from the root directory you would never need
195 the '--absolute-names' option, but using this option may be more
196 convenient than switching to root.
199 Preserves full file names (including superior directory names) when
200 archiving and extracting files.
202 'tar' prints out a message about removing the '/' from file names.
203 This message appears once per GNU 'tar' invocation. It represents
204 something which ought to be told; ignoring what it means can cause very
205 serious surprises, later.
207 Some people, nevertheless, do not want to see this message. Wanting
208 to play really dangerously, one may of course redirect 'tar' standard
209 error to the sink. For example, under 'sh':
211 $ tar -c -f archive.tar /home 2> /dev/null
213 Another solution, both nicer and simpler, would be to change to the '/'
214 directory first, and then avoid absolute notation. For example:
216 $ tar -c -f archive.tar -C / home
218 *Note Integrity::, for some of the security-related implications of
221 ---------- Footnotes ----------
223 (1) A side effect of this is that when '--create' is used with
224 '--verbose' the resulting output is not, generally speaking, the same as
225 the one you'd get running 'tar --list' command. This may be important
226 if you use some scripts for comparing both outputs. *Note listing
227 member and file names::, for the information on how to handle this case.
230 File: tar.info, Node: Date input formats, Next: Formats, Prev: Choosing, Up: Top
237 Our units of temporal measurement, from seconds on up to months,
238 are so complicated, asymmetrical and disjunctive so as to make
239 coherent mental reckoning in time all but impossible. Indeed, had
240 some tyrannical god contrived to enslave our minds to time, to make
241 it all but impossible for us to escape subjection to sodden
242 routines and unpleasant surprises, he could hardly have done better
243 than handing down our present system. It is like a set of
244 trapezoidal building blocks, with no vertical or horizontal
245 surfaces, like a language in which the simplest thought demands
246 ornate constructions, useless particles and lengthy
247 circumlocutions. Unlike the more successful patterns of language
248 and science, which enable us to face experience boldly or at least
249 level-headedly, our system of temporal calculation silently and
250 persistently encourages our terror of time.
252 ... It is as though architects had to measure length in feet, width
253 in meters and height in ells; as though basic instruction manuals
254 demanded a knowledge of five different languages. It is no wonder
255 then that we often look into our own immediate past or future, last
256 Tuesday or a week from Sunday, with feelings of helpless confusion.
259 --Robert Grudin, 'Time and the Art of Living'.
261 This section describes the textual date representations that GNU
262 programs accept. These are the strings you, as a user, can supply as
263 arguments to the various programs. The C interface (via the
264 'parse_datetime' function) is not described here.
268 * General date syntax:: Common rules.
269 * Calendar date items:: 19 Dec 1994.
270 * Time of day items:: 9:20pm.
271 * Time zone items:: EST, PDT, UTC, ...
272 * Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500.
273 * Day of week items:: Monday and others.
274 * Relative items in date strings:: next tuesday, 2 years ago.
275 * Pure numbers in date strings:: 19931219, 1440.
276 * Seconds since the Epoch:: @1078100502.
277 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
278 * Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
281 File: tar.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats
283 7.1 General date syntax
284 =======================
286 A "date" is a string, possibly empty, containing many items separated by
287 whitespace. The whitespace may be omitted when no ambiguity arises.
288 The empty string means the beginning of today (i.e., midnight). Order
289 of the items is immaterial. A date string may contain many flavors of
292 * calendar date items
295 * combined date and time of day items
296 * day of the week items
300 We describe each of these item types in turn, below.
302 A few ordinal numbers may be written out in words in some contexts.
303 This is most useful for specifying day of the week items or relative
304 items (see below). Among the most commonly used ordinal numbers, the
305 word 'last' stands for -1, 'this' stands for 0, and 'first' and 'next'
306 both stand for 1. Because the word 'second' stands for the unit of time
307 there is no way to write the ordinal number 2, but for convenience
308 'third' stands for 3, 'fourth' for 4, 'fifth' for 5, 'sixth' for 6,
309 'seventh' for 7, 'eighth' for 8, 'ninth' for 9, 'tenth' for 10,
310 'eleventh' for 11 and 'twelfth' for 12.
312 When a month is written this way, it is still considered to be
313 written numerically, instead of being "spelled in full"; this changes
316 In the current implementation, only English is supported for words
317 and abbreviations like 'AM', 'DST', 'EST', 'first', 'January', 'Sunday',
318 'tomorrow', and 'year'.
320 The output of the 'date' command is not always acceptable as a date
321 string, not only because of the language problem, but also because there
322 is no standard meaning for time zone items like 'IST'. When using
323 'date' to generate a date string intended to be parsed later, specify a
324 date format that is independent of language and that does not use time
325 zone items other than 'UTC' and 'Z'. Here are some ways to do this:
327 $ LC_ALL=C TZ=UTC0 date
328 Mon Mar 1 00:21:42 UTC 2004
329 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
331 $ date --rfc-3339=ns # --rfc-3339 is a GNU extension.
332 2004-02-29 16:21:42.692722128-08:00
333 $ date --rfc-2822 # a GNU extension
334 Sun, 29 Feb 2004 16:21:42 -0800
335 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
336 2004-02-29 16:21:42 -0800
337 $ date +'@%s.%N' # %s and %N are GNU extensions.
338 @1078100502.692722128
340 Alphabetic case is completely ignored in dates. Comments may be
341 introduced between round parentheses, as long as included parentheses
342 are properly nested. Hyphens not followed by a digit are currently
343 ignored. Leading zeros on numbers are ignored.
345 Invalid dates like '2005-02-29' or times like '24:00' are rejected.
346 In the typical case of a host that does not support leap seconds, a time
347 like '23:59:60' is rejected even if it corresponds to a valid leap
351 File: tar.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats
353 7.2 Calendar date items
354 =======================
356 A "calendar date item" specifies a day of the year. It is specified
357 differently, depending on whether the month is specified numerically or
358 literally. All these strings specify the same calendar date:
360 1972-09-24 # ISO 8601.
361 72-9-24 # Assume 19xx for 69 through 99,
362 # 20xx for 00 through 68.
363 72-09-24 # Leading zeros are ignored.
364 9/24/72 # Common U.S. writing.
366 24 Sept 72 # September has a special abbreviation.
367 24 Sep 72 # Three-letter abbreviations always allowed.
372 The year can also be omitted. In this case, the last specified year
373 is used, or the current year if none. For example:
380 For numeric months, the ISO 8601 format 'YEAR-MONTH-DAY' is allowed,
381 where YEAR is any positive number, MONTH is a number between 01 and 12,
382 and DAY is a number between 01 and 31. A leading zero must be present
383 if a number is less than ten. If YEAR is 68 or smaller, then 2000 is
384 added to it; otherwise, if YEAR is less than 100, then 1900 is added to
385 it. The construct 'MONTH/DAY/YEAR', popular in the United States, is
386 accepted. Also 'MONTH/DAY', omitting the year.
388 Literal months may be spelled out in full: 'January', 'February',
389 'March', 'April', 'May', 'June', 'July', 'August', 'September',
390 'October', 'November' or 'December'. Literal months may be abbreviated
391 to their first three letters, possibly followed by an abbreviating dot.
392 It is also permitted to write 'Sept' instead of 'September'.
394 When months are written literally, the calendar date may be given as
395 any of the following:
402 Or, omitting the year:
407 File: tar.info, Node: Time of day items, Next: Time zone items, Prev: Calendar date items, Up: Date input formats
409 7.3 Time of day items
410 =====================
412 A "time of day item" in date strings specifies the time on a given day.
413 Here are some examples, all of which represent the same time:
418 20:02-0500 # In EST (U.S. Eastern Standard Time).
420 More generally, the time of day may be given as 'HOUR:MINUTE:SECOND',
421 where HOUR is a number between 0 and 23, MINUTE is a number between 0
422 and 59, and SECOND is a number between 0 and 59 possibly followed by '.'
423 or ',' and a fraction containing one or more digits. Alternatively,
424 ':SECOND' can be omitted, in which case it is taken to be zero. On the
425 rare hosts that support leap seconds, SECOND may be 60.
427 If the time is followed by 'am' or 'pm' (or 'a.m.' or 'p.m.'), HOUR
428 is restricted to run from 1 to 12, and ':MINUTE' may be omitted (taken
429 to be zero). 'am' indicates the first half of the day, 'pm' indicates
430 the second half of the day. In this notation, 12 is the predecessor of
431 1: midnight is '12am' while noon is '12pm'. (This is the zero-oriented
432 interpretation of '12am' and '12pm', as opposed to the old tradition
433 derived from Latin which uses '12m' for noon and '12pm' for midnight.)
435 The time may alternatively be followed by a time zone correction,
436 expressed as 'SHHMM', where S is '+' or '-', HH is a number of zone
437 hours and MM is a number of zone minutes. The zone minutes term, MM,
438 may be omitted, in which case the one- or two-digit correction is
439 interpreted as a number of hours. You can also separate HH from MM with
440 a colon. When a time zone correction is given this way, it forces
441 interpretation of the time relative to Coordinated Universal Time (UTC),
442 overriding any previous specification for the time zone or the local
443 time zone. For example, '+0530' and '+05:30' both stand for the time
444 zone 5.5 hours ahead of UTC (e.g., India). This is the best way to
445 specify a time zone correction by fractional parts of an hour. The
446 maximum zone correction is 24 hours.
448 Either 'am'/'pm' or a time zone correction may be specified, but not
452 File: tar.info, Node: Time zone items, Next: Combined date and time of day items, Prev: Time of day items, Up: Date input formats
457 A "time zone item" specifies an international time zone, indicated by a
458 small set of letters, e.g., 'UTC' or 'Z' for Coordinated Universal Time.
459 Any included periods are ignored. By following a non-daylight-saving
460 time zone by the string 'DST' in a separate word (that is, separated by
461 some white space), the corresponding daylight saving time zone may be
462 specified. Alternatively, a non-daylight-saving time zone can be
463 followed by a time zone correction, to add the two values. This is
464 normally done only for 'UTC'; for example, 'UTC+05:30' is equivalent to
467 Time zone items other than 'UTC' and 'Z' are obsolescent and are not
468 recommended, because they are ambiguous; for example, 'EST' has a
469 different meaning in Australia than in the United States. Instead, it's
470 better to use unambiguous numeric time zone corrections like '-0500', as
471 described in the previous section.
473 If neither a time zone item nor a time zone correction is supplied,
474 time stamps are interpreted using the rules of the default time zone
475 (*note Specifying time zone rules::).
478 File: tar.info, Node: Combined date and time of day items, Next: Day of week items, Prev: Time zone items, Up: Date input formats
480 7.5 Combined date and time of day items
481 =======================================
483 The ISO 8601 date and time of day extended format consists of an ISO
484 8601 date, a 'T' character separator, and an ISO 8601 time of day. This
485 format is also recognized if the 'T' is replaced by a space.
487 In this format, the time of day should use 24-hour notation.
488 Fractional seconds are allowed, with either comma or period preceding
489 the fraction. ISO 8601 fractional minutes and hours are not supported.
490 Typically, hosts support nanosecond timestamp resolution; excess
491 precision is silently discarded.
493 Here are some examples:
495 2012-09-24T20:02:00.052-0500
496 2012-12-31T23:59:59,999999999+1100
500 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
502 7.6 Day of week items
503 =====================
505 The explicit mention of a day of the week will forward the date (only if
506 necessary) to reach that day of the week in the future.
508 Days of the week may be spelled out in full: 'Sunday', 'Monday',
509 'Tuesday', 'Wednesday', 'Thursday', 'Friday' or 'Saturday'. Days may be
510 abbreviated to their first three letters, optionally followed by a
511 period. The special abbreviations 'Tues' for 'Tuesday', 'Wednes' for
512 'Wednesday' and 'Thur' or 'Thurs' for 'Thursday' are also allowed.
514 A number may precede a day of the week item to move forward
515 supplementary weeks. It is best used in expression like 'third monday'.
516 In this context, 'last DAY' or 'next DAY' is also acceptable; they move
517 one week before or after the day that DAY by itself would represent.
519 A comma following a day of the week item is ignored.
522 File: tar.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats
524 7.7 Relative items in date strings
525 ==================================
527 "Relative items" adjust a date (or the current date if none) forward or
528 backward. The effects of relative items accumulate. Here are some
536 The unit of time displacement may be selected by the string 'year' or
537 'month' for moving by whole years or months. These are fuzzy units, as
538 years and months are not all of equal duration. More precise units are
539 'fortnight' which is worth 14 days, 'week' worth 7 days, 'day' worth 24
540 hours, 'hour' worth 60 minutes, 'minute' or 'min' worth 60 seconds, and
541 'second' or 'sec' worth one second. An 's' suffix on these units is
542 accepted and ignored.
544 The unit of time may be preceded by a multiplier, given as an
545 optionally signed number. Unsigned numbers are taken as positively
546 signed. No number at all implies 1 for a multiplier. Following a
547 relative item by the string 'ago' is equivalent to preceding the unit by
548 a multiplier with value -1.
550 The string 'tomorrow' is worth one day in the future (equivalent to
551 'day'), the string 'yesterday' is worth one day in the past (equivalent
554 The strings 'now' or 'today' are relative items corresponding to
555 zero-valued time displacement, these strings come from the fact a
556 zero-valued time displacement represents the current time when not
557 otherwise changed by previous items. They may be used to stress other
558 items, like in '12:00 today'. The string 'this' also has the meaning of
559 a zero-valued time displacement, but is preferred in date strings like
562 When a relative item causes the resulting date to cross a boundary
563 where the clocks were adjusted, typically for daylight saving time, the
564 resulting date and time are adjusted accordingly.
566 The fuzz in units can cause problems with relative items. For
567 example, '2003-07-31 -1 month' might evaluate to 2003-07-01, because
568 2003-06-31 is an invalid date. To determine the previous month more
569 reliably, you can ask for the month before the 15th of the current
573 Thu, 31 Jul 2003 13:02:39 -0700
574 $ date --date='-1 month' +'Last month was %B?'
576 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
579 Also, take care when manipulating dates around clock changes such as
580 daylight saving leaps. In a few cases these have added or subtracted as
581 much as 24 hours from the clock, so it is often wise to adopt universal
582 time by setting the 'TZ' environment variable to 'UTC0' before embarking
583 on calendrical calculations.
586 File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats
588 7.8 Pure numbers in date strings
589 ================================
591 The precise interpretation of a pure decimal number depends on the
592 context in the date string.
594 If the decimal number is of the form YYYYMMDD and no other calendar
595 date item (*note Calendar date items::) appears before it in the date
596 string, then YYYY is read as the year, MM as the month number and DD as
597 the day of the month, for the specified calendar date.
599 If the decimal number is of the form HHMM and no other time of day
600 item appears before it in the date string, then HH is read as the hour
601 of the day and MM as the minute of the hour, for the specified time of
602 day. MM can also be omitted.
604 If both a calendar date and a time of day appear to the left of a
605 number in the date string, but no relative item, then the number
609 File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats
611 7.9 Seconds since the Epoch
612 ===========================
614 If you precede a number with '@', it represents an internal time stamp
615 as a count of seconds. The number can contain an internal decimal point
616 (either '.' or ','); any excess precision not supported by the internal
617 representation is truncated toward minus infinity. Such a number cannot
618 be combined with any other date item, as it specifies a complete time
621 Internally, computer times are represented as a count of seconds
622 since an epoch--a well-defined point of time. On GNU and POSIX systems,
623 the epoch is 1970-01-01 00:00:00 UTC, so '@0' represents this time, '@1'
624 represents 1970-01-01 00:00:01 UTC, and so forth. GNU and most other
625 POSIX-compliant systems support such times as an extension to POSIX,
626 using negative counts, so that '@-1' represents 1969-12-31 23:59:59 UTC.
628 Traditional Unix systems count seconds with 32-bit two's-complement
629 integers and can represent times from 1901-12-13 20:45:52 through
630 2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of
631 seconds with nanosecond subcounts, and can represent all the times in
632 the known lifetime of the universe to a resolution of 1 nanosecond.
634 On most hosts, these counts ignore the presence of leap seconds. For
635 example, on most hosts '@915148799' represents 1998-12-31 23:59:59 UTC,
636 '@915148800' represents 1999-01-01 00:00:00 UTC, and there is no way to
637 represent the intervening leap second 1998-12-31 23:59:60 UTC.
640 File: tar.info, Node: Specifying time zone rules, Next: Authors of parse_datetime, Prev: Seconds since the Epoch, Up: Date input formats
642 7.10 Specifying time zone rules
643 ===============================
645 Normally, dates are interpreted using the rules of the current time
646 zone, which in turn are specified by the 'TZ' environment variable, or
647 by a system default if 'TZ' is not set. To specify a different set of
648 default time zone rules that apply just to one date, start the date with
649 a string of the form 'TZ="RULE"'. The two quote characters ('"') must
650 be present in the date, and any quotes or backslashes within RULE must
651 be escaped by a backslash.
653 For example, with the GNU 'date' command you can answer the question
654 "What time is it in New York when a Paris clock shows 6:30am on October
655 31, 2004?" by using a date beginning with 'TZ="Europe/Paris"' as shown
656 in the following shell transcript:
658 $ export TZ="America/New_York"
659 $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
660 Sun Oct 31 01:30:00 EDT 2004
662 In this example, the '--date' operand begins with its own 'TZ'
663 setting, so the rest of that operand is processed according to
664 'Europe/Paris' rules, treating the string '2004-10-31 06:30' as if it
665 were in Paris. However, since the output of the 'date' command is
666 processed according to the overall time zone rules, it uses New York
667 time. (Paris was normally six hours ahead of New York in 2004, but this
668 example refers to a brief Halloween period when the gap was five hours.)
670 A 'TZ' value is a rule that typically names a location in the 'tz'
671 database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of
672 location names appears in the TWiki Date and Time Gateway
673 (http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a
674 colon before a location name in a 'TZ' setting, e.g.,
675 'TZ=":America/New_York"'.
677 The 'tz' database includes a wide variety of locations ranging from
678 'Arctic/Longyearbyen' to 'Antarctica/South_Pole', but if you are at sea
679 and have your own private time zone, or if you are using a non-GNU host
680 that does not support the 'tz' database, you may need to use a POSIX
681 rule instead. Simple POSIX rules like 'UTC0' specify a time zone
682 without daylight saving time; other rules can specify simple daylight
683 saving regimes. *Note Specifying the Time Zone with 'TZ': (libc)TZ
687 File: tar.info, Node: Authors of parse_datetime, Prev: Specifying time zone rules, Up: Date input formats
689 7.11 Authors of 'parse_datetime'
690 ================================
692 'parse_datetime' started life as 'getdate', as originally implemented by
693 Steven M. Bellovin (<smb@research.att.com>) while at the University of
694 North Carolina at Chapel Hill. The code was later tweaked by a couple
695 of people on Usenet, then completely overhauled by Rich $alz
696 (<rsalz@bbn.com>) and Jim Berets (<jberets@bbn.com>) in August, 1990.
697 Various revisions for the GNU system were made by David MacKenzie, Jim
698 Meyering, Paul Eggert and others, including renaming it to 'get_date' to
699 avoid a conflict with the alternative Posix function 'getdate', and a
700 later rename to 'parse_datetime'. The Posix function 'getdate' can
701 parse more locale-specific dates using 'strptime', but relies on an
702 environment variable and external file, and lacks the thread-safety of
705 This chapter was originally produced by Franc,ois Pinard
706 (<pinard@iro.umontreal.ca>) from the 'parse_datetime.y' source code, and
707 then edited by K. Berry (<kb@cs.umb.edu>).
710 File: tar.info, Node: Formats, Next: Media, Prev: Date input formats, Up: Top
712 8 Controlling the Archive Format
713 ********************************
715 Due to historical reasons, there are several formats of tar archives.
716 All of them are based on the same principles, but have some subtle
717 differences that often make them incompatible with each other.
719 GNU tar is able to create and handle archives in a variety of
720 formats. The most frequently used formats are (in alphabetical order):
723 Format used by GNU 'tar' versions up to 1.13.25. This format
724 derived from an early POSIX standard, adding some improvements such
725 as sparse file handling and incremental archives. Unfortunately
726 these features were implemented in a way incompatible with other
729 Archives in 'gnu' format are able to hold file names of unlimited
733 Format used by GNU 'tar' of versions prior to 1.12.
736 Archive format, compatible with the V7 implementation of tar. This
737 format imposes a number of limitations. The most important of them
740 1. The maximum length of a file name is limited to 99 characters.
741 2. The maximum length of a symbolic link is limited to 99
743 3. It is impossible to store special files (block and character
745 4. Maximum value of user or group ID is limited to 2097151
747 5. V7 archives do not contain symbolic ownership information
748 (user and group name of the file owner).
750 This format has traditionally been used by Automake when producing
751 Makefiles. This practice will change in the future, in the
752 meantime, however this means that projects containing file names
753 more than 99 characters long will not be able to use GNU 'tar' 1.29
754 and Automake prior to 1.9.
757 Archive format defined by POSIX.1-1988 specification. It stores
758 symbolic ownership information. It is also able to store special
759 files. However, it imposes several restrictions as well:
761 1. The maximum length of a file name is limited to 256
762 characters, provided that the file name can be split at a
763 directory separator in two parts, first of them being at most
764 155 bytes long. So, in most cases the maximum file name
765 length will be shorter than 256 characters.
766 2. The maximum length of a symbolic link name is limited to 100
768 3. Maximum size of a file the archive is able to accommodate is
770 4. Maximum value of UID/GID is 2097151.
771 5. Maximum number of bits in device major and minor numbers is
775 Format used by Jo"rg Schilling 'star' implementation. GNU 'tar' is
776 able to read 'star' archives but currently does not produce them.
779 Archive format defined by POSIX.1-2001 specification. This is the
780 most flexible and feature-rich format. It does not impose any
781 restrictions on file sizes or file name lengths. This format is
782 quite recent, so not all tar implementations are able to handle it
783 properly. However, this format is designed in such a way that any
784 tar implementation able to read 'ustar' archives will be able to
785 read most 'posix' archives as well, with the only exception that
786 any additional information (such as long file names etc.) will in
787 such case be extracted as plain text files along with the files it
790 This archive format will be the default format for future versions
793 The following table summarizes the limitations of each of these
796 Format UID File Size File Name Devn
797 --------------------------------------------------------------------
798 gnu 1.8e19 Unlimited Unlimited 63
799 oldgnu 1.8e19 Unlimited Unlimited 63
800 v7 2097151 8GB 99 n/a
801 ustar 2097151 8GB 256 21
802 posix Unlimited Unlimited Unlimited Unlimited
804 The default format for GNU 'tar' is defined at compilation time. You
805 may check it by running 'tar --help', and examining the last lines of
806 its output. Usually, GNU 'tar' is configured to create archives in
807 'gnu' format, however, future version will switch to 'posix'.
811 * Compression:: Using Less Space through Compression
812 * Attributes:: Handling File Attributes
813 * Portability:: Making 'tar' Archives More Portable
814 * cpio:: Comparison of 'tar' and 'cpio'
817 File: tar.info, Node: Compression, Next: Attributes, Up: Formats
819 8.1 Using Less Space through Compression
820 ========================================
824 * gzip:: Creating and Reading Compressed Archives
825 * sparse:: Archiving Sparse Files
828 File: tar.info, Node: gzip, Next: sparse, Up: Compression
830 8.1.1 Creating and Reading Compressed Archives
831 ----------------------------------------------
833 GNU 'tar' is able to create and read compressed archives. It supports a
834 wide variety of compression programs, namely: 'gzip', 'bzip2', 'lzip',
835 'lzma', 'lzop', 'xz' and traditional 'compress'. The latter is
836 supported mostly for backward compatibility, and we recommend against
837 using it, because it is by far less effective than the other compression
840 Creating a compressed archive is simple: you just specify a
841 "compression option" along with the usual archive creation commands.
842 The compression option is '-z' ('--gzip') to create a 'gzip' compressed
843 archive, '-j' ('--bzip2') to create a 'bzip2' compressed archive,
844 '--lzip' to create an lzip compressed archive, '-J' ('--xz') to create
845 an XZ archive, '--lzma' to create an LZMA compressed archive, '--lzop'
846 to create an LSOP archive, and '-Z' ('--compress') to use 'compress'
847 program. For example:
849 $ tar czf archive.tar.gz .
851 You can also let GNU 'tar' select the compression program based on
852 the suffix of the archive file name. This is done using
853 '--auto-compress' ('-a') command line option. For example, the
854 following invocation will use 'bzip2' for compression:
856 $ tar caf archive.tar.bz2 .
858 whereas the following one will use 'lzma':
860 $ tar caf archive.tar.lzma .
862 For a complete list of file name suffixes recognized by GNU 'tar',
863 see *note auto-compress::.
865 Reading compressed archive is even simpler: you don't need to specify
866 any additional options as GNU 'tar' recognizes its format automatically.
867 Thus, the following commands will list and extract the archive created
870 # List the compressed archive
871 $ tar tf archive.tar.gz
872 # Extract the compressed archive
873 $ tar xf archive.tar.gz
875 The format recognition algorithm is based on "signatures", a special
876 byte sequences in the beginning of file, that are specific for certain
877 compression formats. If this approach fails, 'tar' falls back to using
878 archive name suffix to determine its format (*note auto-compress::, for
879 a list of recognized suffixes).
881 Some compression programs are able to handle different compression
882 formats. GNU 'tar' uses this, if the principal decompressor for the
883 given format is not available. For example, if 'compress' is not
884 installed, 'tar' will try to use 'gzip'. As of version 1.29 the
885 following alternatives are tried(2):
887 Format Main decompressor Alternatives
888 ---------------------------------------------------------------------
889 compress compress gzip
893 The only case when you have to specify a decompression option while
894 reading the archive is when reading from a pipe or from a tape drive
895 that does not support random access. However, in this case GNU 'tar'
896 will indicate which option you should use. For example:
898 $ cat archive.tar.gz | tar tf -
899 tar: Archive is compressed. Use -z option
900 tar: Error is not recoverable: exiting now
902 If you see such diagnostics, just add the suggested option to the
903 invocation of GNU 'tar':
905 $ cat archive.tar.gz | tar tzf -
907 Notice also, that there are several restrictions on operations on
908 compressed archives. First of all, compressed archives cannot be
909 modified, i.e., you cannot update ('--update', alias '-u') them or
910 delete ('--delete') members from them or add ('--append', alias '-r')
911 members to them. Likewise, you cannot append another 'tar' archive to a
912 compressed archive using '--concatenate' ('-A'). Secondly, multi-volume
913 archives cannot be compressed.
915 The following options allow to select a particular compressor
921 Filter the archive through 'gzip'.
925 Filter the archive through 'xz'.
929 Filter the archive through 'bzip2'.
932 Filter the archive through 'lzip'.
935 Filter the archive through 'lzma'.
938 Filter the archive through 'lzop'.
943 Filter the archive through 'compress'.
945 When any of these options is given, GNU 'tar' searches the compressor
946 binary in the current path and invokes it. The name of the compressor
947 program is specified at compilation time using a corresponding
948 '--with-COMPNAME' option to 'configure', e.g. '--with-bzip2' to select
949 a specific 'bzip2' binary. *Note lbzip2::, for a detailed discussion.
951 The output produced by 'tar --help' shows the actual compressor names
952 along with each of these options.
954 You can use any of these options on physical devices (tape drives,
955 etc.) and remote files as well as on normal files; data to or from such
956 devices or remote files is reblocked by another copy of the 'tar'
957 program to enforce the specified (or default) record size. The default
958 compression parameters are used. You can override them by using the
959 '-I' option (see below), e.g.:
961 $ tar -cf archive.tar.gz -I 'gzip -9 -n' subdir
963 A more traditional way to do this is to use a pipe:
965 $ tar cf - subdir | gzip -9 -n > archive.tar.gz
967 Compressed archives are easily corrupted, because compressed files
968 have little redundancy. The adaptive nature of the compression scheme
969 means that the compression tables are implicitly spread all over the
970 archive. If you lose a few blocks, the dynamic construction of the
971 compression tables becomes unsynchronized, and there is little chance
972 that you could recover later in the archive.
974 Other compression options provide better control over creating
975 compressed archives. These are:
979 Select a compression program to use by the archive file name
980 suffix. The following suffixes are recognized:
982 Suffix Compression program
983 -------------------------------------------------------------------
999 '--use-compress-program=COMMAND'
1001 Use external compression program COMMAND. Use this option if you
1002 want to specify options for the compression program, or if you are
1003 not happy with the compression program associated with the suffix
1004 at compile time, or if you have a compression program that GNU
1005 'tar' does not support. The COMMAND argument is a valid command
1006 invocation, as you would type it at the command line prompt, with
1007 any additional options as needed. Enclose it in quotes if it
1008 contains white space (*note Running External Commands: external.).
1010 The COMMAND should follow two conventions:
1012 First, when invoked without additional options, it should read data
1013 from standard input, compress it and output it on standard output.
1015 Secondly, if invoked with the additional '-d' option, it should do
1016 exactly the opposite, i.e., read the compressed data from the
1017 standard input and produce uncompressed data on the standard
1020 The latter requirement means that you must not use the '-d' option
1021 as a part of the COMMAND itself.
1023 The '--use-compress-program' option, in particular, lets you
1024 implement your own filters, not necessarily dealing with
1025 compression/decompression. For example, suppose you wish to implement
1026 PGP encryption on top of compression, using 'gpg' (*note gpg:
1027 (gpg)Top.). The following script does that:
1031 -d) gpg --decrypt - | gzip -d -c;;
1032 '') gzip -c | gpg -s;;
1033 *) echo "Unknown option $1">&2; exit 1;;
1036 Suppose you name it 'gpgz' and save it somewhere in your 'PATH'.
1037 Then the following command will create a compressed archive signed with
1040 $ tar -cf foo.tar.gpgz -Igpgz .
1042 Likewise, the command below will list its contents:
1044 $ tar -tf foo.tar.gpgz -Igpgz .
1048 * lbzip2:: Using lbzip2 with GNU 'tar'.
1050 ---------- Footnotes ----------
1052 (1) It also had patent problems in the past.
1054 (2) To verbosely trace the decompressor selection, use the
1055 '--warning=decompress-program' option (*note decompress-program:
1059 File: tar.info, Node: lbzip2, Up: gzip
1061 8.1.1.1 Using lbzip2 with GNU 'tar'.
1062 ....................................
1064 'Lbzip2' is a multithreaded utility for handling 'bzip2' compression,
1065 written by Laszlo Ersek. It makes use of multiple processors to speed
1066 up its operation and in general works considerably faster than 'bzip2'.
1067 For a detailed description of 'lbzip2' see
1068 <http://freshmeat.net/projects/lbzip2> and lbzip2: parallel bzip2
1070 (http://www.linuxinsight.com/lbzip2-parallel-bzip2-utility.html).
1072 Recent versions of 'lbzip2' are mostly command line compatible with
1073 'bzip2', which makes it possible to automatically invoke it via the
1074 '--bzip2' GNU 'tar' command line option. To do so, GNU 'tar' must be
1075 configured with the '--with-bzip2' command line option, like this:
1077 $ ./configure --with-bzip2=lbzip2 [OTHER-OPTIONS]
1079 Once configured and compiled this way, 'tar --help' will show the
1082 $ tar --help | grep -- --bzip2
1083 -j, --bzip2 filter the archive through lbzip2
1085 which means that running 'tar --bzip2' will invoke 'lbzip2'.
1088 File: tar.info, Node: sparse, Prev: gzip, Up: Compression
1090 8.1.2 Archiving Sparse Files
1091 ----------------------------
1093 Files in the file system occasionally have "holes". A "hole" in a file
1094 is a section of the file's contents which was never written. The
1095 contents of a hole reads as all zeros. On many operating systems,
1096 actual disk storage is not allocated for holes, but they are counted in
1097 the length of the file. If you archive such a file, 'tar' could create
1098 an archive longer than the original. To have 'tar' attempt to recognize
1099 the holes in a file, use '--sparse' ('-S'). When you use this option,
1100 then, for any file using less disk space than would be expected from its
1101 length, 'tar' searches the file for holes. It then records in the
1102 archive for the file where the holes (consecutive stretches of zeros)
1103 are, and only archives the "real contents" of the file. On extraction
1104 (using '--sparse' is not needed on extraction) any such files have also
1105 holes created wherever the holes were found. Thus, if you use
1106 '--sparse', 'tar' archives won't take more space than the original.
1108 GNU 'tar' uses two methods for detecting holes in sparse files.
1109 These methods are described later in this subsection.
1113 This option instructs 'tar' to test each file for sparseness before
1114 attempting to archive it. If the file is found to be sparse it is
1115 treated specially, thus allowing to decrease the amount of space
1116 used by its image in the archive.
1118 This option is meaningful only when creating or updating archives.
1119 It has no effect on extraction.
1121 Consider using '--sparse' when performing file system backups, to
1122 avoid archiving the expanded forms of files stored sparsely in the
1125 Even if your system has no sparse files currently, some may be
1126 created in the future. If you use '--sparse' while making file system
1127 backups as a matter of course, you can be assured the archive will never
1128 take more space on the media than the files take on disk (otherwise,
1129 archiving a disk filled with sparse files might take hundreds of tapes).
1130 *Note Incremental Dumps::.
1132 However, be aware that '--sparse' option may present a serious
1133 drawback. Namely, in order to determine the positions of holes in a
1134 file 'tar' may have to read it before trying to archive it, so in total
1135 the file may be read *twice*. This may happen when your OS or your FS
1136 does not support "SEEK_HOLE/SEEK_DATA" feature in "lseek" (See
1137 '--hole-detection', below).
1139 When using 'POSIX' archive format, GNU 'tar' is able to store sparse
1140 files using in three distinct ways, called "sparse formats". A sparse
1141 format is identified by its "number", consisting, as usual of two
1142 decimal numbers, delimited by a dot. By default, format '1.0' is used.
1143 If, for some reason, you wish to use an earlier format, you can select
1144 it using '--sparse-version' option.
1146 '--sparse-version=VERSION'
1147 Select the format to store sparse files in. Valid VERSION values
1148 are: '0.0', '0.1' and '1.0'. *Note Sparse Formats::, for a
1149 detailed description of each format.
1151 Using '--sparse-format' option implies '--sparse'.
1153 '--hole-detection=METHOD'
1154 Enforce concrete hole detection method. Before the real contents
1155 of sparse file are stored, 'tar' needs to gather knowledge about
1156 file sparseness. This is because it needs to have the file's map
1157 of holes stored into tar header before it starts archiving the file
1158 contents. Currently, two methods of hole detection are
1161 * '--hole-detection=seek' Seeking the file for data and holes.
1162 It uses enhancement of the 'lseek' system call ('SEEK_HOLE'
1163 and 'SEEK_DATA') which is able to reuse file system knowledge
1164 about sparse file contents - so the detection is usually very
1165 fast. To use this feature, your file system and operating
1166 system must support it. At the time of this writing (2015)
1167 this feature, in spite of not being accepted by POSIX, is
1168 fairly widely supported by different operating systems.
1170 * '--hole-detection=raw' Reading byte-by-byte the whole sparse
1171 file before the archiving. This method detects holes like
1172 consecutive stretches of zeroes. Comparing to the previous
1173 method, it is usually much slower, although more portable.
1175 When no '--hole-detection' option is given, 'tar' uses the 'seek', if
1176 supported by the operating system.
1178 Using '--hole-detection' option implies '--sparse'.
1181 File: tar.info, Node: Attributes, Next: Portability, Prev: Compression, Up: Formats
1183 8.2 Handling File Attributes
1184 ============================
1186 When 'tar' reads files, it updates their access times. To avoid this,
1187 use the '--atime-preserve[=METHOD]' option, which can either reset the
1188 access time retroactively or avoid changing it in the first place.
1191 '--atime-preserve=replace'
1192 '--atime-preserve=system'
1193 Preserve the access times of files that are read. This works only
1194 for files that you own, unless you have superuser privileges.
1196 '--atime-preserve=replace' works on most systems, but it also
1197 restores the data modification time and updates the status change
1198 time. Hence it doesn't interact with incremental dumps nicely
1199 (*note Incremental Dumps::), and it can set access or data
1200 modification times incorrectly if other programs access the file
1201 while 'tar' is running.
1203 '--atime-preserve=system' avoids changing the access time in the
1204 first place, if the operating system supports this. Unfortunately,
1205 this may or may not work on any given operating system or file
1206 system. If 'tar' knows for sure it won't work, it complains right
1209 Currently '--atime-preserve' with no operand defaults to
1210 '--atime-preserve=replace', but this is intended to change to
1211 '--atime-preserve=system' when the latter is better-supported.
1215 Do not extract data modification time.
1217 When this option is used, 'tar' leaves the data modification times
1218 of the files it extracts as the times when the files were
1219 extracted, instead of setting it to the times recorded in the
1222 This option is meaningless with '--list' ('-t').
1225 Create extracted files with the same ownership they have in the
1228 This is the default behavior for the superuser, so this option is
1229 meaningful only for non-root users, when 'tar' is executed on those
1230 systems able to give files away. This is considered as a security
1231 flaw by many people, at least because it makes quite difficult to
1232 correctly account users for the disk space they occupy. Also, the
1233 'suid' or 'sgid' attributes of files are easily and silently lost
1234 when files are given away.
1236 When writing an archive, 'tar' writes the user ID and user name
1237 separately. If it can't find a user name (because the user ID is
1238 not in '/etc/passwd'), then it does not write one. When restoring,
1239 it tries to look the name (if one was written) up in '/etc/passwd'.
1240 If it fails, then it uses the user ID stored in the archive
1245 Do not attempt to restore ownership when extracting. This is the
1246 default behavior for ordinary users, so this option has an effect
1247 only for the superuser.
1250 The '--numeric-owner' option allows (ANSI) archives to be written
1251 without user/group name information or such information to be
1252 ignored when extracting. It effectively disables the generation
1253 and/or use of user/group name information. This option forces
1254 extraction using the numeric ids from the archive, ignoring the
1257 This is useful in certain circumstances, when restoring a backup
1258 from an emergency floppy with different passwd/group files for
1259 example. It is otherwise impossible to extract files with the
1260 right ownerships if the password file in use during the extraction
1261 does not match the one belonging to the file system(s) being
1262 extracted. This occurs, for example, if you are restoring your
1263 files after a major crash and had booted from an emergency floppy
1264 with no password file or put your disk into another machine to do
1267 The numeric ids are _always_ saved into 'tar' archives. The
1268 identifying names are added at create time when provided by the
1269 system, unless '--format=oldgnu' is used. Numeric ids could be
1270 used when moving archives between a collection of machines using a
1271 centralized management for attribution of numeric ids to users and
1272 groups. This is often made through using the NIS capabilities.
1274 When making a 'tar' file for distribution to other sites, it is
1275 sometimes cleaner to use a single owner for all files in the
1276 distribution, and nicer to specify the write permission bits of the
1277 files as stored in the archive independently of their actual value
1278 on the file system. The way to prepare a clean distribution is
1279 usually to have some Makefile rule creating a directory, copying
1280 all needed files in that directory, then setting ownership and
1281 permissions as wanted (there are a lot of possible schemes), and
1282 only then making a 'tar' archive out of this directory, before
1283 cleaning everything out. Of course, we could add a lot of options
1284 to GNU 'tar' for fine tuning permissions and ownership. This is
1285 not the good way, I think. GNU 'tar' is already crowded with
1286 options and moreover, the approach just explained gives you a great
1287 deal of control already.
1290 '--same-permissions'
1291 '--preserve-permissions'
1292 Extract all protection information.
1294 This option causes 'tar' to set the modes (access permissions) of
1295 extracted files exactly as recorded in the archive. If this option
1296 is not used, the current 'umask' setting limits the permissions on
1297 extracted files. This option is by default enabled when 'tar' is
1298 executed by a superuser.
1300 This option is meaningless with '--list' ('-t').
1303 File: tar.info, Node: Portability, Next: cpio, Prev: Attributes, Up: Formats
1305 8.3 Making 'tar' Archives More Portable
1306 =======================================
1308 Creating a 'tar' archive on a particular system that is meant to be
1309 useful later on many other machines and with other versions of 'tar' is
1310 more challenging than you might think. 'tar' archive formats have been
1311 evolving since the first versions of Unix. Many such formats are
1312 around, and are not always compatible with each other. This section
1313 discusses a few problems, and gives some advice about making 'tar'
1314 archives more portable.
1316 One golden rule is simplicity. For example, limit your 'tar'
1317 archives to contain only regular files and directories, avoiding other
1318 kind of special files. Do not attempt to save sparse files or
1319 contiguous files as such. Let's discuss a few more problems, in turn.
1323 * Portable Names:: Portable Names
1324 * dereference:: Symbolic Links
1325 * hard links:: Hard Links
1326 * old:: Old V7 Archives
1327 * ustar:: Ustar Archives
1328 * gnu:: GNU and old GNU format archives.
1329 * posix:: POSIX archives
1330 * Checksumming:: Checksumming Problems
1331 * Large or Negative Values:: Large files, negative time stamps, etc.
1332 * Other Tars:: How to Extract GNU-Specific Data Using
1333 Other 'tar' Implementations
1336 File: tar.info, Node: Portable Names, Next: dereference, Up: Portability
1338 8.3.1 Portable Names
1339 --------------------
1341 Use portable file and member names. A name is portable if it contains
1342 only ASCII letters and digits, '/', '.', '_', and '-'; it cannot be
1343 empty, start with '-' or '//', or contain '/-'. Avoid deep directory
1344 nesting. For portability to old Unix hosts, limit your file name
1345 components to 14 characters or less.
1347 If you intend to have your 'tar' archives to be read under MSDOS, you
1348 should not rely on case distinction for file names, and you might use
1349 the GNU 'doschk' program for helping you further diagnosing illegal
1350 MSDOS names, which are even more limited than System V's.
1353 File: tar.info, Node: dereference, Next: hard links, Prev: Portable Names, Up: Portability
1355 8.3.2 Symbolic Links
1356 --------------------
1358 Normally, when 'tar' archives a symbolic link, it writes a block to the
1359 archive naming the target of the link. In that way, the 'tar' archive
1360 is a faithful record of the file system contents. When '--dereference'
1361 ('-h') is used with '--create' ('-c'), 'tar' archives the files symbolic
1362 links point to, instead of the links themselves.
1364 When creating portable archives, use '--dereference' ('-h'): some
1365 systems do not support symbolic links, and moreover, your distribution
1366 might be unusable if it contains unresolved symbolic links.
1368 When reading from an archive, the '--dereference' ('-h') option
1369 causes 'tar' to follow an already-existing symbolic link when 'tar'
1370 writes or reads a file named in the archive. Ordinarily, 'tar' does not
1371 follow such a link, though it may remove the link before writing a new
1372 file. *Note Dealing with Old Files::.
1374 The '--dereference' option is unsafe if an untrusted user can modify
1375 directories while 'tar' is running. *Note Security::.
1378 File: tar.info, Node: hard links, Next: old, Prev: dereference, Up: Portability
1383 Normally, when 'tar' archives a hard link, it writes a block to the
1384 archive naming the target of the link (a '1' type block). In that way,
1385 the actual file contents is stored in file only once. For example,
1386 consider the following two files:
1389 -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
1390 -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
1392 Here, 'jeden' is a link to 'one'. When archiving this directory with
1393 a verbose level 2, you will get an output similar to the following:
1395 $ tar cvvf ../archive.tar .
1396 drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
1397 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
1398 hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
1400 The last line shows that, instead of storing two copies of the file,
1401 'tar' stored it only once, under the name 'jeden', and stored file 'one'
1402 as a hard link to this file.
1404 It may be important to know that all hard links to the given file are
1405 stored in the archive. For example, this may be necessary for exact
1406 reproduction of the file system. The following option does that:
1410 Check the number of links dumped for each processed file. If this
1411 number does not match the total number of hard links for the file,
1412 print a warning message.
1414 For example, trying to archive only file 'jeden' with this option
1415 produces the following diagnostics:
1417 $ tar -c -f ../archive.tar -l jeden
1418 tar: Missing links to 'jeden'.
1420 Although creating special records for hard links helps keep a
1421 faithful record of the file system contents and makes archives more
1422 compact, it may present some difficulties when extracting individual
1423 members from the archive. For example, trying to extract file 'one'
1424 from the archive created in previous examples produces, in the absence
1427 $ tar xf archive.tar ./one
1428 tar: ./one: Cannot hard link to './jeden': No such file or directory
1429 tar: Error exit delayed from previous errors
1431 The reason for this behavior is that 'tar' cannot seek back in the
1432 archive to the previous member (in this case, 'one'), to extract it(1).
1433 If you wish to avoid such problems at the cost of a bigger archive, use
1434 the following option:
1436 '--hard-dereference'
1437 Dereference hard links and store the files they refer to.
1439 For example, trying this option on our two sample files, we get two
1440 copies in the archive, each of which can then be extracted independently
1443 $ tar -c -vv -f ../archive.tar --hard-dereference .
1444 drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
1445 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
1446 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one
1448 ---------- Footnotes ----------
1450 (1) There are plans to fix this in future releases.
1453 File: tar.info, Node: old, Next: ustar, Prev: hard links, Up: Portability
1455 8.3.4 Old V7 Archives
1456 ---------------------
1458 Certain old versions of 'tar' cannot handle additional information
1459 recorded by newer 'tar' programs. To create an archive in V7 format
1460 (not ANSI), which can be read by these old versions, specify the
1461 '--format=v7' option in conjunction with the '--create' ('-c') ('tar'
1462 also accepts '--portability' or '--old-archive' for this option). When
1463 you specify it, 'tar' leaves out information about directories, pipes,
1464 fifos, contiguous files, and device files, and specifies file ownership
1465 by group and user IDs instead of group and user names.
1467 When updating an archive, do not use '--format=v7' unless the archive
1468 was created using this option.
1470 In most cases, a _new_ format archive can be read by an _old_ 'tar'
1471 program without serious trouble, so this option should seldom be needed.
1472 On the other hand, most modern 'tar's are able to read old format
1473 archives, so it might be safer for you to always use '--format=v7' for
1474 your distributions. Notice, however, that 'ustar' format is a better
1475 alternative, as it is free from many of 'v7''s drawbacks.
1478 File: tar.info, Node: ustar, Next: gnu, Prev: old, Up: Portability
1480 8.3.5 Ustar Archive Format
1481 --------------------------
1483 The archive format defined by the POSIX.1-1988 specification is called
1484 'ustar'. Although it is more flexible than the V7 format, it still has
1485 many restrictions (*note ustar: Formats, for the detailed description of
1486 'ustar' format). Along with V7 format, 'ustar' format is a good choice
1487 for archives intended to be read with other implementations of 'tar'.
1489 To create an archive in 'ustar' format, use the '--format=ustar'
1490 option in conjunction with '--create' ('-c').
1493 File: tar.info, Node: gnu, Next: posix, Prev: ustar, Up: Portability
1495 8.3.6 GNU and old GNU 'tar' format
1496 ----------------------------------
1498 GNU 'tar' was based on an early draft of the POSIX 1003.1 'ustar'
1499 standard. GNU extensions to 'tar', such as the support for file names
1500 longer than 100 characters, use portions of the 'tar' header record
1501 which were specified in that POSIX draft as unused. Subsequent changes
1502 in POSIX have allocated the same parts of the header record for other
1503 purposes. As a result, GNU 'tar' format is incompatible with the
1504 current POSIX specification, and with 'tar' programs that follow it.
1506 In the majority of cases, 'tar' will be configured to create this
1507 format by default. This will change in future releases, since we plan
1508 to make 'POSIX' format the default.
1510 To force creation a GNU 'tar' archive, use option '--format=gnu'.
1513 File: tar.info, Node: posix, Next: Checksumming, Prev: gnu, Up: Portability
1515 8.3.7 GNU 'tar' and POSIX 'tar'
1516 -------------------------------
1518 Starting from version 1.14 GNU 'tar' features full support for
1519 POSIX.1-2001 archives.
1521 A POSIX conformant archive will be created if 'tar' was given
1522 '--format=posix' ('--format=pax') option. No special option is required
1523 to read and extract from a POSIX archive.
1527 * PAX keywords:: Controlling Extended Header Keywords.
1530 File: tar.info, Node: PAX keywords, Up: posix
1532 8.3.7.1 Controlling Extended Header Keywords
1533 ............................................
1535 '--pax-option=KEYWORD-LIST'
1536 Handle keywords in PAX extended headers. This option is equivalent
1537 to '-o' option of the 'pax' utility.
1539 KEYWORD-LIST is a comma-separated list of keyword options, each
1540 keyword option taking one of the following forms:
1543 When used with one of archive-creation commands, this option
1544 instructs 'tar' to omit from extended header records that it
1545 produces any keywords matching the string PATTERN.
1547 When used in extract or list mode, this option instructs tar to
1548 ignore any keywords matching the given PATTERN in the extended
1549 header records. In both cases, matching is performed using the
1550 pattern matching notation described in POSIX 1003.2, 3.13 (*note
1551 wildcards::). For example:
1553 --pax-option delete=security.*
1555 would suppress security-related information.
1557 'exthdr.name=STRING'
1559 This keyword allows user control over the name that is written into
1560 the ustar header blocks for the extended headers. The name is
1561 obtained from STRING after making the following substitutions:
1563 Meta-character Replaced By
1564 ------------------------------------------------------------
1565 %d The directory name of the file,
1566 equivalent to the result of the
1567 'dirname' utility on the translated
1569 %f The name of the file with the
1570 directory information stripped,
1571 equivalent to the result of the
1572 'basename' utility on the translated
1574 %p The process ID of the 'tar' process.
1577 Any other '%' characters in STRING produce undefined results.
1579 If no option 'exthdr.name=string' is specified, 'tar' will use the
1580 following default value:
1584 'exthdr.mtime=VALUE'
1586 This keyword defines the value of the 'mtime' field that is written
1587 into the ustar header blocks for the extended headers. By default,
1588 the 'mtime' field is set to the modification time of the archive
1589 member described by that extended header (or to the value of the
1590 '--mtime' option, if supplied).
1592 'globexthdr.name=STRING'
1593 This keyword allows user control over the name that is written into
1594 the ustar header blocks for global extended header records. The
1595 name is obtained from the contents of STRING, after making the
1596 following substitutions:
1598 Meta-character Replaced By
1599 ------------------------------------------------------------
1600 %n An integer that represents the
1601 sequence number of the global extended
1602 header record in the archive, starting
1604 %p The process ID of the 'tar' process.
1607 Any other '%' characters in STRING produce undefined results.
1609 If no option 'globexthdr.name=string' is specified, 'tar' will use
1610 the following default value:
1612 $TMPDIR/GlobalHead.%p.%n
1614 where '$TMPDIR' represents the value of the TMPDIR environment
1615 variable. If TMPDIR is not set, 'tar' uses '/tmp'.
1617 'globexthdr.mtime=VALUE'
1619 This keyword defines the value of the 'mtime' field that is written
1620 into the ustar header blocks for the global extended headers. By
1621 default, the 'mtime' field is set to the time when 'tar' was
1625 When used with one of archive-creation commands, these
1626 keyword/value pairs will be included at the beginning of the
1627 archive in a global extended header record. When used with one of
1628 archive-reading commands, 'tar' will behave as if it has
1629 encountered these keyword/value pairs at the beginning of the
1630 archive in a global extended header record.
1633 When used with one of archive-creation commands, these
1634 keyword/value pairs will be included as records at the beginning of
1635 an extended header for each file. This is effectively equivalent
1636 to KEYWORD=VALUE form except that it creates no global extended
1639 When used with one of archive-reading commands, 'tar' will behave
1640 as if these keyword/value pairs were included as records at the end
1641 of each extended header; thus, they will override any global or
1642 file-specific extended header record keywords of the same names.
1643 For example, in the command:
1645 tar --format=posix --create \
1646 --file archive --pax-option gname:=user .
1648 the group name will be forced to a new value for all files stored
1651 In any of the forms described above, the VALUE may be a string
1652 enclosed in curly braces. In that case, the string between the braces
1653 is understood either as a textual time representation, as described in
1654 *note Date input formats::, or a name of the existing file, starting
1655 with '/' or '.'. In the latter case, the modification time of that file
1658 For example, to set all modification times to the current date, you
1659 use the following option:
1661 --pax-option='mtime:={now}'
1663 Note quoting of the option's argument.
1665 As another example, here is the option that ensures that any two
1666 archives created using it, will be binary equivalent if they have the
1669 --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0
1671 If you extract files from such an archive and recreate the archive from
1672 them, you will also need to eliminate changes due to ctime, as shown in
1675 --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,ctime:=0
1679 --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,delete=ctime
1682 File: tar.info, Node: Checksumming, Next: Large or Negative Values, Prev: posix, Up: Portability
1684 8.3.8 Checksumming Problems
1685 ---------------------------
1687 SunOS and HP-UX 'tar' fail to accept archives created using GNU 'tar'
1688 and containing non-ASCII file names, that is, file names having
1689 characters with the eighth bit set, because they use signed checksums,
1690 while GNU 'tar' uses unsigned checksums while creating archives, as per
1691 POSIX standards. On reading, GNU 'tar' computes both checksums and
1692 accepts either of them. It is somewhat worrying that a lot of people
1693 may go around doing backup of their files using faulty (or at least
1694 non-standard) software, not learning about it until it's time to restore
1695 their missing files with an incompatible file extractor, or vice versa.
1697 GNU 'tar' computes checksums both ways, and accepts either of them on
1698 read, so GNU tar can read Sun tapes even with their wrong checksums.
1699 GNU 'tar' produces the standard checksum, however, raising
1700 incompatibilities with Sun. That is to say, GNU 'tar' has not been
1701 modified to _produce_ incorrect archives to be read by buggy 'tar''s.
1702 I've been told that more recent Sun 'tar' now read standard archives, so
1703 maybe Sun did a similar patch, after all?
1705 The story seems to be that when Sun first imported 'tar' sources on
1706 their system, they recompiled it without realizing that the checksums
1707 were computed differently, because of a change in the default signing of
1708 'char''s in their compiler. So they started computing checksums
1709 wrongly. When they later realized their mistake, they merely decided to
1710 stay compatible with it, and with themselves afterwards. Presumably,
1711 but I do not really know, HP-UX has chosen their 'tar' archives to be
1712 compatible with Sun's. The current standards do not favor Sun 'tar'
1713 format. In any case, it now falls on the shoulders of SunOS and HP-UX
1714 users to get a 'tar' able to read the good archives they receive.
1717 File: tar.info, Node: Large or Negative Values, Next: Other Tars, Prev: Checksumming, Up: Portability
1719 8.3.9 Large or Negative Values
1720 ------------------------------
1722 _(This message will disappear, once this node revised.)_
1724 The above sections suggest to use 'oldest possible' archive format if
1725 in doubt. However, sometimes it is not possible. If you attempt to
1726 archive a file whose metadata cannot be represented using required
1727 format, GNU 'tar' will print error message and ignore such a file. You
1728 will than have to switch to a format that is able to handle such values.
1729 The format summary table (*note Formats::) will help you to do so.
1731 In particular, when trying to archive files larger than 8GB or with
1732 timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16
1733 12:56:31 UTC, you will have to chose between GNU and POSIX archive
1734 formats. When considering which format to choose, bear in mind that the
1735 GNU format uses two's-complement base-256 notation to store values that
1736 do not fit into standard ustar range. Such archives can generally be
1737 read only by a GNU 'tar' implementation. Moreover, they sometimes
1738 cannot be correctly restored on another hosts even by GNU 'tar'. For
1739 example, using two's complement representation for negative time stamps
1740 that assumes a signed 32-bit 'time_t' generates archives that are not
1741 portable to hosts with differing 'time_t' representations.
1743 On the other hand, POSIX archives, generally speaking, can be
1744 extracted by any tar implementation that understands older ustar format.
1745 The only exception are files larger than 8GB.
1748 File: tar.info, Node: Other Tars, Prev: Large or Negative Values, Up: Portability
1750 8.3.10 How to Extract GNU-Specific Data Using Other 'tar' Implementations
1751 -------------------------------------------------------------------------
1753 In previous sections you became acquainted with various quirks necessary
1754 to make your archives portable. Sometimes you may need to extract
1755 archives containing GNU-specific members using some third-party 'tar'
1756 implementation or an older version of GNU 'tar'. Of course your best
1757 bet is to have GNU 'tar' installed, but if it is for some reason
1758 impossible, this section will explain how to cope without it.
1760 When we speak about "GNU-specific" members we mean two classes of
1761 them: members split between the volumes of a multi-volume archive and
1762 sparse members. You will be able to always recover such members if the
1763 archive is in PAX format. In addition split members can be recovered
1764 from archives in old GNU format. The following subsections describe the
1765 required procedures in detail.
1769 * Split Recovery:: Members Split Between Volumes
1770 * Sparse Recovery:: Sparse Members
1773 File: tar.info, Node: Split Recovery, Next: Sparse Recovery, Up: Other Tars
1775 8.3.10.1 Extracting Members Split Between Volumes
1776 .................................................
1778 If a member is split between several volumes of an old GNU format
1779 archive most third party 'tar' implementation will fail to extract it.
1780 To extract it, use 'tarcat' program (*note Tarcat::). This program is
1781 available from GNU 'tar' home page
1782 (http://www.gnu.org/software/tar/utils/tarcat.html). It concatenates
1783 several archive volumes into a single valid archive. For example, if
1784 you have three volumes named from 'vol-1.tar' to 'vol-3.tar', you can do
1785 the following to extract them using a third-party 'tar':
1787 $ tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -
1789 You could use this approach for most (although not all) PAX format
1790 archives as well. However, extracting split members from a PAX archive
1791 is a much easier task, because PAX volumes are constructed in such a way
1792 that each part of a split member is extracted to a different file by
1793 'tar' implementations that are not aware of GNU extensions. More
1794 specifically, the very first part retains its original name, and all
1795 subsequent parts are named using the pattern:
1797 %d/GNUFileParts.%p/%f.%n
1799 where symbols preceded by '%' are "macro characters" that have the
1802 Meta-character Replaced By
1803 ------------------------------------------------------------
1804 %d The directory name of the file,
1805 equivalent to the result of the
1806 'dirname' utility on its full name.
1807 %f The file name of the file, equivalent
1808 to the result of the 'basename'
1809 utility on its full name.
1810 %p The process ID of the 'tar' process
1811 that created the archive.
1812 %n Ordinal number of this particular
1815 For example, if the file 'var/longfile' was split during archive
1816 creation between three volumes, and the creator 'tar' process had
1817 process ID '27962', then the member names will be:
1820 var/GNUFileParts.27962/longfile.1
1821 var/GNUFileParts.27962/longfile.2
1823 When you extract your archive using a third-party 'tar', these files
1824 will be created on your disk, and the only thing you will need to do to
1825 restore your file in its original form is concatenate them in the proper
1829 $ cat GNUFileParts.27962/longfile.1 \
1830 GNUFileParts.27962/longfile.2 >> longfile
1831 $ rm -f GNUFileParts.27962
1833 Notice, that if the 'tar' implementation you use supports PAX format
1834 archives, it will probably emit warnings about unknown keywords during
1835 extraction. They will look like this:
1838 Unknown extended header keyword 'GNU.volume.filename' ignored.
1839 Unknown extended header keyword 'GNU.volume.size' ignored.
1840 Unknown extended header keyword 'GNU.volume.offset' ignored.
1842 You can safely ignore these warnings.
1844 If your 'tar' implementation is not PAX-aware, you will get more
1845 warnings and more files generated on your disk, e.g.:
1848 var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
1850 Unexpected EOF in archive
1852 tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file
1853 GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type
1854 'x', extracted as normal file
1856 Ignore these warnings. The 'PaxHeaders.*' directories created will
1857 contain files with "extended header keywords" describing the extracted
1858 files. You can delete them, unless they describe sparse members. Read
1859 further to learn more about them.
1862 File: tar.info, Node: Sparse Recovery, Prev: Split Recovery, Up: Other Tars
1864 8.3.10.2 Extracting Sparse Members
1865 ..................................
1867 Any 'tar' implementation will be able to extract sparse members from a
1868 PAX archive. However, the extracted files will be "condensed", i.e.,
1869 any zero blocks will be removed from them. When we restore such a
1870 condensed file to its original form, by adding zero blocks (or "holes")
1871 back to their original locations, we call this process "expanding" a
1872 compressed sparse file.
1874 To expand a file, you will need a simple auxiliary program called
1875 'xsparse'. It is available in source form from GNU 'tar' home page
1876 (http://www.gnu.org/software/tar/utils/xsparse.html).
1878 Let's begin with archive members in "sparse format version 1.0"(1),
1879 which are the easiest to expand. The condensed file will contain both
1880 file map and file data, so no additional data will be needed to restore
1881 it. If the original file name was 'DIR/NAME', then the condensed file
1882 will be named 'DIR/GNUSparseFile.N/NAME', where N is a decimal
1885 To expand a version 1.0 file, run 'xsparse' as follows:
1889 where 'cond-file' is the name of the condensed file. The utility will
1890 deduce the name for the resulting expanded file using the following
1893 1. If 'cond-file' does not contain any directories, '../cond-file'
1896 2. If 'cond-file' has the form 'DIR/T/NAME', where both T and NAME are
1897 simple names, with no '/' characters in them, the output file name
1900 3. Otherwise, if 'cond-file' has the form 'DIR/NAME', the output file
1901 name will be 'NAME'.
1903 In the unlikely case when this algorithm does not suit your needs,
1904 you can explicitly specify output file name as a second argument to the
1907 $ xsparse cond-file out-file
1909 It is often a good idea to run 'xsparse' in "dry run" mode first. In
1910 this mode, the command does not actually expand the file, but verbosely
1911 lists all actions it would be taking to do so. The dry run mode is
1912 enabled by '-n' command line argument:
1914 $ xsparse -n /home/gray/GNUSparseFile.6058/sparsefile
1915 Reading v.1.0 sparse map
1916 Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
1917 '/home/gray/sparsefile'
1920 To actually expand the file, you would run:
1922 $ xsparse /home/gray/GNUSparseFile.6058/sparsefile
1924 The program behaves the same way all UNIX utilities do: it will keep
1925 quiet unless it has something important to tell you (e.g. an error
1926 condition or something). If you wish it to produce verbose output,
1927 similar to that from the dry run mode, use '-v' option:
1929 $ xsparse -v /home/gray/GNUSparseFile.6058/sparsefile
1930 Reading v.1.0 sparse map
1931 Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
1932 '/home/gray/sparsefile'
1935 Additionally, if your 'tar' implementation has extracted the
1936 "extended headers" for this file, you can instruct 'xstar' to use them
1937 in order to verify the integrity of the expanded file. The option '-x'
1938 sets the name of the extended header file to use. Continuing our
1941 $ xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \
1942 /home/gray/GNUSparseFile.6058/sparsefile
1943 Reading extended header file
1944 Found variable GNU.sparse.major = 1
1945 Found variable GNU.sparse.minor = 0
1946 Found variable GNU.sparse.name = sparsefile
1947 Found variable GNU.sparse.realsize = 217481216
1948 Reading v.1.0 sparse map
1949 Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to
1950 '/home/gray/sparsefile'
1953 An "extended header" is a special 'tar' archive header that precedes
1954 an archive member and contains a set of "variables", describing the
1955 member properties that cannot be stored in the standard 'ustar' header.
1956 While optional for expanding sparse version 1.0 members, the use of
1957 extended headers is mandatory when expanding sparse members in older
1958 sparse formats: v.0.0 and v.0.1 (The sparse formats are described in
1959 detail in *note Sparse Formats::.) So, for these formats, the question
1960 is: how to obtain extended headers from the archive?
1962 If you use a 'tar' implementation that does not support PAX format,
1963 extended headers for each member will be extracted as a separate file.
1964 If we represent the member name as 'DIR/NAME', then the extended header
1965 file will be named 'DIR/PaxHeaders.N/NAME', where N is an integer
1968 Things become more difficult if your 'tar' implementation does
1969 support PAX headers, because in this case you will have to manually
1970 extract the headers. We recommend the following algorithm:
1972 1. Consult the documentation of your 'tar' implementation for an
1973 option that prints "block numbers" along with the archive listing
1974 (analogous to GNU 'tar''s '-R' option). For example, 'star' has
1977 2. Obtain verbose listing using the 'block number' option, and find
1978 block numbers of the sparse member in question and the member
1979 immediately following it. For example, running 'star' on our
1982 $ star -t -v -block-number -f arc.tar
1984 star: Unknown extended header keyword 'GNU.sparse.size' ignored.
1985 star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored.
1986 star: Unknown extended header keyword 'GNU.sparse.name' ignored.
1987 star: Unknown extended header keyword 'GNU.sparse.map' ignored.
1988 block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile
1989 block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README
1992 (as usual, ignore the warnings about unknown keywords.)
1994 3. Let SIZE be the size of the sparse member, BS be its block number
1995 and BN be the block number of the next member. Compute:
1997 N = BS - BN - SIZE/512 - 2
1999 This number gives the size of the extended header part in tar
2000 "blocks". In our example, this formula gives: '897 - 56 - 425984 /
2003 4. Use 'dd' to extract the headers:
2005 dd if=ARCHIVE of=HNAME bs=512 skip=BS count=N
2007 where ARCHIVE is the archive name, HNAME is a name of the file to
2008 store the extended header in, BS and N are computed in previous
2011 In our example, this command will be
2013 $ dd if=arc.tar of=xhdr bs=512 skip=56 count=7
2015 Finally, you can expand the condensed file, using the obtained
2018 $ xsparse -v -x xhdr GNUSparseFile.6058/sparsefile
2019 Reading extended header file
2020 Found variable GNU.sparse.size = 217481216
2021 Found variable GNU.sparse.numblocks = 208
2022 Found variable GNU.sparse.name = sparsefile
2023 Found variable GNU.sparse.map = 0,2048,1050624,2048,...
2024 Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile'
2027 ---------- Footnotes ----------
2031 (2) Technically speaking, N is a "process ID" of the 'tar' process
2032 which created the archive (*note PAX keywords::).
2035 File: tar.info, Node: cpio, Prev: Portability, Up: Formats
2037 8.4 Comparison of 'tar' and 'cpio'
2038 ==================================
2040 _(This message will disappear, once this node revised.)_
2042 The 'cpio' archive formats, like 'tar', do have maximum file name
2043 lengths. The binary and old ASCII formats have a maximum file length of
2044 256, and the new ASCII and CRC ASCII formats have a max file length of
2045 1024. GNU 'cpio' can read and write archives with arbitrary file name
2046 lengths, but other 'cpio' implementations may crash unexplainedly trying
2049 'tar' handles symbolic links in the form in which it comes in BSD;
2050 'cpio' doesn't handle symbolic links in the form in which it comes in
2051 System V prior to SVR4, and some vendors may have added symlinks to
2052 their system without enhancing 'cpio' to know about them. Others may
2053 have enhanced it in a way other than the way I did it at Sun, and which
2054 was adopted by AT&T (and which is, I think, also present in the 'cpio'
2055 that Berkeley picked up from AT&T and put into a later BSD release--I
2056 think I gave them my changes).
2058 (SVR4 does some funny stuff with 'tar'; basically, its 'cpio' can
2059 handle 'tar' format input, and write it on output, and it probably
2060 handles symbolic links. They may not have bothered doing anything to
2061 enhance 'tar' as a result.)
2063 'cpio' handles special files; traditional 'tar' doesn't.
2065 'tar' comes with V7, System III, System V, and BSD source; 'cpio'
2066 comes only with System III, System V, and later BSD (4.3-tahoe and
2069 'tar''s way of handling multiple hard links to a file can handle file
2070 systems that support 32-bit i-numbers (e.g., the BSD file system);
2071 'cpio's way requires you to play some games (in its "binary" format,
2072 i-numbers are only 16 bits, and in its "portable ASCII" format, they're
2073 18 bits--it would have to play games with the "file system ID" field of
2074 the header to make sure that the file system ID/i-number pairs of
2075 different files were always different), and I don't know which 'cpio's,
2076 if any, play those games. Those that don't might get confused and think
2077 two files are the same file when they're not, and make hard links
2080 'tar's way of handling multiple hard links to a file places only one
2081 copy of the link on the tape, but the name attached to that copy is the
2082 _only_ one you can use to retrieve the file; 'cpio's way puts one copy
2083 for every link, but you can retrieve it using any of the names.
2085 What type of check sum (if any) is used, and how is this
2088 See the attached manual pages for 'tar' and 'cpio' format. 'tar'
2089 uses a checksum which is the sum of all the bytes in the 'tar' header
2090 for a file; 'cpio' uses no checksum.
2092 If anyone knows why 'cpio' was made when 'tar' was present at the
2095 It wasn't. 'cpio' first showed up in PWB/UNIX 1.0; no
2096 generally-available version of UNIX had 'tar' at the time. I don't know
2097 whether any version that was generally available _within AT&T_ had
2098 'tar', or, if so, whether the people within AT&T who did 'cpio' knew
2101 On restore, if there is a corruption on a tape 'tar' will stop at
2102 that point, while 'cpio' will skip over it and try to restore the rest
2105 The main difference is just in the command syntax and header format.
2107 'tar' is a little more tape-oriented in that everything is blocked to
2108 start on a record boundary.
2110 Is there any differences between the ability to recover crashed
2111 archives between the two of them. (Is there any chance of
2112 recovering crashed archives at all.)
2114 Theoretically it should be easier under 'tar' since the blocking lets
2115 you find a header with some variation of 'dd skip=NN'. However, modern
2116 'cpio''s and variations have an option to just search for the next file
2117 header after an error with a reasonable chance of resyncing. However,
2118 lots of tape driver software won't allow you to continue past a media
2119 error which should be the only reason for getting out of sync unless a
2120 file changed sizes while you were writing the archive.
2122 If anyone knows why 'cpio' was made when 'tar' was present at the
2123 unix scene, please tell me about this too.
2125 Probably because it is more media efficient (by not blocking
2126 everything and using only the space needed for the headers where 'tar'
2127 always uses 512 bytes per file header) and it knows how to archive
2130 You might want to look at the freely available alternatives. The
2131 major ones are 'afio', GNU 'tar', and 'pax', each of which have their
2132 own extensions with some backwards compatibility.
2134 Sparse files were 'tar'red as sparse files (which you can easily
2135 test, because the resulting archive gets smaller, and GNU 'cpio' can no
2139 File: tar.info, Node: Media, Next: Reliability and security, Prev: Formats, Up: Top
2141 9 Tapes and Other Archive Media
2142 *******************************
2144 _(This message will disappear, once this node revised.)_
2146 A few special cases about tape handling warrant more detailed
2147 description. These special cases are discussed below.
2149 Many complexities surround the use of 'tar' on tape drives. Since
2150 the creation and manipulation of archives located on magnetic tape was
2151 the original purpose of 'tar', it contains many features making such
2152 manipulation easier.
2154 Archives are usually written on dismountable media--tape cartridges,
2155 mag tapes, or floppy disks.
2157 The amount of data a tape or disk holds depends not only on its size,
2158 but also on how it is formatted. A 2400 foot long reel of mag tape
2159 holds 40 megabytes of data when formatted at 1600 bits per inch. The
2160 physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
2162 Magnetic media are re-usable--once the archive on a tape is no longer
2163 needed, the archive can be erased and the tape or disk used over. Media
2164 quality does deteriorate with use, however. Most tapes or disks should
2165 be discarded when they begin to produce data errors. EXABYTE tape
2166 cartridges should be discarded when they generate an "error count"
2167 (number of non-usable bits) of more than 10k.
2169 Magnetic media are written and erased using magnetic fields, and
2170 should be protected from such fields to avoid damage to stored data.
2171 Sticking a floppy disk to a filing cabinet using a magnet is probably
2176 * Device:: Device selection and switching
2177 * Remote Tape Server::
2178 * Common Problems and Solutions::
2179 * Blocking:: Blocking
2180 * Many:: Many archives on one tape
2181 * Using Multiple Tapes:: Using Multiple Tapes
2182 * label:: Including a Label in the Archive
2184 * Write Protection::
2187 File: tar.info, Node: Device, Next: Remote Tape Server, Up: Media
2189 9.1 Device Selection and Switching
2190 ==================================
2192 _(This message will disappear, once this node revised.)_
2194 '-f [HOSTNAME:]FILE'
2195 '--file=[HOSTNAME:]FILE'
2196 Use archive file or device FILE on HOSTNAME.
2198 This option is used to specify the file name of the archive 'tar'
2201 If the file name is '-', 'tar' reads the archive from standard input
2202 (when listing or extracting), or writes it to standard output (when
2203 creating). If the '-' file name is given when updating an archive,
2204 'tar' will read the original archive from its standard input, and will
2205 write the entire new archive to its standard output.
2207 If the file name contains a ':', it is interpreted as 'hostname:file
2208 name'. If the HOSTNAME contains an "at" sign ('@'), it is treated as
2209 'user@hostname:file name'. In either case, 'tar' will invoke the
2210 command 'rsh' (or 'remsh') to start up an '/usr/libexec/rmt' on the
2211 remote machine. If you give an alternate login name, it will be given
2212 to the 'rsh'. Naturally, the remote machine must have an executable
2213 '/usr/libexec/rmt'. This program is free software from the University
2214 of California, and a copy of the source code can be found with the
2215 sources for 'tar'; it's compiled and installed by default. The exact
2216 path to this utility is determined when configuring the package. It is
2217 'PREFIX/libexec/rmt', where PREFIX stands for your installation prefix.
2218 This location may also be overridden at runtime by using the
2219 '--rmt-command=COMMAND' option (*Note --rmt-command: Option Summary, for
2220 detailed description of this option. *Note Remote Tape Server::, for
2221 the description of 'rmt' command).
2223 If this option is not given, but the environment variable 'TAPE' is
2224 set, its value is used; otherwise, old versions of 'tar' used a default
2225 archive name (which was picked when 'tar' was compiled). The default is
2226 normally set up to be the "first" tape drive or other transportable I/O
2227 medium on the system.
2229 Starting with version 1.11.5, GNU 'tar' uses standard input and
2230 standard output as the default device, and I will not try anymore
2231 supporting automatic device detection at installation time. This was
2232 failing really in too many cases, it was hopeless. This is now
2233 completely left to the installer to override standard input and standard
2234 output for default device, if this seems preferable. Further, I think
2235 _most_ actual usages of 'tar' are done with pipes or disks, not really
2236 tapes, cartridges or diskettes.
2238 Some users think that using standard input and output is running
2239 after trouble. This could lead to a nasty surprise on your screen if
2240 you forget to specify an output file name--especially if you are going
2241 through a network or terminal server capable of buffering large amounts
2242 of output. We had so many bug reports in that area of configuring
2243 default tapes automatically, and so many contradicting requests, that we
2244 finally consider the problem to be portably intractable. We could of
2245 course use something like '/dev/tape' as a default, but this is _also_
2246 running after various kind of trouble, going from hung processes to
2247 accidental destruction of real tapes. After having seen all this mess,
2248 using standard input and output as a default really sounds like the only
2249 clean choice left, and a very useful one too.
2251 GNU 'tar' reads and writes archive in records, I suspect this is the
2252 main reason why block devices are preferred over character devices.
2253 Most probably, block devices are more efficient too. The installer
2254 could also check for 'DEFTAPE' in '<sys/mtio.h>'.
2257 Archive file is local even if it contains a colon.
2259 '--rsh-command=COMMAND'
2260 Use remote COMMAND instead of 'rsh'. This option exists so that
2261 people who use something other than the standard 'rsh' (e.g., a
2262 Kerberized 'rsh') can access a remote device.
2264 When this command is not used, the shell command found when the
2265 'tar' program was installed is used instead. This is the first
2266 found of '/usr/ucb/rsh', '/usr/bin/remsh', '/usr/bin/rsh',
2267 '/usr/bsd/rsh' or '/usr/bin/nsh'. The installer may have
2268 overridden this by defining the environment variable 'RSH' _at
2272 Specify drive and density.
2276 Create/list/extract multi-volume archive.
2278 This option causes 'tar' to write a "multi-volume" archive--one
2279 that may be larger than will fit on the medium used to hold it.
2280 *Note Multi-Volume Archives::.
2283 '--tape-length=SIZE[SUF]'
2284 Change tape after writing SIZE units of data. Unless SUF is given,
2285 SIZE is treated as kilobytes, i.e. 'SIZE x 1024' bytes. The
2286 following suffixes alter this behavior:
2288 Suffix Units Byte Equivalent
2289 -------------------------------------------------------------
2291 B Kilobytes SIZE x 1024
2293 G Gigabytes SIZE x 1024^3
2294 K Kilobytes SIZE x 1024
2295 k Kilobytes SIZE x 1024
2296 M Megabytes SIZE x 1024^2
2297 P Petabytes SIZE x 1024^5
2298 T Terabytes SIZE x 1024^4
2301 Table 9.1: Size Suffixes
2303 This option might be useful when your tape drivers do not properly
2304 detect end of physical tapes. By being slightly conservative on
2305 the maximum tape length, you might avoid the problem entirely.
2308 '--info-script=COMMAND'
2309 '--new-volume-script=COMMAND'
2310 Execute COMMAND at end of each tape. This implies '--multi-volume'
2311 ('-M'). *Note info-script::, for a detailed description of this
2315 File: tar.info, Node: Remote Tape Server, Next: Common Problems and Solutions, Prev: Device, Up: Media
2317 9.2 Remote Tape Server
2318 ======================
2320 In order to access the tape drive on a remote machine, 'tar' uses the
2321 remote tape server written at the University of California at Berkeley.
2322 The remote tape server must be installed as 'PREFIX/libexec/rmt' on any
2323 machine whose tape drive you want to use. 'tar' calls 'rmt' by running
2324 an 'rsh' or 'remsh' to the remote machine, optionally using a different
2325 login name if one is supplied.
2327 A copy of the source for the remote tape server is provided. Its
2328 source code can be freely distributed. It is compiled and installed by
2331 Unless you use the '--absolute-names' ('-P') option, GNU 'tar' will
2332 not allow you to create an archive that contains absolute file names (a
2333 file name beginning with '/'). If you try, 'tar' will automatically
2334 remove the leading '/' from the file names it stores in the archive. It
2335 will also type a warning message telling you what it is doing.
2337 When reading an archive that was created with a different 'tar'
2338 program, GNU 'tar' automatically extracts entries in the archive which
2339 have absolute file names as if the file names were not absolute. This
2340 is an important feature. A visitor here once gave a 'tar' tape to an
2341 operator to restore; the operator used Sun 'tar' instead of GNU 'tar',
2342 and the result was that it replaced large portions of our '/bin' and
2343 friends with versions from the tape; needless to say, we were unhappy
2344 about having to recover the file system from backup tapes.
2346 For example, if the archive contained a file '/usr/bin/computoy', GNU
2347 'tar' would extract the file to 'usr/bin/computoy', relative to the
2348 current directory. If you want to extract the files in an archive to
2349 the same absolute names that they had when the archive was created, you
2350 should do a 'cd /' before extracting the files from the archive, or you
2351 should either use the '--absolute-names' option, or use the command 'tar
2354 Some versions of Unix (Ultrix 3.1 is known to have this problem), can
2355 claim that a short write near the end of a tape succeeded, when it
2356 actually failed. This will result in the -M option not working
2357 correctly. The best workaround at the moment is to use a significantly
2358 larger blocking factor than the default 20.
2360 In order to update an archive, 'tar' must be able to backspace the
2361 archive in order to reread or rewrite a record that was just read (or
2362 written). This is currently possible only on two kinds of files: normal
2363 disk files (or any other file that can be backspaced with 'lseek'), and
2364 industry-standard 9-track magnetic tape (or any other kind of tape that
2365 can be backspaced with the 'MTIOCTOP' 'ioctl').
2367 This means that the '--append', '--concatenate', and '--delete'
2368 commands will not work on any other kind of file. Some media simply
2369 cannot be backspaced, which means these commands and options will never
2370 be able to work on them. These non-backspacing media include pipes and
2371 cartridge tape drives.
2373 Some other media can be backspaced, and 'tar' will work on them once
2374 'tar' is modified to do so.
2376 Archives created with the '--multi-volume', '--label', and
2377 '--incremental' ('-G') options may not be readable by other version of
2378 'tar'. In particular, restoring a file that was split over a volume
2379 boundary will require some careful work with 'dd', if it can be done at
2380 all. Other versions of 'tar' may also create an empty file whose name
2381 is that of the volume header. Some versions of 'tar' may create normal
2382 files instead of directories archived with the '--incremental' ('-G')
2386 File: tar.info, Node: Common Problems and Solutions, Next: Blocking, Prev: Remote Tape Server, Up: Media
2388 9.3 Some Common Problems and their Solutions
2389 ============================================
2393 no such file or directory
2397 directory checksum error
2400 errors from media/system:
2405 File: tar.info, Node: Blocking, Next: Many, Prev: Common Problems and Solutions, Up: Media
2410 "Block" and "record" terminology is rather confused, and it is also
2411 confusing to the expert reader. On the other hand, readers who are new
2412 to the field have a fresh mind, and they may safely skip the next two
2413 paragraphs, as the remainder of this manual uses those two terms in a
2414 quite consistent way.
2416 John Gilmore, the writer of the public domain 'tar' from which GNU
2417 'tar' was originally derived, wrote (June 1995):
2419 The nomenclature of tape drives comes from IBM, where I believe
2420 they were invented for the IBM 650 or so. On IBM mainframes, what
2421 is recorded on tape are tape blocks. The logical organization of
2422 data is into records. There are various ways of putting records
2423 into blocks, including 'F' (fixed sized records), 'V' (variable
2424 sized records), 'FB' (fixed blocked: fixed size records, N to a
2425 block), 'VB' (variable size records, N to a block), 'VSB' (variable
2426 spanned blocked: variable sized records that can occupy more than
2427 one block), etc. The 'JCL' 'DD RECFORM=' parameter specified this
2428 to the operating system.
2430 The Unix man page on 'tar' was totally confused about this. When I
2431 wrote 'PD TAR', I used the historically correct terminology ('tar'
2432 writes data records, which are grouped into blocks). It appears
2433 that the bogus terminology made it into POSIX (no surprise here),
2434 and now Franc,ois has migrated that terminology back into the
2437 The term "physical block" means the basic transfer chunk from or to a
2438 device, after which reading or writing may stop without anything being
2439 lost. In this manual, the term "block" usually refers to a disk
2440 physical block, _assuming_ that each disk block is 512 bytes in length.
2441 It is true that some disk devices have different physical blocks, but
2442 'tar' ignore these differences in its own format, which is meant to be
2443 portable, so a 'tar' block is always 512 bytes in length, and "block"
2444 always mean a 'tar' block. The term "logical block" often represents
2445 the basic chunk of allocation of many disk blocks as a single entity,
2446 which the operating system treats somewhat atomically; this concept is
2447 only barely used in GNU 'tar'.
2449 The term "physical record" is another way to speak of a physical
2450 block, those two terms are somewhat interchangeable. In this manual,
2451 the term "record" usually refers to a tape physical block, _assuming_
2452 that the 'tar' archive is kept on magnetic tape. It is true that
2453 archives may be put on disk or used with pipes, but nevertheless, 'tar'
2454 tries to read and write the archive one "record" at a time, whatever the
2455 medium in use. One record is made up of an integral number of blocks,
2456 and this operation of putting many disk blocks into a single tape block
2457 is called "reblocking", or more simply, "blocking". The term "logical
2458 record" refers to the logical organization of many characters into
2459 something meaningful to the application. The term "unit record"
2460 describes a small set of characters which are transmitted whole to or by
2461 the application, and often refers to a line of text. Those two last
2462 terms are unrelated to what we call a "record" in GNU 'tar'.
2464 When writing to tapes, 'tar' writes the contents of the archive in
2465 chunks known as "records". To change the default blocking factor, use
2466 the '--blocking-factor=512-SIZE' ('-b 512-SIZE') option. Each record
2467 will then be composed of 512-SIZE blocks. (Each 'tar' block is 512
2468 bytes. *Note Standard::.) Each file written to the archive uses at
2469 least one full record. As a result, using a larger record size can
2470 result in more wasted space for small files. On the other hand, a
2471 larger record size can often be read and written much more efficiently.
2473 Further complicating the problem is that some tape drives ignore the
2474 blocking entirely. For these, a larger record size can still improve
2475 performance (because the software layers above the tape drive still
2476 honor the blocking), but not as dramatically as on tape drives that
2479 When reading an archive, 'tar' can usually figure out the record size
2480 on itself. When this is the case, and a non-standard record size was
2481 used when the archive was created, 'tar' will print a message about a
2482 non-standard blocking factor, and then operate normally(1). On some
2483 tape devices, however, 'tar' cannot figure out the record size itself.
2484 On most of those, you can specify a blocking factor (with
2485 '--blocking-factor') larger than the actual blocking factor, and then
2486 use the '--read-full-records' ('-B') option. (If you specify a blocking
2487 factor with '--blocking-factor' and don't use the '--read-full-records'
2488 option, then 'tar' will not attempt to figure out the recording size
2489 itself.) On some devices, you must always specify the record size
2490 exactly with '--blocking-factor' when reading, because 'tar' cannot
2491 figure it out. In any case, use '--list' ('-t') before doing any
2492 extractions to see whether 'tar' is reading the archive correctly.
2494 'tar' blocks are all fixed size (512 bytes), and its scheme for
2495 putting them into records is to put a whole number of them (one or more)
2496 into each record. 'tar' records are all the same size; at the end of
2497 the file there's a block containing all zeros, which is how you tell
2498 that the remainder of the last record(s) are garbage.
2500 In a standard 'tar' file (no options), the block size is 512 and the
2501 record size is 10240, for a blocking factor of 20. What the
2502 '--blocking-factor' option does is sets the blocking factor, changing
2503 the record size while leaving the block size at 512 bytes. 20 was fine
2504 for ancient 800 or 1600 bpi reel-to-reel tape drives; most tape drives
2505 these days prefer much bigger records in order to stream and not waste
2506 tape. When writing tapes for myself, some tend to use a factor of the
2507 order of 2048, say, giving a record size of around one megabyte.
2509 If you use a blocking factor larger than 20, older 'tar' programs
2510 might not be able to read the archive, so we recommend this as a limit
2511 to use in practice. GNU 'tar', however, will support arbitrarily large
2512 record sizes, limited only by the amount of virtual memory or the
2513 physical characteristics of the tape device.
2517 * Format Variations:: Format Variations
2518 * Blocking Factor:: The Blocking Factor of an Archive
2520 ---------- Footnotes ----------
2522 (1) If this message is not needed, you can turn it off using the
2523 '--warning=no-record-size' option.
2526 File: tar.info, Node: Format Variations, Next: Blocking Factor, Up: Blocking
2528 9.4.1 Format Variations
2529 -----------------------
2531 _(This message will disappear, once this node revised.)_
2533 Format parameters specify how an archive is written on the archive
2534 media. The best choice of format parameters will vary depending on the
2535 type and number of files being archived, and on the media used to store
2538 To specify format parameters when accessing or creating an archive,
2539 you can use the options described in the following sections. If you do
2540 not specify any format parameters, 'tar' uses default parameters. You
2541 cannot modify a compressed archive. If you create an archive with the
2542 '--blocking-factor' option specified (*note Blocking Factor::), you must
2543 specify that blocking-factor when operating on the archive. *Note
2544 Formats::, for other examples of format parameter considerations.
2547 File: tar.info, Node: Blocking Factor, Prev: Format Variations, Up: Blocking
2549 9.4.2 The Blocking Factor of an Archive
2550 ---------------------------------------
2552 _(This message will disappear, once this node revised.)_
2554 The data in an archive is grouped into blocks, which are 512 bytes.
2555 Blocks are read and written in whole number multiples called "records".
2556 The number of blocks in a record (i.e., the size of a record in units of
2557 512 bytes) is called the "blocking factor". The
2558 '--blocking-factor=512-SIZE' ('-b 512-SIZE') option specifies the
2559 blocking factor of an archive. The default blocking factor is typically
2560 20 (i.e., 10240 bytes), but can be specified at installation. To find
2561 out the blocking factor of an existing archive, use 'tar --list
2562 --file=ARCHIVE-NAME'. This may not work on some devices.
2564 Records are separated by gaps, which waste space on the archive
2565 media. If you are archiving on magnetic tape, using a larger blocking
2566 factor (and therefore larger records) provides faster throughput and
2567 allows you to fit more data on a tape (because there are fewer gaps).
2568 If you are archiving on cartridge, a very large blocking factor (say 126
2569 or more) greatly increases performance. A smaller blocking factor, on
2570 the other hand, may be useful when archiving small files, to avoid
2571 archiving lots of nulls as 'tar' fills out the archive to the end of the
2572 record. In general, the ideal record size depends on the size of the
2573 inter-record gaps on the tape you are using, and the average size of the
2574 files you are archiving. *Note create::, for information on writing
2577 Archives with blocking factors larger than 20 cannot be read by very
2578 old versions of 'tar', or by some newer versions of 'tar' running on old
2579 machines with small address spaces. With GNU 'tar', the blocking factor
2580 of an archive is limited only by the maximum record size of the device
2581 containing the archive, or by the amount of available virtual memory.
2583 Also, on some systems, not using adequate blocking factors, as
2584 sometimes imposed by the device drivers, may yield unexpected
2585 diagnostics. For example, this has been reported:
2587 Cannot write to /dev/dlt: Invalid argument
2589 In such cases, it sometimes happen that the 'tar' bundled by the system
2590 is aware of block size idiosyncrasies, while GNU 'tar' requires an
2591 explicit specification for the block size, which it cannot guess. This
2592 yields some people to consider GNU 'tar' is misbehaving, because by
2593 comparison, 'the bundle 'tar' works OK'. Adding '-b 256', for example,
2594 might resolve the problem.
2596 If you use a non-default blocking factor when you create an archive,
2597 you must specify the same blocking factor when you modify that archive.
2598 Some archive devices will also require you to specify the blocking
2599 factor when reading that archive, however this is not typically the
2600 case. Usually, you can use '--list' ('-t') without specifying a
2601 blocking factor--'tar' reports a non-default record size and then lists
2602 the archive members as it would normally. To extract files from an
2603 archive with a non-standard blocking factor (particularly if you're not
2604 sure what the blocking factor is), you can usually use the
2605 '--read-full-records' ('-B') option while specifying a blocking factor
2606 larger then the blocking factor of the archive (i.e., 'tar --extract
2607 --read-full-records --blocking-factor=300'). *Note list::, for more
2608 information on the '--list' ('-t') operation. *Note Reading::, for a
2609 more detailed explanation of that option.
2611 '--blocking-factor=NUMBER'
2613 Specifies the blocking factor of an archive. Can be used with any
2614 operation, but is usually not necessary with '--list' ('-t').
2619 '--blocking-factor=BLOCKS'
2620 Set record size to BLOCKS*512 bytes.
2622 This option is used to specify a "blocking factor" for the archive.
2623 When reading or writing the archive, 'tar', will do reads and
2624 writes of the archive in records of BLOCK*512 bytes. This is true
2625 even when the archive is compressed. Some devices requires that
2626 all write operations be a multiple of a certain size, and so, 'tar'
2627 pads the archive out to the next record boundary.
2629 The default blocking factor is set when 'tar' is compiled, and is
2630 typically 20. Blocking factors larger than 20 cannot be read by
2631 very old versions of 'tar', or by some newer versions of 'tar'
2632 running on old machines with small address spaces.
2634 With a magnetic tape, larger records give faster throughput and fit
2635 more data on a tape (because there are fewer inter-record gaps).
2636 If the archive is in a disk file or a pipe, you may want to specify
2637 a smaller blocking factor, since a large one will result in a large
2638 number of null bytes at the end of the archive.
2640 When writing cartridge or other streaming tapes, a much larger
2641 blocking factor (say 126 or more) will greatly increase
2642 performance. However, you must specify the same blocking factor
2643 when reading or updating the archive.
2645 Apparently, Exabyte drives have a physical block size of 8K bytes.
2646 If we choose our blocksize as a multiple of 8k bytes, then the
2647 problem seems to disappear. Id est, we are using block size of 112
2648 right now, and we haven't had the problem since we switched...
2650 With GNU 'tar' the blocking factor is limited only by the maximum
2651 record size of the device containing the archive, or by the amount
2652 of available virtual memory.
2654 However, deblocking or reblocking is virtually avoided in a special
2655 case which often occurs in practice, but which requires all the
2656 following conditions to be simultaneously true:
2657 * the archive is subject to a compression option,
2658 * the archive is not handled through standard input or output,
2659 nor redirected nor piped,
2660 * the archive is directly handled to a local disk, instead of
2662 * '--blocking-factor' is not explicitly specified on the 'tar'
2665 If the output goes directly to a local disk, and not through
2666 stdout, then the last write is not extended to a full record size.
2667 Otherwise, reblocking occurs. Here are a few other remarks on this
2670 * 'gzip' will complain about trailing garbage if asked to
2671 uncompress a compressed archive on tape, there is an option to
2672 turn the message off, but it breaks the regularity of simply
2673 having to use 'PROG -d' for decompression. It would be nice
2674 if gzip was silently ignoring any number of trailing zeros.
2675 I'll ask Jean-loup Gailly, by sending a copy of this message
2678 * 'compress' does not show this problem, but as Jean-loup
2679 pointed out to Michael, 'compress -d' silently adds garbage
2680 after the result of decompression, which tar ignores because
2681 it already recognized its end-of-file indicator. So this bug
2682 may be safely ignored.
2684 * 'gzip -d -q' will be silent about the trailing zeros indeed,
2685 but will still return an exit status of 2 which tar reports in
2686 turn. 'tar' might ignore the exit status returned, but I hate
2687 doing that, as it weakens the protection 'tar' offers users
2688 against other possible problems at decompression time. If
2689 'gzip' was silently skipping trailing zeros _and_ also
2690 avoiding setting the exit status in this innocuous case, that
2691 would solve this situation.
2693 * 'tar' should become more solid at not stopping to read a pipe
2694 at the first null block encountered. This inelegantly breaks
2695 the pipe. 'tar' should rather drain the pipe out before
2700 Ignore blocks of zeros in archive (means EOF).
2702 The '--ignore-zeros' ('-i') option causes 'tar' to ignore blocks of
2703 zeros in the archive. Normally a block of zeros indicates the end
2704 of the archive, but when reading a damaged archive, or one which
2705 was created by concatenating several archives together, this option
2706 allows 'tar' to read the entire archive. This option is not on by
2707 default because many versions of 'tar' write garbage after the
2710 Note that this option causes 'tar' to read to the end of the
2711 archive file, which may sometimes avoid problems when multiple
2712 files are stored on a single physical tape.
2715 '--read-full-records'
2716 Reblock as we read (for reading 4.2BSD pipes).
2718 If '--read-full-records' is used, 'tar' will not panic if an
2719 attempt to read a record from the archive does not return a full
2720 record. Instead, 'tar' will keep reading until it has obtained a
2723 This option is turned on by default when 'tar' is reading an
2724 archive from standard input, or from a remote machine. This is
2725 because on BSD Unix systems, a read of a pipe will return however
2726 much happens to be in the pipe, even if it is less than 'tar'
2727 requested. If this option was not used, 'tar' would fail as soon
2728 as it read an incomplete record from the pipe.
2730 This option is also useful with the commands for updating an
2735 When handling various tapes or cartridges, you have to take care of
2736 selecting a proper blocking, that is, the number of disk blocks you put
2737 together as a single tape block on the tape, without intervening tape
2738 gaps. A "tape gap" is a small landing area on the tape with no
2739 information on it, used for decelerating the tape to a full stop, and
2740 for later regaining the reading or writing speed. When the tape driver
2741 starts reading a record, the record has to be read whole without
2742 stopping, as a tape gap is needed to stop the tape motion without losing
2745 Using higher blocking (putting more disk blocks per tape block) will
2746 use the tape more efficiently as there will be less tape gaps. But
2747 reading such tapes may be more difficult for the system, as more memory
2748 will be required to receive at once the whole record. Further, if there
2749 is a reading error on a huge record, this is less likely that the system
2750 will succeed in recovering the information. So, blocking should not be
2751 too low, nor it should be too high. 'tar' uses by default a blocking of
2752 20 for historical reasons, and it does not really matter when reading or
2753 writing to disk. Current tape technology would easily accommodate
2754 higher blockings. Sun recommends a blocking of 126 for Exabytes and 96
2755 for DATs. We were told that for some DLT drives, the blocking should be
2756 a multiple of 4Kb, preferably 64Kb ('-b 128') or 256 for decent
2757 performance. Other manufacturers may use different recommendations for
2758 the same tapes. This might also depends of the buffering techniques
2759 used inside modern tape controllers. Some imposes a minimum blocking,
2760 or a maximum blocking. Others request blocking to be some exponent of
2763 So, there is no fixed rule for blocking. But blocking at read time
2764 should ideally be the same as blocking used at write time. At one place
2765 I know, with a wide variety of equipment, they found it best to use a
2766 blocking of 32 to guarantee that their tapes are fully interchangeable.
2768 I was also told that, for recycled tapes, prior erasure (by the same
2769 drive unit that will be used to create the archives) sometimes lowers
2770 the error rates observed at rewriting time.
2772 I might also use '--number-blocks' instead of '--block-number', so
2773 '--block' will then expand to '--blocking-factor' unambiguously.
2776 File: tar.info, Node: Many, Next: Using Multiple Tapes, Prev: Blocking, Up: Media
2778 9.5 Many Archives on One Tape
2779 =============================
2781 Most tape devices have two entries in the '/dev' directory, or entries
2782 that come in pairs, which differ only in the minor number for this
2783 device. Let's take for example '/dev/tape', which often points to the
2784 only or usual tape device of a given system. There might be a
2785 corresponding '/dev/nrtape' or '/dev/ntape'. The simpler name is the
2786 _rewinding_ version of the device, while the name having 'nr' in it is
2787 the _no rewinding_ version of the same device.
2789 A rewinding tape device will bring back the tape to its beginning
2790 point automatically when this device is opened or closed. Since 'tar'
2791 opens the archive file before using it and closes it afterwards, this
2792 means that a simple:
2794 $ tar cf /dev/tape DIRECTORY
2796 will reposition the tape to its beginning both prior and after saving
2797 DIRECTORY contents to it, thus erasing prior tape contents and making it
2798 so that any subsequent write operation will destroy what has just been
2801 So, a rewinding device is normally meant to hold one and only one
2802 file. If you want to put more than one 'tar' archive on a given tape,
2803 you will need to avoid using the rewinding version of the tape device.
2804 You will also have to pay special attention to tape positioning. Errors
2805 in positioning may overwrite the valuable data already on your tape.
2806 Many people, burnt by past experiences, will only use rewinding devices
2807 and limit themselves to one file per tape, precisely to avoid the risk
2808 of such errors. Be fully aware that writing at the wrong position on a
2809 tape loses all information past this point and most probably until the
2810 end of the tape, and this destroyed information _cannot_ be recovered.
2812 To save DIRECTORY-1 as a first archive at the beginning of a tape,
2813 and leave that tape ready for a second archive, you should use:
2815 $ mt -f /dev/nrtape rewind
2816 $ tar cf /dev/nrtape DIRECTORY-1
2818 "Tape marks" are special magnetic patterns written on the tape media,
2819 which are later recognizable by the reading hardware. These marks are
2820 used after each file, when there are many on a single tape. An empty
2821 file (that is to say, two tape marks in a row) signal the logical end of
2822 the tape, after which no file exist. Usually, non-rewinding tape device
2823 drivers will react to the close request issued by 'tar' by first writing
2824 two tape marks after your archive, and by backspacing over one of these.
2825 So, if you remove the tape at that time from the tape drive, it is
2826 properly terminated. But if you write another file at the current
2827 position, the second tape mark will be erased by the new information,
2828 leaving only one tape mark between files.
2830 So, you may now save DIRECTORY-2 as a second archive after the first
2831 on the same tape by issuing the command:
2833 $ tar cf /dev/nrtape DIRECTORY-2
2835 and so on for all the archives you want to put on the same tape.
2837 Another usual case is that you do not write all the archives the same
2838 day, and you need to remove and store the tape between two archive
2839 sessions. In general, you must remember how many files are already
2840 saved on your tape. Suppose your tape already has 16 files on it, and
2841 that you are ready to write the 17th. You have to take care of skipping
2842 the first 16 tape marks before saving DIRECTORY-17, say, by using these
2845 $ mt -f /dev/nrtape rewind
2846 $ mt -f /dev/nrtape fsf 16
2847 $ tar cf /dev/nrtape DIRECTORY-17
2849 In all the previous examples, we put aside blocking considerations,
2850 but you should do the proper things for that as well. *Note Blocking::.
2854 * Tape Positioning:: Tape Positions and Tape Marks
2855 * mt:: The 'mt' Utility
2858 File: tar.info, Node: Tape Positioning, Next: mt, Up: Many
2860 9.5.1 Tape Positions and Tape Marks
2861 -----------------------------------
2863 _(This message will disappear, once this node revised.)_
2865 Just as archives can store more than one file from the file system,
2866 tapes can store more than one archive file. To keep track of where
2867 archive files (or any other type of file stored on tape) begin and end,
2868 tape archive devices write magnetic "tape marks" on the archive media.
2869 Tape drives write one tape mark between files, two at the end of all the
2872 If you think of data as a series of records "rrrr"'s, and tape marks
2873 as "*"'s, a tape might look like the following:
2875 rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
2877 Tape devices read and write tapes using a read/write "tape head"--a
2878 physical part of the device which can only access one point on the tape
2879 at a time. When you use 'tar' to read or write archive data from a tape
2880 device, the device will begin reading or writing from wherever on the
2881 tape the tape head happens to be, regardless of which archive or what
2882 part of the archive the tape head is on. Before writing an archive, you
2883 should make sure that no data on the tape will be overwritten (unless it
2884 is no longer needed). Before reading an archive, you should make sure
2885 the tape head is at the beginning of the archive you want to read. You
2886 can do it manually via 'mt' utility (*note mt::). The 'restore' script
2887 does that automatically (*note Scripted Restoration::).
2889 If you want to add new archive file entries to a tape, you should
2890 advance the tape to the end of the existing file entries, backspace over
2891 the last tape mark, and write the new archive file. If you were to add
2892 two archives to the example above, the tape might look like the
2895 rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
2898 File: tar.info, Node: mt, Prev: Tape Positioning, Up: Many
2900 9.5.2 The 'mt' Utility
2901 ----------------------
2903 _(This message will disappear, once this node revised.)_
2905 *Note Blocking Factor::.
2907 You can use the 'mt' utility to advance or rewind a tape past a
2908 specified number of archive files on the tape. This will allow you to
2909 move to the beginning of an archive before extracting or reading it, or
2910 to the end of all the archives before writing a new one.
2912 The syntax of the 'mt' command is:
2914 mt [-f TAPENAME] OPERATION [NUMBER]
2916 where TAPENAME is the name of the tape device, NUMBER is the number
2917 of times an operation is performed (with a default of one), and
2918 OPERATION is one of the following:
2922 Writes NUMBER tape marks at the current position on the tape.
2925 Moves tape position forward NUMBER files.
2928 Moves tape position back NUMBER files.
2931 Rewinds the tape. (Ignores NUMBER.)
2935 Rewinds the tape and takes the tape device off-line. (Ignores
2939 Prints status information about the tape unit.
2941 If you don't specify a TAPENAME, 'mt' uses the environment variable
2942 'TAPE'; if 'TAPE' is not set, 'mt' will use the default device specified
2943 in your 'sys/mtio.h' file ('DEFTAPE' variable). If this is not defined,
2944 the program will display a descriptive error message and exit with code
2947 'mt' returns a 0 exit status when the operation(s) were successful, 1
2948 if the command was unrecognized, and 2 if an operation failed.
2951 File: tar.info, Node: Using Multiple Tapes, Next: label, Prev: Many, Up: Media
2953 9.6 Using Multiple Tapes
2954 ========================
2956 Often you might want to write a large archive, one larger than will fit
2957 on the actual tape you are using. In such a case, you can run multiple
2958 'tar' commands, but this can be inconvenient, particularly if you are
2959 using options like '--exclude=PATTERN' or dumping entire file systems.
2960 Therefore, 'tar' provides a special mode for creating multi-volume
2963 "Multi-volume" archive is a single 'tar' archive, stored on several
2964 media volumes of fixed size. Although in this section we will often
2965 call 'volume' a "tape", there is absolutely no requirement for
2966 multi-volume archives to be stored on tapes. Instead, they can use
2967 whatever media type the user finds convenient, they can even be located
2970 When creating a multi-volume archive, GNU 'tar' continues to fill
2971 current volume until it runs out of space, then it switches to next
2972 volume (usually the operator is queried to replace the tape on this
2973 point), and continues working on the new volume. This operation
2974 continues until all requested files are dumped. If GNU 'tar' detects
2975 end of media while dumping a file, such a file is archived in split
2976 form. Some very big files can even be split across several volumes.
2978 Each volume is itself a valid GNU 'tar' archive, so it can be read
2979 without any special options. Consequently any file member residing
2980 entirely on one volume can be extracted or otherwise operated upon
2981 without needing the other volume. Sure enough, to extract a split
2982 member you would need all volumes its parts reside on.
2984 Multi-volume archives suffer from several limitations. In
2985 particular, they cannot be compressed.
2987 GNU 'tar' is able to create multi-volume archives of two formats
2988 (*note Formats::): 'GNU' and 'POSIX'.
2992 * Multi-Volume Archives:: Archives Longer than One Tape or Disk
2993 * Tape Files:: Tape Files
2994 * Tarcat:: Concatenate Volumes into a Single Archive
2997 File: tar.info, Node: Multi-Volume Archives, Next: Tape Files, Up: Using Multiple Tapes
2999 9.6.1 Archives Longer than One Tape or Disk
3000 -------------------------------------------
3002 To create an archive that is larger than will fit on a single unit of
3003 the media, use the '--multi-volume' ('-M') option in conjunction with
3004 the '--create' option (*note create::). A "multi-volume" archive can be
3005 manipulated like any other archive (provided the '--multi-volume' option
3006 is specified), but is stored on more than one tape or file.
3008 When you specify '--multi-volume', 'tar' does not report an error
3009 when it comes to the end of an archive volume (when reading), or the end
3010 of the media (when writing). Instead, it prompts you to load a new
3011 storage volume. If the archive is on a magnetic tape, you should change
3012 tapes when you see the prompt; if the archive is on a floppy disk, you
3013 should change disks; etc.
3017 Creates a multi-volume archive, when used in conjunction with
3018 '--create' ('-c'). To perform any other operation on a
3019 multi-volume archive, specify '--multi-volume' in conjunction with
3020 that operation. For example:
3022 $ tar --create --multi-volume --file=/dev/tape FILES
3024 The method 'tar' uses to detect end of tape is not perfect, and fails
3025 on some operating systems or on some devices. If 'tar' cannot detect
3026 the end of the tape itself, you can use '--tape-length' option to inform
3027 it about the capacity of the tape:
3029 '--tape-length=SIZE[SUF]'
3031 Set maximum length of a volume. The SUF, if given, specifies units
3032 in which SIZE is expressed, e.g. '2M' mean 2 megabytes (*note
3033 Table 9.1: size-suffixes, for a list of allowed size suffixes).
3034 Without SUF, units of 1024 bytes (kilobyte) are assumed.
3036 This option selects '--multi-volume' automatically. For example:
3038 $ tar --create --tape-length=41943040 --file=/dev/tape FILES
3040 or, which is equivalent:
3042 $ tar --create --tape-length=4G --file=/dev/tape FILES
3044 When GNU 'tar' comes to the end of a storage media, it asks you to
3045 change the volume. The built-in prompt for POSIX locale is(1):
3047 Prepare volume #N for 'ARCHIVE' and hit return:
3049 where N is the ordinal number of the volume to be created and ARCHIVE is
3050 archive file or device name.
3052 When prompting for a new tape, 'tar' accepts any of the following
3056 Request 'tar' to explain possible responses.
3058 Request 'tar' to exit immediately.
3060 Request 'tar' to write the next volume on the file FILE-NAME.
3062 Request 'tar' to run a subshell. This option can be disabled by
3063 giving '--restrict' command line option to 'tar'(2).
3065 Request 'tar' to begin writing the next volume.
3067 (You should only type 'y' after you have changed the tape; otherwise
3068 'tar' will write over the volume it just finished.)
3070 The volume number used by 'tar' in its tape-changing prompt can be
3071 changed; if you give the '--volno-file=FILE-OF-NUMBER' option, then
3072 FILE-OF-NUMBER should be an non-existing file to be created, or else, a
3073 file already containing a decimal number. That number will be used as
3074 the volume number of the first volume written. When 'tar' is finished,
3075 it will rewrite the file with the now-current volume number. (This does
3076 not change the volume number written on a tape label, as per *note
3077 label::, it _only_ affects the number used in the prompt.)
3079 If you want more elaborate behavior than this, you can write a
3080 special "new volume script", that will be responsible for changing the
3081 volume, and instruct 'tar' to use it instead of its normal prompting
3084 '--info-script=COMMAND'
3085 '--new-volume-script=COMMAND'
3087 Specify the command to invoke when switching volumes. The COMMAND
3088 can be used to eject cassettes, or to broadcast messages such as
3089 'Someone please come change my tape' when performing unattended
3092 The COMMAND can contain additional options, if such are needed.
3093 *Note Running External Commands: external, for a detailed discussion of
3094 the way GNU 'tar' runs external commands. It inherits 'tar''s shell
3095 environment. Additional data is passed to it via the following
3096 environment variables:
3099 GNU 'tar' version number.
3102 The name of the archive 'tar' is processing.
3104 'TAR_BLOCKING_FACTOR'
3105 Current blocking factor (*note Blocking::).
3108 Ordinal number of the volume 'tar' is about to start.
3111 A short option describing the operation 'tar' is executing. *Note
3112 Operations::, for a complete list of subcommand options.
3115 Format of the archive being processed. *Note Formats::, for a
3116 complete list of archive format names.
3119 File descriptor which can be used to communicate the new volume
3122 These variables can be used in the COMMAND itself, provided that they
3123 are properly quoted to prevent them from being expanded by the shell
3126 The volume script can instruct 'tar' to use new archive name, by
3127 writing in to file descriptor '$TAR_FD' (see below for an example).
3129 If the info script fails, 'tar' exits; otherwise, it begins writing
3132 If you want 'tar' to cycle through a series of files or tape drives,
3133 there are three approaches to choose from. First of all, you can give
3134 'tar' multiple '--file' options. In this case the specified files will
3135 be used, in sequence, as the successive volumes of the archive. Only
3136 when the first one in the sequence needs to be used again will 'tar'
3137 prompt for a tape change (or run the info script). For example, suppose
3138 someone has two tape drives on a system named '/dev/tape0' and
3139 '/dev/tape1'. For having GNU 'tar' to switch to the second drive when
3140 it needs to write the second tape, and then back to the first tape,
3141 etc., just do either of:
3143 $ tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 FILES
3144 $ tar -cM -f /dev/tape0 -f /dev/tape1 FILES
3146 The second method is to use the 'n' response to the tape-change
3149 Finally, the most flexible approach is to use a volume script, that
3150 writes new archive name to the file descriptor '$TAR_FD'. For example,
3151 the following volume script will create a series of archive files, named
3152 'ARCHIVE-VOL', where ARCHIVE is the name of the archive being created
3153 (as given by '--file' option) and VOL is the ordinal number of the
3154 archive being created:
3157 # For this script it's advisable to use a shell, such as Bash,
3158 # that supports a TAR_FD value greater than 9.
3160 echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
3162 name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
3163 case $TAR_SUBCOMMAND in
3165 -d|-x|-t) test -r ${name:-$TAR_ARCHIVE}-$TAR_VOLUME || exit 1
3170 echo ${name:-$TAR_ARCHIVE}-$TAR_VOLUME >&$TAR_FD
3172 The same script can be used while listing, comparing or extracting
3173 from the created archive. For example:
3175 # Create a multi-volume archive:
3176 $ tar -c -L1024 -f archive.tar -F new-volume .
3177 # Extract from the created archive:
3178 $ tar -x -f archive.tar -F new-volume .
3180 Notice, that the first command had to use '-L' option, since otherwise
3181 GNU 'tar' will end up writing everything to file 'archive.tar'.
3183 You can read each individual volume of a multi-volume archive as if
3184 it were an archive by itself. For example, to list the contents of one
3185 volume, use '--list', without '--multi-volume' specified. To extract an
3186 archive member from one volume (assuming it is described that volume),
3187 use '--extract', again without '--multi-volume'.
3189 If an archive member is split across volumes (i.e., its entry begins
3190 on one volume of the media and ends on another), you need to specify
3191 '--multi-volume' to extract it successfully. In this case, you should
3192 load the volume where the archive member starts, and use 'tar --extract
3193 --multi-volume'--'tar' will prompt for later volumes as it needs them.
3194 *Note extracting archives::, for more information about extracting
3197 Multi-volume archives can be modified like any other archive. To add
3198 files to a multi-volume archive, you need to only mount the last volume
3199 of the archive media (and new volumes, if needed). For all other
3200 operations, you need to use the entire archive.
3202 If a multi-volume archive was labeled using '--label=ARCHIVE-LABEL'
3203 (*note label::) when it was created, 'tar' will not automatically label
3204 volumes which are added later. To label subsequent volumes, specify
3205 '--label=ARCHIVE-LABEL' again in conjunction with the '--append',
3206 '--update' or '--concatenate' operation.
3208 Notice that multi-volume support is a GNU extension and the archives
3209 created in this mode should be read only using GNU 'tar'. If you
3210 absolutely have to process such archives using a third-party 'tar'
3211 implementation, read *note Split Recovery::.
3213 ---------- Footnotes ----------
3215 (1) If you run GNU 'tar' under a different locale, the translation to
3216 the locale's language will be used.
3218 (2) *Note --restrict::, for more information about this option.
3221 File: tar.info, Node: Tape Files, Next: Tarcat, Prev: Multi-Volume Archives, Up: Using Multiple Tapes
3226 _(This message will disappear, once this node revised.)_
3228 To give the archive a name which will be recorded in it, use the
3229 '--label=VOLUME-LABEL' ('-V VOLUME-LABEL') option. This will write a
3230 special block identifying VOLUME-LABEL as the name of the archive to the
3231 front of the archive which will be displayed when the archive is listed
3232 with '--list'. If you are creating a multi-volume archive with
3233 '--multi-volume' (*note Using Multiple Tapes::), then the volume label
3234 will have 'Volume NNN' appended to the name you give, where NNN is the
3235 number of the volume of the archive. If you use the
3236 '--label=VOLUME-LABEL' option when reading an archive, it checks to make
3237 sure the label on the tape matches the one you gave. *Note label::.
3239 When 'tar' writes an archive to tape, it creates a single tape file.
3240 If multiple archives are written to the same tape, one after the other,
3241 they each get written as separate tape files. When extracting, it is
3242 necessary to position the tape at the right place before running 'tar'.
3243 To do this, use the 'mt' command. For more information on the 'mt'
3244 command and on the organization of tapes into a sequence of tape files,
3247 People seem to often do:
3249 --label="SOME-PREFIX `date +SOME-FORMAT`"
3251 or such, for pushing a common date in all volumes or an archive set.
3254 File: tar.info, Node: Tarcat, Prev: Tape Files, Up: Using Multiple Tapes
3256 9.6.3 Concatenate Volumes into a Single Archive
3257 -----------------------------------------------
3259 Sometimes it is necessary to convert existing GNU 'tar' multi-volume
3260 archive to a single 'tar' archive. Simply concatenating all volumes
3261 into one will not work, since each volume carries an additional
3262 information at the beginning. GNU 'tar' is shipped with the shell
3263 script 'tarcat' designed for this purpose.
3265 The script takes a list of files comprising a multi-volume archive
3266 and creates the resulting archive at the standard output. For example:
3268 tarcat vol.1 vol.2 vol.3 | tar tf -
3270 The script implements a simple heuristics to determine the format of
3271 the first volume file and to decide how to process the rest of the
3272 files. However, it makes no attempt to verify whether the files are
3273 given in order or even if they are valid 'tar' archives. It uses 'dd'
3274 and does not filter its standard error, so you will usually see lots of
3278 File: tar.info, Node: label, Next: verify, Prev: Using Multiple Tapes, Up: Media
3280 9.7 Including a Label in the Archive
3281 ====================================
3283 To avoid problems caused by misplaced paper labels on the archive media,
3284 you can include a "label" entry -- an archive member which contains the
3285 name of the archive -- in the archive itself. Use the
3286 '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') option(1) in conjunction
3287 with the '--create' operation to include a label entry in the archive as
3288 it is being created.
3290 '--label=ARCHIVE-LABEL'
3292 Includes an "archive-label" at the beginning of the archive when
3293 the archive is being created, when used in conjunction with the
3294 '--create' operation. Checks to make sure the archive label
3295 matches the one specified (when used in conjunction with any other
3298 If you create an archive using both '--label=ARCHIVE-LABEL' ('-V
3299 ARCHIVE-LABEL') and '--multi-volume' ('-M'), each volume of the archive
3300 will have an archive label of the form 'ARCHIVE-LABEL Volume N', where N
3301 is 1 for the first volume, 2 for the next, and so on. *Note Using
3302 Multiple Tapes::, for information on creating multiple volume archives.
3304 The volume label will be displayed by '--list' along with the file
3305 contents. If verbose display is requested, it will also be explicitly
3306 marked as in the example below:
3308 $ tar --verbose --list --file=iamanarchive
3309 V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header--
3310 -rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename
3312 However, '--list' option will cause listing entire contents of the
3313 archive, which may be undesirable (for example, if the archive is stored
3314 on a tape). You can request checking only the volume label by
3315 specifying '--test-label' option. This option reads only the first
3316 block of an archive, so it can be used with slow storage devices. For
3319 $ tar --test-label --file=iamanarchive
3322 If '--test-label' is used with one or more command line arguments,
3323 'tar' compares the volume label with each argument. It exits with code
3324 0 if a match is found, and with code 1 otherwise(2). No output is
3325 displayed, unless you also used the '--verbose' option. For example:
3327 $ tar --test-label --file=iamanarchive 'iamalabel'
3329 $ tar --test-label --file=iamanarchive 'alabel'
3332 When used with the '--verbose' option, 'tar' prints the actual volume
3333 label (if any), and a verbose diagnostics in case of a mismatch:
3335 $ tar --test-label --verbose --file=iamanarchive 'iamalabel'
3338 $ tar --test-label --verbose --file=iamanarchive 'alabel'
3340 tar: Archive label mismatch
3343 If you request any operation, other than '--create', along with using
3344 '--label' option, 'tar' will first check if the archive label matches
3345 the one specified and will refuse to proceed if it does not. Use this
3346 as a safety precaution to avoid accidentally overwriting existing
3347 archives. For example, if you wish to add files to 'archive',
3348 presumably labeled with string 'My volume', you will get:
3350 $ tar -rf archive --label 'My volume' .
3351 tar: Archive not labeled to match 'My volume'
3353 in case its label does not match. This will work even if 'archive' is
3356 Similarly, 'tar' will refuse to list or extract the archive if its
3357 label doesn't match the ARCHIVE-LABEL specified. In those cases,
3358 ARCHIVE-LABEL argument is interpreted as a globbing-style pattern which
3359 must match the actual magnetic volume label. *Note exclude::, for a
3360 precise description of how match is attempted(3). If the switch
3361 '--multi-volume' ('-M') is being used, the volume label matcher will
3362 also suffix ARCHIVE-LABEL by ' Volume [1-9]*' if the initial match
3363 fails, before giving up. Since the volume numbering is automatically
3364 added in labels at creation time, it sounded logical to equally help the
3365 user taking care of it when the archive is being read.
3367 You can also use '--label' to get a common information on all tapes
3368 of a series. For having this information different in each series
3369 created through a single script used on a regular basis, just manage to
3370 get some date string as part of the label. For example:
3372 $ tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"
3373 $ tar --create --file=/dev/tape --multi-volume \
3374 --label="Daily backup for `date +%Y-%m-%d`"
3376 Some more notes about volume labels:
3378 * Each label has its own date and time, which corresponds to the time
3379 when GNU 'tar' initially attempted to write it, often soon after
3380 the operator launches 'tar' or types the carriage return telling
3381 that the next tape is ready.
3383 * Comparing date labels to get an idea of tape throughput is
3384 unreliable. It gives correct results only if the delays for
3385 rewinding tapes and the operator switching them were negligible,
3386 which is usually not the case.
3388 ---------- Footnotes ----------
3390 (1) Until version 1.10, that option was called '--volume', but is not
3391 available under that name anymore.
3393 (2) Note that GNU 'tar' versions up to 1.23 indicated mismatch with
3394 an exit code 2 and printed a spurious diagnostics on stderr.
3396 (3) Previous versions of 'tar' used full regular expression matching,
3397 or before that, only exact string matching, instead of wildcard
3398 matchers. We decided for the sake of simplicity to use a uniform
3399 matching device through 'tar'.
3402 File: tar.info, Node: verify, Next: Write Protection, Prev: label, Up: Media
3404 9.8 Verifying Data as It is Stored
3405 ==================================
3409 Attempt to verify the archive after writing.
3411 This option causes 'tar' to verify the archive after writing it.
3412 Each volume is checked after it is written, and any discrepancies are
3413 recorded on the standard error output.
3415 Verification requires that the archive be on a back-space-able
3416 medium. This means pipes, some cartridge tape drives, and some other
3417 devices cannot be verified.
3419 You can insure the accuracy of an archive by comparing files in the
3420 system with archive members. 'tar' can compare an archive to the file
3421 system as the archive is being written, to verify a write operation, or
3422 can compare a previously written archive, to insure that it is up to
3425 To check for discrepancies in an archive immediately after it is
3426 written, use the '--verify' ('-W') option in conjunction with the
3427 '--create' operation. When this option is specified, 'tar' checks
3428 archive members against their counterparts in the file system, and
3429 reports discrepancies on the standard error.
3431 To verify an archive, you must be able to read it from before the end
3432 of the last written entry. This option is useful for detecting data
3433 errors on some tapes. Archives written to pipes, some cartridge tape
3434 drives, and some other devices cannot be verified.
3436 One can explicitly compare an already made archive with the file
3437 system by using the '--compare' ('--diff', '-d') option, instead of
3438 using the more automatic '--verify' option. *Note compare::.
3440 Note that these two options have a slightly different intent. The
3441 '--compare' option checks how identical are the logical contents of some
3442 archive with what is on your disks, while the '--verify' option is
3443 really for checking if the physical contents agree and if the recording
3444 media itself is of dependable quality. So, for the '--verify'
3445 operation, 'tar' tries to defeat all in-memory cache pertaining to the
3446 archive, while it lets the speed optimization undisturbed for the
3447 '--compare' option. If you nevertheless use '--compare' for media
3448 verification, you may have to defeat the in-memory cache yourself, maybe
3449 by opening and reclosing the door latch of your recording unit, forcing
3450 some doubt in your operating system about the fact this is really the
3451 same volume as the one just written or read.
3453 The '--verify' option would not be necessary if drivers were indeed
3454 able to detect dependably all write failures. This sometimes require
3455 many magnetic heads, some able to read after the writes occurred. One
3456 would not say that drivers unable to detect all cases are necessarily
3457 flawed, as long as programming is concerned.
3459 The '--verify' ('-W') option will not work in conjunction with the
3460 '--multi-volume' ('-M') option or the '--append' ('-r'), '--update'
3461 ('-u') and '--delete' operations. *Note Operations::, for more
3462 information on these operations.
3464 Also, since 'tar' normally strips leading '/' from file names (*note
3465 absolute::), a command like 'tar --verify -cf /tmp/foo.tar /etc' will
3466 work as desired only if the working directory is '/', as 'tar' uses the
3467 archive's relative member names (e.g., 'etc/motd') when verifying the
3471 File: tar.info, Node: Write Protection, Prev: verify, Up: Media
3473 9.9 Write Protection
3474 ====================
3476 Almost all tapes and diskettes, and in a few rare cases, even disks can
3477 be "write protected", to protect data on them from being changed. Once
3478 an archive is written, you should write protect the media to prevent the
3479 archive from being accidentally overwritten or deleted. (This will
3480 protect the archive from being changed with a tape or floppy drive--it
3481 will not protect it from magnet fields or other physical hazards.)
3483 The write protection device itself is usually an integral part of the
3484 physical media, and can be a two position (write enabled/write disabled)
3485 switch, a notch which can be popped out or covered, a ring which can be
3486 removed from the center of a tape reel, or some other changeable
3490 File: tar.info, Node: Reliability and security, Next: Changes, Prev: Media, Up: Top
3492 10 Reliability and Security
3493 ***************************
3495 The 'tar' command reads and writes files as any other application does,
3496 and is subject to the usual caveats about reliability and security.
3497 This section contains some commonsense advice on the topic.
3505 File: tar.info, Node: Reliability, Next: Security, Up: Reliability and security
3510 Ideally, when 'tar' is creating an archive, it reads from a file system
3511 that is not being modified, and encounters no errors or inconsistencies
3512 while reading and writing. If this is the case, the archive should
3513 faithfully reflect what was read. Similarly, when extracting from an
3514 archive, ideally 'tar' ideally encounters no errors and the extracted
3515 files faithfully reflect what was in the archive.
3517 However, when reading or writing real-world file systems, several
3518 things can go wrong; these include permissions problems, corruption of
3519 data, and race conditions.
3523 * Permissions problems::
3524 * Data corruption and repair::
3528 File: tar.info, Node: Permissions problems, Next: Data corruption and repair, Up: Reliability
3530 10.1.1 Permissions Problems
3531 ---------------------------
3533 If 'tar' encounters errors while reading or writing files, it normally
3534 reports an error and exits with nonzero status. The work it does may
3535 therefore be incomplete. For example, when creating an archive, if
3536 'tar' cannot read a file then it cannot copy the file into the archive.
3539 File: tar.info, Node: Data corruption and repair, Next: Race conditions, Prev: Permissions problems, Up: Reliability
3541 10.1.2 Data Corruption and Repair
3542 ---------------------------------
3544 If an archive becomes corrupted by an I/O error, this may corrupt the
3545 data in an extracted file. Worse, it may corrupt the file's metadata,
3546 which may cause later parts of the archive to become misinterpreted. An
3547 tar-format archive contains a checksum that most likely will detect
3548 errors in the metadata, but it will not detect errors in the data.
3550 If data corruption is a concern, you can compute and check your own
3551 checksums of an archive by using other programs, such as 'cksum'.
3553 When attempting to recover from a read error or data corruption in an
3554 archive, you may need to skip past the questionable data and read the
3555 rest of the archive. This requires some expertise in the archive format
3556 and in other software tools.
3559 File: tar.info, Node: Race conditions, Prev: Data corruption and repair, Up: Reliability
3561 10.1.3 Race conditions
3562 ----------------------
3564 If some other process is modifying the file system while 'tar' is
3565 reading or writing files, the result may well be inconsistent due to
3566 race conditions. For example, if another process creates some files in
3567 a directory while 'tar' is creating an archive containing the
3568 directory's files, 'tar' may see some of the files but not others, or it
3569 may see a file that is in the process of being created. The resulting
3570 archive may not be a snapshot of the file system at any point in time.
3571 If an application such as a database system depends on an accurate
3572 snapshot, restoring from the 'tar' archive of a live file system may
3573 therefore break that consistency and may break the application. The
3574 simplest way to avoid the consistency issues is to avoid making other
3575 changes to the file system while tar is reading it or writing it.
3577 When creating an archive, several options are available to avoid race
3578 conditions. Some hosts have a way of snapshotting a file system, or of
3579 temporarily suspending all changes to a file system, by (say) suspending
3580 the only virtual machine that can modify a file system; if you use these
3581 facilities and have 'tar -c' read from a snapshot when creating an
3582 archive, you can avoid inconsistency problems. More drastically, before
3583 starting 'tar' you could suspend or shut down all processes other than
3584 'tar' that have access to the file system, or you could unmount the file
3585 system and then mount it read-only.
3587 When extracting from an archive, one approach to avoid race
3588 conditions is to create a directory that no other process can write to,
3589 and extract into that.
3592 File: tar.info, Node: Security, Prev: Reliability, Up: Reliability and security
3597 In some cases 'tar' may be used in an adversarial situation, where an
3598 untrusted user is attempting to gain information about or modify
3599 otherwise-inaccessible files. Dealing with untrusted data (that is,
3600 data generated by an untrusted user) typically requires extra care,
3601 because even the smallest mistake in the use of 'tar' is more likely to
3602 be exploited by an adversary than by a race condition.
3608 * Live untrusted data::
3609 * Security rules of thumb::
3612 File: tar.info, Node: Privacy, Next: Integrity, Up: Security
3617 Standard privacy concerns apply when using 'tar'. For example, suppose
3618 you are archiving your home directory into a file '/archive/myhome.tar'.
3619 Any secret information in your home directory, such as your SSH secret
3620 keys, are copied faithfully into the archive. Therefore, if your home
3621 directory contains any file that should not be read by some other user,
3622 the archive itself should be not be readable by that user. And even if
3623 the archive's data are inaccessible to untrusted users, its metadata
3624 (such as size or last-modified date) may reveal some information about
3625 your home directory; if the metadata are intended to be private, the
3626 archive's parent directory should also be inaccessible to untrusted
3629 One precaution is to create '/archive' so that it is not accessible
3630 to any user, unless that user also has permission to access all the
3631 files in your home directory.
3633 Similarly, when extracting from an archive, take care that the
3634 permissions of the extracted files are not more generous than what you
3635 want. Even if the archive itself is readable only to you, files
3636 extracted from it have their own permissions that may differ.
3639 File: tar.info, Node: Integrity, Next: Live untrusted data, Prev: Privacy, Up: Security
3644 When creating archives, take care that they are not writable by a
3645 untrusted user; otherwise, that user could modify the archive, and when
3646 you later extract from the archive you will get incorrect data.
3648 When 'tar' extracts from an archive, by default it writes into files
3649 relative to the working directory. If the archive was generated by an
3650 untrusted user, that user therefore can write into any file under the
3651 working directory. If the working directory contains a symbolic link to
3652 another directory, the untrusted user can also write into any file under
3653 the referenced directory. When extracting from an untrusted archive, it
3654 is therefore good practice to create an empty directory and run 'tar' in
3657 When extracting from two or more untrusted archives, each one should
3658 be extracted independently, into different empty directories.
3659 Otherwise, the first archive could create a symbolic link into an area
3660 outside the working directory, and the second one could follow the link
3661 and overwrite data that is not under the working directory. For
3662 example, when restoring from a series of incremental dumps, the archives
3663 should have been created by a trusted process, as otherwise the
3664 incremental restores might alter data outside the working directory.
3666 If you use the '--absolute-names' ('-P') option when extracting,
3667 'tar' respects any file names in the archive, even file names that begin
3668 with '/' or contain '..'. As this lets the archive overwrite any file
3669 in your system that you can write, the '--absolute-names' ('-P') option
3670 should be used only for trusted archives.
3672 Conversely, with the '--keep-old-files' ('-k') and '--skip-old-files'
3673 options, 'tar' refuses to replace existing files when extracting. The
3674 difference between the two options is that the former treats existing
3675 files as errors whereas the latter just silently ignores them.
3677 Finally, with the '--no-overwrite-dir' option, 'tar' refuses to
3678 replace the permissions or ownership of already-existing directories.
3679 These options may help when extracting from untrusted archives.
3682 File: tar.info, Node: Live untrusted data, Next: Security rules of thumb, Prev: Integrity, Up: Security
3684 10.2.3 Dealing with Live Untrusted Data
3685 ---------------------------------------
3687 Extra care is required when creating from or extracting into a file
3688 system that is accessible to untrusted users. For example, superusers
3689 who invoke 'tar' must be wary about its actions being hijacked by an
3690 adversary who is reading or writing the file system at the same time
3691 that 'tar' is operating.
3693 When creating an archive from a live file system, 'tar' is vulnerable
3694 to denial-of-service attacks. For example, an adversarial user could
3695 create the illusion of an indefinitely-deep directory hierarchy
3696 'd/e/f/g/...' by creating directories one step ahead of 'tar', or the
3697 illusion of an indefinitely-long file by creating a sparse file but
3698 arranging for blocks to be allocated just before 'tar' reads them.
3699 There is no easy way for 'tar' to distinguish these scenarios from
3700 legitimate uses, so you may need to monitor 'tar', just as you'd need to
3701 monitor any other system service, to detect such attacks.
3703 While a superuser is extracting from an archive into a live file
3704 system, an untrusted user might replace a directory with a symbolic
3705 link, in hopes that 'tar' will follow the symbolic link and extract data
3706 into files that the untrusted user does not have access to. Even if the
3707 archive was generated by the superuser, it may contain a file such as
3708 'd/etc/passwd' that the untrusted user earlier created in order to break
3709 in; if the untrusted user replaces the directory 'd/etc' with a symbolic
3710 link to '/etc' while 'tar' is running, 'tar' will overwrite
3711 '/etc/passwd'. This attack can be prevented by extracting into a
3712 directory that is inaccessible to untrusted users.
3714 Similar attacks via symbolic links are also possible when creating an
3715 archive, if the untrusted user can modify an ancestor of a top-level
3716 argument of 'tar'. For example, an untrusted user that can modify
3717 '/home/eve' can hijack a running instance of 'tar -cf -
3718 /home/eve/Documents/yesterday' by replacing '/home/eve/Documents' with a
3719 symbolic link to some other location. Attacks like these can be
3720 prevented by making sure that untrusted users cannot modify any files
3721 that are top-level arguments to 'tar', or any ancestor directories of
3725 File: tar.info, Node: Security rules of thumb, Prev: Live untrusted data, Up: Security
3727 10.2.4 Security Rules of Thumb
3728 ------------------------------
3730 This section briefly summarizes rules of thumb for avoiding security
3733 * Protect archives at least as much as you protect any of the files
3736 * Extract from an untrusted archive only into an otherwise-empty
3737 directory. This directory and its parent should be accessible only
3738 to trusted users. For example:
3741 $ mkdir -m go-rwx dir
3743 $ tar -xvf /archives/got-it-off-the-net.tar.gz
3745 As a corollary, do not do an incremental restore from an untrusted
3748 * Do not let untrusted users access files extracted from untrusted
3749 archives without checking first for problems such as setuid
3752 * Do not let untrusted users modify directories that are ancestors of
3753 top-level arguments of 'tar'. For example, while you are executing
3754 'tar -cf /archive/u-home.tar /u/home', do not let an untrusted user
3755 modify '/', '/archive', or '/u'.
3757 * Pay attention to the diagnostics and exit status of 'tar'.
3759 * When archiving live file systems, monitor running instances of
3760 'tar' to detect denial-of-service attacks.
3762 * Avoid unusual options such as '--absolute-names' ('-P'),
3763 '--dereference' ('-h'), '--overwrite', '--recursive-unlink', and
3764 '--remove-files' unless you understand their security implications.
3767 File: tar.info, Node: Changes, Next: Configuring Help Summary, Prev: Reliability and security, Up: Top
3772 This appendix lists some important user-visible changes between version
3773 GNU 'tar' 1.29 and previous versions. An up-to-date version of this
3774 document is available at the GNU 'tar' documentation page
3775 (http://www.gnu.org/software/tar/manual/changes.html).
3777 Use of globbing patterns when listing and extracting.
3779 Previous versions of GNU tar assumed shell-style globbing when
3780 extracting from or listing an archive. For example:
3782 $ tar xf foo.tar '*.c'
3784 would extract all files whose names end in '.c'. This behavior was
3785 not documented and was incompatible with traditional tar
3786 implementations. Therefore, starting from version 1.15.91, GNU tar
3787 no longer uses globbing by default. For example, the above
3788 invocation is now interpreted as a request to extract from the
3789 archive the file named '*.c'.
3791 To facilitate transition to the new behavior for those users who
3792 got used to the previous incorrect one, 'tar' will print a warning
3793 if it finds out that a requested member was not found in the
3794 archive and its name looks like a globbing pattern. For example:
3796 $ tar xf foo.tar '*.c'
3797 tar: Pattern matching characters used in file names. Please,
3798 tar: use --wildcards to enable pattern matching, or --no-wildcards to
3799 tar: suppress this warning.
3800 tar: *.c: Not found in archive
3801 tar: Error exit delayed from previous errors
3803 To treat member names as globbing patterns, use the '--wildcards'
3804 option. If you want to tar to mimic the behavior of versions prior
3805 to 1.15.91, add this option to your 'TAR_OPTIONS' variable.
3807 *Note wildcards::, for the detailed discussion of the use of
3808 globbing patterns by GNU 'tar'.
3810 Use of short option '-o'.
3812 Earlier versions of GNU 'tar' understood '-o' command line option
3813 as a synonym for '--old-archive'.
3815 GNU 'tar' starting from version 1.13.90 understands this option as
3816 a synonym for '--no-same-owner'. This is compatible with UNIX98
3817 'tar' implementations.
3819 However, to facilitate transition, '-o' option retains its old
3820 semantics when it is used with one of archive-creation commands.
3821 Users are encouraged to use '--format=oldgnu' instead.
3823 It is especially important, since versions of GNU Automake up to
3824 and including 1.8.4 invoke tar with this option to produce
3825 distribution tarballs. *Note v7: Formats, for the detailed
3826 discussion of this issue and its implications.
3828 *Note tar-formats: (automake)Options, for a description on how to
3829 use various archive formats with 'automake'.
3831 Future versions of GNU 'tar' will understand '-o' only as a synonym
3832 for '--no-same-owner'.
3834 Use of short option '-l'
3836 Earlier versions of GNU 'tar' understood '-l' option as a synonym
3837 for '--one-file-system'. Since such usage contradicted to UNIX98
3838 specification and harmed compatibility with other implementations,
3839 it was declared deprecated in version 1.14. However, to facilitate
3840 transition to its new semantics, it was supported by versions 1.15
3841 and 1.15.90. The present use of '-l' as a short variant of
3842 '--check-links' was introduced in version 1.15.91.
3844 Use of options '--portability' and '--old-archive'
3846 These options are deprecated. Please use '--format=v7' instead.
3848 Use of option '--posix'
3850 This option is deprecated. Please use '--format=posix' instead.
3853 File: tar.info, Node: Configuring Help Summary, Next: Fixing Snapshot Files, Prev: Changes, Up: Top
3855 Appendix B Configuring Help Summary
3856 ***********************************
3858 Running 'tar --help' displays the short 'tar' option summary (*note
3859 help::). This summary is organized by "groups" of semantically close
3860 options. The options within each group are printed in the following
3861 order: a short option, eventually followed by a list of corresponding
3862 long option names, followed by a short description of the option. For
3863 example, here is an excerpt from the actual 'tar --help' output:
3865 Main operation mode:
3867 -A, --catenate, --concatenate append tar files to an archive
3868 -c, --create create a new archive
3869 -d, --diff, --compare find differences between archive and
3871 --delete delete from the archive
3873 The exact visual representation of the help output is configurable
3874 via 'ARGP_HELP_FMT' environment variable. The value of this variable is
3875 a comma-separated list of "format variable" assignments. There are two
3876 kinds of format variables. An "offset variable" keeps the offset of
3877 some part of help output text from the leftmost column on the screen. A
3878 "boolean" variable is a flag that toggles some output feature on or off.
3879 Depending on the type of the corresponding variable, there are two kinds
3884 The assignment to an offset variable has the following syntax:
3888 where VARIABLE is the variable name, and VALUE is a numeric value
3889 to be assigned to the variable.
3893 To assign 'true' value to a variable, simply put this variable
3894 name. To assign 'false' value, prefix the variable name with
3897 # Assign true value:
3899 # Assign false value:
3902 Following variables are declared:
3904 -- Help Output: boolean dup-args
3905 If true, arguments for an option are shown with both short and long
3906 options, even when a given option has both forms, for example:
3908 -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
3910 If false, then if an option has both short and long forms, the
3911 argument is only shown with the long one, for example:
3913 -f, --file=ARCHIVE use archive file or device ARCHIVE
3915 and a message indicating that the argument is applicable to both
3916 forms is printed below the options. This message can be disabled
3917 using 'dup-args-note' (see below).
3919 The default is false.
3921 -- Help Output: boolean dup-args-note
3922 If this variable is true, which is the default, the following
3923 notice is displayed at the end of the help output:
3925 Mandatory or optional arguments to long options are also
3926 mandatory or optional for any corresponding short options.
3928 Setting 'no-dup-args-note' inhibits this message. Normally, only
3929 one of variables 'dup-args' or 'dup-args-note' should be set.
3931 -- Help Output: offset short-opt-col
3932 Column in which short options start. Default is 2.
3934 $ tar --help|grep ARCHIVE
3935 -f, --file=ARCHIVE use archive file or device ARCHIVE
3936 $ ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE
3937 -f, --file=ARCHIVE use archive file or device ARCHIVE
3939 -- Help Output: offset long-opt-col
3940 Column in which long options start. Default is 6. For example:
3942 $ tar --help|grep ARCHIVE
3943 -f, --file=ARCHIVE use archive file or device ARCHIVE
3944 $ ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE
3945 -f, --file=ARCHIVE use archive file or device ARCHIVE
3947 -- Help Output: offset doc-opt-col
3948 Column in which "doc options" start. A doc option isn't actually
3949 an option, but rather an arbitrary piece of documentation that is
3950 displayed in much the same manner as the options. For example, in
3951 the description of '--format' option:
3953 -H, --format=FORMAT create archive of the given format.
3955 FORMAT is one of the following:
3957 gnu GNU tar 1.13.x format
3958 oldgnu GNU format as per tar <= 1.12
3959 pax POSIX 1003.1-2001 (pax) format
3961 ustar POSIX 1003.1-1988 (ustar) format
3962 v7 old V7 tar format
3964 the format names are doc options. Thus, if you set
3965 'ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output
3966 will look as follows:
3968 -H, --format=FORMAT create archive of the given format.
3970 FORMAT is one of the following:
3972 gnu GNU tar 1.13.x format
3973 oldgnu GNU format as per tar <= 1.12
3974 pax POSIX 1003.1-2001 (pax) format
3976 ustar POSIX 1003.1-1988 (ustar) format
3977 v7 old V7 tar format
3979 -- Help Output: offset opt-doc-col
3980 Column in which option description starts. Default is 29.
3982 $ tar --help|grep ARCHIVE
3983 -f, --file=ARCHIVE use archive file or device ARCHIVE
3984 $ ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE
3985 -f, --file=ARCHIVE use archive file or device ARCHIVE
3986 $ ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE
3988 use archive file or device ARCHIVE
3990 Notice, that the description starts on a separate line if
3991 'opt-doc-col' value is too small.
3993 -- Help Output: offset header-col
3994 Column in which "group headers" are printed. A group header is a
3995 descriptive text preceding an option group. For example, in the
3998 Main operation mode:
4000 -A, --catenate, --concatenate append tar files to
4002 -c, --create create a new archive
4003 'Main operation mode:' is the group header.
4005 The default value is 1.
4007 -- Help Output: offset usage-indent
4008 Indentation of wrapped usage lines. Affects '--usage' output.
4011 -- Help Output: offset rmargin
4012 Right margin of the text output. Used for wrapping.
4015 File: tar.info, Node: Fixing Snapshot Files, Next: Tar Internals, Prev: Configuring Help Summary, Up: Top
4017 Appendix C Fixing Snapshot Files
4018 ********************************
4020 Various situations can cause device numbers to change: upgrading your
4021 kernel version, reconfiguring your hardware, loading kernel modules in a
4022 different order, using virtual volumes that are assembled dynamically
4023 (such as with LVM or RAID), hot-plugging drives (e.g. external USB or
4024 Firewire drives), etc. In the majority of cases this change is
4025 unnoticed by the users. However, it influences 'tar' incremental
4026 backups: the device number is stored in tar snapshot files (*note
4027 Snapshot Files::) and is used to determine whether the file has changed
4028 since the last backup. If the device numbers change for some reason, by
4029 default the next backup you run will be a full backup.
4031 To minimize the impact in these cases, GNU 'tar' comes with the
4032 'tar-snapshot-edit' utility for inspecting and updating device numbers
4033 in snapshot files. (The utility, written by Dustin J. Mitchell, is also
4034 available from the GNU 'tar' home page
4035 (http://www.gnu.org/software/tar/utils/tar-snapshot-edit.html).)
4037 To obtain a summary of the device numbers found in the snapshot file,
4040 $ tar-snapshot-edit SNAPFILE
4042 where SNAPFILE is the name of the snapshot file (you can supply as many
4043 files as you wish in a single command line). You can then compare the
4044 numbers across snapshot files, or against those currently in use on the
4045 live filesystem (using 'ls -l' or 'stat').
4047 Assuming the device numbers have indeed changed, it's often possible
4048 to simply tell GNU 'tar' to ignore the device number when processing the
4049 incremental snapshot files for these backups, using the
4050 '--no-check-device' option (*note device numbers::).
4052 Alternatively, you can use the 'tar-edit-snapshot' script's '-r'
4053 option to update all occurrences of the given device number in the
4054 snapshot file(s). It takes a single argument of the form
4055 'OLDDEV-NEWDEV', where OLDDEV is the device number used in the snapshot
4056 file, and NEWDEV is the corresponding new device number. Both numbers
4057 may be specified in hex (e.g., '0xfe01'), decimal (e.g., '65025'), or as
4058 a major:minor number pair (e.g., '254:1'). To change several device
4059 numbers at once, specify them in a single comma-separated list, as in
4060 '-r 0x3060-0x4500,0x307-0x4600'.
4062 Before updating the snapshot file, it is a good idea to create a
4063 backup copy of it. This is accomplished by '-b' option. The name of
4064 the backup file is obtained by appending '~' to the original file name.
4067 $ tar-snapshot-edit root_snap.0 boot_snap.0
4069 Detected snapshot file version: 2
4071 Device 0x0000 occurs 1 times.
4072 Device 0x0003 occurs 1 times.
4073 Device 0x0005 occurs 1 times.
4074 Device 0x0013 occurs 1 times.
4075 Device 0x6801 occurs 1 times.
4076 Device 0x6803 occurs 6626 times.
4077 Device 0xfb00 occurs 1 times.
4080 Detected snapshot file version: 2
4082 Device 0x6801 occurs 3 times.
4083 $ tar-snapshot-edit -b -r 0x6801-0x6901,0x6803-0x6903 root_snap.0 boot_snap.0
4085 Detected snapshot file version: 2
4087 Updated 6627 records.
4090 Detected snapshot file version: 2
4095 File: tar.info, Node: Tar Internals, Next: Genfile, Prev: Fixing Snapshot Files, Up: Top
4097 Appendix D Tar Internals
4098 ************************
4102 * Standard:: Basic Tar Format
4103 * Extensions:: GNU Extensions to the Archive Format
4104 * Sparse Formats:: Storing Sparse Files
4109 File: tar.info, Node: Standard, Next: Extensions, Up: Tar Internals
4114 _(This message will disappear, once this node revised.)_
4116 While an archive may contain many files, the archive itself is a
4117 single ordinary file. Like any other file, an archive file can be
4118 written to a storage device such as a tape or disk, sent through a pipe
4119 or over a network, saved on the active file system, or even stored in
4120 another archive. An archive file is not easy to read or manipulate
4121 without using the 'tar' utility or Tar mode in GNU Emacs.
4123 Physically, an archive consists of a series of file entries
4124 terminated by an end-of-archive entry, which consists of two 512 blocks
4125 of zero bytes. A file entry usually describes one of the files in the
4126 archive (an "archive member"), and consists of a file header and the
4127 contents of the file. File headers contain file names and statistics,
4128 checksum information which 'tar' uses to detect file corruption, and
4129 information about file types.
4131 Archives are permitted to have more than one member with the same
4132 member name. One way this situation can occur is if more than one
4133 version of a file has been stored in the archive. For information about
4134 adding new versions of a file to an archive, see *note update::.
4136 In addition to entries describing archive members, an archive may
4137 contain entries which 'tar' itself uses to store information. *Note
4138 label::, for an example of such an archive entry.
4140 A 'tar' archive file contains a series of blocks. Each block
4141 contains 'BLOCKSIZE' bytes. Although this format may be thought of as
4142 being on magnetic tape, other media are often used.
4144 Each file archived is represented by a header block which describes
4145 the file, followed by zero or more blocks which give the contents of the
4146 file. At the end of the archive file there are two 512-byte blocks
4147 filled with binary zeros as an end-of-file marker. A reasonable system
4148 should write such end-of-file marker at the end of an archive, but must
4149 not assume that such a block exists when reading an archive. In
4150 particular GNU 'tar' always issues a warning if it does not encounter
4153 The blocks may be "blocked" for physical I/O operations. Each record
4154 of N blocks (where N is set by the '--blocking-factor=512-SIZE' ('-b
4155 512-SIZE') option to 'tar') is written with a single 'write ()'
4156 operation. On magnetic tapes, the result of such a write is a single
4157 record. When writing an archive, the last record of blocks should be
4158 written at the full size, with blocks after the zero block containing
4159 all zeros. When reading an archive, a reasonable system should properly
4160 handle an archive whose last record is shorter than the rest, or which
4161 contains garbage records after a zero block.
4163 The header block is defined in C as follows. In the GNU 'tar'
4164 distribution, this is part of file 'src/tar.h':
4167 /* tar Header Block, from POSIX 1003.1-1990. */
4173 char name[100]; /* 0 */
4174 char mode[8]; /* 100 */
4175 char uid[8]; /* 108 */
4176 char gid[8]; /* 116 */
4177 char size[12]; /* 124 */
4178 char mtime[12]; /* 136 */
4179 char chksum[8]; /* 148 */
4180 char typeflag; /* 156 */
4181 char linkname[100]; /* 157 */
4182 char magic[6]; /* 257 */
4183 char version[2]; /* 263 */
4184 char uname[32]; /* 265 */
4185 char gname[32]; /* 297 */
4186 char devmajor[8]; /* 329 */
4187 char devminor[8]; /* 337 */
4188 char prefix[155]; /* 345 */
4192 #define TMAGIC "ustar" /* ustar and a null */
4194 #define TVERSION "00" /* 00 and no null */
4197 /* Values used in typeflag field. */
4198 #define REGTYPE '0' /* regular file */
4199 #define AREGTYPE '\0' /* regular file */
4200 #define LNKTYPE '1' /* link */
4201 #define SYMTYPE '2' /* reserved */
4202 #define CHRTYPE '3' /* character special */
4203 #define BLKTYPE '4' /* block special */
4204 #define DIRTYPE '5' /* directory */
4205 #define FIFOTYPE '6' /* FIFO special */
4206 #define CONTTYPE '7' /* reserved */
4208 #define XHDTYPE 'x' /* Extended header referring to the
4209 next file in the archive */
4210 #define XGLTYPE 'g' /* Global extended header */
4212 /* Bits used in the mode field, values in octal. */
4213 #define TSUID 04000 /* set UID on execution */
4214 #define TSGID 02000 /* set GID on execution */
4215 #define TSVTX 01000 /* reserved */
4216 /* file permissions */
4217 #define TUREAD 00400 /* read by owner */
4218 #define TUWRITE 00200 /* write by owner */
4219 #define TUEXEC 00100 /* execute/search by owner */
4220 #define TGREAD 00040 /* read by group */
4221 #define TGWRITE 00020 /* write by group */
4222 #define TGEXEC 00010 /* execute/search by group */
4223 #define TOREAD 00004 /* read by other */
4224 #define TOWRITE 00002 /* write by other */
4225 #define TOEXEC 00001 /* execute/search by other */
4227 /* tar Header Block, GNU extensions. */
4229 /* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for
4230 contiguous files, so maybe disobeying the "reserved" comment in POSIX
4231 header description. I suspect these were meant to be used this way, and
4232 should not have really been "reserved" in the published standards. */
4234 /* *BEWARE* *BEWARE* *BEWARE* that the following information is still
4235 boiling, and may change. Even if the OLDGNU format description should be
4236 accurate, the so-called GNU format is not yet fully decided. It is
4237 surely meant to use only extensions allowed by POSIX, but the sketch
4238 below repeats some ugliness from the OLDGNU format, which should rather
4239 go away. Sparse files should be saved in such a way that they do *not*
4240 require two passes at archive creation time. Huge files get some POSIX
4241 fields to overflow, alternate solutions have to be sought for this. */
4243 /* Descriptor for a single file hole. */
4247 char offset[12]; /* 0 */
4248 char numbytes[12]; /* 12 */
4252 /* Sparse files are not supported in POSIX ustar format. For sparse files
4253 with a POSIX header, a GNU extra header is provided which holds overall
4254 sparse information and a few sparse descriptors. When an old GNU header
4255 replaces both the POSIX header and the GNU extra header, it holds some
4256 sparse descriptors too. Whether POSIX or not, if more sparse descriptors
4257 are still needed, they are put into as many successive sparse headers as
4258 necessary. The following constants tell how many sparse descriptors fit
4259 in each kind of header able to hold them. */
4261 #define SPARSES_IN_EXTRA_HEADER 16
4262 #define SPARSES_IN_OLDGNU_HEADER 4
4263 #define SPARSES_IN_SPARSE_HEADER 21
4265 /* Extension header for sparse files, used immediately after the GNU extra
4266 header, and used only if all sparse information cannot fit into that
4267 extra header. There might even be many such extension headers, one after
4268 the other, until all sparse information has been recorded. */
4270 struct sparse_header
4272 struct sparse sp[SPARSES_IN_SPARSE_HEADER];
4274 char isextended; /* 504 */
4278 /* The old GNU format header conflicts with POSIX format in such a way that
4279 POSIX archives may fool old GNU tar's, and POSIX tar's might well be
4280 fooled by old GNU tar archives. An old GNU format header uses the space
4281 used by the prefix field in a POSIX header, and cumulates information
4282 normally found in a GNU extra header. With an old GNU tar header, we
4283 never see any POSIX header nor GNU extra header. Supplementary sparse
4284 headers are allowed, however. */
4286 struct oldgnu_header
4288 char unused_pad1[345]; /* 0 */
4289 char atime[12]; /* 345 Incr. archive: atime of the file */
4290 char ctime[12]; /* 357 Incr. archive: ctime of the file */
4291 char offset[12]; /* 369 Multivolume archive: the offset of
4292 the start of this volume */
4293 char longnames[4]; /* 381 Not used */
4294 char unused_pad2; /* 385 */
4295 struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
4297 char isextended; /* 482 Sparse file: Extension sparse header
4299 char realsize[12]; /* 483 Sparse file: Real size*/
4303 /* OLDGNU_MAGIC uses both magic and version fields, which are contiguous.
4304 Found in an archive, it indicates an old GNU header format, which will be
4305 hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are
4306 valid, though the header is not truly POSIX conforming. */
4307 #define OLDGNU_MAGIC "ustar " /* 7 chars and a null */
4309 /* The standards committee allows only capital A through capital Z for
4310 user-defined expansion. Other letters in use include:
4312 'A' Solaris Access Control List
4313 'E' Solaris Extended Attribute File
4314 'I' Inode only, as in 'star'
4315 'N' Obsolete GNU tar, for file names that do not fit into the main header.
4316 'X' POSIX 1003.1-2001 eXtended (VU version) */
4318 /* This is a dir entry that contains the names of files that were in the
4319 dir at the time the dump was made. */
4320 #define GNUTYPE_DUMPDIR 'D'
4322 /* Identifies the *next* file on the tape as having a long linkname. */
4323 #define GNUTYPE_LONGLINK 'K'
4325 /* Identifies the *next* file on the tape as having a long name. */
4326 #define GNUTYPE_LONGNAME 'L'
4328 /* This is the continuation of a file that began on another volume. */
4329 #define GNUTYPE_MULTIVOL 'M'
4331 /* This is for sparse files. */
4332 #define GNUTYPE_SPARSE 'S'
4334 /* This file is a tape/volume header. Ignore it on extraction. */
4335 #define GNUTYPE_VOLHDR 'V'
4337 /* Solaris extended header */
4338 #define SOLARIS_XHDTYPE 'X'
4340 /* Jo"rg Schilling star header */
4344 char name[100]; /* 0 */
4345 char mode[8]; /* 100 */
4346 char uid[8]; /* 108 */
4347 char gid[8]; /* 116 */
4348 char size[12]; /* 124 */
4349 char mtime[12]; /* 136 */
4350 char chksum[8]; /* 148 */
4351 char typeflag; /* 156 */
4352 char linkname[100]; /* 157 */
4353 char magic[6]; /* 257 */
4354 char version[2]; /* 263 */
4355 char uname[32]; /* 265 */
4356 char gname[32]; /* 297 */
4357 char devmajor[8]; /* 329 */
4358 char devminor[8]; /* 337 */
4359 char prefix[131]; /* 345 */
4360 char atime[12]; /* 476 */
4361 char ctime[12]; /* 488 */
4365 #define SPARSES_IN_STAR_HEADER 4
4366 #define SPARSES_IN_STAR_EXT_HEADER 21
4368 struct star_in_header
4370 char fill[345]; /* 0 Everything that is before t_prefix */
4371 char prefix[1]; /* 345 t_name prefix */
4372 char fill2; /* 346 */
4373 char fill3[8]; /* 347 */
4374 char isextended; /* 355 */
4375 struct sparse sp[SPARSES_IN_STAR_HEADER]; /* 356 */
4376 char realsize[12]; /* 452 Actual size of the file */
4377 char offset[12]; /* 464 Offset of multivolume contents */
4378 char atime[12]; /* 476 */
4379 char ctime[12]; /* 488 */
4380 char mfill[8]; /* 500 */
4381 char xmagic[4]; /* 508 "tar" */
4384 struct star_ext_header
4386 struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
4391 All characters in header blocks are represented by using 8-bit
4392 characters in the local variant of ASCII. Each field within the
4393 structure is contiguous; that is, there is no padding used within the
4394 structure. Each character on the archive medium is stored contiguously.
4396 Bytes representing the contents of files (after the header block of
4397 each file) are not translated in any way and are not constrained to
4398 represent characters in any character set. The 'tar' format does not
4399 distinguish text files from binary files, and no translation of file
4400 contents is performed.
4402 The 'name', 'linkname', 'magic', 'uname', and 'gname' are
4403 null-terminated character strings. All other fields are zero-filled
4404 octal numbers in ASCII. Each numeric field of width W contains W minus 1
4407 The 'name' field is the file name of the file, with directory names
4408 (if any) preceding the file name, separated by slashes.
4410 The 'mode' field provides nine bits specifying file permissions and
4411 three bits to specify the Set UID, Set GID, and Save Text ("sticky")
4412 modes. Values for these bits are defined above. When special
4413 permissions are required to create a file with a given mode, and the
4414 user restoring files from the archive does not hold such permissions,
4415 the mode bit(s) specifying those special permissions are ignored. Modes
4416 which are not supported by the operating system restoring files from the
4417 archive will be ignored. Unsupported modes should be faked up when
4418 creating or updating an archive; e.g., the group permission could be
4419 copied from the _other_ permission.
4421 The 'uid' and 'gid' fields are the numeric user and group ID of the
4422 file owners, respectively. If the operating system does not support
4423 numeric user or group IDs, these fields should be ignored.
4425 The 'size' field is the size of the file in bytes; linked files are
4426 archived with this field specified as zero.
4428 The 'mtime' field is the data modification time of the file at the
4429 time it was archived. It is the ASCII representation of the octal value
4430 of the last time the file's contents were modified, represented as an
4431 integer number of seconds since January 1, 1970, 00:00 Coordinated
4434 The 'chksum' field is the ASCII representation of the octal value of
4435 the simple sum of all bytes in the header block. Each 8-bit byte in the
4436 header is added to an unsigned integer, initialized to zero, the
4437 precision of which shall be no less than seventeen bits. When
4438 calculating the checksum, the 'chksum' field is treated as if it were
4441 The 'typeflag' field specifies the type of file archived. If a
4442 particular implementation does not recognize or permit the specified
4443 type, the file will be extracted as if it were a regular file. As this
4444 action occurs, 'tar' issues a warning to the standard error.
4446 The 'atime' and 'ctime' fields are used in making incremental
4447 backups; they store, respectively, the particular file's access and
4448 status change times.
4450 The 'offset' is used by the '--multi-volume' ('-M') option, when
4451 making a multi-volume archive. The offset is number of bytes into the
4452 file that we need to restart at to continue the file on the next tape,
4453 i.e., where we store the location that a continued file is continued at.
4455 The following fields were added to deal with sparse files. A file is
4456 "sparse" if it takes in unallocated blocks which end up being
4457 represented as zeros, i.e., no useful data. A test to see if a file is
4458 sparse is to look at the number blocks allocated for it versus the
4459 number of characters in the file; if there are fewer blocks allocated
4460 for the file than would normally be allocated for a file of that size,
4461 then the file is sparse. This is the method 'tar' uses to detect a
4462 sparse file, and once such a file is detected, it is treated differently
4463 from non-sparse files.
4465 Sparse files are often 'dbm' files, or other database-type files
4466 which have data at some points and emptiness in the greater part of the
4467 file. Such files can appear to be very large when an 'ls -l' is done on
4468 them, when in truth, there may be a very small amount of important data
4469 contained in the file. It is thus undesirable to have 'tar' think that
4470 it must back up this entire file, as great quantities of room are wasted
4471 on empty blocks, which can lead to running out of room on a tape far
4472 earlier than is necessary. Thus, sparse files are dealt with so that
4473 these empty blocks are not written to the tape. Instead, what is
4474 written to the tape is a description, of sorts, of the sparse file:
4475 where the holes are, how big the holes are, and how much data is found
4476 at the end of the hole. This way, the file takes up potentially far
4477 less room on the tape, and when the file is extracted later on, it will
4478 look exactly the way it looked beforehand. The following is a
4479 description of the fields used to handle a sparse file:
4481 The 'sp' is an array of 'struct sparse'. Each 'struct sparse'
4482 contains two 12-character strings which represent an offset into the
4483 file and a number of bytes to be written at that offset. The offset is
4484 absolute, and not relative to the offset in preceding array element.
4486 The header can hold four of these 'struct sparse' at the moment; if
4487 more are needed, they are not stored in the header.
4489 The 'isextended' flag is set when an 'extended_header' is needed to
4490 deal with a file. Note that this means that this flag can only be set
4491 when dealing with a sparse file, and it is only set in the event that
4492 the description of the file will not fit in the allotted room for sparse
4493 structures in the header. In other words, an extended_header is needed.
4495 The 'extended_header' structure is used for sparse files which need
4496 more sparse structures than can fit in the header. The header can fit 4
4497 such structures; if more are needed, the flag 'isextended' gets set and
4498 the next block is an 'extended_header'.
4500 Each 'extended_header' structure contains an array of 21 sparse
4501 structures, along with a similar 'isextended' flag that the header had.
4502 There can be an indeterminate number of such 'extended_header's to
4503 describe a sparse file.
4507 These flags represent a regular file. In order to be compatible
4508 with older versions of 'tar', a 'typeflag' value of 'AREGTYPE'
4509 should be silently recognized as a regular file. New archives
4510 should be created using 'REGTYPE'. Also, for backward
4511 compatibility, 'tar' treats a regular file whose name ends with a
4512 slash as a directory.
4515 This flag represents a file linked to another file, of any type,
4516 previously archived. Such files are identified in Unix by each
4517 file having the same device and inode number. The linked-to name
4518 is specified in the 'linkname' field with a trailing null.
4521 This represents a symbolic link to another file. The linked-to
4522 name is specified in the 'linkname' field with a trailing null.
4526 These represent character special files and block special files
4527 respectively. In this case the 'devmajor' and 'devminor' fields
4528 will contain the major and minor device numbers respectively.
4529 Operating systems may map the device specifications to their own
4530 local specification, or may ignore the entry.
4533 This flag specifies a directory or sub-directory. The directory
4534 name in the 'name' field should end with a slash. On systems where
4535 disk allocation is performed on a directory basis, the 'size' field
4536 will contain the maximum number of bytes (which may be rounded to
4537 the nearest disk block allocation unit) which the directory may
4538 hold. A 'size' field of zero indicates no such limiting. Systems
4539 which do not support limiting in this manner should ignore the
4543 This specifies a FIFO special file. Note that the archiving of a
4544 FIFO file archives the existence of this file and not its contents.
4547 This specifies a contiguous file, which is the same as a normal
4548 file except that, in operating systems which support it, all its
4549 space is allocated contiguously on the disk. Operating systems
4550 which do not allow contiguous allocation should silently treat this
4551 type as a normal file.
4554 These are reserved for custom implementations. Some of these are
4555 used in the GNU modified format, as described below.
4557 Other values are reserved for specification in future revisions of
4558 the P1003 standard, and should not be used by any 'tar' program.
4560 The 'magic' field indicates that this archive was output in the P1003
4561 archive format. If this field contains 'TMAGIC', the 'uname' and
4562 'gname' fields will contain the ASCII representation of the owner and
4563 group of the file respectively. If found, the user and group IDs are
4564 used rather than the values in the 'uid' and 'gid' fields.
4566 For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990,
4567 pages 169-173 (section 10.1) for 'Archive/Interchange File Format'; and
4568 IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
4569 (section E.4.48) for 'pax - Portable archive interchange'.
4572 File: tar.info, Node: Extensions, Next: Sparse Formats, Prev: Standard, Up: Tar Internals
4574 GNU Extensions to the Archive Format
4575 ====================================
4577 _(This message will disappear, once this node revised.)_
4579 The GNU format uses additional file types to describe new types of
4580 files in an archive. These are listed below.
4584 This represents a directory and a list of files created by the
4585 '--incremental' ('-G') option. The 'size' field gives the total
4586 size of the associated list of files. Each file name is preceded
4587 by either a 'Y' (the file should be in this archive) or an 'N'.
4588 (The file is a directory, or is not stored in the archive.) Each
4589 file name is terminated by a null. There is an additional null
4590 after the last file name.
4594 This represents a file continued from another volume of a
4595 multi-volume archive created with the '--multi-volume' ('-M')
4596 option. The original type of the file is not given here. The
4597 'size' field gives the maximum size of this piece of the file
4598 (assuming the volume does not end before the file is written out).
4599 The 'offset' field gives the offset from the beginning of the file
4600 where this part of the file begins. Thus 'size' plus 'offset'
4601 should equal the original size of the file.
4605 This flag indicates that we are dealing with a sparse file. Note
4606 that archiving a sparse file requires special operations to find
4607 holes in the file, which mark the positions of these holes, along
4608 with the number of bytes of data to be found after the hole.
4612 This file type is used to mark the volume header that was given
4613 with the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') option when
4614 the archive was created. The 'name' field contains the 'name'
4615 given after the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL')
4616 option. The 'size' field is zero. Only the first file in each
4617 volume of an archive should have this type.
4619 You may have trouble reading a GNU format archive on a non-GNU system
4620 if the options '--incremental' ('-G'), '--multi-volume' ('-M'),
4621 '--sparse' ('-S'), or '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') were
4622 used when writing the archive. In general, if 'tar' does not use the
4623 GNU-added fields of the header, other versions of 'tar' should be able
4624 to read the archive. Otherwise, the 'tar' program will give an error,
4625 the most likely one being a checksum error.
4628 File: tar.info, Node: Sparse Formats, Next: Snapshot Files, Prev: Extensions, Up: Tar Internals
4630 Storing Sparse Files
4631 ====================
4633 The notion of sparse file, and the ways of handling it from the point of
4634 view of GNU 'tar' user have been described in detail in *note sparse::.
4635 This chapter describes the internal format GNU 'tar' uses to store such
4638 The support for sparse files in GNU 'tar' has a long history. The
4639 earliest version featuring this support that I was able to find was
4640 1.09, released in November, 1990. The format introduced back then is
4641 called "old GNU" sparse format and in spite of the fact that its design
4642 contained many flaws, it was the only format GNU 'tar' supported until
4643 version 1.14 (May, 2004), which introduced initial support for sparse
4644 archives in PAX archives (*note posix::). This format was not free from
4645 design flaws, either and it was subsequently improved in versions 1.15.2
4646 (November, 2005) and 1.15.92 (June, 2006).
4648 In addition to GNU sparse format, GNU 'tar' is able to read and
4649 extract sparse files archived by 'star'.
4651 The following subsections describe each format in detail.
4656 * PAX 0:: PAX Format, Versions 0.0 and 0.1
4657 * PAX 1:: PAX Format, Version 1.0
4660 File: tar.info, Node: Old GNU Format, Next: PAX 0, Up: Sparse Formats
4665 The format introduced in November 1990 (v. 1.09) was designed on top of
4666 standard 'ustar' headers in such an unfortunate way that some of its
4667 fields overwrote fields required by POSIX.
4669 An old GNU sparse header is designated by type 'S' ('GNUTYPE_SPARSE')
4670 and has the following layout:
4672 Offset Size Name Data type Contents
4673 ----------------------------------------------------------------------------
4675 345 12 atime Number 'atime' of the file.
4676 357 12 ctime Number 'ctime' of the file .
4677 369 12 offset Number For multivolume archives:
4678 the offset of the start of
4682 386 96 sp 'sparse_header'(4 entries) File map.
4683 482 1 isextended Bool '1' if an extension sparse
4686 483 12 realsize Number Real size of the file.
4688 Each of 'sparse_header' object at offset 386 describes a single data
4689 chunk. It has the following structure:
4691 Offset Size Data type Contents
4692 ---------------------------------------------------------------------------
4693 0 12 Number Offset of the beginning of the chunk.
4694 12 12 Number Size of the chunk.
4696 If the member contains more than four chunks, the 'isextended' field
4697 of the header has the value '1' and the main header is followed by one
4698 or more "extension headers". Each such header has the following
4701 Offset Size Name Data type Contents
4702 ----------------------------------------------------------------------------
4703 0 21 sp 'sparse_header'(21 entries) File map.
4704 504 1 isextended Bool '1' if an extension sparse
4705 header follows, or '0'
4708 A header with 'isextended=0' ends the map.
4711 File: tar.info, Node: PAX 0, Next: PAX 1, Prev: Old GNU Format, Up: Sparse Formats
4713 PAX Format, Versions 0.0 and 0.1
4714 --------------------------------
4716 There are two formats available in this branch. The version '0.0' is
4717 the initial version of sparse format used by 'tar' versions 1.14-1.15.1.
4718 The sparse file map is kept in extended ('x') PAX header variables:
4721 Real size of the stored file;
4723 'GNU.sparse.numblocks'
4724 Number of blocks in the sparse map;
4727 Offset of the data block;
4729 'GNU.sparse.numbytes'
4730 Size of the data block.
4732 The latter two variables repeat for each data block, so the overall
4733 structure is like this:
4735 GNU.sparse.size=SIZE
4736 GNU.sparse.numblocks=NUMBLOCKS
4737 repeat NUMBLOCKS times
4738 GNU.sparse.offset=OFFSET
4739 GNU.sparse.numbytes=NUMBYTES
4742 This format presented the following two problems:
4744 1. Whereas the POSIX specification allows a variable to appear
4745 multiple times in a header, it requires that only the last
4746 occurrence be meaningful. Thus, multiple occurrences of
4747 'GNU.sparse.offset' and 'GNU.sparse.numbytes' are conflicting with
4750 2. Attempting to extract such archives using a third-party's 'tar'
4751 results in extraction of sparse files in _condensed form_. If the
4752 'tar' implementation in question does not support POSIX format, it
4753 will also extract a file containing extension header attributes.
4754 This file can be used to expand the file to its original state.
4755 However, posix-aware 'tar's will usually ignore the unknown
4756 variables, which makes restoring the file more difficult. *Note
4757 Extraction of sparse members in v.0.0 format: extracting sparse
4758 v.0.x, for the detailed description of how to restore such members
4759 using non-GNU 'tar's.
4761 GNU 'tar' 1.15.2 introduced sparse format version '0.1', which
4762 attempted to solve these problems. As its predecessor, this format
4763 stores sparse map in the extended POSIX header. It retains
4764 'GNU.sparse.size' and 'GNU.sparse.numblocks' variables, but instead of
4765 'GNU.sparse.offset'/'GNU.sparse.numbytes' pairs it uses a single
4769 Map of non-null data chunks. It is a string consisting of
4770 comma-separated values "OFFSET,SIZE[,OFFSET-1,SIZE-1...]"
4772 To address the 2nd problem, the 'name' field in 'ustar' is replaced
4773 with a special name, constructed using the following pattern:
4775 %d/GNUSparseFile.%p/%f
4777 The real name of the sparse file is stored in the variable
4778 'GNU.sparse.name'. Thus, those 'tar' implementations that are not aware
4779 of GNU extensions will at least extract the files into separate
4780 directories, giving the user a possibility to expand it afterwards.
4781 *Note Extraction of sparse members in v.0.1 format: extracting sparse
4782 v.0.x, for the detailed description of how to restore such members using
4785 The resulting 'GNU.sparse.map' string can be _very_ long. Although
4786 POSIX does not impose any limit on the length of a 'x' header variable,
4787 this possibly can confuse some 'tar's.
4790 File: tar.info, Node: PAX 1, Prev: PAX 0, Up: Sparse Formats
4792 PAX Format, Version 1.0
4793 -----------------------
4795 The version '1.0' of sparse format was introduced with GNU 'tar'
4796 1.15.92. Its main objective was to make the resulting file extractable
4797 with little effort even by non-posix aware 'tar' implementations.
4798 Starting from this version, the extended header preceding a sparse
4799 member always contains the following variables that identify the format
4808 The 'name' field in 'ustar' header contains a special name,
4809 constructed using the following pattern:
4811 %d/GNUSparseFile.%p/%f
4813 The real name of the sparse file is stored in the variable
4814 'GNU.sparse.name'. The real size of the file is stored in the variable
4815 'GNU.sparse.realsize'.
4817 The sparse map itself is stored in the file data block, preceding the
4818 actual file data. It consists of a series of octal numbers of arbitrary
4819 length, delimited by newlines. The map is padded with nulls to the
4820 nearest block boundary.
4822 The first number gives the number of entries in the map. Following
4823 are map entries, each one consisting of two numbers giving the offset
4824 and size of the data block it describes.
4826 The format is designed in such a way that non-posix aware 'tar's and
4827 'tar's not supporting 'GNU.sparse.*' keywords will extract each sparse
4828 file in its condensed form with the file map prepended and will place it
4829 into a separate directory. Then, using a simple program it would be
4830 possible to expand the file to its original form even without GNU 'tar'.
4831 *Note Sparse Recovery::, for the detailed information on how to extract
4832 sparse members without GNU 'tar'.
4835 File: tar.info, Node: Snapshot Files, Next: Dumpdir, Prev: Sparse Formats, Up: Tar Internals
4837 Format of the Incremental Snapshot Files
4838 ========================================
4840 A "snapshot file" (or "directory file") is created during incremental
4841 backups (*note Incremental Dumps::). It contains the status of the file
4842 system at the time of the dump and is used to determine which files were
4843 modified since the last backup.
4845 GNU 'tar' version 1.29 supports three snapshot file formats. The
4846 first format, called "format 0", is the one used by GNU 'tar' versions
4847 up to and including 1.15.1. The second format, called "format 1" is an
4848 extended version of this format, that contains more metadata and allows
4849 for further extensions. It was used by alpha release version 1.15.90.
4850 For alpha version 1.15.91 and stable releases version 1.16 up through
4851 1.29, the "format 2" is used.
4853 GNU 'tar' is able to read all three formats, but will create
4854 snapshots only in format 2.
4856 This appendix describes all three formats in detail.
4858 0. 'Format 0' snapshot file begins with a line containing a decimal
4859 number that represents a UNIX timestamp of the beginning of the
4860 last archivation. This line is followed by directory metadata
4861 descriptions, one per line. Each description has the following
4869 A single plus character ('+'), if this directory is located on
4870 an NFS-mounted partition, otherwise empty.
4872 (That is, for non-NFS directories, the first character on the
4873 description line contains the start of the DEV field.)
4876 Device number of the directory;
4879 I-node number of the directory;
4882 Name of the directory. Any special characters (white-space,
4883 backslashes, etc.) are quoted.
4885 1. 'Format 1' snapshot file begins with a line specifying the format
4886 of the file. This line has the following structure:
4888 'GNU tar-'TAR-VERSION'-'INCR-FORMAT-VERSION
4890 where TAR-VERSION is the version number of GNU 'tar' implementation
4891 that created this snapshot, and INCR-FORMAT-VERSION is the version
4892 number of the snapshot format (in this case '1').
4894 Next line contains two decimal numbers, representing the time of
4895 the last backup. First number is the number of seconds, the second
4896 one is the number of nanoseconds, since the beginning of the epoch.
4898 Lines that follow contain directory metadata, one line per
4899 directory. Each line is formatted as follows:
4901 [NFS]MTIME-SEC MTIME-NSEC DEV INODE NAME
4903 where MTIME-SEC and MTIME-NSEC represent last modification time of
4904 this directory with nanosecond precision; NFS, DEV, INODE and NAME
4905 have the same meaning as with 'format 0'.
4907 2. 'Format 2' snapshot file begins with a format identifier, as
4908 described for version 1, e.g.:
4912 This line is followed by newline. Rest of file consists of
4913 records, separated by null (ASCII 0) characters. Thus, in contrast
4914 to the previous formats, format 2 snapshot is a binary file.
4916 First two records are decimal integers, representing the time of
4917 the last backup. First number is the number of seconds, the second
4918 one is the number of nanoseconds, since the beginning of the epoch.
4919 These are followed by arbitrary number of directory records.
4921 Each "directory record" contains a set of metadata describing a
4922 particular directory. Parts of a directory record are delimited
4923 with ASCII 0 characters. The following table describes each part.
4924 The "Number" type in this table stands for a decimal integer in
4925 ASCII notation. (Negative values are preceded with a "-"
4926 character, while positive values have no leading punctuation.)
4928 Field Type Description
4929 ---------------------------------------------------------------------------
4930 nfs Character '1' if the directory is located on an
4931 NFS-mounted partition, or '0' otherwise;
4932 timestamp_sec Number Modification time, seconds;
4933 timestamp_nsec Number Modification time, nanoseconds;
4934 dev Number Device number;
4935 ino Number I-node number;
4936 name String Directory name; in contrast to the
4937 previous versions it is not quoted;
4938 contents Dumpdir Contents of the directory;
4939 *Note Dumpdir::, for a description of its
4942 Dumpdirs stored in snapshot files contain only records of types
4945 The specific range of values allowed in each of the "Number" fields
4946 depends on the underlying C datatypes as determined when 'tar' is
4947 compiled. To see the specific ranges allowed for a particular
4948 'tar' binary, you can use the '--show-snapshot-field-ranges'
4951 $ tar --show-shapshot-field-ranges
4952 This tar's snapshot file field ranges are
4953 (field name => [ min, max ]):
4956 timestamp_sec => [ -9223372036854775808, 9223372036854775807 ],
4957 timestamp_nsec => [ 0, 999999999 ],
4958 dev => [ 0, 18446744073709551615 ],
4959 ino => [ 0, 18446744073709551615 ],
4961 (This example is from a GNU/Linux x86_64 system.)
4964 File: tar.info, Node: Dumpdir, Prev: Snapshot Files, Up: Tar Internals
4969 Incremental archives keep information about contents of each dumped
4970 directory in special data blocks called "dumpdirs".
4972 Dumpdir is a sequence of entries of the following form:
4976 where C is one of the "control codes" described below, FILENAME is the
4977 name of the file C operates upon, and '\0' represents a nul character
4978 (ASCII 0). The white space characters were added for readability, real
4979 dumpdirs do not contain them.
4981 Each dumpdir ends with a single nul character.
4983 The following table describes control codes and their meanings:
4986 FILENAME is contained in the archive.
4989 FILENAME was present in the directory at the time the archive was
4990 made, yet it was not dumped to the archive, because it had not
4991 changed since the last backup.
4994 FILENAME is a directory.
4997 This code requests renaming of the FILENAME to the name specified
4998 with the 'T' command, that immediately follows it.
5001 Specify target file name for 'R' command (see below).
5004 Specify "temporary directory" name for a rename operation (see
5007 Codes 'Y', 'N' and 'D' require FILENAME argument to be a relative
5008 file name to the directory this dumpdir describes, whereas codes 'R',
5009 'T' and 'X' require their argument to be an absolute file name.
5011 The three codes 'R', 'T' and 'X' specify a "renaming operation". In
5012 the simplest case it is:
5016 which means "rename file 'source' to file 'dest'".
5018 However, there are cases that require using a "temporary directory".
5019 For example, consider the following scenario:
5021 1. Previous run dumped a directory 'foo' which contained the following
5028 2. They were renamed _cyclically_, so that:
5034 3. New incremental dump was made.
5036 This case cannot be handled by three successive renames, since
5037 renaming 'a' to 'b' will destroy the existing directory. To correctly
5038 process it, GNU 'tar' needs a temporary directory, so it creates the
5039 following dumpdir (newlines have been added for readability):
5047 The first command, 'Xfoo\0', instructs the extractor to create a
5048 temporary directory in the directory 'foo'. Second command,
5049 'Rfoo/aT\0', says "rename file 'foo/a' to the temporary directory that
5050 has just been created" (empty file name after a command means use
5051 temporary directory). Third and fourth commands work as usual, and,
5052 finally, the last command, 'R\0Tfoo/a\0' tells tar to rename the
5053 temporary directory to 'foo/a'.
5055 The exact placement of a dumpdir in the archive depends on the
5056 archive format (*note Formats::):
5060 In PAX archives, dumpdir is stored in the extended header of the
5061 corresponding directory, in variable 'GNU.dumpdir'.
5063 * GNU and old GNU archives
5065 These formats implement special header type 'D', which is similar
5066 to ustar header '5' (directory), except that it precedes a data
5067 block containing the dumpdir.
5070 File: tar.info, Node: Genfile, Next: Free Software Needs Free Documentation, Prev: Tar Internals, Up: Top
5075 This appendix describes 'genfile', an auxiliary program used in the GNU
5076 tar testsuite. If you are not interested in developing GNU tar, skip
5079 Initially, 'genfile' was used to generate data files for the
5080 testsuite, hence its name. However, new operation modes were being
5081 implemented as the testsuite grew more sophisticated, and now 'genfile'
5082 is a multi-purpose instrument.
5084 There are three basic operation modes:
5087 This is the default mode. In this mode, 'genfile' generates data
5091 In this mode 'genfile' displays status of specified files.
5093 Synchronous Execution.
5094 In this mode 'genfile' executes the given program with
5095 '--checkpoint' option and executes a set of actions when specified
5096 checkpoints are reached.
5100 * Generate Mode:: File Generation Mode.
5101 * Status Mode:: File Status Mode.
5102 * Exec Mode:: Synchronous Execution mode.
5105 File: tar.info, Node: Generate Mode, Next: Status Mode, Up: Genfile
5110 In this mode 'genfile' creates a data file for the test suite. The size
5111 of the file is given with the '--length' ('-l') option. By default the
5112 file contents is written to the standard output, this can be changed
5113 using '--file' ('-f') command line option. Thus, the following two
5114 commands are equivalent:
5116 genfile --length 100 > outfile
5117 genfile --length 100 --file outfile
5119 If '--length' is not given, 'genfile' will generate an empty
5122 The command line option '--seek=N' istructs 'genfile' to skip the
5123 given number of bytes (N) in the output file before writing to it. It
5124 is similar to the 'seek=N' of the 'dd' utility.
5126 You can instruct 'genfile' to create several files at one go, by
5127 giving it '--files-from' ('-T') option followed by a name of file
5128 containing a list of file names. Using dash ('-') instead of the file
5129 name causes 'genfile' to read file list from the standard input. For
5132 # Read file names from file file.list
5133 genfile --files-from file.list
5134 # Read file names from standard input
5135 genfile --files-from -
5137 The list file is supposed to contain one file name per line. To use
5138 file lists separated by ASCII NUL character, use '--null' ('-0') command
5141 genfile --null --files-from file.list
5143 The default data pattern for filling the generated file consists of
5144 first 256 letters of ASCII code, repeated enough times to fill the
5145 entire file. This behavior can be changed with '--pattern' option.
5146 This option takes a mandatory argument, specifying pattern name to use.
5147 Currently two patterns are implemented:
5150 The default pattern as described above.
5153 Fills the file with zeroes.
5155 If no file name was given, the program exits with the code '0'.
5156 Otherwise, it exits with '0' only if it was able to create a file of the
5159 Special option '--sparse' ('-s') instructs 'genfile' to create a
5160 sparse file. Sparse files consist of "data fragments", separated by
5161 "holes" or blocks of zeros. On many operating systems, actual disk
5162 storage is not allocated for holes, but they are counted in the length
5163 of the file. To create a sparse file, 'genfile' should know where to
5164 put data fragments, and what data to use to fill them. So, when
5165 '--sparse' is given the rest of the command line specifies a so-called
5168 The file map consists of any number of "fragment descriptors". Each
5169 descriptor is composed of two values: a number, specifying fragment
5170 offset from the end of the previous fragment or, for the very first
5171 fragment, from the beginning of the file, and "contents string", that
5172 specifies the pattern to fill the fragment with. File offset can be
5173 suffixed with the following quantifiers:
5177 The number is expressed in kilobytes.
5180 The number is expressed in megabytes.
5183 The number is expressed in gigabytes.
5185 Contents string can be either a fragment size or a pattern. Fragment
5186 size is a decimal number, prefixed with an equals sign. It can be
5187 suffixed with a quantifier, as discussed above. If fragment size is
5188 given, the fragment of that size will be filled with the currently
5189 selected pattern (*note -pattern: Generate Mode.) and written to the
5192 A pattern is a string of arbitrary ASCII characters. For each of
5193 them, 'genfile' will generate a "block" of data, filled with that
5194 character and will write it to the fragment. The size of block is given
5195 by '--block-size' option. It defaults to 512. Thus, if pattern
5196 consists of N characters, the resulting file fragment will contain
5197 'N*BLOCK-SIZE' bytes of data.
5199 The last fragment descriptor can have only file offset part. In this
5200 case 'genfile' will create a hole at the end of the file up to the given
5203 A dash appearing as a fragment descriptor instructs 'genfile' to read
5204 file map from the standard input. Each line of input should consist of
5205 fragment offset and contents string, separated by any amount of
5208 For example, consider the following invocation:
5210 genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K
5212 It will create 3101184-bytes long file of the following structure:
5214 Offset Length Contents
5215 0 4*512=2048 Four 512-byte blocks, filled
5216 with letters 'A', 'B', 'C' and
5218 2048 1046528 Zero bytes
5219 1050624 5*512=2560 Five blocks, filled with
5220 letters 'E', 'F', 'G', 'H',
5222 1053184 2048000 Zero bytes
5224 The exit code of 'genfile --sparse' command is '0' only if created
5225 file is actually sparse. If it is not, the appropriate error message is
5226 displayed and the command exists with code '1'. The '--quite' ('-q')
5227 option suppresses this behavior. If '--quite' is given, 'genfile
5228 --sparse' exits with code '0' if it was able to create the file, whether
5229 the resulting file is sparse or not.
5232 File: tar.info, Node: Status Mode, Next: Exec Mode, Prev: Generate Mode, Up: Genfile
5237 In status mode, 'genfile' prints file system status for each file
5238 specified in the command line. This mode is toggled by '--stat' ('-S')
5239 command line option. An optional argument to this option specifies
5240 output "format": a comma-separated list of 'struct stat' fields to be
5241 displayed. This list can contain following identifiers:
5248 Device number in decimal.
5257 File mode in octal. Optional NUMBER specifies octal mask to be
5258 applied to the mode before outputting. For example, '--stat
5259 mode.777' will preserve lower nine bits of it. Notice, that you
5260 can use any punctuation character in place of '.'.
5264 Number of hard links.
5276 File size in decimal.
5280 The size in bytes of each file block.
5284 Number of blocks allocated.
5288 Time of last access.
5292 Time of last modification
5296 Time of last status change
5299 A boolean value indicating whether the file is 'sparse'.
5301 Modification times are displayed in UTC as UNIX timestamps, unless
5302 suffixed with 'H' (for "human-readable"), as in 'ctimeH', in which case
5303 usual 'tar tv' output format is used.
5305 The default output format is: 'name,dev,ino,mode,
5306 nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime'.
5308 For example, the following command will display file names and
5309 corresponding times of last access for each file in the current working
5312 genfile --stat=name,atime *
5315 File: tar.info, Node: Exec Mode, Prev: Status Mode, Up: Genfile
5320 This mode is designed for testing the behavior of 'paxutils' commands
5321 when some of the files change during archiving. It is an experimental
5324 The 'Exec Mode' is toggled by '--run' command line option (or its
5325 alias '-r'). The non-optional arguments to 'getopt' give the command
5326 line to be executed. Normally, it should contain at least the
5327 '--checkpoint' option.
5329 A set of options is provided for defining checkpoint values and
5330 actions to be executed upon reaching them. Checkpoint values are
5331 introduced with the '--checkpoint' command line option. Argument to
5332 this option is the number of checkpoint in decimal.
5334 Any number of "actions" may be specified after a checkpoint.
5335 Available actions are
5339 Truncate FILE to the size specified by previous '--length' option
5340 (or 0, if it is not given).
5343 Append data to FILE. The size of data and its pattern are given by
5344 previous '--length' and 'pattern' options.
5347 Update the access and modification times of FILE. These timestamps
5348 are changed to the current time, unless '--date' option was given,
5349 in which case they are changed to the specified time. Argument to
5350 '--date' option is a date specification in an almost arbitrary
5351 format (*note Date input formats::).
5354 Execute given shell command.
5359 Option '--verbose' instructs 'genfile' to print on standard output
5360 notifications about checkpoints being executed and to verbosely describe
5361 exit status of the command.
5363 While the command is being executed its standard output remains
5364 connected to descriptor 1. All messages it prints to file descriptor 2,
5365 except checkpoint notifications, are forwarded to standard error.
5367 'Genfile' exits with the exit status of the executed command.
5369 For compatibility with previous 'genfile' versions, the '--run'
5370 option takes an optional argument. If used this way, its argument
5371 supplies the command line to be executed. There should be no
5372 non-optional arguments in the 'genfile' command line.
5374 The actual command line is constructed by inserting the
5375 '--checkpoint' option between the command name and its first argument
5376 (if any). Due to this, the argument to '--run' may not use traditional
5377 'tar' option syntax, i.e., the following is wrong:
5380 genfile --run='tar cf foo bar'
5382 Use the following syntax instead:
5384 genfile --run='tar -cf foo bar' ACTIONS...
5386 The above command line is equivalent to
5388 genfile ACTIONS... -- tar -cf foo bar
5390 Notice, that the use of compatibility mode is deprecated.
5393 File: tar.info, Node: Free Software Needs Free Documentation, Next: GNU Free Documentation License, Prev: Genfile, Up: Top
5395 Appendix F Free Software Needs Free Documentation
5396 *************************************************
5398 The biggest deficiency in the free software community today is not in
5399 the software--it is the lack of good free documentation that we can
5400 include with the free software. Many of our most important programs do
5401 not come with free reference manuals and free introductory texts.
5402 Documentation is an essential part of any software package; when an
5403 important free software package does not come with a free manual and a
5404 free tutorial, that is a major gap. We have many such gaps today.
5406 Consider Perl, for instance. The tutorial manuals that people
5407 normally use are non-free. How did this come about? Because the
5408 authors of those manuals published them with restrictive terms--no
5409 copying, no modification, source files not available--which exclude them
5410 from the free software world.
5412 That wasn't the first time this sort of thing happened, and it was
5413 far from the last. Many times we have heard a GNU user eagerly describe
5414 a manual that he is writing, his intended contribution to the community,
5415 only to learn that he had ruined everything by signing a publication
5416 contract to make it non-free.
5418 Free documentation, like free software, is a matter of freedom, not
5419 price. The problem with the non-free manual is not that publishers
5420 charge a price for printed copies--that in itself is fine. (The Free
5421 Software Foundation sells printed copies of manuals, too.) The problem
5422 is the restrictions on the use of the manual. Free manuals are
5423 available in source code form, and give you permission to copy and
5424 modify. Non-free manuals do not allow this.
5426 The criteria of freedom for a free manual are roughly the same as for
5427 free software. Redistribution (including the normal kinds of commercial
5428 redistribution) must be permitted, so that the manual can accompany
5429 every copy of the program, both on-line and on paper.
5431 Permission for modification of the technical content is crucial too.
5432 When people modify the software, adding or changing features, if they
5433 are conscientious they will change the manual too--so they can provide
5434 accurate and clear documentation for the modified program. A manual
5435 that leaves you no choice but to write a new manual to document a
5436 changed version of the program is not really available to our community.
5438 Some kinds of limits on the way modification is handled are
5439 acceptable. For example, requirements to preserve the original author's
5440 copyright notice, the distribution terms, or the list of authors, are
5441 ok. It is also no problem to require modified versions to include
5442 notice that they were modified. Even entire sections that may not be
5443 deleted or changed are acceptable, as long as they deal with
5444 nontechnical topics (like this one). These kinds of restrictions are
5445 acceptable because they don't obstruct the community's normal use of the
5448 However, it must be possible to modify all the _technical_ content of
5449 the manual, and then distribute the result in all the usual media,
5450 through all the usual channels. Otherwise, the restrictions obstruct
5451 the use of the manual, it is not free, and we need another manual to
5454 Please spread the word about this issue. Our community continues to
5455 lose manuals to proprietary publishing. If we spread the word that free
5456 software needs free reference manuals and free tutorials, perhaps the
5457 next person who wants to contribute by writing documentation will
5458 realize, before it is too late, that only free manuals contribute to the
5459 free software community.
5461 If you are writing documentation, please insist on publishing it
5462 under the GNU Free Documentation License or another free documentation
5463 license. Remember that this decision requires your approval--you don't
5464 have to let the publisher decide. Some commercial publishers will use a
5465 free license if you insist, but they will not propose the option; it is
5466 up to you to raise the issue and say firmly that this is what you want.
5467 If the publisher you are dealing with refuses, please try other
5468 publishers. If you're not sure whether a proposed license is free,
5469 write to <licensing@gnu.org>.
5471 You can encourage commercial publishers to sell more free, copylefted
5472 manuals and tutorials by buying them, and particularly by buying copies
5473 from the publishers that paid for their writing or for major
5474 improvements. Meanwhile, try to avoid buying non-free documentation at
5475 all. Check the distribution terms of a manual before you buy it, and
5476 insist that whoever seeks your business must respect your freedom.
5477 Check the history of the book, and try reward the publishers that have
5478 paid or pay the authors to work on it.
5480 The Free Software Foundation maintains a list of free documentation
5481 published by other publishers, at
5482 <http://www.fsf.org/doc/other-free-books.html>.
5485 File: tar.info, Node: GNU Free Documentation License, Next: Index of Command Line Options, Prev: Free Software Needs Free Documentation, Up: Top
5487 Appendix G GNU Free Documentation License
5488 *****************************************
5490 Version 1.3, 3 November 2008
5492 Copyright (C) 2000-2002, 2007-2008, 2014, 2016 Free Software
5496 Everyone is permitted to copy and distribute verbatim copies
5497 of this license document, but changing it is not allowed.
5501 The purpose of this License is to make a manual, textbook, or other
5502 functional and useful document "free" in the sense of freedom: to
5503 assure everyone the effective freedom to copy and redistribute it,
5504 with or without modifying it, either commercially or
5505 noncommercially. Secondarily, this License preserves for the
5506 author and publisher a way to get credit for their work, while not
5507 being considered responsible for modifications made by others.
5509 This License is a kind of "copyleft", which means that derivative
5510 works of the document must themselves be free in the same sense.
5511 It complements the GNU General Public License, which is a copyleft
5512 license designed for free software.
5514 We have designed this License in order to use it for manuals for
5515 free software, because free software needs free documentation: a
5516 free program should come with manuals providing the same freedoms
5517 that the software does. But this License is not limited to
5518 software manuals; it can be used for any textual work, regardless
5519 of subject matter or whether it is published as a printed book. We
5520 recommend this License principally for works whose purpose is
5521 instruction or reference.
5523 1. APPLICABILITY AND DEFINITIONS
5525 This License applies to any manual or other work, in any medium,
5526 that contains a notice placed by the copyright holder saying it can
5527 be distributed under the terms of this License. Such a notice
5528 grants a world-wide, royalty-free license, unlimited in duration,
5529 to use that work under the conditions stated herein. The
5530 "Document", below, refers to any such manual or work. Any member
5531 of the public is a licensee, and is addressed as "you". You accept
5532 the license if you copy, modify or distribute the work in a way
5533 requiring permission under copyright law.
5535 A "Modified Version" of the Document means any work containing the
5536 Document or a portion of it, either copied verbatim, or with
5537 modifications and/or translated into another language.
5539 A "Secondary Section" is a named appendix or a front-matter section
5540 of the Document that deals exclusively with the relationship of the
5541 publishers or authors of the Document to the Document's overall
5542 subject (or to related matters) and contains nothing that could
5543 fall directly within that overall subject. (Thus, if the Document
5544 is in part a textbook of mathematics, a Secondary Section may not
5545 explain any mathematics.) The relationship could be a matter of
5546 historical connection with the subject or with related matters, or
5547 of legal, commercial, philosophical, ethical or political position
5550 The "Invariant Sections" are certain Secondary Sections whose
5551 titles are designated, as being those of Invariant Sections, in the
5552 notice that says that the Document is released under this License.
5553 If a section does not fit the above definition of Secondary then it
5554 is not allowed to be designated as Invariant. The Document may
5555 contain zero Invariant Sections. If the Document does not identify
5556 any Invariant Sections then there are none.
5558 The "Cover Texts" are certain short passages of text that are
5559 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
5560 that says that the Document is released under this License. A
5561 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
5562 be at most 25 words.
5564 A "Transparent" copy of the Document means a machine-readable copy,
5565 represented in a format whose specification is available to the
5566 general public, that is suitable for revising the document
5567 straightforwardly with generic text editors or (for images composed
5568 of pixels) generic paint programs or (for drawings) some widely
5569 available drawing editor, and that is suitable for input to text
5570 formatters or for automatic translation to a variety of formats
5571 suitable for input to text formatters. A copy made in an otherwise
5572 Transparent file format whose markup, or absence of markup, has
5573 been arranged to thwart or discourage subsequent modification by
5574 readers is not Transparent. An image format is not Transparent if
5575 used for any substantial amount of text. A copy that is not
5576 "Transparent" is called "Opaque".
5578 Examples of suitable formats for Transparent copies include plain
5579 ASCII without markup, Texinfo input format, LaTeX input format,
5580 SGML or XML using a publicly available DTD, and standard-conforming
5581 simple HTML, PostScript or PDF designed for human modification.
5582 Examples of transparent image formats include PNG, XCF and JPG.
5583 Opaque formats include proprietary formats that can be read and
5584 edited only by proprietary word processors, SGML or XML for which
5585 the DTD and/or processing tools are not generally available, and
5586 the machine-generated HTML, PostScript or PDF produced by some word
5587 processors for output purposes only.
5589 The "Title Page" means, for a printed book, the title page itself,
5590 plus such following pages as are needed to hold, legibly, the
5591 material this License requires to appear in the title page. For
5592 works in formats which do not have any title page as such, "Title
5593 Page" means the text near the most prominent appearance of the
5594 work's title, preceding the beginning of the body of the text.
5596 The "publisher" means any person or entity that distributes copies
5597 of the Document to the public.
5599 A section "Entitled XYZ" means a named subunit of the Document
5600 whose title either is precisely XYZ or contains XYZ in parentheses
5601 following text that translates XYZ in another language. (Here XYZ
5602 stands for a specific section name mentioned below, such as
5603 "Acknowledgements", "Dedications", "Endorsements", or "History".)
5604 To "Preserve the Title" of such a section when you modify the
5605 Document means that it remains a section "Entitled XYZ" according
5608 The Document may include Warranty Disclaimers next to the notice
5609 which states that this License applies to the Document. These
5610 Warranty Disclaimers are considered to be included by reference in
5611 this License, but only as regards disclaiming warranties: any other
5612 implication that these Warranty Disclaimers may have is void and
5613 has no effect on the meaning of this License.
5617 You may copy and distribute the Document in any medium, either
5618 commercially or noncommercially, provided that this License, the
5619 copyright notices, and the license notice saying this License
5620 applies to the Document are reproduced in all copies, and that you
5621 add no other conditions whatsoever to those of this License. You
5622 may not use technical measures to obstruct or control the reading
5623 or further copying of the copies you make or distribute. However,
5624 you may accept compensation in exchange for copies. If you
5625 distribute a large enough number of copies you must also follow the
5626 conditions in section 3.
5628 You may also lend copies, under the same conditions stated above,
5629 and you may publicly display copies.
5631 3. COPYING IN QUANTITY
5633 If you publish printed copies (or copies in media that commonly
5634 have printed covers) of the Document, numbering more than 100, and
5635 the Document's license notice requires Cover Texts, you must
5636 enclose the copies in covers that carry, clearly and legibly, all
5637 these Cover Texts: Front-Cover Texts on the front cover, and
5638 Back-Cover Texts on the back cover. Both covers must also clearly
5639 and legibly identify you as the publisher of these copies. The
5640 front cover must present the full title with all words of the title
5641 equally prominent and visible. You may add other material on the
5642 covers in addition. Copying with changes limited to the covers, as
5643 long as they preserve the title of the Document and satisfy these
5644 conditions, can be treated as verbatim copying in other respects.
5646 If the required texts for either cover are too voluminous to fit
5647 legibly, you should put the first ones listed (as many as fit
5648 reasonably) on the actual cover, and continue the rest onto
5651 If you publish or distribute Opaque copies of the Document
5652 numbering more than 100, you must either include a machine-readable
5653 Transparent copy along with each Opaque copy, or state in or with
5654 each Opaque copy a computer-network location from which the general
5655 network-using public has access to download using public-standard
5656 network protocols a complete Transparent copy of the Document, free
5657 of added material. If you use the latter option, you must take
5658 reasonably prudent steps, when you begin distribution of Opaque
5659 copies in quantity, to ensure that this Transparent copy will
5660 remain thus accessible at the stated location until at least one
5661 year after the last time you distribute an Opaque copy (directly or
5662 through your agents or retailers) of that edition to the public.
5664 It is requested, but not required, that you contact the authors of
5665 the Document well before redistributing any large number of copies,
5666 to give them a chance to provide you with an updated version of the
5671 You may copy and distribute a Modified Version of the Document
5672 under the conditions of sections 2 and 3 above, provided that you
5673 release the Modified Version under precisely this License, with the
5674 Modified Version filling the role of the Document, thus licensing
5675 distribution and modification of the Modified Version to whoever
5676 possesses a copy of it. In addition, you must do these things in
5677 the Modified Version:
5679 A. Use in the Title Page (and on the covers, if any) a title
5680 distinct from that of the Document, and from those of previous
5681 versions (which should, if there were any, be listed in the
5682 History section of the Document). You may use the same title
5683 as a previous version if the original publisher of that
5684 version gives permission.
5686 B. List on the Title Page, as authors, one or more persons or
5687 entities responsible for authorship of the modifications in
5688 the Modified Version, together with at least five of the
5689 principal authors of the Document (all of its principal
5690 authors, if it has fewer than five), unless they release you
5691 from this requirement.
5693 C. State on the Title page the name of the publisher of the
5694 Modified Version, as the publisher.
5696 D. Preserve all the copyright notices of the Document.
5698 E. Add an appropriate copyright notice for your modifications
5699 adjacent to the other copyright notices.
5701 F. Include, immediately after the copyright notices, a license
5702 notice giving the public permission to use the Modified
5703 Version under the terms of this License, in the form shown in
5706 G. Preserve in that license notice the full lists of Invariant
5707 Sections and required Cover Texts given in the Document's
5710 H. Include an unaltered copy of this License.
5712 I. Preserve the section Entitled "History", Preserve its Title,
5713 and add to it an item stating at least the title, year, new
5714 authors, and publisher of the Modified Version as given on the
5715 Title Page. If there is no section Entitled "History" in the
5716 Document, create one stating the title, year, authors, and
5717 publisher of the Document as given on its Title Page, then add
5718 an item describing the Modified Version as stated in the
5721 J. Preserve the network location, if any, given in the Document
5722 for public access to a Transparent copy of the Document, and
5723 likewise the network locations given in the Document for
5724 previous versions it was based on. These may be placed in the
5725 "History" section. You may omit a network location for a work
5726 that was published at least four years before the Document
5727 itself, or if the original publisher of the version it refers
5728 to gives permission.
5730 K. For any section Entitled "Acknowledgements" or "Dedications",
5731 Preserve the Title of the section, and preserve in the section
5732 all the substance and tone of each of the contributor
5733 acknowledgements and/or dedications given therein.
5735 L. Preserve all the Invariant Sections of the Document, unaltered
5736 in their text and in their titles. Section numbers or the
5737 equivalent are not considered part of the section titles.
5739 M. Delete any section Entitled "Endorsements". Such a section
5740 may not be included in the Modified Version.
5742 N. Do not retitle any existing section to be Entitled
5743 "Endorsements" or to conflict in title with any Invariant
5746 O. Preserve any Warranty Disclaimers.
5748 If the Modified Version includes new front-matter sections or
5749 appendices that qualify as Secondary Sections and contain no
5750 material copied from the Document, you may at your option designate
5751 some or all of these sections as invariant. To do this, add their
5752 titles to the list of Invariant Sections in the Modified Version's
5753 license notice. These titles must be distinct from any other
5756 You may add a section Entitled "Endorsements", provided it contains
5757 nothing but endorsements of your Modified Version by various
5758 parties--for example, statements of peer review or that the text
5759 has been approved by an organization as the authoritative
5760 definition of a standard.
5762 You may add a passage of up to five words as a Front-Cover Text,
5763 and a passage of up to 25 words as a Back-Cover Text, to the end of
5764 the list of Cover Texts in the Modified Version. Only one passage
5765 of Front-Cover Text and one of Back-Cover Text may be added by (or
5766 through arrangements made by) any one entity. If the Document
5767 already includes a cover text for the same cover, previously added
5768 by you or by arrangement made by the same entity you are acting on
5769 behalf of, you may not add another; but you may replace the old
5770 one, on explicit permission from the previous publisher that added
5773 The author(s) and publisher(s) of the Document do not by this
5774 License give permission to use their names for publicity for or to
5775 assert or imply endorsement of any Modified Version.
5777 5. COMBINING DOCUMENTS
5779 You may combine the Document with other documents released under
5780 this License, under the terms defined in section 4 above for
5781 modified versions, provided that you include in the combination all
5782 of the Invariant Sections of all of the original documents,
5783 unmodified, and list them all as Invariant Sections of your
5784 combined work in its license notice, and that you preserve all
5785 their Warranty Disclaimers.
5787 The combined work need only contain one copy of this License, and
5788 multiple identical Invariant Sections may be replaced with a single
5789 copy. If there are multiple Invariant Sections with the same name
5790 but different contents, make the title of each such section unique
5791 by adding at the end of it, in parentheses, the name of the
5792 original author or publisher of that section if known, or else a
5793 unique number. Make the same adjustment to the section titles in
5794 the list of Invariant Sections in the license notice of the
5797 In the combination, you must combine any sections Entitled
5798 "History" in the various original documents, forming one section
5799 Entitled "History"; likewise combine any sections Entitled
5800 "Acknowledgements", and any sections Entitled "Dedications". You
5801 must delete all sections Entitled "Endorsements."
5803 6. COLLECTIONS OF DOCUMENTS
5805 You may make a collection consisting of the Document and other
5806 documents released under this License, and replace the individual
5807 copies of this License in the various documents with a single copy
5808 that is included in the collection, provided that you follow the
5809 rules of this License for verbatim copying of each of the documents
5810 in all other respects.
5812 You may extract a single document from such a collection, and
5813 distribute it individually under this License, provided you insert
5814 a copy of this License into the extracted document, and follow this
5815 License in all other respects regarding verbatim copying of that
5818 7. AGGREGATION WITH INDEPENDENT WORKS
5820 A compilation of the Document or its derivatives with other
5821 separate and independent documents or works, in or on a volume of a
5822 storage or distribution medium, is called an "aggregate" if the
5823 copyright resulting from the compilation is not used to limit the
5824 legal rights of the compilation's users beyond what the individual
5825 works permit. When the Document is included in an aggregate, this
5826 License does not apply to the other works in the aggregate which
5827 are not themselves derivative works of the Document.
5829 If the Cover Text requirement of section 3 is applicable to these
5830 copies of the Document, then if the Document is less than one half
5831 of the entire aggregate, the Document's Cover Texts may be placed
5832 on covers that bracket the Document within the aggregate, or the
5833 electronic equivalent of covers if the Document is in electronic
5834 form. Otherwise they must appear on printed covers that bracket
5835 the whole aggregate.
5839 Translation is considered a kind of modification, so you may
5840 distribute translations of the Document under the terms of section
5841 4. Replacing Invariant Sections with translations requires special
5842 permission from their copyright holders, but you may include
5843 translations of some or all Invariant Sections in addition to the
5844 original versions of these Invariant Sections. You may include a
5845 translation of this License, and all the license notices in the
5846 Document, and any Warranty Disclaimers, provided that you also
5847 include the original English version of this License and the
5848 original versions of those notices and disclaimers. In case of a
5849 disagreement between the translation and the original version of
5850 this License or a notice or disclaimer, the original version will
5853 If a section in the Document is Entitled "Acknowledgements",
5854 "Dedications", or "History", the requirement (section 4) to
5855 Preserve its Title (section 1) will typically require changing the
5860 You may not copy, modify, sublicense, or distribute the Document
5861 except as expressly provided under this License. Any attempt
5862 otherwise to copy, modify, sublicense, or distribute it is void,
5863 and will automatically terminate your rights under this License.
5865 However, if you cease all violation of this License, then your
5866 license from a particular copyright holder is reinstated (a)
5867 provisionally, unless and until the copyright holder explicitly and
5868 finally terminates your license, and (b) permanently, if the
5869 copyright holder fails to notify you of the violation by some
5870 reasonable means prior to 60 days after the cessation.
5872 Moreover, your license from a particular copyright holder is
5873 reinstated permanently if the copyright holder notifies you of the
5874 violation by some reasonable means, this is the first time you have
5875 received notice of violation of this License (for any work) from
5876 that copyright holder, and you cure the violation prior to 30 days
5877 after your receipt of the notice.
5879 Termination of your rights under this section does not terminate
5880 the licenses of parties who have received copies or rights from you
5881 under this License. If your rights have been terminated and not
5882 permanently reinstated, receipt of a copy of some or all of the
5883 same material does not give you any rights to use it.
5885 10. FUTURE REVISIONS OF THIS LICENSE
5887 The Free Software Foundation may publish new, revised versions of
5888 the GNU Free Documentation License from time to time. Such new
5889 versions will be similar in spirit to the present version, but may
5890 differ in detail to address new problems or concerns. See
5891 <http://www.gnu.org/copyleft/>.
5893 Each version of the License is given a distinguishing version
5894 number. If the Document specifies that a particular numbered
5895 version of this License "or any later version" applies to it, you
5896 have the option of following the terms and conditions either of
5897 that specified version or of any later version that has been
5898 published (not as a draft) by the Free Software Foundation. If the
5899 Document does not specify a version number of this License, you may
5900 choose any version ever published (not as a draft) by the Free
5901 Software Foundation. If the Document specifies that a proxy can
5902 decide which future versions of this License can be used, that
5903 proxy's public statement of acceptance of a version permanently
5904 authorizes you to choose that version for the Document.
5908 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
5909 World Wide Web server that publishes copyrightable works and also
5910 provides prominent facilities for anybody to edit those works. A
5911 public wiki that anybody can edit is an example of such a server.
5912 A "Massive Multiauthor Collaboration" (or "MMC") contained in the
5913 site means any set of copyrightable works thus published on the MMC
5916 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
5917 license published by Creative Commons Corporation, a not-for-profit
5918 corporation with a principal place of business in San Francisco,
5919 California, as well as future copyleft versions of that license
5920 published by that same organization.
5922 "Incorporate" means to publish or republish a Document, in whole or
5923 in part, as part of another Document.
5925 An MMC is "eligible for relicensing" if it is licensed under this
5926 License, and if all works that were first published under this
5927 License somewhere other than this MMC, and subsequently
5928 incorporated in whole or in part into the MMC, (1) had no cover
5929 texts or invariant sections, and (2) were thus incorporated prior
5930 to November 1, 2008.
5932 The operator of an MMC Site may republish an MMC contained in the
5933 site under CC-BY-SA on the same site at any time before August 1,
5934 2009, provided the MMC is eligible for relicensing.
5936 ADDENDUM: How to use this License for your documents
5937 ====================================================
5939 To use this License in a document you have written, include a copy of
5940 the License in the document and put the following copyright and license
5941 notices just after the title page:
5943 Copyright (C) YEAR YOUR NAME.
5944 Permission is granted to copy, distribute and/or modify this document
5945 under the terms of the GNU Free Documentation License, Version 1.3
5946 or any later version published by the Free Software Foundation;
5947 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
5948 Texts. A copy of the license is included in the section entitled ``GNU
5949 Free Documentation License''.
5951 If you have Invariant Sections, Front-Cover Texts and Back-Cover
5952 Texts, replace the "with...Texts." line with this:
5954 with the Invariant Sections being LIST THEIR TITLES, with
5955 the Front-Cover Texts being LIST, and with the Back-Cover Texts
5958 If you have Invariant Sections without Cover Texts, or some other
5959 combination of the three, merge those two alternatives to suit the
5962 If your document contains nontrivial examples of program code, we
5963 recommend releasing these examples in parallel under your choice of free
5964 software license, such as the GNU General Public License, to permit
5965 their use in free software.
5968 File: tar.info, Node: Index of Command Line Options, Next: Index, Prev: GNU Free Documentation License, Up: Top
5970 Appendix H Index of Command Line Options
5971 ****************************************
5973 This appendix contains an index of all GNU 'tar' long command line
5974 options. The options are listed without the preceding double-dash. For
5975 a cross-reference of short command line options, see *note Short Option
5981 * absolute-names: absolute. (line 10)
5982 * absolute-names, summary: Option Summary. (line 6)
5983 * acls, summary: Option Summary. (line 14)
5984 * add-file: files. (line 79)
5985 * after-date: after. (line 24)
5986 * after-date, summary: Option Summary. (line 17)
5987 * anchored: controlling pattern-matching.
5989 * anchored, summary: Option Summary. (line 21)
5990 * append: append. (line 6)
5991 * append <1>: appending files. (line 6)
5992 * append, summary: Operation Summary. (line 6)
5993 * atime-preserve: Attributes. (line 10)
5994 * atime-preserve, summary: Option Summary. (line 25)
5995 * auto-compress: gzip. (line 150)
5996 * auto-compress, summary: Option Summary. (line 71)
5997 * backup: backup. (line 41)
5998 * backup, summary: Option Summary. (line 78)
5999 * block-number: verbose. (line 112)
6000 * block-number, summary: Option Summary. (line 84)
6001 * blocking-factor: Blocking Factor. (line 8)
6002 * blocking-factor, summary: Option Summary. (line 91)
6003 * bzip2, summary: Option Summary. (line 97)
6004 * catenate: concatenate. (line 6)
6005 * catenate, summary: Operation Summary. (line 11)
6006 * check-device, described: Incremental Dumps. (line 107)
6007 * check-device, summary: Option Summary. (line 103)
6008 * check-links, described: hard links. (line 31)
6009 * check-links, summary: Option Summary. (line 155)
6010 * checkpoint: checkpoints. (line 6)
6011 * checkpoint, defined: checkpoints. (line 13)
6012 * checkpoint, summary: Option Summary. (line 108)
6013 * checkpoint-action: checkpoints. (line 6)
6014 * checkpoint-action, defined: checkpoints. (line 22)
6015 * checkpoint-action, summary: Option Summary. (line 117)
6016 * clamp-mtime, summary: Option Summary. (line 172)
6017 * compare: compare. (line 6)
6018 * compare, summary: Operation Summary. (line 16)
6019 * compress: gzip. (line 113)
6020 * compress, summary: Option Summary. (line 164)
6021 * concatenate: concatenate. (line 6)
6022 * concatenate, summary: Operation Summary. (line 23)
6023 * confirmation, summary: Option Summary. (line 176)
6024 * create, additional options: create options. (line 6)
6025 * create, complementary notes: Basic tar. (line 11)
6026 * create, introduced: Creating the archive.
6028 * create, summary: Operation Summary. (line 29)
6029 * create, using with '--verbose': create verbose. (line 6)
6030 * create, using with '--verify': verify. (line 24)
6031 * delay-directory-restore: Directory Modification Times and Permissions.
6033 * delay-directory-restore, summary: Option Summary. (line 180)
6034 * delete: delete. (line 6)
6035 * delete, summary: Operation Summary. (line 34)
6036 * delete, using before -append: append. (line 47)
6037 * dereference: dereference. (line 6)
6038 * dereference, summary: Option Summary. (line 186)
6039 * diff, summary: Operation Summary. (line 39)
6040 * directory: directory. (line 11)
6041 * directory, summary: Option Summary. (line 193)
6042 * exclude: exclude. (line 6)
6043 * exclude <1>: exclude. (line 9)
6044 * exclude, potential problems with: problems with exclude.
6046 * exclude, summary: Option Summary. (line 201)
6047 * exclude-backups: exclude. (line 114)
6048 * exclude-backups, summary: Option Summary. (line 206)
6049 * exclude-caches: exclude. (line 134)
6050 * exclude-caches, summary: Option Summary. (line 215)
6051 * exclude-caches-all: exclude. (line 142)
6052 * exclude-caches-all, summary: Option Summary. (line 230)
6053 * exclude-caches-under: exclude. (line 138)
6054 * exclude-caches-under, summary: Option Summary. (line 223)
6055 * exclude-from: exclude. (line 6)
6056 * exclude-from <1>: exclude. (line 20)
6057 * exclude-from, summary: Option Summary. (line 209)
6058 * exclude-ignore: exclude. (line 76)
6059 * exclude-ignore, summary: Option Summary. (line 235)
6060 * exclude-ignore-recursive: exclude. (line 81)
6061 * exclude-ignore-recursive, summary: Option Summary. (line 240)
6062 * exclude-tag: exclude. (line 151)
6063 * exclude-tag, summary: Option Summary. (line 245)
6064 * exclude-tag-all: exclude. (line 159)
6065 * exclude-tag-all, summary: Option Summary. (line 257)
6066 * exclude-tag-under: exclude. (line 155)
6067 * exclude-tag-under, summary: Option Summary. (line 251)
6068 * exclude-vcs: exclude. (line 85)
6069 * exclude-vcs, summary: Option Summary. (line 262)
6070 * exclude-vcs-ignores: exclude. (line 42)
6071 * exclude-vcs-ignores, summary: Option Summary. (line 269)
6072 * extract: extract. (line 6)
6073 * extract, additional options: extract options. (line 6)
6074 * extract, complementary notes: Basic tar. (line 49)
6075 * extract, summary: Operation Summary. (line 44)
6076 * extract, using with '--listed-incremental': Incremental Dumps.
6078 * file: file. (line 6)
6079 * file, short description: file. (line 15)
6080 * file, summary: Option Summary. (line 277)
6081 * file, tutorial: file tutorial. (line 6)
6082 * files-from: files. (line 14)
6083 * files-from, summary: Option Summary. (line 284)
6084 * force-local, short description: Device. (line 70)
6085 * force-local, summary: Option Summary. (line 291)
6086 * format, summary: Option Summary. (line 297)
6087 * full-time, summary: Option Summary. (line 322)
6088 * get, summary: Operation Summary. (line 50)
6089 * group: override. (line 99)
6090 * group, summary: Option Summary. (line 340)
6091 * group-map, summary: Option Summary. (line 350)
6092 * gunzip, summary: Option Summary. (line 360)
6093 * gzip: gzip. (line 91)
6094 * gzip, summary: Option Summary. (line 360)
6095 * hard-dereference, described: hard links. (line 59)
6096 * hard-dereference, summary: Option Summary. (line 369)
6097 * help: help tutorial. (line 6)
6098 * help, introduction: help. (line 26)
6099 * help, summary: Option Summary. (line 375)
6100 * hole-detection: sparse. (line 66)
6101 * hole-detection, summary: Option Summary. (line 381)
6102 * ignore-case: controlling pattern-matching.
6104 * ignore-case, summary: Option Summary. (line 386)
6105 * ignore-command-error: Writing to an External Program.
6107 * ignore-command-error, summary: Option Summary. (line 390)
6108 * ignore-failed-read: Ignore Failed Read. (line 7)
6109 * ignore-failed-read, summary: Option Summary. (line 394)
6110 * ignore-zeros: Ignore Zeros. (line 6)
6111 * ignore-zeros, short description: Blocking Factor. (line 152)
6112 * ignore-zeros, summary: Option Summary. (line 399)
6113 * incremental, summary: Option Summary. (line 405)
6114 * incremental, using with '--list': Incremental Dumps. (line 185)
6115 * index-file, summary: Option Summary. (line 413)
6116 * info-script: Multi-Volume Archives.
6118 * info-script, short description: Device. (line 121)
6119 * info-script, summary: Option Summary. (line 417)
6120 * interactive: interactive. (line 14)
6121 * interactive, summary: Option Summary. (line 426)
6122 * keep-directory-symlink, summary: Option Summary. (line 434)
6123 * keep-newer-files: Keep Newer Files. (line 6)
6124 * keep-newer-files, summary: Option Summary. (line 448)
6125 * keep-old-files: Keep Old Files. (line 9)
6126 * keep-old-files, introduced: Dealing with Old Files.
6128 * keep-old-files, summary: Option Summary. (line 453)
6129 * label: Tape Files. (line 6)
6130 * label <1>: label. (line 6)
6131 * label, summary: Option Summary. (line 462)
6132 * level, described: Incremental Dumps. (line 75)
6133 * level, summary: Option Summary. (line 470)
6134 * list: list. (line 6)
6135 * list, summary: Operation Summary. (line 55)
6136 * list, using with '--incremental': Incremental Dumps. (line 185)
6137 * list, using with '--listed-incremental': Incremental Dumps.
6139 * list, using with '--verbose': list. (line 34)
6140 * list, using with file name arguments: list. (line 25)
6141 * listed-incremental, described: Incremental Dumps. (line 14)
6142 * listed-incremental, summary: Option Summary. (line 480)
6143 * listed-incremental, using with '--extract': Incremental Dumps.
6145 * listed-incremental, using with '--list': Incremental Dumps.
6147 * lzip: gzip. (line 104)
6148 * lzip, summary: Option Summary. (line 489)
6149 * lzma: gzip. (line 107)
6150 * lzma, summary: Option Summary. (line 494)
6151 * lzop: gzip. (line 110)
6152 * mode: override. (line 14)
6153 * mode, summary: Option Summary. (line 504)
6154 * mtime: override. (line 30)
6155 * mtime, summary: Option Summary. (line 511)
6156 * multi-volume: Multi-Volume Archives.
6158 * multi-volume, short description: Device. (line 88)
6159 * multi-volume, summary: Option Summary. (line 526)
6160 * new-volume-script: Multi-Volume Archives.
6162 * new-volume-script, short description: Device. (line 121)
6163 * new-volume-script, summary: Option Summary. (line 417)
6164 * new-volume-script, summary <1>: Option Summary. (line 532)
6165 * newer: after. (line 24)
6166 * newer, summary: Option Summary. (line 536)
6167 * newer-mtime: after. (line 35)
6168 * newer-mtime, summary: Option Summary. (line 545)
6169 * no-acls, summary: Option Summary. (line 551)
6170 * no-anchored: controlling pattern-matching.
6172 * no-anchored, summary: Option Summary. (line 555)
6173 * no-auto-compress, summary: Option Summary. (line 559)
6174 * no-check-device, described: Incremental Dumps. (line 103)
6175 * no-check-device, summary: Option Summary. (line 564)
6176 * no-delay-directory-restore: Directory Modification Times and Permissions.
6178 * no-delay-directory-restore, summary: Option Summary. (line 569)
6179 * no-ignore-case: controlling pattern-matching.
6181 * no-ignore-case, summary: Option Summary. (line 575)
6182 * no-ignore-command-error: Writing to an External Program.
6184 * no-ignore-command-error, summary: Option Summary. (line 578)
6185 * no-null, described: nul. (line 15)
6186 * no-null, summary: Option Summary. (line 582)
6187 * no-overwrite-dir, summary: Option Summary. (line 588)
6188 * no-quote-chars, summary: Option Summary. (line 593)
6189 * no-recursion: recurse. (line 11)
6190 * no-recursion, summary: Option Summary. (line 598)
6191 * no-same-owner: Attributes. (line 63)
6192 * no-same-owner, summary: Option Summary. (line 603)
6193 * no-same-permissions, summary: Option Summary. (line 610)
6194 * no-seek, summary: Option Summary. (line 616)
6195 * no-selinux, summary: Option Summary. (line 622)
6196 * no-unquote: Selecting Archive Members.
6198 * no-unquote, summary: Option Summary. (line 626)
6199 * no-verbatim-files-from: files. (line 75)
6200 * no-verbatim-files-from, summary: Option Summary. (line 630)
6201 * no-wildcards: controlling pattern-matching.
6203 * no-wildcards, summary: Option Summary. (line 644)
6204 * no-wildcards-match-slash: controlling pattern-matching.
6206 * no-wildcards-match-slash, summary: Option Summary. (line 647)
6207 * no-xattrs, summary: Option Summary. (line 650)
6208 * null, described: nul. (line 11)
6209 * null, summary: Option Summary. (line 654)
6210 * numeric-owner: Attributes. (line 69)
6211 * numeric-owner, summary: Option Summary. (line 667)
6212 * occurrence, described: append. (line 34)
6213 * occurrence, summary: Option Summary. (line 685)
6214 * old-archive, summary: Option Summary. (line 700)
6215 * one-file-system: one. (line 14)
6216 * one-file-system, summary: Option Summary. (line 703)
6217 * one-top-level, summary: Option Summary. (line 708)
6218 * overwrite: Overwrite Old Files.
6220 * overwrite, introduced: Dealing with Old Files.
6222 * overwrite, summary: Option Summary. (line 719)
6223 * overwrite-dir: Overwrite Old Files.
6225 * overwrite-dir, introduced: Dealing with Old Files.
6227 * overwrite-dir, summary: Option Summary. (line 724)
6228 * owner: override. (line 67)
6229 * owner, summary: Option Summary. (line 729)
6230 * owner-map, summary: Option Summary. (line 739)
6231 * pax-option: PAX keywords. (line 6)
6232 * pax-option, summary: Option Summary. (line 749)
6233 * portability, summary: Option Summary. (line 755)
6234 * posix, summary: Option Summary. (line 759)
6235 * preserve-order: Same Order. (line 6)
6236 * preserve-order, summary: Option Summary. (line 762)
6237 * preserve-permissions: Setting Access Permissions.
6239 * preserve-permissions, short description: Attributes. (line 109)
6240 * preserve-permissions, summary: Option Summary. (line 766)
6241 * quote-chars, summary: Option Summary. (line 777)
6242 * quoting-style: quoting styles. (line 38)
6243 * quoting-style, summary: Option Summary. (line 781)
6244 * read-full-records: Reading. (line 6)
6245 * read-full-records <1>: read full records. (line 6)
6246 * read-full-records, short description: Blocking Factor. (line 168)
6247 * read-full-records, summary: Option Summary. (line 788)
6248 * record-size, summary: Option Summary. (line 794)
6249 * recursion: recurse. (line 22)
6250 * recursion, summary: Option Summary. (line 802)
6251 * recursive-unlink: Recursive Unlink. (line 6)
6252 * recursive-unlink, summary: Option Summary. (line 807)
6253 * remove-files: remove files. (line 6)
6254 * remove-files, summary: Option Summary. (line 812)
6255 * restrict, summary: Option Summary. (line 817)
6256 * rmt-command, summary: Option Summary. (line 823)
6257 * rsh-command: Device. (line 73)
6258 * rsh-command, summary: Option Summary. (line 828)
6259 * same-order: Same Order. (line 6)
6260 * same-order, summary: Option Summary. (line 833)
6261 * same-owner: Attributes. (line 44)
6262 * same-owner, summary: Option Summary. (line 842)
6263 * same-permissions: Setting Access Permissions.
6265 * same-permissions, short description: Attributes. (line 109)
6266 * same-permissions, summary: Option Summary. (line 766)
6267 * same-permissions, summary <1>: Option Summary. (line 849)
6268 * seek, summary: Option Summary. (line 853)
6269 * selinux, summary: Option Summary. (line 863)
6270 * show-defaults: defaults. (line 6)
6271 * show-defaults, summary: Option Summary. (line 867)
6272 * show-omitted-dirs: verbose. (line 105)
6273 * show-omitted-dirs, summary: Option Summary. (line 880)
6274 * show-snapshot-field-ranges: Snapshot Files. (line 111)
6275 * show-snapshot-field-ranges, summary: Option Summary. (line 885)
6276 * show-stored-names: list. (line 68)
6277 * show-stored-names, summary: Option Summary. (line 891)
6278 * show-transformed-names: transform. (line 45)
6279 * show-transformed-names, summary: Option Summary. (line 891)
6280 * skip-old-files, introduced: Dealing with Old Files.
6282 * skip-old-files, summary: Option Summary. (line 900)
6283 * sort, summary: Option Summary. (line 913)
6284 * sparse: sparse. (line 24)
6285 * sparse, summary: Option Summary. (line 930)
6286 * sparse-version: sparse. (line 59)
6287 * sparse-version, summary: Option Summary. (line 936)
6288 * starting-file: Starting File. (line 6)
6289 * starting-file, summary: Option Summary. (line 942)
6290 * strip-components: transform. (line 25)
6291 * strip-components, summary: Option Summary. (line 949)
6292 * suffix: backup. (line 67)
6293 * suffix, summary: Option Summary. (line 960)
6294 * tape-length: Multi-Volume Archives.
6296 * tape-length, short description: Device. (line 96)
6297 * tape-length, summary: Option Summary. (line 965)
6298 * test-label: label. (line 35)
6299 * test-label, summary: Option Summary. (line 976)
6300 * to-command: Writing to an External Program.
6302 * to-command, summary: Option Summary. (line 981)
6303 * to-stdout: Writing to Standard Output.
6305 * to-stdout, summary: Option Summary. (line 986)
6306 * totals: verbose. (line 45)
6307 * totals, summary: Option Summary. (line 992)
6308 * touch: Data Modification Times.
6310 * touch <1>: Attributes. (line 33)
6311 * touch, summary: Option Summary. (line 998)
6312 * transform: transform. (line 74)
6313 * transform, summary: Option Summary. (line 1005)
6314 * uncompress: gzip. (line 113)
6315 * uncompress, summary: Option Summary. (line 164)
6316 * uncompress, summary <1>: Option Summary. (line 1019)
6317 * ungzip: gzip. (line 91)
6318 * ungzip, summary: Option Summary. (line 360)
6319 * ungzip, summary <1>: Option Summary. (line 1023)
6320 * unlink-first: Unlink First. (line 6)
6321 * unlink-first, introduced: Dealing with Old Files.
6323 * unlink-first, summary: Option Summary. (line 1027)
6324 * unquote: Selecting Archive Members.
6326 * unquote, summary: Option Summary. (line 1033)
6327 * update: update. (line 6)
6328 * update <1>: how to update. (line 6)
6329 * update, summary: Operation Summary. (line 60)
6330 * usage: help. (line 53)
6331 * use-compress-program: gzip. (line 172)
6332 * use-compress-program, summary: Option Summary. (line 1037)
6333 * utc, summary: Option Summary. (line 1043)
6334 * verbatim-files-from: files. (line 70)
6335 * verbatim-files-from, summary: Option Summary. (line 1048)
6336 * verbose: verbose. (line 18)
6337 * verbose, introduced: verbose tutorial. (line 6)
6338 * verbose, summary: Option Summary. (line 1070)
6339 * verbose, using with '--create': create verbose. (line 6)
6340 * verbose, using with '--list': list. (line 34)
6341 * verify, short description: verify. (line 8)
6342 * verify, summary: Option Summary. (line 1078)
6343 * verify, using with '--create': verify. (line 24)
6344 * version: help. (line 6)
6345 * version, summary: Option Summary. (line 1084)
6346 * volno-file: Multi-Volume Archives.
6348 * volno-file, summary: Option Summary. (line 1090)
6349 * warning, explained: warnings. (line 12)
6350 * warning, summary: Option Summary. (line 1096)
6351 * wildcards: controlling pattern-matching.
6353 * wildcards, summary: Option Summary. (line 1102)
6354 * wildcards-match-slash: controlling pattern-matching.
6356 * wildcards-match-slash, summary: Option Summary. (line 1106)
6357 * xattrs, summary: Option Summary. (line 1109)
6358 * xattrs-exclude, summary: Option Summary. (line 1113)
6359 * xattrs-include, summary: Option Summary. (line 1117)
6360 * xform: transform. (line 74)
6361 * xform, summary: Option Summary. (line 1005)
6362 * xz: gzip. (line 96)
6363 * xz, summary: Option Summary. (line 1123)
6366 File: tar.info, Node: Index, Prev: Index of Command Line Options, Up: Top
6374 * '%s: Directory has been renamed from %s', warning message: warnings.
6376 * '%s: Directory has been renamed', warning message: warnings.
6378 * '%s: Directory is new', warning message: warnings. (line 98)
6379 * '%s: directory is on a different device: not purging', warning message: warnings.
6381 * '%s: skipping existing file', warning message: warnings. (line 62)
6382 * -after-date and -update compared: after. (line 19)
6383 * -newer-mtime and -update compared: after. (line 19)
6384 * -quite, option: Generate Mode. (line 120)
6385 * .bzrignore: exclude. (line 63)
6386 * .cvsignore: exclude. (line 50)
6387 * .gitignore: exclude. (line 55)
6388 * .hgignore: exclude. (line 70)
6389 * 'A lone zero block at', warning message: warnings. (line 33)
6390 * abbreviations for months: Calendar date items. (line 38)
6391 * absolute file names: absolute. (line 6)
6392 * absolute file names <1>: Remote Tape Server. (line 17)
6393 * Adding archives to an archive: concatenate. (line 6)
6394 * Adding files to an Archive: appending files. (line 6)
6395 * ADMINISTRATOR: General-Purpose Variables.
6397 * Age, excluding files by: after. (line 6)
6398 * ago in date strings: Relative items in date strings.
6400 * all: warnings. (line 28)
6401 * alone-zero-block: warnings. (line 33)
6402 * alternative decompression programs: gzip. (line 54)
6403 * am in date strings: Time of day items. (line 21)
6404 * Appending files to an Archive: appending files. (line 6)
6405 * appending files to existing archive: append. (line 6)
6406 * Arch, excluding files: exclude. (line 85)
6407 * archive: Definitions. (line 6)
6408 * Archive creation: file. (line 34)
6409 * archive member: Definitions. (line 15)
6410 * Archive Name: file. (line 6)
6411 * Archive, creation of: create. (line 6)
6412 * Archives, Appending files to: appending files. (line 6)
6413 * archives, binary equivalent: PAX keywords. (line 136)
6414 * Archiving Directories: create dir. (line 6)
6415 * archiving files: Top. (line 23)
6416 * ARGP_HELP_FMT, environment variable: Configuring Help Summary.
6418 * arguments to long options: Long Options. (line 31)
6419 * arguments to old options: Old Options. (line 26)
6420 * arguments to short options: Short Options. (line 13)
6421 * 'Attempting extraction of symbolic links as hard links', warning message: warnings.
6423 * attributes, files: Attributes. (line 6)
6424 * authors of 'parse_datetime': Authors of parse_datetime.
6426 * Avoiding recursion in directories: recurse. (line 6)
6427 * backup options: backup. (line 6)
6428 * backup suffix: backup. (line 67)
6429 * backups: backup. (line 41)
6430 * backups <1>: Backups. (line 6)
6431 * BACKUP_DIRS: General-Purpose Variables.
6433 * BACKUP_FILES: General-Purpose Variables.
6435 * BACKUP_HOUR: General-Purpose Variables.
6437 * bad-dumpdir: warnings. (line 102)
6438 * basic operations: Operations. (line 6)
6439 * Bazaar, excluding files: exclude. (line 85)
6440 * Bazaar, ignore files: exclude. (line 37)
6441 * beginning of time, for POSIX: Seconds since the Epoch.
6443 * 'bell', checkpoint action: checkpoints. (line 106)
6444 * Bellovin, Steven M.: Authors of parse_datetime.
6446 * Berets, Jim: Authors of parse_datetime.
6448 * Berry, K.: Authors of parse_datetime.
6450 * binary equivalent archives, creating: PAX keywords. (line 136)
6451 * block: Blocking. (line 6)
6452 * Block number where error occurred: verbose. (line 112)
6453 * BLOCKING: General-Purpose Variables.
6455 * Blocking Factor: Blocking Factor. (line 6)
6456 * blocking factor: Blocking Factor. (line 189)
6457 * Blocks per record: Blocking Factor. (line 6)
6458 * bug reports: Reports. (line 6)
6459 * Bytes per record: Blocking Factor. (line 6)
6460 * bzip2: gzip. (line 6)
6461 * cachedir: warnings. (line 40)
6462 * calendar date item: Calendar date items. (line 6)
6463 * case, ignored in dates: General date syntax. (line 60)
6464 * 'cat' vs 'concatenate': concatenate. (line 63)
6465 * Changing directory mid-stream: directory. (line 6)
6466 * Character class, excluding characters from: wildcards. (line 34)
6467 * checkpoints, defined: checkpoints. (line 6)
6468 * Choosing an archive file: file. (line 6)
6469 * combined date and time of day item: Combined date and time of day items.
6471 * comments, in dates: General date syntax. (line 60)
6472 * compress: gzip. (line 6)
6473 * Compressed archives: gzip. (line 6)
6474 * 'concatenate' vs 'cat': concatenate. (line 63)
6475 * Concatenating Archives: concatenate. (line 6)
6476 * 'contains a cache directory tag', warning message: warnings.
6478 * contiguous-cast: warnings. (line 66)
6479 * corrupted archives: Full Dumps. (line 8)
6480 * corrupted archives <1>: gzip. (line 140)
6481 * Creation of the archive: create. (line 6)
6482 * 'Current %s is newer or same age', warning message: warnings.
6484 * CVS, excluding files: exclude. (line 85)
6485 * CVS, ignore files: exclude. (line 37)
6486 * Darcs, excluding files: exclude. (line 85)
6487 * DAT blocking: Blocking Factor. (line 199)
6488 * Data Modification time, excluding files by: after. (line 6)
6489 * Data modification times of extracted files: Data Modification Times.
6491 * date and time of day format, ISO 8601: Combined date and time of day items.
6493 * date format, ISO 8601: Calendar date items. (line 30)
6494 * date input formats: Date input formats. (line 6)
6495 * day in date strings: Relative items in date strings.
6497 * day in date strings <1>: Relative items in date strings.
6499 * day of week item: Day of week items. (line 6)
6500 * decompress-program: warnings. (line 76)
6501 * Deleting files from an archive: delete. (line 6)
6502 * Deleting from tape archives: delete. (line 17)
6503 * dereferencing hard links: hard links. (line 6)
6504 * Descending directories, avoiding: recurse. (line 6)
6505 * Device numbers, changing: Fixing Snapshot Files.
6507 * Device numbers, using in incremental backups: Incremental Dumps.
6509 * Directories, Archiving: create dir. (line 6)
6510 * Directories, avoiding recursion: recurse. (line 6)
6511 * Directory, changing mid-stream: directory. (line 6)
6512 * DIRLIST: General-Purpose Variables.
6514 * displacement of dates: Relative items in date strings.
6516 * doc-opt-col: Configuring Help Summary.
6518 * 'door ignored', warning message: warnings. (line 45)
6519 * 'dot', checkpoint action: checkpoints. (line 130)
6520 * Double-checking a write operation: verify. (line 6)
6521 * dumps, full: Full Dumps. (line 8)
6522 * DUMP_BEGIN: User Hooks. (line 31)
6523 * DUMP_END: User Hooks. (line 35)
6524 * DUMP_REMIND_SCRIPT: General-Purpose Variables.
6526 * dup-args: Configuring Help Summary.
6528 * dup-args-note: Configuring Help Summary.
6530 * 'echo', checkpoint action: checkpoints. (line 25)
6531 * Eggert, Paul: Authors of parse_datetime.
6533 * End-of-archive blocks, ignoring: Ignore Zeros. (line 6)
6534 * End-of-archive info script: Multi-Volume Archives.
6536 * entry: Naming tar Archives. (line 11)
6537 * epoch, for POSIX: Seconds since the Epoch.
6539 * Error message, block number of: verbose. (line 122)
6540 * Exabyte blocking: Blocking Factor. (line 199)
6541 * exclude: exclude. (line 12)
6542 * exclude-caches: exclude. (line 122)
6543 * exclude-from: exclude. (line 25)
6544 * exclude-tag: exclude. (line 145)
6545 * Excluding characters from a character class: wildcards. (line 34)
6546 * Excluding file by age: after. (line 6)
6547 * Excluding files by file system: exclude. (line 6)
6548 * Excluding files by name and pattern: exclude. (line 6)
6549 * Exec Mode, 'genfile': Exec Mode. (line 6)
6550 * 'exec', checkpoint action: checkpoints. (line 151)
6551 * existing backup method: backup. (line 59)
6552 * existing-file: warnings. (line 62)
6553 * exit status: Synopsis. (line 67)
6554 * 'Extracting contiguous files as regular files', warning message: warnings.
6556 * extracting Nth copy of the file: append. (line 34)
6557 * extraction: Definitions. (line 22)
6558 * Extraction: extract. (line 6)
6559 * file archival: Top. (line 23)
6560 * file attributes: Attributes. (line 6)
6561 * 'file changed as we read it', warning message: warnings. (line 55)
6562 * 'file is on a different filesystem', warning message: warnings.
6564 * 'file is the archive; not dumped', warning message: warnings.
6566 * 'file is the archive; not dumped', warning message <1>: warnings.
6568 * 'file is unchanged; not dumped', warning message: warnings. (line 49)
6569 * File lists separated by NUL characters: Generate Mode. (line 33)
6570 * file name: Definitions. (line 15)
6571 * File Name arguments, alternatives: files. (line 6)
6572 * File name arguments, using '--list' with: list. (line 25)
6573 * 'file name read contains nul character', warning message: warnings.
6575 * file names, absolute: absolute. (line 6)
6576 * File names, excluding files by: exclude. (line 6)
6577 * File names, terminated by 'NUL': nul. (line 6)
6578 * File names, using hard links: hard links. (line 6)
6579 * File names, using symbolic links: dereference. (line 6)
6580 * 'File removed before we read it', warning message: warnings.
6582 * 'File shrank by %s bytes', warning message: warnings. (line 41)
6583 * File system boundaries, not crossing: one. (line 6)
6584 * file-changed: warnings. (line 55)
6585 * file-ignored: warnings. (line 45)
6586 * file-removed: warnings. (line 53)
6587 * file-shrank: warnings. (line 41)
6588 * file-unchanged: warnings. (line 49)
6589 * FILELIST: General-Purpose Variables.
6591 * filename-with-nuls: warnings. (line 31)
6592 * 'find', using with 'tar': files. (line 6)
6593 * 'find', using with 'tar' <1>: recurse. (line 11)
6594 * first in date strings: General date syntax. (line 22)
6595 * format 0, snapshot file: Snapshot Files. (line 24)
6596 * format 1, snapshot file: Snapshot Files. (line 51)
6597 * format 2, snapshot file: Snapshot Files. (line 73)
6598 * Format Options: Format Variations. (line 6)
6599 * Format Parameters: Format Variations. (line 6)
6600 * Format, old style: old. (line 6)
6601 * fortnight in date strings: Relative items in date strings.
6603 * free documentation: Free Software Needs Free Documentation.
6605 * full dumps: Full Dumps. (line 8)
6606 * future time stamps: Large or Negative Values.
6608 * general date syntax: General date syntax. (line 6)
6609 * Generate Mode, 'genfile': Generate Mode. (line 6)
6610 * genfile: Genfile. (line 6)
6611 * 'genfile', create file: Generate Mode. (line 6)
6612 * 'genfile', creating sparse files: Generate Mode. (line 55)
6613 * 'genfile', generate mode: Generate Mode. (line 6)
6614 * 'genfile', reading a list of file names: Generate Mode. (line 22)
6615 * 'genfile', seeking to a given offset: Generate Mode. (line 18)
6616 * Getting program version number: help. (line 6)
6617 * git, excluding files: exclude. (line 85)
6618 * Git, ignore files: exclude. (line 37)
6619 * GNU archive format: gnu. (line 6)
6620 * GNU.sparse.major, extended header variable: PAX 1. (line 14)
6621 * GNU.sparse.map, extended header variable: PAX 0. (line 59)
6622 * GNU.sparse.minor, extended header variable: PAX 1. (line 17)
6623 * GNU.sparse.name, extended header variable: PAX 0. (line 67)
6624 * GNU.sparse.name, extended header variable, in v.1.0: PAX 1. (line 24)
6625 * GNU.sparse.numblocks, extended header variable: PAX 0. (line 14)
6626 * GNU.sparse.numbytes, extended header variable: PAX 0. (line 20)
6627 * GNU.sparse.offset, extended header variable: PAX 0. (line 17)
6628 * GNU.sparse.realsize, extended header variable: PAX 1. (line 24)
6629 * GNU.sparse.size, extended header variable: PAX 0. (line 10)
6630 * gnupg, using with tar: gzip. (line 196)
6631 * gpg, using with tar: gzip. (line 196)
6632 * gzip: gzip. (line 6)
6633 * hard links, dereferencing: hard links. (line 6)
6634 * header-col: Configuring Help Summary.
6636 * hole detection: sparse. (line 66)
6637 * hook: User Hooks. (line 12)
6638 * hour in date strings: Relative items in date strings.
6640 * ignore-archive: warnings. (line 51)
6641 * ignore-archive <1>: warnings. (line 51)
6642 * ignore-newer: warnings. (line 72)
6643 * Ignoring end-of-archive blocks: Ignore Zeros. (line 6)
6644 * 'Ignoring unknown extended header keyword '%s'', warning message: warnings.
6646 * 'implausibly old time stamp %s', warning message: warnings. (line 63)
6647 * Info script: Multi-Volume Archives.
6649 * Interactive operation: interactive. (line 6)
6650 * ISO 8601 date and time of day format: Combined date and time of day items.
6652 * ISO 8601 date format: Calendar date items. (line 30)
6653 * items in date strings: General date syntax. (line 6)
6654 * Labeling an archive: label. (line 6)
6655 * labeling archives: Tape Files. (line 6)
6656 * Labeling multi-volume archives: label. (line 6)
6657 * Labels on the archive media: label. (line 6)
6658 * language, in dates: General date syntax. (line 36)
6659 * language, in dates <1>: General date syntax. (line 40)
6660 * Large lists of file names on small machines: Same Order. (line 6)
6661 * large values: Large or Negative Values.
6663 * last DAY: Day of week items. (line 15)
6664 * last in date strings: General date syntax. (line 22)
6665 * Laszlo Ersek: lbzip2. (line 6)
6666 * lbzip2: lbzip2. (line 6)
6667 * leap seconds: General date syntax. (line 65)
6668 * leap seconds <1>: Time of day items. (line 14)
6669 * leap seconds <2>: Seconds since the Epoch.
6671 * Listing all 'tar' options: help. (line 26)
6672 * listing member and file names: list. (line 45)
6673 * Listing volume label: label. (line 27)
6674 * Lists of file names: files. (line 6)
6675 * Local and remote archives: file. (line 70)
6676 * long options: Long Options. (line 6)
6677 * long options with mandatory arguments: Long Options. (line 31)
6678 * long options with optional arguments: Long Options. (line 39)
6679 * long-opt-col: Configuring Help Summary.
6681 * lzip: gzip. (line 6)
6682 * lzma: gzip. (line 6)
6683 * lzop: gzip. (line 6)
6684 * MacKenzie, David: Authors of parse_datetime.
6686 * 'Malformed dumpdir: 'X' never used', warning message: warnings.
6688 * member: Definitions. (line 15)
6689 * member name: Definitions. (line 15)
6690 * members, multiple: multiple. (line 6)
6691 * Members, replacing with other members: append. (line 47)
6692 * Mercurial, excluding files: exclude. (line 85)
6693 * Mercurial, ignore files: exclude. (line 37)
6694 * Meyering, Jim: Authors of parse_datetime.
6696 * Middle of the archive, starting in the: Starting File. (line 11)
6697 * midnight in date strings: Time of day items. (line 21)
6698 * minute in date strings: Relative items in date strings.
6700 * minutes, time zone correction by: Time of day items. (line 29)
6701 * Modes of extracted files: Setting Access Permissions.
6703 * Modification time, excluding files by: after. (line 6)
6704 * Modification times of extracted files: Data Modification Times.
6706 * month in date strings: Relative items in date strings.
6708 * month names in date strings: Calendar date items. (line 38)
6709 * months, written-out: General date syntax. (line 32)
6710 * MT: General-Purpose Variables.
6712 * MT_BEGIN: Magnetic Tape Control.
6714 * MT_OFFLINE: Magnetic Tape Control.
6716 * MT_REWIND: Magnetic Tape Control.
6718 * MT_STATUS: Magnetic Tape Control.
6720 * Multi-volume archives: Multi-Volume Archives.
6722 * Multi-volume archives in PAX format, extracting using non-GNU tars: Split Recovery.
6724 * Multi-volume archives, extracting using non-GNU tars: Split Recovery.
6726 * multiple members: multiple. (line 6)
6727 * Naming an archive: file. (line 6)
6728 * negative time stamps: Large or Negative Values.
6730 * new-directory: warnings. (line 98)
6731 * next DAY: Day of week items. (line 15)
6732 * next in date strings: General date syntax. (line 22)
6733 * none: warnings. (line 29)
6734 * noon in date strings: Time of day items. (line 21)
6735 * now in date strings: Relative items in date strings.
6737 * ntape device: Many. (line 6)
6738 * 'NUL'-terminated file names: nul. (line 6)
6739 * Number of blocks per record: Blocking Factor. (line 6)
6740 * Number of bytes per record: Blocking Factor. (line 6)
6741 * numbered backup method: backup. (line 55)
6742 * numbers, written-out: General date syntax. (line 22)
6743 * Obtaining help: help. (line 26)
6744 * Obtaining total status information: verbose. (line 45)
6745 * Old GNU archive format: gnu. (line 6)
6746 * Old GNU sparse format: Old GNU Format. (line 6)
6747 * old option style: Old Options. (line 6)
6748 * old options with mandatory arguments: Old Options. (line 26)
6749 * Old style archives: old. (line 6)
6750 * Old style format: old. (line 6)
6751 * opt-doc-col: Configuring Help Summary.
6753 * option syntax, traditional: Old Options. (line 6)
6754 * optional arguments to long options: Long Options. (line 39)
6755 * optional arguments to short options: Short Options. (line 22)
6756 * options for use with '--extract': extract options. (line 6)
6757 * Options when reading archives: Reading. (line 6)
6758 * Options, archive format specifying: Format Variations. (line 6)
6759 * Options, format specifying: Format Variations. (line 6)
6760 * options, GNU style: Long Options. (line 6)
6761 * options, long style: Long Options. (line 6)
6762 * options, mixing different styles: Mixing. (line 6)
6763 * options, mnemonic names: Long Options. (line 6)
6764 * options, old style: Old Options. (line 6)
6765 * options, short style: Short Options. (line 6)
6766 * options, traditional: Short Options. (line 6)
6767 * ordinal numbers: General date syntax. (line 22)
6768 * Overwriting old files, prevention: Dealing with Old Files.
6770 * parse_datetime: Date input formats. (line 6)
6771 * pattern, 'genfile': Generate Mode. (line 39)
6772 * PAX archive format: posix. (line 6)
6773 * Permissions of extracted files: Setting Access Permissions.
6775 * Pinard, F.: Authors of parse_datetime.
6777 * pm in date strings: Time of day items. (line 21)
6778 * POSIX archive format: posix. (line 6)
6779 * Progress information: verbose. (line 82)
6780 * Protecting old files: Dealing with Old Files.
6782 * pure numbers in date strings: Pure numbers in date strings.
6784 * RCS, excluding files: exclude. (line 85)
6785 * Reading file names from a file: files. (line 6)
6786 * Reading incomplete records: Reading. (line 6)
6787 * record: Blocking. (line 6)
6788 * Record Size: Blocking Factor. (line 6)
6789 * 'Record size = %lu blocks', warning message: warnings. (line 89)
6790 * record-size: warnings. (line 89)
6791 * Records, incomplete: Reading. (line 6)
6792 * Recursion in directories, avoiding: recurse. (line 6)
6793 * relative items in date strings: Relative items in date strings.
6795 * Remote devices: file. (line 60)
6796 * remote tape drive: Remote Tape Server. (line 6)
6797 * Removing files from an archive: delete. (line 6)
6798 * rename-directory: warnings. (line 96)
6799 * Replacing members with other members: append. (line 47)
6800 * reporting bugs: Reports. (line 6)
6801 * RESTORE_BEGIN: User Hooks. (line 38)
6802 * RESTORE_END: User Hooks. (line 41)
6803 * Resurrecting files from an archive: extract. (line 6)
6804 * Retrieving files from an archive: extract. (line 6)
6805 * return status: Synopsis. (line 67)
6806 * rmargin: Configuring Help Summary.
6808 * rmt: Remote Tape Server. (line 6)
6809 * RSH: General-Purpose Variables.
6811 * RSH_COMMAND: General-Purpose Variables.
6813 * Running out of space: Scarce. (line 8)
6814 * Salz, Rich: Authors of parse_datetime.
6816 * SCCS, excluding files: exclude. (line 85)
6817 * short options: Short Options. (line 6)
6818 * short options with mandatory arguments: Short Options. (line 13)
6819 * short options with optional arguments: Short Options. (line 22)
6820 * short-opt-col: Configuring Help Summary.
6822 * simple backup method: backup. (line 64)
6823 * SIMPLE_BACKUP_SUFFIX: backup. (line 67)
6824 * 'sleep', checkpoint action: checkpoints. (line 145)
6825 * SLEEP_MESSAGE: General-Purpose Variables.
6827 * SLEEP_TIME: General-Purpose Variables.
6829 * Small memory: Scarce. (line 8)
6830 * snapshot file field ranges: Snapshot Files. (line 111)
6831 * snapshot file, format 0: Snapshot Files. (line 24)
6832 * snapshot file, format 1: Snapshot Files. (line 51)
6833 * snapshot file, format 2: Snapshot Files. (line 73)
6834 * snapshot files, editing: Fixing Snapshot Files.
6836 * snapshot files, fixing device numbers: Fixing Snapshot Files.
6838 * 'socket ignored', warning message: warnings. (line 45)
6839 * Sparse Files: sparse. (line 6)
6840 * sparse files v.0.0, extracting with non-GNU tars: Sparse Recovery.
6842 * sparse files v.0.1, extracting with non-GNU tars: Sparse Recovery.
6844 * sparse files v.1.0, extracting with non-GNU tars: Sparse Recovery.
6846 * Sparse files, creating using 'genfile': Generate Mode. (line 55)
6847 * sparse files, extracting with non-GNU tars: Sparse Recovery.
6849 * sparse formats: Sparse Formats. (line 6)
6850 * sparse formats, defined: sparse. (line 52)
6851 * sparse formats, Old GNU: Old GNU Format. (line 6)
6852 * sparse formats, v.0.0: PAX 0. (line 6)
6853 * sparse formats, v.0.1: PAX 0. (line 51)
6854 * sparse formats, v.1.0: PAX 1. (line 6)
6855 * sparse versions: Sparse Formats. (line 6)
6856 * Specifying archive members: Selecting Archive Members.
6858 * Specifying files to act on: Selecting Archive Members.
6860 * Standard input and output: file. (line 39)
6861 * Standard output, writing extracted files to: Writing to Standard Output.
6863 * Storing archives in compressed format: gzip. (line 6)
6864 * SVN, excluding files: exclude. (line 85)
6865 * Symbolic link as file name: dereference. (line 6)
6866 * symlink-cast: warnings. (line 68)
6867 * TAPE: file tutorial. (line 14)
6868 * tape blocking: Blocking Factor. (line 189)
6869 * tape marks: Many. (line 43)
6870 * tape positioning: Many. (line 26)
6871 * Tapes, using '--delete' and: delete. (line 17)
6872 * TAPE_FILE: General-Purpose Variables.
6874 * tar: What tar Does. (line 6)
6875 * TAR: General-Purpose Variables.
6877 * tar archive: Definitions. (line 6)
6878 * Tar archive formats: Formats. (line 6)
6879 * tar entry: Naming tar Archives. (line 11)
6880 * tar file: Naming tar Archives. (line 11)
6881 * tar to a remote device: file. (line 60)
6882 * tar to standard input and output: file. (line 39)
6883 * tar-snapshot-edit: Fixing Snapshot Files.
6885 * tarcat: Tarcat. (line 6)
6886 * TAR_ARCHIVE, checkpoint script environment: checkpoints. (line 167)
6887 * TAR_ARCHIVE, info script environment variable: Multi-Volume Archives.
6889 * TAR_ARCHIVE, to-command environment: Writing to an External Program.
6891 * TAR_ATIME, to-command environment: Writing to an External Program.
6893 * TAR_BLOCKING_FACTOR, checkpoint script environment: checkpoints.
6895 * TAR_BLOCKING_FACTOR, info script environment variable: Multi-Volume Archives.
6897 * TAR_BLOCKING_FACTOR, to-command environment: Writing to an External Program.
6899 * TAR_CHECKPOINT, checkpoint script environment: checkpoints. (line 173)
6900 * TAR_CTIME, to-command environment: Writing to an External Program.
6902 * TAR_FD, info script environment variable: Multi-Volume Archives.
6904 * TAR_FILENAME, to-command environment: Writing to an External Program.
6906 * TAR_FILETYPE, to-command environment: Writing to an External Program.
6908 * TAR_FORMAT, checkpoint script environment: checkpoints. (line 180)
6909 * TAR_FORMAT, info script environment variable: Multi-Volume Archives.
6911 * TAR_FORMAT, to-command environment: Writing to an External Program.
6913 * TAR_GID, to-command environment: Writing to an External Program.
6915 * TAR_GNAME, to-command environment: Writing to an External Program.
6917 * TAR_MODE, to-command environment: Writing to an External Program.
6919 * TAR_MTIME, to-command environment: Writing to an External Program.
6921 * TAR_OPTIONS, environment variable: using tar options. (line 30)
6922 * TAR_REALNAME, to-command environment: Writing to an External Program.
6924 * TAR_SIZE, to-command environment: Writing to an External Program.
6926 * TAR_SUBCOMMAND, checkpoint script environment: checkpoints. (line 176)
6927 * TAR_SUBCOMMAND, info script environment variable: Multi-Volume Archives.
6929 * TAR_UID, to-command environment: Writing to an External Program.
6931 * TAR_UNAME, to-command environment: Writing to an External Program.
6933 * TAR_VERSION, checkpoint script environment: checkpoints. (line 164)
6934 * TAR_VERSION, info script environment variable: Multi-Volume Archives.
6936 * TAR_VERSION, to-command environment: Writing to an External Program.
6938 * TAR_VOLUME, info script environment variable: Multi-Volume Archives.
6940 * TAR_VOLUME, to-command environment: Writing to an External Program.
6942 * this in date strings: Relative items in date strings.
6944 * time of day item: Time of day items. (line 6)
6945 * 'time stamp %s is %s s in the future', warning message: warnings.
6947 * time zone correction: Time of day items. (line 29)
6948 * time zone item: General date syntax. (line 40)
6949 * time zone item <1>: Time zone items. (line 6)
6950 * timestamp: warnings. (line 63)
6951 * today in date strings: Relative items in date strings.
6953 * tomorrow in date strings: Relative items in date strings.
6955 * 'totals', checkpoint action: checkpoints. (line 140)
6956 * 'ttyout', checkpoint action: checkpoints. (line 111)
6957 * TZ: Specifying time zone rules.
6959 * Ultrix 3.1 and write failure: Remote Tape Server. (line 40)
6960 * 'Unknown file type '%c', extracted as normal file', warning message: warnings.
6962 * 'Unknown file type; file ignored', warning message: warnings.
6964 * unknown-cast: warnings. (line 70)
6965 * unknown-keyword: warnings. (line 74)
6966 * unpacking: Definitions. (line 22)
6967 * Updating an archive: update. (line 6)
6968 * usage-indent: Configuring Help Summary.
6970 * Using encrypted archives: gzip. (line 196)
6971 * ustar archive format: ustar. (line 6)
6972 * uuencode: Applications. (line 8)
6973 * v7 archive format: old. (line 6)
6974 * VCS, excluding files: exclude. (line 85)
6975 * VCS, excluding patterns from ignore files: exclude. (line 37)
6976 * VCS, ignore files: exclude. (line 37)
6977 * Verbose operation: verbose. (line 18)
6978 * Verifying a write operation: verify. (line 6)
6979 * Verifying the currency of an archive: compare. (line 6)
6980 * version control system, excluding files: exclude. (line 85)
6981 * Version of the 'tar' program: help. (line 6)
6982 * version-control Emacs variable: backup. (line 49)
6983 * VERSION_CONTROL: backup. (line 41)
6984 * volno file: Multi-Volume Archives.
6986 * VOLNO_FILE: General-Purpose Variables.
6988 * Volume label, listing: label. (line 27)
6989 * Volume number file: Multi-Volume Archives.
6991 * week in date strings: Relative items in date strings.
6993 * Where is the archive?: file. (line 6)
6994 * Working directory, specifying: directory. (line 6)
6995 * Writing extracted files to standard output: Writing to Standard Output.
6997 * Writing new archives: file. (line 34)
6998 * xdev: warnings. (line 43)
6999 * xdev <1>: warnings. (line 100)
7000 * XLIST: General-Purpose Variables.
7002 * xsparse: Sparse Recovery. (line 13)
7003 * year in date strings: Relative items in date strings.
7005 * yesterday in date strings: Relative items in date strings.