1This is tar.info, produced by makeinfo version 6.7 from tar.texi. 2 3This manual is for GNU 'tar' (version 1.34, 4 February 2021), which 4creates and extracts files from archives. 5 6 Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2017, 2021 Free 7Software Foundation, Inc. 8 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". 16 17 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and 18 modify this GNU manual." 19INFO-DIR-SECTION Archiving 20START-INFO-DIR-ENTRY 21* Tar: (tar). Making tape (or disk) archives. 22END-INFO-DIR-ENTRY 23 24INFO-DIR-SECTION Individual utilities 25START-INFO-DIR-ENTRY 26* tar: (tar)tar invocation. Invoking GNU 'tar'. 27END-INFO-DIR-ENTRY 28 29 30File: tar.info, Node: one, Prev: recurse, Up: Choosing 31 326.10 Crossing File System Boundaries 33==================================== 34 35'tar' will normally automatically cross file system boundaries in order 36to archive files which are part of a directory tree. You can change 37this behavior by running 'tar' and specifying '--one-file-system'. This 38option only affects files that are archived because they are in a 39directory that is being archived; 'tar' will still archive files 40explicitly named on the command line or through '--files-from', 41regardless of where they reside. 42 43'--one-file-system' 44 Prevents 'tar' from crossing file system boundaries when archiving. 45 Use in conjunction with any write operation. 46 47 The '--one-file-system' option causes 'tar' to modify its normal 48behavior in archiving the contents of directories. If a file in a 49directory 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 52not cross mount points. 53 54 This option is useful for making full or incremental archival backups 55of a file system. If this option is used in conjunction with 56'--verbose' ('-v'), files that are excluded are mentioned by name on the 57standard error. 58 59* Menu: 60 61* directory:: Changing Directory 62* absolute:: Absolute File Names 63 64 65File: tar.info, Node: directory, Next: absolute, Up: one 66 676.10.1 Changing the Working Directory 68------------------------------------- 69 70To change the working directory in the middle of a list of file names, 71either on the command line or in a file specified using '--files-from' 72('-T'), use '--directory' ('-C'). This will change the working 73directory to the specified directory after that point in the list. 74 75'--directory=DIRECTORY' 76'-C DIRECTORY' 77 Changes the working directory in the middle of a command line. 78 79 For example, 80 81 $ tar -c -f jams.tar grape prune -C food cherry 82 83will place the files 'grape' and 'prune' from the current directory into 84the archive 'jams.tar', followed by the file 'cherry' from the directory 85'food'. This option is especially useful when you have several widely 86separated files that you want to store in the same archive. 87 88 Note that the file 'cherry' is recorded in the archive under the 89precise name 'cherry', _not_ 'food/cherry'. Thus, the archive will 90contain three files that all appear to have come from the same 91directory; if the archive is extracted with plain 'tar --extract', all 92three files will be written in the current directory. 93 94 Contrast this with the command, 95 96 $ tar -c -f jams.tar grape prune -C food red/cherry 97 98which records the third file in the archive under the name 'red/cherry' 99so that, if the archive is extracted using 'tar --extract', the third 100file will be written in a subdirectory named 'red'. 101 102 You can use the '--directory' option to make the archive independent 103of the original name of the directory holding the files. The following 104command places the files '/etc/passwd', '/etc/hosts', and '/lib/libc.a' 105into the archive 'foo.tar': 106 107 $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a 108 109However, the names of the archive members will be exactly what they were 110on the command line: 'passwd', 'hosts', and 'libc.a'. They will not 111appear to be related by file name to the original directories where 112those files were located. 113 114 Note that '--directory' options are interpreted consecutively. If 115'--directory' specifies a relative file name, it is interpreted relative 116to the then current directory, which might not be the same as the 117original current working directory of 'tar', due to a previous 118'--directory' option. 119 120 When using '--files-from' (*note files::), you can put various 'tar' 121options (including '-C') in the file list. Notice, however, that in 122this case the option and its argument may not be separated by 123whitespace. If you use short option, its argument must either follow 124the option letter immediately, without any intervening whitespace, or 125occupy the next line. Otherwise, if you use long option, separate its 126argument by an equal sign. 127 128 For instance, the file list for the above example will be: 129 130 -C/etc 131 passwd 132 hosts 133 --directory=/lib 134 libc.a 135 136To use it, you would invoke 'tar' as follows: 137 138 $ tar -c -f foo.tar --files-from list 139 140 The interpretation of options in file lists is disabled by 141'--verbatim-files-from' and '--null' options. 142 143 144File: tar.info, Node: absolute, Prev: directory, Up: one 145 1466.10.2 Absolute File Names 147-------------------------- 148 149By default, GNU 'tar' drops a leading '/' on input or output, and 150complains about file names containing a '..' component. There is an 151option that turns off this behavior: 152 153'--absolute-names' 154'-P' 155 Do not strip leading slashes from file names, and permit file names 156 containing a '..' file name component. 157 158 When 'tar' extracts archive members from an archive, it strips any 159leading slashes ('/') from the member name. This causes absolute member 160names in the archive to be treated as relative file names. This allows 161you to have such members extracted wherever you want, instead of being 162restricted to extracting the member in the exact directory named in the 163archive. For example, if the archive member has the name '/etc/passwd', 164'tar' will extract it as if the name were really 'etc/passwd'. 165 166 File names containing '..' can cause problems when extracting, so 167'tar' normally warns you about such files when creating an archive, and 168rejects attempts to extracts such files. 169 170 Other 'tar' programs do not do this. As a result, if you create an 171archive whose member names start with a slash, they will be difficult 172for other people with a non-GNU 'tar' program to use. Therefore, GNU 173'tar' also strips leading slashes from member names when putting members 174into 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 176'bin/ls'(1). 177 178 Symbolic links containing '..' or leading '/' can also cause problems 179when extracting, so 'tar' normally extracts them last; it may create 180empty files as placeholders during extraction. 181 182 If you use the '--absolute-names' ('-P') option, 'tar' will do none 183of these transformations. 184 185 To archive or extract files relative to the root directory, specify 186the '--absolute-names' ('-P') option. 187 188 Normally, 'tar' acts on files relative to the working 189directory--ignoring superior directory names when archiving, and 190ignoring leading slashes when extracting. 191 192 When you specify '--absolute-names' ('-P'), 'tar' stores file names 193including all superior directory names, and preserves leading slashes. 194If you only invoked 'tar' from the root directory you would never need 195the '--absolute-names' option, but using this option may be more 196convenient than switching to root. 197 198'--absolute-names' 199 Preserves full file names (including superior directory names) when 200 archiving and extracting files. 201 202 'tar' prints out a message about removing the '/' from file names. 203This message appears once per GNU 'tar' invocation. It represents 204something which ought to be told; ignoring what it means can cause very 205serious surprises, later. 206 207 Some people, nevertheless, do not want to see this message. Wanting 208to play really dangerously, one may of course redirect 'tar' standard 209error to the sink. For example, under 'sh': 210 211 $ tar -c -f archive.tar /home 2> /dev/null 212 213Another solution, both nicer and simpler, would be to change to the '/' 214directory first, and then avoid absolute notation. For example: 215 216 $ tar -c -f archive.tar -C / home 217 218 *Note Integrity::, for some of the security-related implications of 219using this option. 220 221 ---------- Footnotes ---------- 222 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 225the one you'd get running 'tar --list' command. This may be important 226if you use some scripts for comparing both outputs. *Note listing 227member and file names::, for the information on how to handle this case. 228 229 230File: tar.info, Node: Date input formats, Next: Formats, Prev: Choosing, Up: Top 231 2327 Date input formats 233******************** 234 235First, a quote: 236 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. 251 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. 257 ... 258 259 --Robert Grudin, 'Time and the Art of Living'. 260 261 This section describes the textual date representations that GNU 262programs accept. These are the strings you, as a user, can supply as 263arguments to the various programs. The C interface (via the 264'parse_datetime' function) is not described here. 265 266* Menu: 267 268* General date syntax:: Common rules 269* Calendar date items:: 21 Jul 2020 270* Time of day items:: 9:20pm 271* Time zone items:: UTC, -0700, +0900, ... 272* Combined date and time of day items:: 2020-07-21T20:02:00,000000-0400 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:: 20200721, 1440 276* Seconds since the Epoch:: @1595289600 277* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0" 278* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al. 279 280 281File: tar.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats 282 2837.1 General date syntax 284======================= 285 286A "date" is a string, possibly empty, containing many items separated by 287whitespace. The whitespace may be omitted when no ambiguity arises. 288The empty string means the beginning of today (i.e., midnight). Order 289of the items is immaterial. A date string may contain many flavors of 290items: 291 292 * calendar date items 293 * time of day items 294 * time zone items 295 * combined date and time of day items 296 * day of the week items 297 * relative items 298 * pure numbers. 299 300We describe each of these item types in turn, below. 301 302 A few ordinal numbers may be written out in words in some contexts. 303This is most useful for specifying day of the week items or relative 304items (see below). Among the most commonly used ordinal numbers, the 305word 'last' stands for -1, 'this' stands for 0, and 'first' and 'next' 306both stand for 1. Because the word 'second' stands for the unit of time 307there 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. 311 312 When a month is written this way, it is still considered to be 313written numerically, instead of being "spelled in full"; this changes 314the allowed strings. 315 316 In the current implementation, only English is supported for words 317and abbreviations like 'AM', 'DST', 'EST', 'first', 'January', 'Sunday', 318'tomorrow', and 'year'. 319 320 The output of the 'date' command is not always acceptable as a date 321string, not only because of the language problem, but also because there 322is 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 324date format that is independent of language and that does not use time 325zone items other than 'UTC' and 'Z'. Here are some ways to do this: 326 327 $ LC_ALL=C TZ=UTC0 date 328 Tue Jul 21 23:00:37 UTC 2020 329 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' 330 2020-07-21 23:00:37Z 331 $ date --rfc-3339=ns # --rfc-3339 is a GNU extension. 332 2020-07-21 19:00:37.692722128-04:00 333 $ date --rfc-2822 # a GNU extension 334 Tue, 21 Jul 2020 19:00:37 -0400 335 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. 336 2020-07-21 19:00:37 -0400 337 $ date +'@%s.%N' # %s and %N are GNU extensions. 338 @1595372437.692722128 339 340 Alphabetic case is completely ignored in dates. Comments may be 341introduced between round parentheses, as long as included parentheses 342are properly nested. Hyphens not followed by a digit are currently 343ignored. Leading zeros on numbers are ignored. 344 345 Invalid dates like '2019-02-29' or times like '24:00' are rejected. 346In the typical case of a host that does not support leap seconds, a time 347like '23:59:60' is rejected even if it corresponds to a valid leap 348second. 349 350 351File: tar.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats 352 3537.2 Calendar date items 354======================= 355 356A "calendar date item" specifies a day of the year. It is specified 357differently, depending on whether the month is specified numerically or 358literally. All these strings specify the same calendar date: 359 360 2020-07-20 # ISO 8601. 361 20-7-20 # Assume 19xx for 69 through 99, 362 # 20xx for 00 through 68 (not recommended). 363 7/20/2020 # Common U.S. writing. 364 20 July 2020 365 20 Jul 2020 # Three-letter abbreviations always allowed. 366 Jul 20, 2020 367 20-jul-2020 368 20jul2020 369 370 The year can also be omitted. In this case, the last specified year 371is used, or the current year if none. For example: 372 373 7/20 374 jul 20 375 376 Here are the rules. 377 378 For numeric months, the ISO 8601 format 'YEAR-MONTH-DAY' is allowed, 379where YEAR is any positive number, MONTH is a number between 01 and 12, 380and DAY is a number between 01 and 31. A leading zero must be present 381if a number is less than ten. If YEAR is 68 or smaller, then 2000 is 382added to it; otherwise, if YEAR is less than 100, then 1900 is added to 383it. The construct 'MONTH/DAY/YEAR', popular in the United States, is 384accepted. Also 'MONTH/DAY', omitting the year. 385 386 Literal months may be spelled out in full: 'January', 'February', 387'March', 'April', 'May', 'June', 'July', 'August', 'September', 388'October', 'November' or 'December'. Literal months may be abbreviated 389to their first three letters, possibly followed by an abbreviating dot. 390It is also permitted to write 'Sept' instead of 'September'. 391 392 When months are written literally, the calendar date may be given as 393any of the following: 394 395 DAY MONTH YEAR 396 DAY MONTH 397 MONTH DAY YEAR 398 DAY-MONTH-YEAR 399 400 Or, omitting the year: 401 402 MONTH DAY 403 404 405File: tar.info, Node: Time of day items, Next: Time zone items, Prev: Calendar date items, Up: Date input formats 406 4077.3 Time of day items 408===================== 409 410A "time of day item" in date strings specifies the time on a given day. 411Here are some examples, all of which represent the same time: 412 413 20:02:00.000000 414 20:02 415 8:02pm 416 20:02-0500 # In EST (U.S. Eastern Standard Time). 417 418 More generally, the time of day may be given as 'HOUR:MINUTE:SECOND', 419where HOUR is a number between 0 and 23, MINUTE is a number between 0 420and 59, and SECOND is a number between 0 and 59 possibly followed by '.' 421or ',' and a fraction containing one or more digits. Alternatively, 422':SECOND' can be omitted, in which case it is taken to be zero. On the 423rare hosts that support leap seconds, SECOND may be 60. 424 425 If the time is followed by 'am' or 'pm' (or 'a.m.' or 'p.m.'), HOUR 426is restricted to run from 1 to 12, and ':MINUTE' may be omitted (taken 427to be zero). 'am' indicates the first half of the day, 'pm' indicates 428the second half of the day. In this notation, 12 is the predecessor of 4291: midnight is '12am' while noon is '12pm'. (This is the zero-oriented 430interpretation of '12am' and '12pm', as opposed to the old tradition 431derived from Latin which uses '12m' for noon and '12pm' for midnight.) 432 433 The time may alternatively be followed by a time zone correction, 434expressed as 'SHHMM', where S is '+' or '-', HH is a number of zone 435hours and MM is a number of zone minutes. The zone minutes term, MM, 436may be omitted, in which case the one- or two-digit correction is 437interpreted as a number of hours. You can also separate HH from MM with 438a colon. When a time zone correction is given this way, it forces 439interpretation of the time relative to Coordinated Universal Time (UTC), 440overriding any previous specification for the time zone or the local 441time zone. For example, '+0530' and '+05:30' both stand for the time 442zone 5.5 hours ahead of UTC (e.g., India). This is the best way to 443specify a time zone correction by fractional parts of an hour. The 444maximum zone correction is 24 hours. 445 446 Either 'am'/'pm' or a time zone correction may be specified, but not 447both. 448 449 450File: tar.info, Node: Time zone items, Next: Combined date and time of day items, Prev: Time of day items, Up: Date input formats 451 4527.4 Time zone items 453=================== 454 455A "time zone item" specifies an international time zone, indicated by a 456small set of letters, e.g., 'UTC' or 'Z' for Coordinated Universal Time. 457Any included periods are ignored. By following a non-daylight-saving 458time zone by the string 'DST' in a separate word (that is, separated by 459some white space), the corresponding daylight saving time zone may be 460specified. Alternatively, a non-daylight-saving time zone can be 461followed by a time zone correction, to add the two values. This is 462normally done only for 'UTC'; for example, 'UTC+05:30' is equivalent to 463'+05:30'. 464 465 Time zone items other than 'UTC' and 'Z' are obsolescent and are not 466recommended, because they are ambiguous; for example, 'EST' has a 467different meaning in Australia than in the United States, and 'A' has 468different meaning as a military time zone than as an obsolescent RFC 822 469time zone. Instead, it's better to use unambiguous numeric time zone 470corrections like '-0500', as described in the previous section. 471 472 If neither a time zone item nor a time zone correction is supplied, 473timestamps are interpreted using the rules of the default time zone 474(*note Specifying time zone rules::). 475 476 477File: tar.info, Node: Combined date and time of day items, Next: Day of week items, Prev: Time zone items, Up: Date input formats 478 4797.5 Combined date and time of day items 480======================================= 481 482The ISO 8601 date and time of day extended format consists of an ISO 4838601 date, a 'T' character separator, and an ISO 8601 time of day. This 484format is also recognized if the 'T' is replaced by a space. 485 486 In this format, the time of day should use 24-hour notation. 487Fractional seconds are allowed, with either comma or period preceding 488the fraction. ISO 8601 fractional minutes and hours are not supported. 489Typically, hosts support nanosecond timestamp resolution; excess 490precision is silently discarded. 491 492 Here are some examples: 493 494 2012-09-24T20:02:00.052-05:00 495 2012-12-31T23:59:59,999999999+11:00 496 1970-01-01 00:00Z 497 498 499File: 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 500 5017.6 Day of week items 502===================== 503 504The explicit mention of a day of the week will forward the date (only if 505necessary) to reach that day of the week in the future. 506 507 Days of the week may be spelled out in full: 'Sunday', 'Monday', 508'Tuesday', 'Wednesday', 'Thursday', 'Friday' or 'Saturday'. Days may be 509abbreviated to their first three letters, optionally followed by a 510period. The special abbreviations 'Tues' for 'Tuesday', 'Wednes' for 511'Wednesday' and 'Thur' or 'Thurs' for 'Thursday' are also allowed. 512 513 A number may precede a day of the week item to move forward 514supplementary weeks. It is best used in expression like 'third monday'. 515In this context, 'last DAY' or 'next DAY' is also acceptable; they move 516one week before or after the day that DAY by itself would represent. 517 518 A comma following a day of the week item is ignored. 519 520 521File: tar.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats 522 5237.7 Relative items in date strings 524================================== 525 526"Relative items" adjust a date (or the current date if none) forward or 527backward. The effects of relative items accumulate. Here are some 528examples: 529 530 1 year 531 1 year ago 532 3 years 533 2 days 534 535 The unit of time displacement may be selected by the string 'year' or 536'month' for moving by whole years or months. These are fuzzy units, as 537years and months are not all of equal duration. More precise units are 538'fortnight' which is worth 14 days, 'week' worth 7 days, 'day' worth 24 539hours, 'hour' worth 60 minutes, 'minute' or 'min' worth 60 seconds, and 540'second' or 'sec' worth one second. An 's' suffix on these units is 541accepted and ignored. 542 543 The unit of time may be preceded by a multiplier, given as an 544optionally signed number. Unsigned numbers are taken as positively 545signed. No number at all implies 1 for a multiplier. Following a 546relative item by the string 'ago' is equivalent to preceding the unit by 547a multiplier with value -1. 548 549 The string 'tomorrow' is worth one day in the future (equivalent to 550'day'), the string 'yesterday' is worth one day in the past (equivalent 551to 'day ago'). 552 553 The strings 'now' or 'today' are relative items corresponding to 554zero-valued time displacement, these strings come from the fact a 555zero-valued time displacement represents the current time when not 556otherwise changed by previous items. They may be used to stress other 557items, like in '12:00 today'. The string 'this' also has the meaning of 558a zero-valued time displacement, but is preferred in date strings like 559'this thursday'. 560 561 When a relative item causes the resulting date to cross a boundary 562where the clocks were adjusted, typically for daylight saving time, the 563resulting date and time are adjusted accordingly. 564 565 The fuzz in units can cause problems with relative items. For 566example, '2020-07-31 -1 month' might evaluate to 2020-07-01, because 5672020-06-31 is an invalid date. To determine the previous month more 568reliably, you can ask for the month before the 15th of the current 569month. For example: 570 571 $ date -R 572 Thu, 31 Jul 2020 13:02:39 -0400 573 $ date --date='-1 month' +'Last month was %B?' 574 Last month was July? 575 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' 576 Last month was June! 577 578 Also, take care when manipulating dates around clock changes such as 579daylight saving leaps. In a few cases these have added or subtracted as 580much as 24 hours from the clock, so it is often wise to adopt universal 581time by setting the 'TZ' environment variable to 'UTC0' before embarking 582on calendrical calculations. 583 584 585File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats 586 5877.8 Pure numbers in date strings 588================================ 589 590The precise interpretation of a pure decimal number depends on the 591context in the date string. 592 593 If the decimal number is of the form YYYYMMDD and no other calendar 594date item (*note Calendar date items::) appears before it in the date 595string, then YYYY is read as the year, MM as the month number and DD as 596the day of the month, for the specified calendar date. 597 598 If the decimal number is of the form HHMM and no other time of day 599item appears before it in the date string, then HH is read as the hour 600of the day and MM as the minute of the hour, for the specified time of 601day. MM can also be omitted. 602 603 If both a calendar date and a time of day appear to the left of a 604number in the date string, but no relative item, then the number 605overrides the year. 606 607 608File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats 609 6107.9 Seconds since the Epoch 611=========================== 612 613If you precede a number with '@', it represents an internal timestamp as 614a count of seconds. The number can contain an internal decimal point 615(either '.' or ','); any excess precision not supported by the internal 616representation is truncated toward minus infinity. Such a number cannot 617be combined with any other date item, as it specifies a complete 618timestamp. 619 620 Internally, computer times are represented as a count of seconds 621since an Epoch--a well-defined point of time. On GNU and POSIX systems, 622the Epoch is 1970-01-01 00:00:00 UTC, so '@0' represents this time, '@1' 623represents 1970-01-01 00:00:01 UTC, and so forth. GNU and most other 624POSIX-compliant systems support such times as an extension to POSIX, 625using negative counts, so that '@-1' represents 1969-12-31 23:59:59 UTC. 626 627 Most modern systems count seconds with 64-bit two's-complement 628integers of seconds with nanosecond subcounts, which is a range that 629includes the known lifetime of the universe with nanosecond resolution. 630Some obsolescent systems count seconds with 32-bit two's-complement 631integers and can represent times from 1901-12-13 20:45:52 through 6322038-01-19 03:14:07 UTC. A few systems sport other time ranges. 633 634 On most hosts, these counts ignore the presence of leap seconds. For 635example, on most hosts '@1483228799' represents 2016-12-31 23:59:59 UTC, 636'@1483228800' represents 2017-01-01 00:00:00 UTC, and there is no way to 637represent the intervening leap second 2016-12-31 23:59:60 UTC. 638 639 640File: tar.info, Node: Specifying time zone rules, Next: Authors of parse_datetime, Prev: Seconds since the Epoch, Up: Date input formats 641 6427.10 Specifying time zone rules 643=============================== 644 645Normally, dates are interpreted using the rules of the current time 646zone, which in turn are specified by the 'TZ' environment variable, or 647by a system default if 'TZ' is not set. To specify a different set of 648default time zone rules that apply just to one date, start the date with 649a string of the form 'TZ="RULE"'. The two quote characters ('"') must 650be present in the date, and any quotes or backslashes within RULE must 651be escaped by a backslash. 652 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 65531, 2019?" by using a date beginning with 'TZ="Europe/Paris"' as shown 656in the following shell transcript: 657 658 $ export TZ="America/New_York" 659 $ date --date='TZ="Europe/Paris" 2019-10-31 06:30' 660 Sun Oct 31 01:30:00 EDT 2019 661 662 In this example, the '--date' operand begins with its own 'TZ' 663setting, so the rest of that operand is processed according to 664'Europe/Paris' rules, treating the string '2019-10-31 06:30' as if it 665were in Paris. However, since the output of the 'date' command is 666processed according to the overall time zone rules, it uses New York 667time. (Paris was normally six hours ahead of New York in 2019, but this 668example refers to a brief Halloween period when the gap was five hours.) 669 670 A 'TZ' value is a rule that typically names a location in the 'tz' 671database (https://www.iana.org/time-zones). A recent catalog of 672location names appears in the TWiki Date and Time Gateway 673(https://twiki.org/cgi-bin/xtra/tzdatepick.html). A few non-GNU hosts 674require a colon before a location name in a 'TZ' setting, e.g., 675'TZ=":America/New_York"'. 676 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 679and have your own private time zone, or if you are using a non-GNU host 680that does not support the 'tz' database, you may need to use a POSIX 681rule instead. Simple POSIX rules like 'UTC0' specify a time zone 682without daylight saving time; other rules can specify simple daylight 683saving regimes. *Note Specifying the Time Zone with 'TZ': (libc)TZ 684Variable. 685 686 687File: tar.info, Node: Authors of parse_datetime, Prev: Specifying time zone rules, Up: Date input formats 688 6897.11 Authors of 'parse_datetime' 690================================ 691 692'parse_datetime' started life as 'getdate', as originally implemented by 693Steven M. Bellovin (<smb@research.att.com>) while at the University of 694North Carolina at Chapel Hill. The code was later tweaked by a couple 695of people on Usenet, then completely overhauled by Rich $alz 696(<rsalz@bbn.com>) and Jim Berets (<jberets@bbn.com>) in August, 1990. 697Various revisions for the GNU system were made by David MacKenzie, Jim 698Meyering, Paul Eggert and others, including renaming it to 'get_date' to 699avoid a conflict with the alternative Posix function 'getdate', and a 700later rename to 'parse_datetime'. The Posix function 'getdate' can 701parse more locale-specific dates using 'strptime', but relies on an 702environment variable and external file, and lacks the thread-safety of 703'parse_datetime'. 704 705 This chapter was originally produced by François Pinard 706(<pinard@iro.umontreal.ca>) from the 'parse_datetime.y' source code, and 707then edited by K. Berry (<kb@cs.umb.edu>). 708 709 710File: tar.info, Node: Formats, Next: Media, Prev: Date input formats, Up: Top 711 7128 Controlling the Archive Format 713******************************** 714 715Due to historical reasons, there are several formats of tar archives. 716All of them are based on the same principles, but have some subtle 717differences that often make them incompatible with each other. 718 719 GNU tar is able to create and handle archives in a variety of 720formats. The most frequently used formats are (in alphabetical order): 721 722gnu 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 727 archive formats. 728 729 Archives in 'gnu' format are able to hold file names of unlimited 730 length. 731 732oldgnu 733 Format used by GNU 'tar' of versions prior to 1.12. 734 735v7 736 Archive format, compatible with the V7 implementation of tar. This 737 format imposes a number of limitations. The most important of them 738 are: 739 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 742 characters. 743 3. It is impossible to store special files (block and character 744 devices, fifos etc.) 745 4. Maximum value of user or group ID is limited to 2097151 746 (7777777 octal) 747 5. V7 archives do not contain symbolic ownership information 748 (user and group name of the file owner). 749 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.34 754 and Automake prior to 1.9. 755 756ustar 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: 760 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 767 characters. 768 3. Maximum size of a file the archive is able to accommodate is 769 8GB 770 4. Maximum value of UID/GID is 2097151. 771 5. Maximum number of bits in device major and minor numbers is 772 21. 773 774star 775 Format used by Jörg Schilling 'star' implementation. GNU 'tar' is 776 able to read 'star' archives but currently does not produce them. 777 778posix 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 788 refers to. 789 790 This archive format will be the default format for future versions 791 of GNU 'tar'. 792 793 The following table summarizes the limitations of each of these 794formats: 795 796Format UID File Size File Name Devn 797-------------------------------------------------------------------- 798gnu 1.8e19 Unlimited Unlimited 63 799oldgnu 1.8e19 Unlimited Unlimited 63 800v7 2097151 8GB 99 n/a 801ustar 2097151 8GB 256 21 802posix Unlimited Unlimited Unlimited Unlimited 803 804 The default format for GNU 'tar' is defined at compilation time. You 805may check it by running 'tar --help', and examining the last lines of 806its output. Usually, GNU 'tar' is configured to create archives in 807'gnu' format, however, future version will switch to 'posix'. 808 809* Menu: 810 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' 815 816 817File: tar.info, Node: Compression, Next: Attributes, Up: Formats 818 8198.1 Using Less Space through Compression 820======================================== 821 822* Menu: 823 824* gzip:: Creating and Reading Compressed Archives 825* sparse:: Archiving Sparse Files 826 827 828File: tar.info, Node: gzip, Next: sparse, Up: Compression 829 8308.1.1 Creating and Reading Compressed Archives 831---------------------------------------------- 832 833GNU 'tar' is able to create and read compressed archives. It supports a 834wide variety of compression programs, namely: 'gzip', 'bzip2', 'lzip', 835'lzma', 'lzop', 'zstd', 'xz' and traditional 'compress'. The latter is 836supported mostly for backward compatibility, and we recommend against 837using it, because it is by far less effective than the other compression 838programs(1). 839 840 Creating a compressed archive is simple: you just specify a 841"compression option" along with the usual archive creation commands. 842Available compression options are summarized in the table below: 843 844Long Short Archive format 845--------------------------------------------------------------------------- 846'--gzip' '-z' 'gzip' 847'--bzip2' '-j' 'bzip2' 848'--xz' '-J' 'xz' 849'--lzip' 'lzip' 850'--lzma' 'lzma' 851'--lzop' 'lzop' 852'--zstd' 'zstd' 853'--compress' '-Z' 'compress' 854 855 For example: 856 857 $ tar czf archive.tar.gz . 858 859 You can also let GNU 'tar' select the compression program based on 860the suffix of the archive file name. This is done using 861'--auto-compress' ('-a') command line option. For example, the 862following invocation will use 'bzip2' for compression: 863 864 $ tar caf archive.tar.bz2 . 865 866whereas the following one will use 'lzma': 867 868 $ tar caf archive.tar.lzma . 869 870 For a complete list of file name suffixes recognized by GNU 'tar', 871see *note auto-compress::. 872 873 Reading compressed archive is even simpler: you don't need to specify 874any additional options as GNU 'tar' recognizes its format automatically. 875Thus, the following commands will list and extract the archive created 876in previous example: 877 878 # List the compressed archive 879 $ tar tf archive.tar.gz 880 # Extract the compressed archive 881 $ tar xf archive.tar.gz 882 883 The format recognition algorithm is based on "signatures", a special 884byte sequences in the beginning of file, that are specific for certain 885compression formats. If this approach fails, 'tar' falls back to using 886archive name suffix to determine its format (*note auto-compress::, for 887a list of recognized suffixes). 888 889 Some compression programs are able to handle different compression 890formats. GNU 'tar' uses this, if the principal decompressor for the 891given format is not available. For example, if 'compress' is not 892installed, 'tar' will try to use 'gzip'. As of version 1.34 the 893following alternatives are tried(2): 894 895Format Main decompressor Alternatives 896--------------------------------------------------------------------- 897compress compress gzip 898lzma lzma xz 899bzip2 bzip2 lbzip2 900 901 The only case when you have to specify a decompression option while 902reading the archive is when reading from a pipe or from a tape drive 903that does not support random access. However, in this case GNU 'tar' 904will indicate which option you should use. For example: 905 906 $ cat archive.tar.gz | tar tf - 907 tar: Archive is compressed. Use -z option 908 tar: Error is not recoverable: exiting now 909 910 If you see such diagnostics, just add the suggested option to the 911invocation of GNU 'tar': 912 913 $ cat archive.tar.gz | tar tzf - 914 915 Notice also, that there are several restrictions on operations on 916compressed archives. First of all, compressed archives cannot be 917modified, i.e., you cannot update ('--update', alias '-u') them or 918delete ('--delete') members from them or add ('--append', alias '-r') 919members to them. Likewise, you cannot append another 'tar' archive to a 920compressed archive using '--concatenate' ('-A'). Secondly, multi-volume 921archives cannot be compressed. 922 923 The following options allow to select a particular compressor 924program: 925 926'-z' 927'--gzip' 928'--ungzip' 929 Filter the archive through 'gzip'. 930 931'-J' 932'--xz' 933 Filter the archive through 'xz'. 934 935'-j' 936'--bzip2' 937 Filter the archive through 'bzip2'. 938 939'--lzip' 940 Filter the archive through 'lzip'. 941 942'--lzma' 943 Filter the archive through 'lzma'. 944 945'--lzop' 946 Filter the archive through 'lzop'. 947 948'--zstd' 949 Filter the archive through 'zstd'. 950 951'-Z' 952'--compress' 953'--uncompress' 954 Filter the archive through 'compress'. 955 956 When any of these options is given, GNU 'tar' searches the compressor 957binary in the current path and invokes it. The name of the compressor 958program is specified at compilation time using a corresponding 959'--with-COMPNAME' option to 'configure', e.g. '--with-bzip2' to select 960a specific 'bzip2' binary. *Note lbzip2::, for a detailed discussion. 961 962 The output produced by 'tar --help' shows the actual compressor names 963along with each of these options. 964 965 You can use any of these options on physical devices (tape drives, 966etc.) and remote files as well as on normal files; data to or from such 967devices or remote files is reblocked by another copy of the 'tar' 968program to enforce the specified (or default) record size. The default 969compression parameters are used. You can override them by using the 970'-I' option (see below), e.g.: 971 972 $ tar -cf archive.tar.gz -I 'gzip -9 -n' subdir 973 974A more traditional way to do this is to use a pipe: 975 976 $ tar cf - subdir | gzip -9 -n > archive.tar.gz 977 978 Compressed archives are easily corrupted, because compressed files 979have little redundancy. The adaptive nature of the compression scheme 980means that the compression tables are implicitly spread all over the 981archive. If you lose a few blocks, the dynamic construction of the 982compression tables becomes unsynchronized, and there is little chance 983that you could recover later in the archive. 984 985 Other compression options provide better control over creating 986compressed archives. These are: 987 988'--auto-compress' 989'-a' 990 Select a compression program to use by the archive file name 991 suffix. The following suffixes are recognized: 992 993 Suffix Compression program 994 ------------------------------------------------------------------- 995 '.gz' 'gzip' 996 '.tgz' 'gzip' 997 '.taz' 'gzip' 998 '.Z' 'compress' 999 '.taZ' 'compress' 1000 '.bz2' 'bzip2' 1001 '.tz2' 'bzip2' 1002 '.tbz2' 'bzip2' 1003 '.tbz' 'bzip2' 1004 '.lz' 'lzip' 1005 '.lzma' 'lzma' 1006 '.tlz' 'lzma' 1007 '.lzo' 'lzop' 1008 '.xz' 'xz' 1009 '.zst' 'zstd' 1010 '.tzst' 'zstd' 1011 1012'--use-compress-program=COMMAND' 1013'-I=COMMAND' 1014 Use external compression program COMMAND. Use this option if you 1015 want to specify options for the compression program, or if you are 1016 not happy with the compression program associated with the suffix 1017 at compile time, or if you have a compression program that GNU 1018 'tar' does not support. The COMMAND argument is a valid command 1019 invocation, as you would type it at the command line prompt, with 1020 any additional options as needed. Enclose it in quotes if it 1021 contains white space (*note Running External Commands: external.). 1022 1023 The COMMAND should follow two conventions: 1024 1025 First, when invoked without additional options, it should read data 1026 from standard input, compress it and output it on standard output. 1027 1028 Secondly, if invoked with the additional '-d' option, it should do 1029 exactly the opposite, i.e., read the compressed data from the 1030 standard input and produce uncompressed data on the standard 1031 output. 1032 1033 The latter requirement means that you must not use the '-d' option 1034 as a part of the COMMAND itself. 1035 1036 The '--use-compress-program' option, in particular, lets you 1037implement your own filters, not necessarily dealing with 1038compression/decompression. For example, suppose you wish to implement 1039PGP encryption on top of compression, using 'gpg' (*note gpg: 1040(gpg)Top.). The following script does that: 1041 1042 #! /bin/sh 1043 case $1 in 1044 -d) gpg --decrypt - | gzip -d -c;; 1045 '') gzip -c | gpg -s;; 1046 *) echo "Unknown option $1">&2; exit 1;; 1047 esac 1048 1049 Suppose you name it 'gpgz' and save it somewhere in your 'PATH'. 1050Then the following command will create a compressed archive signed with 1051your private key: 1052 1053 $ tar -cf foo.tar.gpgz -Igpgz . 1054 1055Likewise, the command below will list its contents: 1056 1057 $ tar -tf foo.tar.gpgz -Igpgz . 1058 1059* Menu: 1060 1061* lbzip2:: Using lbzip2 with GNU 'tar'. 1062 1063 ---------- Footnotes ---------- 1064 1065 (1) It also had patent problems in the past. 1066 1067 (2) To verbosely trace the decompressor selection, use the 1068'--warning=decompress-program' option (*note decompress-program: 1069warnings.). 1070 1071 1072File: tar.info, Node: lbzip2, Up: gzip 1073 10748.1.1.1 Using lbzip2 with GNU 'tar'. 1075.................................... 1076 1077'Lbzip2' is a multithreaded utility for handling 'bzip2' compression, 1078written by Laszlo Ersek. It makes use of multiple processors to speed 1079up its operation and in general works considerably faster than 'bzip2'. 1080For a detailed description of 'lbzip2' see 1081<http://freshmeat.net/projects/lbzip2> and lbzip2: parallel bzip2 1082utility 1083(http://www.linuxinsight.com/lbzip2-parallel-bzip2-utility.html). 1084 1085 Recent versions of 'lbzip2' are mostly command line compatible with 1086'bzip2', which makes it possible to automatically invoke it via the 1087'--bzip2' GNU 'tar' command line option. To do so, GNU 'tar' must be 1088configured with the '--with-bzip2' command line option, like this: 1089 1090 $ ./configure --with-bzip2=lbzip2 [OTHER-OPTIONS] 1091 1092 Once configured and compiled this way, 'tar --help' will show the 1093following: 1094 1095 $ tar --help | grep -- --bzip2 1096 -j, --bzip2 filter the archive through lbzip2 1097 1098which means that running 'tar --bzip2' will invoke 'lbzip2'. 1099 1100 1101File: tar.info, Node: sparse, Prev: gzip, Up: Compression 1102 11038.1.2 Archiving Sparse Files 1104---------------------------- 1105 1106Files in the file system occasionally have "holes". A "hole" in a file 1107is a section of the file's contents which was never written. The 1108contents of a hole reads as all zeros. On many operating systems, 1109actual disk storage is not allocated for holes, but they are counted in 1110the length of the file. If you archive such a file, 'tar' could create 1111an archive longer than the original. To have 'tar' attempt to recognize 1112the holes in a file, use '--sparse' ('-S'). When you use this option, 1113then, for any file using less disk space than would be expected from its 1114length, 'tar' searches the file for holes. It then records in the 1115archive for the file where the holes (consecutive stretches of zeros) 1116are, and only archives the "real contents" of the file. On extraction 1117(using '--sparse' is not needed on extraction) any such files have also 1118holes created wherever the holes were found. Thus, if you use 1119'--sparse', 'tar' archives won't take more space than the original. 1120 1121 GNU 'tar' uses two methods for detecting holes in sparse files. 1122These methods are described later in this subsection. 1123 1124'-S' 1125'--sparse' 1126 This option instructs 'tar' to test each file for sparseness before 1127 attempting to archive it. If the file is found to be sparse it is 1128 treated specially, thus allowing to decrease the amount of space 1129 used by its image in the archive. 1130 1131 This option is meaningful only when creating or updating archives. 1132 It has no effect on extraction. 1133 1134 Consider using '--sparse' when performing file system backups, to 1135avoid archiving the expanded forms of files stored sparsely in the 1136system. 1137 1138 Even if your system has no sparse files currently, some may be 1139created in the future. If you use '--sparse' while making file system 1140backups as a matter of course, you can be assured the archive will never 1141take more space on the media than the files take on disk (otherwise, 1142archiving a disk filled with sparse files might take hundreds of tapes). 1143*Note Incremental Dumps::. 1144 1145 However, be aware that '--sparse' option may present a serious 1146drawback. Namely, in order to determine the positions of holes in a 1147file 'tar' may have to read it before trying to archive it, so in total 1148the file may be read *twice*. This may happen when your OS or your FS 1149does not support "SEEK_HOLE/SEEK_DATA" feature in "lseek" (See 1150'--hole-detection', below). 1151 1152 When using 'POSIX' archive format, GNU 'tar' is able to store sparse 1153files using in three distinct ways, called "sparse formats". A sparse 1154format is identified by its "number", consisting, as usual of two 1155decimal numbers, delimited by a dot. By default, format '1.0' is used. 1156If, for some reason, you wish to use an earlier format, you can select 1157it using '--sparse-version' option. 1158 1159'--sparse-version=VERSION' 1160 Select the format to store sparse files in. Valid VERSION values 1161 are: '0.0', '0.1' and '1.0'. *Note Sparse Formats::, for a 1162 detailed description of each format. 1163 1164 Using '--sparse-format' option implies '--sparse'. 1165 1166'--hole-detection=METHOD' 1167 Enforce concrete hole detection method. Before the real contents 1168 of sparse file are stored, 'tar' needs to gather knowledge about 1169 file sparseness. This is because it needs to have the file's map 1170 of holes stored into tar header before it starts archiving the file 1171 contents. Currently, two methods of hole detection are 1172 implemented: 1173 1174 * '--hole-detection=seek' Seeking the file for data and holes. 1175 It uses enhancement of the 'lseek' system call ('SEEK_HOLE' 1176 and 'SEEK_DATA') which is able to reuse file system knowledge 1177 about sparse file contents - so the detection is usually very 1178 fast. To use this feature, your file system and operating 1179 system must support it. At the time of this writing (2015) 1180 this feature, in spite of not being accepted by POSIX, is 1181 fairly widely supported by different operating systems. 1182 1183 * '--hole-detection=raw' Reading byte-by-byte the whole sparse 1184 file before the archiving. This method detects holes like 1185 consecutive stretches of zeroes. Comparing to the previous 1186 method, it is usually much slower, although more portable. 1187 1188 When no '--hole-detection' option is given, 'tar' uses the 'seek', if 1189supported by the operating system. 1190 1191 Using '--hole-detection' option implies '--sparse'. 1192 1193 1194File: tar.info, Node: Attributes, Next: Portability, Prev: Compression, Up: Formats 1195 11968.2 Handling File Attributes 1197============================ 1198 1199When 'tar' reads files, it updates their access times. To avoid this, 1200use the '--atime-preserve[=METHOD]' option, which can either reset the 1201access time retroactively or avoid changing it in the first place. 1202 1203'--atime-preserve' 1204'--atime-preserve=replace' 1205'--atime-preserve=system' 1206 Preserve the access times of files that are read. This works only 1207 for files that you own, unless you have superuser privileges. 1208 1209 '--atime-preserve=replace' works on most systems, but it also 1210 restores the data modification time and updates the status change 1211 time. Hence it doesn't interact with incremental dumps nicely 1212 (*note Incremental Dumps::), and it can set access or data 1213 modification times incorrectly if other programs access the file 1214 while 'tar' is running. 1215 1216 '--atime-preserve=system' avoids changing the access time in the 1217 first place, if the operating system supports this. Unfortunately, 1218 this may or may not work on any given operating system or file 1219 system. If 'tar' knows for sure it won't work, it complains right 1220 away. 1221 1222 Currently '--atime-preserve' with no operand defaults to 1223 '--atime-preserve=replace', but this is intended to change to 1224 '--atime-preserve=system' when the latter is better-supported. 1225 1226'-m' 1227'--touch' 1228 Do not extract data modification time. 1229 1230 When this option is used, 'tar' leaves the data modification times 1231 of the files it extracts as the times when the files were 1232 extracted, instead of setting it to the times recorded in the 1233 archive. 1234 1235 This option is meaningless with '--list' ('-t'). 1236 1237'--same-owner' 1238 Create extracted files with the same ownership they have in the 1239 archive. 1240 1241 This is the default behavior for the superuser, so this option is 1242 meaningful only for non-root users, when 'tar' is executed on those 1243 systems able to give files away. This is considered as a security 1244 flaw by many people, at least because it makes quite difficult to 1245 correctly account users for the disk space they occupy. Also, the 1246 'suid' or 'sgid' attributes of files are easily and silently lost 1247 when files are given away. 1248 1249 When writing an archive, 'tar' writes the user ID and user name 1250 separately. If it can't find a user name (because the user ID is 1251 not in '/etc/passwd'), then it does not write one. When restoring, 1252 it tries to look the name (if one was written) up in '/etc/passwd'. 1253 If it fails, then it uses the user ID stored in the archive 1254 instead. 1255 1256'--no-same-owner' 1257'-o' 1258 Do not attempt to restore ownership when extracting. This is the 1259 default behavior for ordinary users, so this option has an effect 1260 only for the superuser. 1261 1262'--numeric-owner' 1263 The '--numeric-owner' option allows (ANSI) archives to be written 1264 without user/group name information or such information to be 1265 ignored when extracting. It effectively disables the generation 1266 and/or use of user/group name information. This option forces 1267 extraction using the numeric ids from the archive, ignoring the 1268 names. 1269 1270 This is useful in certain circumstances, when restoring a backup 1271 from an emergency floppy with different passwd/group files for 1272 example. It is otherwise impossible to extract files with the 1273 right ownerships if the password file in use during the extraction 1274 does not match the one belonging to the file system(s) being 1275 extracted. This occurs, for example, if you are restoring your 1276 files after a major crash and had booted from an emergency floppy 1277 with no password file or put your disk into another machine to do 1278 the restore. 1279 1280 The numeric ids are _always_ saved into 'tar' archives. The 1281 identifying names are added at create time when provided by the 1282 system, unless '--format=oldgnu' is used. Numeric ids could be 1283 used when moving archives between a collection of machines using a 1284 centralized management for attribution of numeric ids to users and 1285 groups. This is often made through using the NIS capabilities. 1286 1287 When making a 'tar' file for distribution to other sites, it is 1288 sometimes cleaner to use a single owner for all files in the 1289 distribution, and nicer to specify the write permission bits of the 1290 files as stored in the archive independently of their actual value 1291 on the file system. The way to prepare a clean distribution is 1292 usually to have some Makefile rule creating a directory, copying 1293 all needed files in that directory, then setting ownership and 1294 permissions as wanted (there are a lot of possible schemes), and 1295 only then making a 'tar' archive out of this directory, before 1296 cleaning everything out. Of course, we could add a lot of options 1297 to GNU 'tar' for fine tuning permissions and ownership. This is 1298 not the good way, I think. GNU 'tar' is already crowded with 1299 options and moreover, the approach just explained gives you a great 1300 deal of control already. 1301 1302'-p' 1303'--same-permissions' 1304'--preserve-permissions' 1305 Extract all protection information. 1306 1307 This option causes 'tar' to set the modes (access permissions) of 1308 extracted files exactly as recorded in the archive. If this option 1309 is not used, the current 'umask' setting limits the permissions on 1310 extracted files. This option is by default enabled when 'tar' is 1311 executed by a superuser. 1312 1313 This option is meaningless with '--list' ('-t'). 1314 1315 1316File: tar.info, Node: Portability, Next: cpio, Prev: Attributes, Up: Formats 1317 13188.3 Making 'tar' Archives More Portable 1319======================================= 1320 1321Creating a 'tar' archive on a particular system that is meant to be 1322useful later on many other machines and with other versions of 'tar' is 1323more challenging than you might think. 'tar' archive formats have been 1324evolving since the first versions of Unix. Many such formats are 1325around, and are not always compatible with each other. This section 1326discusses a few problems, and gives some advice about making 'tar' 1327archives more portable. 1328 1329 One golden rule is simplicity. For example, limit your 'tar' 1330archives to contain only regular files and directories, avoiding other 1331kind of special files. Do not attempt to save sparse files or 1332contiguous files as such. Let's discuss a few more problems, in turn. 1333 1334* Menu: 1335 1336* Portable Names:: Portable Names 1337* dereference:: Symbolic Links 1338* hard links:: Hard Links 1339* old:: Old V7 Archives 1340* ustar:: Ustar Archives 1341* gnu:: GNU and old GNU format archives. 1342* posix:: POSIX archives 1343* Checksumming:: Checksumming Problems 1344* Large or Negative Values:: Large files, negative time stamps, etc. 1345* Other Tars:: How to Extract GNU-Specific Data Using 1346 Other 'tar' Implementations 1347 1348 1349File: tar.info, Node: Portable Names, Next: dereference, Up: Portability 1350 13518.3.1 Portable Names 1352-------------------- 1353 1354Use portable file and member names. A name is portable if it contains 1355only ASCII letters and digits, '/', '.', '_', and '-'; it cannot be 1356empty, start with '-' or '//', or contain '/-'. Avoid deep directory 1357nesting. For portability to old Unix hosts, limit your file name 1358components to 14 characters or less. 1359 1360 If you intend to have your 'tar' archives to be read under MSDOS, you 1361should not rely on case distinction for file names, and you might use 1362the GNU 'doschk' program for helping you further diagnosing illegal 1363MSDOS names, which are even more limited than System V's. 1364 1365 1366File: tar.info, Node: dereference, Next: hard links, Prev: Portable Names, Up: Portability 1367 13688.3.2 Symbolic Links 1369-------------------- 1370 1371Normally, when 'tar' archives a symbolic link, it writes a block to the 1372archive naming the target of the link. In that way, the 'tar' archive 1373is a faithful record of the file system contents. When '--dereference' 1374('-h') is used with '--create' ('-c'), 'tar' archives the files symbolic 1375links point to, instead of the links themselves. 1376 1377 When creating portable archives, use '--dereference' ('-h'): some 1378systems do not support symbolic links, and moreover, your distribution 1379might be unusable if it contains unresolved symbolic links. 1380 1381 When reading from an archive, the '--dereference' ('-h') option 1382causes 'tar' to follow an already-existing symbolic link when 'tar' 1383writes or reads a file named in the archive. Ordinarily, 'tar' does not 1384follow such a link, though it may remove the link before writing a new 1385file. *Note Dealing with Old Files::. 1386 1387 The '--dereference' option is unsafe if an untrusted user can modify 1388directories while 'tar' is running. *Note Security::. 1389 1390 1391File: tar.info, Node: hard links, Next: old, Prev: dereference, Up: Portability 1392 13938.3.3 Hard Links 1394---------------- 1395 1396Normally, when 'tar' archives a hard link, it writes a block to the 1397archive naming the target of the link (a '1' type block). In that way, 1398the actual file contents is stored in file only once. For example, 1399consider the following two files: 1400 1401 $ ls -l 1402 -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one 1403 -rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden 1404 1405 Here, 'jeden' is a link to 'one'. When archiving this directory with 1406a verbose level 2, you will get an output similar to the following: 1407 1408 $ tar cvvf ../archive.tar . 1409 drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./ 1410 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden 1411 hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden 1412 1413 The last line shows that, instead of storing two copies of the file, 1414'tar' stored it only once, under the name 'jeden', and stored file 'one' 1415as a hard link to this file. 1416 1417 It may be important to know that all hard links to the given file are 1418stored in the archive. For example, this may be necessary for exact 1419reproduction of the file system. The following option does that: 1420 1421'--check-links' 1422'-l' 1423 Check the number of links dumped for each processed file. If this 1424 number does not match the total number of hard links for the file, 1425 print a warning message. 1426 1427 For example, trying to archive only file 'jeden' with this option 1428produces the following diagnostics: 1429 1430 $ tar -c -f ../archive.tar -l jeden 1431 tar: Missing links to 'jeden'. 1432 1433 Although creating special records for hard links helps keep a 1434faithful record of the file system contents and makes archives more 1435compact, it may present some difficulties when extracting individual 1436members from the archive. For example, trying to extract file 'one' 1437from the archive created in previous examples produces, in the absence 1438of file 'jeden': 1439 1440 $ tar xf archive.tar ./one 1441 tar: ./one: Cannot hard link to './jeden': No such file or directory 1442 tar: Error exit delayed from previous errors 1443 1444 The reason for this behavior is that 'tar' cannot seek back in the 1445archive to the previous member (in this case, 'one'), to extract it(1). 1446If you wish to avoid such problems at the cost of a bigger archive, use 1447the following option: 1448 1449'--hard-dereference' 1450 Dereference hard links and store the files they refer to. 1451 1452 For example, trying this option on our two sample files, we get two 1453copies in the archive, each of which can then be extracted independently 1454of the other: 1455 1456 $ tar -c -vv -f ../archive.tar --hard-dereference . 1457 drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./ 1458 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden 1459 -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one 1460 1461 ---------- Footnotes ---------- 1462 1463 (1) There are plans to fix this in future releases. 1464 1465 1466File: tar.info, Node: old, Next: ustar, Prev: hard links, Up: Portability 1467 14688.3.4 Old V7 Archives 1469--------------------- 1470 1471Certain old versions of 'tar' cannot handle additional information 1472recorded by newer 'tar' programs. To create an archive in V7 format 1473(not ANSI), which can be read by these old versions, specify the 1474'--format=v7' option in conjunction with the '--create' ('-c') ('tar' 1475also accepts '--portability' or '--old-archive' for this option). When 1476you specify it, 'tar' leaves out information about directories, pipes, 1477fifos, contiguous files, and device files, and specifies file ownership 1478by group and user IDs instead of group and user names. 1479 1480 When updating an archive, do not use '--format=v7' unless the archive 1481was created using this option. 1482 1483 In most cases, a _new_ format archive can be read by an _old_ 'tar' 1484program without serious trouble, so this option should seldom be needed. 1485On the other hand, most modern 'tar's are able to read old format 1486archives, so it might be safer for you to always use '--format=v7' for 1487your distributions. Notice, however, that 'ustar' format is a better 1488alternative, as it is free from many of 'v7''s drawbacks. 1489 1490 1491File: tar.info, Node: ustar, Next: gnu, Prev: old, Up: Portability 1492 14938.3.5 Ustar Archive Format 1494-------------------------- 1495 1496The archive format defined by the POSIX.1-1988 specification is called 1497'ustar'. Although it is more flexible than the V7 format, it still has 1498many restrictions (*note ustar: Formats, for the detailed description of 1499'ustar' format). Along with V7 format, 'ustar' format is a good choice 1500for archives intended to be read with other implementations of 'tar'. 1501 1502 To create an archive in 'ustar' format, use the '--format=ustar' 1503option in conjunction with '--create' ('-c'). 1504 1505 1506File: tar.info, Node: gnu, Next: posix, Prev: ustar, Up: Portability 1507 15088.3.6 GNU and old GNU 'tar' format 1509---------------------------------- 1510 1511GNU 'tar' was based on an early draft of the POSIX 1003.1 'ustar' 1512standard. GNU extensions to 'tar', such as the support for file names 1513longer than 100 characters, use portions of the 'tar' header record 1514which were specified in that POSIX draft as unused. Subsequent changes 1515in POSIX have allocated the same parts of the header record for other 1516purposes. As a result, GNU 'tar' format is incompatible with the 1517current POSIX specification, and with 'tar' programs that follow it. 1518 1519 In the majority of cases, 'tar' will be configured to create this 1520format by default. This will change in future releases, since we plan 1521to make 'POSIX' format the default. 1522 1523 To force creation a GNU 'tar' archive, use option '--format=gnu'. 1524 1525 1526File: tar.info, Node: posix, Next: Checksumming, Prev: gnu, Up: Portability 1527 15288.3.7 GNU 'tar' and POSIX 'tar' 1529------------------------------- 1530 1531Starting from version 1.14 GNU 'tar' features full support for 1532POSIX.1-2001 archives. 1533 1534 A POSIX conformant archive will be created if 'tar' was given 1535'--format=posix' ('--format=pax') option. No special option is required 1536to read and extract from a POSIX archive. 1537 1538* Menu: 1539 1540* PAX keywords:: Controlling Extended Header Keywords. 1541 1542 1543File: tar.info, Node: PAX keywords, Up: posix 1544 15458.3.7.1 Controlling Extended Header Keywords 1546............................................ 1547 1548'--pax-option=KEYWORD-LIST' 1549 Handle keywords in PAX extended headers. This option is equivalent 1550 to '-o' option of the 'pax' utility. 1551 1552 KEYWORD-LIST is a comma-separated list of keyword options, each 1553keyword option taking one of the following forms: 1554 1555'delete=PATTERN' 1556 When used with one of archive-creation commands, this option 1557 instructs 'tar' to omit from extended header records that it 1558 produces any keywords matching the string PATTERN. 1559 1560 When used in extract or list mode, this option instructs tar to 1561 ignore any keywords matching the given PATTERN in the extended 1562 header records. In both cases, matching is performed using the 1563 pattern matching notation described in POSIX 1003.2, 3.13 (*note 1564 wildcards::). For example: 1565 1566 --pax-option delete=security.* 1567 1568 would suppress security-related information. 1569 1570'exthdr.name=STRING' 1571 1572 This keyword allows user control over the name that is written into 1573 the ustar header blocks for the extended headers. The name is 1574 obtained from STRING after making the following substitutions: 1575 1576 Meta-character Replaced By 1577 ------------------------------------------------------------ 1578 %d The directory name of the file, 1579 equivalent to the result of the 1580 'dirname' utility on the translated 1581 file name. 1582 %f The name of the file with the 1583 directory information stripped, 1584 equivalent to the result of the 1585 'basename' utility on the translated 1586 file name. 1587 %p The process ID of the 'tar' process. 1588 %% A '%' character. 1589 1590 Any other '%' characters in STRING produce undefined results. 1591 1592 If no option 'exthdr.name=string' is specified, 'tar' will use the 1593 following default value: 1594 1595 %d/PaxHeaders/%f 1596 1597 This default is selected to ensure the reproducibility of the 1598 archive. POSIX standard recommends to use '%d/PaxHeaders.%p/%f' 1599 instead, which means the two archives created with the same set of 1600 options and containing the same set of files will be byte-to-byte 1601 different. This default will be used if the environment variable 1602 'POSIXLY_CORRECT' is set. 1603 1604'exthdr.mtime=VALUE' 1605 1606 This keyword defines the value of the 'mtime' field that is written 1607 into the ustar header blocks for the extended headers. By default, 1608 the 'mtime' field is set to the modification time of the archive 1609 member described by that extended header (or to the value of the 1610 '--mtime' option, if supplied). 1611 1612'globexthdr.name=STRING' 1613 This keyword allows user control over the name that is written into 1614 the ustar header blocks for global extended header records. The 1615 name is obtained from the contents of STRING, after making the 1616 following substitutions: 1617 1618 Meta-character Replaced By 1619 ------------------------------------------------------------ 1620 %n An integer that represents the 1621 sequence number of the global extended 1622 header record in the archive, starting 1623 at 1. 1624 %p The process ID of the 'tar' process. 1625 %% A '%' character. 1626 1627 Any other '%' characters in STRING produce undefined results. 1628 1629 If no option 'globexthdr.name=string' is specified, 'tar' will use 1630 the following default value: 1631 1632 $TMPDIR/GlobalHead.%n 1633 1634 If the environment variable 'POSIXLY_CORRECT' is set, the following 1635 value is used instead: 1636 1637 $TMPDIR/GlobalHead.%p.%n 1638 1639 In both cases, '$TMPDIR' stands for the value of the TMPDIR 1640 environment variable. If TMPDIR is not set, 'tar' uses '/tmp'. 1641 1642'globexthdr.mtime=VALUE' 1643 1644 This keyword defines the value of the 'mtime' field that is written 1645 into the ustar header blocks for the global extended headers. By 1646 default, the 'mtime' field is set to the time when 'tar' was 1647 invoked. 1648 1649'KEYWORD=VALUE' 1650 When used with one of archive-creation commands, these 1651 keyword/value pairs will be included at the beginning of the 1652 archive in a global extended header record. When used with one of 1653 archive-reading commands, 'tar' will behave as if it has 1654 encountered these keyword/value pairs at the beginning of the 1655 archive in a global extended header record. 1656 1657'KEYWORD:=VALUE' 1658 When used with one of archive-creation commands, these 1659 keyword/value pairs will be included as records at the beginning of 1660 an extended header for each file. This is effectively equivalent 1661 to KEYWORD=VALUE form except that it creates no global extended 1662 header records. 1663 1664 When used with one of archive-reading commands, 'tar' will behave 1665 as if these keyword/value pairs were included as records at the end 1666 of each extended header; thus, they will override any global or 1667 file-specific extended header record keywords of the same names. 1668 For example, in the command: 1669 1670 tar --format=posix --create \ 1671 --file archive --pax-option gname:=user . 1672 1673 the group name will be forced to a new value for all files stored 1674 in the archive. 1675 1676 In any of the forms described above, the VALUE may be a string 1677enclosed in curly braces. In that case, the string between the braces 1678is understood either as a textual time representation, as described in 1679*note Date input formats::, or a name of the existing file, starting 1680with '/' or '.'. In the latter case, the modification time of that file 1681is used. 1682 1683 For example, to set all modification times to the current date, you 1684use the following option: 1685 1686 --pax-option='mtime:={now}' 1687 1688 Note quoting of the option's argument. 1689 1690 As another example, here is the option that ensures that any two 1691archives created using it, will be binary equivalent if they have the 1692same contents: 1693 1694 --pax-option=atime:=0 1695 1696If you extract files from such an archive and recreate the archive from 1697them, you will also need to eliminate changes due to ctime, as shown in 1698examples below: 1699 1700 --pax-option=atime:=0,ctime:=0 1701 1702or 1703 1704 --pax-option=atime:=0,delete=ctime 1705 1706 Notice, that if you create an archive in POSIX format (*note posix::) 1707and the environment variable 'POSIXLY_CORRECT' is set, then the two 1708archives created using the same options on the same set of files will 1709not be byte-to-byte equivalent even with the above option. This is 1710because the posix default for extended header names includes the PID of 1711the tar process, which is different at each run. To produce 1712byte-to-byte equivalent archives in this case, either unset 1713'POSIXLY_CORRECT', or use the following option: 1714 1715 ---pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,ctime:=0 1716 1717 1718File: tar.info, Node: Checksumming, Next: Large or Negative Values, Prev: posix, Up: Portability 1719 17208.3.8 Checksumming Problems 1721--------------------------- 1722 1723SunOS and HP-UX 'tar' fail to accept archives created using GNU 'tar' 1724and containing non-ASCII file names, that is, file names having 1725characters with the eighth bit set, because they use signed checksums, 1726while GNU 'tar' uses unsigned checksums while creating archives, as per 1727POSIX standards. On reading, GNU 'tar' computes both checksums and 1728accepts either of them. It is somewhat worrying that a lot of people 1729may go around doing backup of their files using faulty (or at least 1730non-standard) software, not learning about it until it's time to restore 1731their missing files with an incompatible file extractor, or vice versa. 1732 1733 GNU 'tar' computes checksums both ways, and accepts either of them on 1734read, so GNU tar can read Sun tapes even with their wrong checksums. 1735GNU 'tar' produces the standard checksum, however, raising 1736incompatibilities with Sun. That is to say, GNU 'tar' has not been 1737modified to _produce_ incorrect archives to be read by buggy 'tar''s. 1738I've been told that more recent Sun 'tar' now read standard archives, so 1739maybe Sun did a similar patch, after all? 1740 1741 The story seems to be that when Sun first imported 'tar' sources on 1742their system, they recompiled it without realizing that the checksums 1743were computed differently, because of a change in the default signing of 1744'char''s in their compiler. So they started computing checksums 1745wrongly. When they later realized their mistake, they merely decided to 1746stay compatible with it, and with themselves afterwards. Presumably, 1747but I do not really know, HP-UX has chosen their 'tar' archives to be 1748compatible with Sun's. The current standards do not favor Sun 'tar' 1749format. In any case, it now falls on the shoulders of SunOS and HP-UX 1750users to get a 'tar' able to read the good archives they receive. 1751 1752 1753File: tar.info, Node: Large or Negative Values, Next: Other Tars, Prev: Checksumming, Up: Portability 1754 17558.3.9 Large or Negative Values 1756------------------------------ 1757 1758 _(This message will disappear, once this node revised.)_ 1759 1760 The above sections suggest to use 'oldest possible' archive format if 1761in doubt. However, sometimes it is not possible. If you attempt to 1762archive a file whose metadata cannot be represented using required 1763format, GNU 'tar' will print error message and ignore such a file. You 1764will than have to switch to a format that is able to handle such values. 1765The format summary table (*note Formats::) will help you to do so. 1766 1767 In particular, when trying to archive files larger than 8GB or with 1768timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16 176912:56:31 UTC, you will have to chose between GNU and POSIX archive 1770formats. When considering which format to choose, bear in mind that the 1771GNU format uses two's-complement base-256 notation to store values that 1772do not fit into standard ustar range. Such archives can generally be 1773read only by a GNU 'tar' implementation. Moreover, they sometimes 1774cannot be correctly restored on another hosts even by GNU 'tar'. For 1775example, using two's complement representation for negative time stamps 1776that assumes a signed 32-bit 'time_t' generates archives that are not 1777portable to hosts with differing 'time_t' representations. 1778 1779 On the other hand, POSIX archives, generally speaking, can be 1780extracted by any tar implementation that understands older ustar format. 1781The only exception are files larger than 8GB. 1782 1783 1784File: tar.info, Node: Other Tars, Prev: Large or Negative Values, Up: Portability 1785 17868.3.10 How to Extract GNU-Specific Data Using Other 'tar' Implementations 1787------------------------------------------------------------------------- 1788 1789In previous sections you became acquainted with various quirks necessary 1790to make your archives portable. Sometimes you may need to extract 1791archives containing GNU-specific members using some third-party 'tar' 1792implementation or an older version of GNU 'tar'. Of course your best 1793bet is to have GNU 'tar' installed, but if it is for some reason 1794impossible, this section will explain how to cope without it. 1795 1796 When we speak about "GNU-specific" members we mean two classes of 1797them: members split between the volumes of a multi-volume archive and 1798sparse members. You will be able to always recover such members if the 1799archive is in PAX format. In addition split members can be recovered 1800from archives in old GNU format. The following subsections describe the 1801required procedures in detail. 1802 1803* Menu: 1804 1805* Split Recovery:: Members Split Between Volumes 1806* Sparse Recovery:: Sparse Members 1807 1808 1809File: tar.info, Node: Split Recovery, Next: Sparse Recovery, Up: Other Tars 1810 18118.3.10.1 Extracting Members Split Between Volumes 1812................................................. 1813 1814If a member is split between several volumes of an old GNU format 1815archive most third party 'tar' implementation will fail to extract it. 1816To extract it, use 'tarcat' program (*note Tarcat::). This program is 1817available from GNU 'tar' home page 1818(http://www.gnu.org/software/tar/utils/tarcat.html). It concatenates 1819several archive volumes into a single valid archive. For example, if 1820you have three volumes named from 'vol-1.tar' to 'vol-3.tar', you can do 1821the following to extract them using a third-party 'tar': 1822 1823 $ tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf - 1824 1825 You could use this approach for most (although not all) PAX format 1826archives as well. However, extracting split members from a PAX archive 1827is a much easier task, because PAX volumes are constructed in such a way 1828that each part of a split member is extracted to a different file by 1829'tar' implementations that are not aware of GNU extensions. More 1830specifically, the very first part retains its original name, and all 1831subsequent parts are named using the pattern: 1832 1833 %d/GNUFileParts/%f.%n 1834 1835where symbols preceded by '%' are "macro characters" that have the 1836following meaning: 1837 1838Meta-character Replaced By 1839------------------------------------------------------------ 1840%d The directory name of the file, 1841 equivalent to the result of the 1842 'dirname' utility on its full name. 1843%f The file name of the file, equivalent 1844 to the result of the 'basename' 1845 utility on its full name. 1846%p The process ID of the 'tar' process 1847 that created the archive. 1848%n Ordinal number of this particular 1849 part. 1850 1851 For example, if the file 'var/longfile' was split during archive 1852creation between three volumes, then the member names will be: 1853 1854 var/longfile 1855 var/GNUFileParts/longfile.1 1856 var/GNUFileParts/longfile.2 1857 1858 When you extract your archive using a third-party 'tar', these files 1859will be created on your disk, and the only thing you will need to do to 1860restore your file in its original form is concatenate them in the proper 1861order, for example: 1862 1863 $ cd var 1864 $ cat GNUFileParts/longfile.1 \ 1865 GNUFileParts/longfile.2 >> longfile 1866 $ rm -f GNUFileParts 1867 1868 Notice, that if the 'tar' implementation you use supports PAX format 1869archives, it will probably emit warnings about unknown keywords during 1870extraction. They will look like this: 1871 1872 Tar file too small 1873 Unknown extended header keyword 'GNU.volume.filename' ignored. 1874 Unknown extended header keyword 'GNU.volume.size' ignored. 1875 Unknown extended header keyword 'GNU.volume.offset' ignored. 1876 1877You can safely ignore these warnings. 1878 1879 If your 'tar' implementation is not PAX-aware, you will get more 1880warnings and more files generated on your disk, e.g.: 1881 1882 $ tar xf vol-1.tar 1883 var/PaxHeaders/longfile: Unknown file type 'x', extracted as 1884 normal file 1885 Unexpected EOF in archive 1886 $ tar xf vol-2.tar 1887 tmp/GlobalHead.1: Unknown file type 'g', extracted as normal file 1888 GNUFileParts/PaxHeaders/sparsefile.1: Unknown file type 1889 'x', extracted as normal file 1890 1891 Ignore these warnings. The 'PaxHeaders.*' directories created will 1892contain files with "extended header keywords" describing the extracted 1893files. You can delete them, unless they describe sparse members. Read 1894further to learn more about them. 1895 1896 1897File: tar.info, Node: Sparse Recovery, Prev: Split Recovery, Up: Other Tars 1898 18998.3.10.2 Extracting Sparse Members 1900.................................. 1901 1902Any 'tar' implementation will be able to extract sparse members from a 1903PAX archive. However, the extracted files will be "condensed", i.e., 1904any zero blocks will be removed from them. When we restore such a 1905condensed file to its original form, by adding zero blocks (or "holes") 1906back to their original locations, we call this process "expanding" a 1907compressed sparse file. 1908 1909 To expand a file, you will need a simple auxiliary program called 1910'xsparse'. It is available in source form from GNU 'tar' home page 1911(http://www.gnu.org/software/tar/utils/xsparse.html). 1912 1913 Let's begin with archive members in "sparse format version 1.0"(1), 1914which are the easiest to expand. The condensed file will contain both 1915file map and file data, so no additional data will be needed to restore 1916it. If the original file name was 'DIR/NAME', then the condensed file 1917will be named 'DIR/GNUSparseFile.N/NAME', where N is a decimal 1918number(2). 1919 1920 To expand a version 1.0 file, run 'xsparse' as follows: 1921 1922 $ xsparse cond-file 1923 1924where 'cond-file' is the name of the condensed file. The utility will 1925deduce the name for the resulting expanded file using the following 1926algorithm: 1927 1928 1. If 'cond-file' does not contain any directories, '../cond-file' 1929 will be used; 1930 1931 2. If 'cond-file' has the form 'DIR/T/NAME', where both T and NAME are 1932 simple names, with no '/' characters in them, the output file name 1933 will be 'DIR/NAME'. 1934 1935 3. Otherwise, if 'cond-file' has the form 'DIR/NAME', the output file 1936 name will be 'NAME'. 1937 1938 In the unlikely case when this algorithm does not suit your needs, 1939you can explicitly specify output file name as a second argument to the 1940command: 1941 1942 $ xsparse cond-file out-file 1943 1944 It is often a good idea to run 'xsparse' in "dry run" mode first. In 1945this mode, the command does not actually expand the file, but verbosely 1946lists all actions it would be taking to do so. The dry run mode is 1947enabled by '-n' command line argument: 1948 1949 $ xsparse -n /home/gray/GNUSparseFile.6058/sparsefile 1950 Reading v.1.0 sparse map 1951 Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to 1952 '/home/gray/sparsefile' 1953 Finished dry run 1954 1955 To actually expand the file, you would run: 1956 1957 $ xsparse /home/gray/GNUSparseFile.6058/sparsefile 1958 1959The program behaves the same way all UNIX utilities do: it will keep 1960quiet unless it has something important to tell you (e.g. an error 1961condition or something). If you wish it to produce verbose output, 1962similar to that from the dry run mode, use '-v' option: 1963 1964 $ xsparse -v /home/gray/GNUSparseFile.6058/sparsefile 1965 Reading v.1.0 sparse map 1966 Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to 1967 '/home/gray/sparsefile' 1968 Done 1969 1970 Additionally, if your 'tar' implementation has extracted the 1971"extended headers" for this file, you can instruct 'xstar' to use them 1972in order to verify the integrity of the expanded file. The option '-x' 1973sets the name of the extended header file to use. Continuing our 1974example: 1975 1976 $ xsparse -v -x /home/gray/PaxHeaders/sparsefile \ 1977 /home/gray/GNUSparseFile/sparsefile 1978 Reading extended header file 1979 Found variable GNU.sparse.major = 1 1980 Found variable GNU.sparse.minor = 0 1981 Found variable GNU.sparse.name = sparsefile 1982 Found variable GNU.sparse.realsize = 217481216 1983 Reading v.1.0 sparse map 1984 Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to 1985 '/home/gray/sparsefile' 1986 Done 1987 1988 An "extended header" is a special 'tar' archive header that precedes 1989an archive member and contains a set of "variables", describing the 1990member properties that cannot be stored in the standard 'ustar' header. 1991While optional for expanding sparse version 1.0 members, the use of 1992extended headers is mandatory when expanding sparse members in older 1993sparse formats: v.0.0 and v.0.1 (The sparse formats are described in 1994detail in *note Sparse Formats::.) So, for these formats, the question 1995is: how to obtain extended headers from the archive? 1996 1997 If you use a 'tar' implementation that does not support PAX format, 1998extended headers for each member will be extracted as a separate file. 1999If we represent the member name as 'DIR/NAME', then the extended header 2000file will be named 'DIR/PaxHeaders/NAME'. 2001 2002 Things become more difficult if your 'tar' implementation does 2003support PAX headers, because in this case you will have to manually 2004extract the headers. We recommend the following algorithm: 2005 2006 1. Consult the documentation of your 'tar' implementation for an 2007 option that prints "block numbers" along with the archive listing 2008 (analogous to GNU 'tar''s '-R' option). For example, 'star' has 2009 '-block-number'. 2010 2011 2. Obtain verbose listing using the 'block number' option, and find 2012 block numbers of the sparse member in question and the member 2013 immediately following it. For example, running 'star' on our 2014 archive we obtain: 2015 2016 $ star -t -v -block-number -f arc.tar 2017 ... 2018 star: Unknown extended header keyword 'GNU.sparse.size' ignored. 2019 star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored. 2020 star: Unknown extended header keyword 'GNU.sparse.name' ignored. 2021 star: Unknown extended header keyword 'GNU.sparse.map' ignored. 2022 block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile 2023 block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README 2024 ... 2025 2026 (as usual, ignore the warnings about unknown keywords.) 2027 2028 3. Let SIZE be the size of the sparse member, BS be its block number 2029 and BN be the block number of the next member. Compute: 2030 2031 N = BS - BN - SIZE/512 - 2 2032 2033 This number gives the size of the extended header part in tar 2034 "blocks". In our example, this formula gives: '897 - 56 - 425984 / 2035 512 - 2 = 7'. 2036 2037 4. Use 'dd' to extract the headers: 2038 2039 dd if=ARCHIVE of=HNAME bs=512 skip=BS count=N 2040 2041 where ARCHIVE is the archive name, HNAME is a name of the file to 2042 store the extended header in, BS and N are computed in previous 2043 steps. 2044 2045 In our example, this command will be 2046 2047 $ dd if=arc.tar of=xhdr bs=512 skip=56 count=7 2048 2049 Finally, you can expand the condensed file, using the obtained 2050header: 2051 2052 $ xsparse -v -x xhdr GNUSparseFile.6058/sparsefile 2053 Reading extended header file 2054 Found variable GNU.sparse.size = 217481216 2055 Found variable GNU.sparse.numblocks = 208 2056 Found variable GNU.sparse.name = sparsefile 2057 Found variable GNU.sparse.map = 0,2048,1050624,2048,... 2058 Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile' 2059 Done 2060 2061 ---------- Footnotes ---------- 2062 2063 (1) *Note PAX 1::. 2064 2065 (2) Technically speaking, N is a "process ID" of the 'tar' process 2066which created the archive (*note PAX keywords::). 2067 2068 2069File: tar.info, Node: cpio, Prev: Portability, Up: Formats 2070 20718.4 Comparison of 'tar' and 'cpio' 2072================================== 2073 2074 _(This message will disappear, once this node revised.)_ 2075 2076 The 'cpio' archive formats, like 'tar', do have maximum file name 2077lengths. The binary and old ASCII formats have a maximum file length of 2078256, and the new ASCII and CRC ASCII formats have a max file length of 20791024. GNU 'cpio' can read and write archives with arbitrary file name 2080lengths, but other 'cpio' implementations may crash unexplainedly trying 2081to read them. 2082 2083 'tar' handles symbolic links in the form in which it comes in BSD; 2084'cpio' doesn't handle symbolic links in the form in which it comes in 2085System V prior to SVR4, and some vendors may have added symlinks to 2086their system without enhancing 'cpio' to know about them. Others may 2087have enhanced it in a way other than the way I did it at Sun, and which 2088was adopted by AT&T (and which is, I think, also present in the 'cpio' 2089that Berkeley picked up from AT&T and put into a later BSD release--I 2090think I gave them my changes). 2091 2092 (SVR4 does some funny stuff with 'tar'; basically, its 'cpio' can 2093handle 'tar' format input, and write it on output, and it probably 2094handles symbolic links. They may not have bothered doing anything to 2095enhance 'tar' as a result.) 2096 2097 'cpio' handles special files; traditional 'tar' doesn't. 2098 2099 'tar' comes with V7, System III, System V, and BSD source; 'cpio' 2100comes only with System III, System V, and later BSD (4.3-tahoe and 2101later). 2102 2103 'tar''s way of handling multiple hard links to a file can handle file 2104systems that support 32-bit i-numbers (e.g., the BSD file system); 2105'cpio's way requires you to play some games (in its "binary" format, 2106i-numbers are only 16 bits, and in its "portable ASCII" format, they're 210718 bits--it would have to play games with the "file system ID" field of 2108the header to make sure that the file system ID/i-number pairs of 2109different files were always different), and I don't know which 'cpio's, 2110if any, play those games. Those that don't might get confused and think 2111two files are the same file when they're not, and make hard links 2112between them. 2113 2114 'tar's way of handling multiple hard links to a file places only one 2115copy of the link on the tape, but the name attached to that copy is the 2116_only_ one you can use to retrieve the file; 'cpio's way puts one copy 2117for every link, but you can retrieve it using any of the names. 2118 2119 What type of check sum (if any) is used, and how is this 2120 calculated. 2121 2122 See the attached manual pages for 'tar' and 'cpio' format. 'tar' 2123uses a checksum which is the sum of all the bytes in the 'tar' header 2124for a file; 'cpio' uses no checksum. 2125 2126 If anyone knows why 'cpio' was made when 'tar' was present at the 2127 unix scene, 2128 2129 It wasn't. 'cpio' first showed up in PWB/UNIX 1.0; no 2130generally-available version of UNIX had 'tar' at the time. I don't know 2131whether any version that was generally available _within AT&T_ had 2132'tar', or, if so, whether the people within AT&T who did 'cpio' knew 2133about it. 2134 2135 On restore, if there is a corruption on a tape 'tar' will stop at 2136that point, while 'cpio' will skip over it and try to restore the rest 2137of the files. 2138 2139 The main difference is just in the command syntax and header format. 2140 2141 'tar' is a little more tape-oriented in that everything is blocked to 2142start on a record boundary. 2143 2144 Is there any differences between the ability to recover crashed 2145 archives between the two of them. (Is there any chance of 2146 recovering crashed archives at all.) 2147 2148 Theoretically it should be easier under 'tar' since the blocking lets 2149you find a header with some variation of 'dd skip=NN'. However, modern 2150'cpio''s and variations have an option to just search for the next file 2151header after an error with a reasonable chance of resyncing. However, 2152lots of tape driver software won't allow you to continue past a media 2153error which should be the only reason for getting out of sync unless a 2154file changed sizes while you were writing the archive. 2155 2156 If anyone knows why 'cpio' was made when 'tar' was present at the 2157 unix scene, please tell me about this too. 2158 2159 Probably because it is more media efficient (by not blocking 2160everything and using only the space needed for the headers where 'tar' 2161always uses 512 bytes per file header) and it knows how to archive 2162special files. 2163 2164 You might want to look at the freely available alternatives. The 2165major ones are 'afio', GNU 'tar', and 'pax', each of which have their 2166own extensions with some backwards compatibility. 2167 2168 Sparse files were 'tar'red as sparse files (which you can easily 2169test, because the resulting archive gets smaller, and GNU 'cpio' can no 2170longer read it). 2171 2172 2173File: tar.info, Node: Media, Next: Reliability and security, Prev: Formats, Up: Top 2174 21759 Tapes and Other Archive Media 2176******************************* 2177 2178 _(This message will disappear, once this node revised.)_ 2179 2180 A few special cases about tape handling warrant more detailed 2181description. These special cases are discussed below. 2182 2183 Many complexities surround the use of 'tar' on tape drives. Since 2184the creation and manipulation of archives located on magnetic tape was 2185the original purpose of 'tar', it contains many features making such 2186manipulation easier. 2187 2188 Archives are usually written on dismountable media--tape cartridges, 2189mag tapes, or floppy disks. 2190 2191 The amount of data a tape or disk holds depends not only on its size, 2192but also on how it is formatted. A 2400 foot long reel of mag tape 2193holds 40 megabytes of data when formatted at 1600 bits per inch. The 2194physically smaller EXABYTE tape cartridge holds 2.3 gigabytes. 2195 2196 Magnetic media are re-usable--once the archive on a tape is no longer 2197needed, the archive can be erased and the tape or disk used over. Media 2198quality does deteriorate with use, however. Most tapes or disks should 2199be discarded when they begin to produce data errors. EXABYTE tape 2200cartridges should be discarded when they generate an "error count" 2201(number of non-usable bits) of more than 10k. 2202 2203 Magnetic media are written and erased using magnetic fields, and 2204should be protected from such fields to avoid damage to stored data. 2205Sticking a floppy disk to a filing cabinet using a magnet is probably 2206not a good idea. 2207 2208* Menu: 2209 2210* Device:: Device selection and switching 2211* Remote Tape Server:: 2212* Common Problems and Solutions:: 2213* Blocking:: Blocking 2214* Many:: Many archives on one tape 2215* Using Multiple Tapes:: Using Multiple Tapes 2216* label:: Including a Label in the Archive 2217* verify:: 2218* Write Protection:: 2219 2220 2221File: tar.info, Node: Device, Next: Remote Tape Server, Up: Media 2222 22239.1 Device Selection and Switching 2224================================== 2225 2226 _(This message will disappear, once this node revised.)_ 2227 2228'-f [HOSTNAME:]FILE' 2229'--file=[HOSTNAME:]FILE' 2230 Use archive file or device FILE on HOSTNAME. 2231 2232 This option is used to specify the file name of the archive 'tar' 2233works on. 2234 2235 If the file name is '-', 'tar' reads the archive from standard input 2236(when listing or extracting), or writes it to standard output (when 2237creating). If the '-' file name is given when updating an archive, 2238'tar' will read the original archive from its standard input, and will 2239write the entire new archive to its standard output. 2240 2241 If the file name contains a ':', it is interpreted as 'hostname:file 2242name'. If the HOSTNAME contains an "at" sign ('@'), it is treated as 2243'user@hostname:file name'. In either case, 'tar' will invoke the 2244command 'rsh' (or 'remsh') to start up an '/usr/libexec/rmt' on the 2245remote machine. If you give an alternate login name, it will be given 2246to the 'rsh'. Naturally, the remote machine must have an executable 2247'/usr/libexec/rmt'. This program is free software from the University 2248of California, and a copy of the source code can be found with the 2249sources for 'tar'; it's compiled and installed by default. The exact 2250path to this utility is determined when configuring the package. It is 2251'PREFIX/libexec/rmt', where PREFIX stands for your installation prefix. 2252This location may also be overridden at runtime by using the 2253'--rmt-command=COMMAND' option (*Note --rmt-command: Option Summary, for 2254detailed description of this option. *Note Remote Tape Server::, for 2255the description of 'rmt' command). 2256 2257 If this option is not given, but the environment variable 'TAPE' is 2258set, its value is used; otherwise, old versions of 'tar' used a default 2259archive name (which was picked when 'tar' was compiled). The default is 2260normally set up to be the "first" tape drive or other transportable I/O 2261medium on the system. 2262 2263 Starting with version 1.11.5, GNU 'tar' uses standard input and 2264standard output as the default device, and I will not try anymore 2265supporting automatic device detection at installation time. This was 2266failing really in too many cases, it was hopeless. This is now 2267completely left to the installer to override standard input and standard 2268output for default device, if this seems preferable. Further, I think 2269_most_ actual usages of 'tar' are done with pipes or disks, not really 2270tapes, cartridges or diskettes. 2271 2272 Some users think that using standard input and output is running 2273after trouble. This could lead to a nasty surprise on your screen if 2274you forget to specify an output file name--especially if you are going 2275through a network or terminal server capable of buffering large amounts 2276of output. We had so many bug reports in that area of configuring 2277default tapes automatically, and so many contradicting requests, that we 2278finally consider the problem to be portably intractable. We could of 2279course use something like '/dev/tape' as a default, but this is _also_ 2280running after various kind of trouble, going from hung processes to 2281accidental destruction of real tapes. After having seen all this mess, 2282using standard input and output as a default really sounds like the only 2283clean choice left, and a very useful one too. 2284 2285 GNU 'tar' reads and writes archive in records, I suspect this is the 2286main reason why block devices are preferred over character devices. 2287Most probably, block devices are more efficient too. The installer 2288could also check for 'DEFTAPE' in '<sys/mtio.h>'. 2289 2290'--force-local' 2291 Archive file is local even if it contains a colon. 2292 2293'--rsh-command=COMMAND' 2294 Use remote COMMAND instead of 'rsh'. This option exists so that 2295 people who use something other than the standard 'rsh' (e.g., a 2296 Kerberized 'rsh') can access a remote device. 2297 2298 When this command is not used, the shell command found when the 2299 'tar' program was installed is used instead. This is the first 2300 found of '/usr/ucb/rsh', '/usr/bin/remsh', '/usr/bin/rsh', 2301 '/usr/bsd/rsh' or '/usr/bin/nsh'. The installer may have 2302 overridden this by defining the environment variable 'RSH' _at 2303 installation time_. 2304 2305'-[0-7][lmh]' 2306 Specify drive and density. 2307 2308'-M' 2309'--multi-volume' 2310 Create/list/extract multi-volume archive. 2311 2312 This option causes 'tar' to write a "multi-volume" archive--one 2313 that may be larger than will fit on the medium used to hold it. 2314 *Note Multi-Volume Archives::. 2315 2316'-L NUM' 2317'--tape-length=SIZE[SUF]' 2318 Change tape after writing SIZE units of data. Unless SUF is given, 2319 SIZE is treated as kilobytes, i.e. 'SIZE x 1024' bytes. The 2320 following suffixes alter this behavior: 2321 2322 Suffix Units Byte Equivalent 2323 ------------------------------------------------------------- 2324 b Blocks SIZE x 512 2325 B Kilobytes SIZE x 1024 2326 c Bytes SIZE 2327 G Gigabytes SIZE x 1024^3 2328 K Kilobytes SIZE x 1024 2329 k Kilobytes SIZE x 1024 2330 M Megabytes SIZE x 1024^2 2331 P Petabytes SIZE x 1024^5 2332 T Terabytes SIZE x 1024^4 2333 w Words SIZE x 2 2334 2335 Table 9.1: Size Suffixes 2336 2337 This option might be useful when your tape drivers do not properly 2338 detect end of physical tapes. By being slightly conservative on 2339 the maximum tape length, you might avoid the problem entirely. 2340 2341'-F COMMAND' 2342'--info-script=COMMAND' 2343'--new-volume-script=COMMAND' 2344 Execute COMMAND at end of each tape. This implies '--multi-volume' 2345 ('-M'). *Note info-script::, for a detailed description of this 2346 option. 2347 2348 2349File: tar.info, Node: Remote Tape Server, Next: Common Problems and Solutions, Prev: Device, Up: Media 2350 23519.2 Remote Tape Server 2352====================== 2353 2354In order to access the tape drive on a remote machine, 'tar' uses the 2355remote tape server written at the University of California at Berkeley. 2356The remote tape server must be installed as 'PREFIX/libexec/rmt' on any 2357machine whose tape drive you want to use. 'tar' calls 'rmt' by running 2358an 'rsh' or 'remsh' to the remote machine, optionally using a different 2359login name if one is supplied. 2360 2361 A copy of the source for the remote tape server is provided. Its 2362source code can be freely distributed. It is compiled and installed by 2363default. 2364 2365 Unless you use the '--absolute-names' ('-P') option, GNU 'tar' will 2366not allow you to create an archive that contains absolute file names (a 2367file name beginning with '/'). If you try, 'tar' will automatically 2368remove the leading '/' from the file names it stores in the archive. It 2369will also type a warning message telling you what it is doing. 2370 2371 When reading an archive that was created with a different 'tar' 2372program, GNU 'tar' automatically extracts entries in the archive which 2373have absolute file names as if the file names were not absolute. This 2374is an important feature. A visitor here once gave a 'tar' tape to an 2375operator to restore; the operator used Sun 'tar' instead of GNU 'tar', 2376and the result was that it replaced large portions of our '/bin' and 2377friends with versions from the tape; needless to say, we were unhappy 2378about having to recover the file system from backup tapes. 2379 2380 For example, if the archive contained a file '/usr/bin/computoy', GNU 2381'tar' would extract the file to 'usr/bin/computoy', relative to the 2382current directory. If you want to extract the files in an archive to 2383the same absolute names that they had when the archive was created, you 2384should do a 'cd /' before extracting the files from the archive, or you 2385should either use the '--absolute-names' option, or use the command 'tar 2386-C / ...'. 2387 2388 Some versions of Unix (Ultrix 3.1 is known to have this problem), can 2389claim that a short write near the end of a tape succeeded, when it 2390actually failed. This will result in the -M option not working 2391correctly. The best workaround at the moment is to use a significantly 2392larger blocking factor than the default 20. 2393 2394 In order to update an archive, 'tar' must be able to backspace the 2395archive in order to reread or rewrite a record that was just read (or 2396written). This is currently possible only on two kinds of files: normal 2397disk files (or any other file that can be backspaced with 'lseek'), and 2398industry-standard 9-track magnetic tape (or any other kind of tape that 2399can be backspaced with the 'MTIOCTOP' 'ioctl'). 2400 2401 This means that the '--append', '--concatenate', and '--delete' 2402commands will not work on any other kind of file. Some media simply 2403cannot be backspaced, which means these commands and options will never 2404be able to work on them. These non-backspacing media include pipes and 2405cartridge tape drives. 2406 2407 Some other media can be backspaced, and 'tar' will work on them once 2408'tar' is modified to do so. 2409 2410 Archives created with the '--multi-volume', '--label', and 2411'--incremental' ('-G') options may not be readable by other version of 2412'tar'. In particular, restoring a file that was split over a volume 2413boundary will require some careful work with 'dd', if it can be done at 2414all. Other versions of 'tar' may also create an empty file whose name 2415is that of the volume header. Some versions of 'tar' may create normal 2416files instead of directories archived with the '--incremental' ('-G') 2417option. 2418 2419 2420File: tar.info, Node: Common Problems and Solutions, Next: Blocking, Prev: Remote Tape Server, Up: Media 2421 24229.3 Some Common Problems and their Solutions 2423============================================ 2424 2425errors from system: 2426permission denied 2427no such file or directory 2428not owner 2429 2430errors from 'tar': 2431directory checksum error 2432header format error 2433 2434errors from media/system: 2435i/o error 2436device busy 2437 2438 2439File: tar.info, Node: Blocking, Next: Many, Prev: Common Problems and Solutions, Up: Media 2440 24419.4 Blocking 2442============ 2443 2444"Block" and "record" terminology is rather confused, and it is also 2445confusing to the expert reader. On the other hand, readers who are new 2446to the field have a fresh mind, and they may safely skip the next two 2447paragraphs, as the remainder of this manual uses those two terms in a 2448quite consistent way. 2449 2450 John Gilmore, the writer of the public domain 'tar' from which GNU 2451'tar' was originally derived, wrote (June 1995): 2452 2453 The nomenclature of tape drives comes from IBM, where I believe 2454 they were invented for the IBM 650 or so. On IBM mainframes, what 2455 is recorded on tape are tape blocks. The logical organization of 2456 data is into records. There are various ways of putting records 2457 into blocks, including 'F' (fixed sized records), 'V' (variable 2458 sized records), 'FB' (fixed blocked: fixed size records, N to a 2459 block), 'VB' (variable size records, N to a block), 'VSB' (variable 2460 spanned blocked: variable sized records that can occupy more than 2461 one block), etc. The 'JCL' 'DD RECFORM=' parameter specified this 2462 to the operating system. 2463 2464 The Unix man page on 'tar' was totally confused about this. When I 2465 wrote 'PD TAR', I used the historically correct terminology ('tar' 2466 writes data records, which are grouped into blocks). It appears 2467 that the bogus terminology made it into POSIX (no surprise here), 2468 and now François has migrated that terminology back into the source 2469 code too. 2470 2471 The term "physical block" means the basic transfer chunk from or to a 2472device, after which reading or writing may stop without anything being 2473lost. In this manual, the term "block" usually refers to a disk 2474physical block, _assuming_ that each disk block is 512 bytes in length. 2475It is true that some disk devices have different physical blocks, but 2476'tar' ignore these differences in its own format, which is meant to be 2477portable, so a 'tar' block is always 512 bytes in length, and "block" 2478always mean a 'tar' block. The term "logical block" often represents 2479the basic chunk of allocation of many disk blocks as a single entity, 2480which the operating system treats somewhat atomically; this concept is 2481only barely used in GNU 'tar'. 2482 2483 The term "physical record" is another way to speak of a physical 2484block, those two terms are somewhat interchangeable. In this manual, 2485the term "record" usually refers to a tape physical block, _assuming_ 2486that the 'tar' archive is kept on magnetic tape. It is true that 2487archives may be put on disk or used with pipes, but nevertheless, 'tar' 2488tries to read and write the archive one "record" at a time, whatever the 2489medium in use. One record is made up of an integral number of blocks, 2490and this operation of putting many disk blocks into a single tape block 2491is called "reblocking", or more simply, "blocking". The term "logical 2492record" refers to the logical organization of many characters into 2493something meaningful to the application. The term "unit record" 2494describes a small set of characters which are transmitted whole to or by 2495the application, and often refers to a line of text. Those two last 2496terms are unrelated to what we call a "record" in GNU 'tar'. 2497 2498 When writing to tapes, 'tar' writes the contents of the archive in 2499chunks known as "records". To change the default blocking factor, use 2500the '--blocking-factor=512-SIZE' ('-b 512-SIZE') option. Each record 2501will then be composed of 512-SIZE blocks. (Each 'tar' block is 512 2502bytes. *Note Standard::.) Each file written to the archive uses at 2503least one full record. As a result, using a larger record size can 2504result in more wasted space for small files. On the other hand, a 2505larger record size can often be read and written much more efficiently. 2506 2507 Further complicating the problem is that some tape drives ignore the 2508blocking entirely. For these, a larger record size can still improve 2509performance (because the software layers above the tape drive still 2510honor the blocking), but not as dramatically as on tape drives that 2511honor blocking. 2512 2513 When reading an archive, 'tar' can usually figure out the record size 2514on itself. When this is the case, and a non-standard record size was 2515used when the archive was created, 'tar' will print a message about a 2516non-standard blocking factor, and then operate normally(1). On some 2517tape devices, however, 'tar' cannot figure out the record size itself. 2518On most of those, you can specify a blocking factor (with 2519'--blocking-factor') larger than the actual blocking factor, and then 2520use the '--read-full-records' ('-B') option. (If you specify a blocking 2521factor with '--blocking-factor' and don't use the '--read-full-records' 2522option, then 'tar' will not attempt to figure out the recording size 2523itself.) On some devices, you must always specify the record size 2524exactly with '--blocking-factor' when reading, because 'tar' cannot 2525figure it out. In any case, use '--list' ('-t') before doing any 2526extractions to see whether 'tar' is reading the archive correctly. 2527 2528 'tar' blocks are all fixed size (512 bytes), and its scheme for 2529putting them into records is to put a whole number of them (one or more) 2530into each record. 'tar' records are all the same size; at the end of 2531the file there's a block containing all zeros, which is how you tell 2532that the remainder of the last record(s) are garbage. 2533 2534 In a standard 'tar' file (no options), the block size is 512 and the 2535record size is 10240, for a blocking factor of 20. What the 2536'--blocking-factor' option does is sets the blocking factor, changing 2537the record size while leaving the block size at 512 bytes. 20 was fine 2538for ancient 800 or 1600 bpi reel-to-reel tape drives; most tape drives 2539these days prefer much bigger records in order to stream and not waste 2540tape. When writing tapes for myself, some tend to use a factor of the 2541order of 2048, say, giving a record size of around one megabyte. 2542 2543 If you use a blocking factor larger than 20, older 'tar' programs 2544might not be able to read the archive, so we recommend this as a limit 2545to use in practice. GNU 'tar', however, will support arbitrarily large 2546record sizes, limited only by the amount of virtual memory or the 2547physical characteristics of the tape device. 2548 2549* Menu: 2550 2551* Format Variations:: Format Variations 2552* Blocking Factor:: The Blocking Factor of an Archive 2553 2554 ---------- Footnotes ---------- 2555 2556 (1) If this message is not needed, you can turn it off using the 2557'--warning=no-record-size' option. 2558 2559 2560File: tar.info, Node: Format Variations, Next: Blocking Factor, Up: Blocking 2561 25629.4.1 Format Variations 2563----------------------- 2564 2565 _(This message will disappear, once this node revised.)_ 2566 2567 Format parameters specify how an archive is written on the archive 2568media. The best choice of format parameters will vary depending on the 2569type and number of files being archived, and on the media used to store 2570the archive. 2571 2572 To specify format parameters when accessing or creating an archive, 2573you can use the options described in the following sections. If you do 2574not specify any format parameters, 'tar' uses default parameters. You 2575cannot modify a compressed archive. If you create an archive with the 2576'--blocking-factor' option specified (*note Blocking Factor::), you must 2577specify that blocking-factor when operating on the archive. *Note 2578Formats::, for other examples of format parameter considerations. 2579 2580 2581File: tar.info, Node: Blocking Factor, Prev: Format Variations, Up: Blocking 2582 25839.4.2 The Blocking Factor of an Archive 2584--------------------------------------- 2585 2586 _(This message will disappear, once this node revised.)_ 2587 2588 The data in an archive is grouped into blocks, which are 512 bytes. 2589Blocks are read and written in whole number multiples called "records". 2590The number of blocks in a record (i.e., the size of a record in units of 2591512 bytes) is called the "blocking factor". The 2592'--blocking-factor=512-SIZE' ('-b 512-SIZE') option specifies the 2593blocking factor of an archive. The default blocking factor is typically 259420 (i.e., 10240 bytes), but can be specified at installation. To find 2595out the blocking factor of an existing archive, use 'tar --list 2596--file=ARCHIVE-NAME'. This may not work on some devices. 2597 2598 Records are separated by gaps, which waste space on the archive 2599media. If you are archiving on magnetic tape, using a larger blocking 2600factor (and therefore larger records) provides faster throughput and 2601allows you to fit more data on a tape (because there are fewer gaps). 2602If you are archiving on cartridge, a very large blocking factor (say 126 2603or more) greatly increases performance. A smaller blocking factor, on 2604the other hand, may be useful when archiving small files, to avoid 2605archiving lots of nulls as 'tar' fills out the archive to the end of the 2606record. In general, the ideal record size depends on the size of the 2607inter-record gaps on the tape you are using, and the average size of the 2608files you are archiving. *Note create::, for information on writing 2609archives. 2610 2611 Archives with blocking factors larger than 20 cannot be read by very 2612old versions of 'tar', or by some newer versions of 'tar' running on old 2613machines with small address spaces. With GNU 'tar', the blocking factor 2614of an archive is limited only by the maximum record size of the device 2615containing the archive, or by the amount of available virtual memory. 2616 2617 Also, on some systems, not using adequate blocking factors, as 2618sometimes imposed by the device drivers, may yield unexpected 2619diagnostics. For example, this has been reported: 2620 2621 Cannot write to /dev/dlt: Invalid argument 2622 2623In such cases, it sometimes happen that the 'tar' bundled by the system 2624is aware of block size idiosyncrasies, while GNU 'tar' requires an 2625explicit specification for the block size, which it cannot guess. This 2626yields some people to consider GNU 'tar' is misbehaving, because by 2627comparison, 'the bundle 'tar' works OK'. Adding '-b 256', for example, 2628might resolve the problem. 2629 2630 If you use a non-default blocking factor when you create an archive, 2631you must specify the same blocking factor when you modify that archive. 2632Some archive devices will also require you to specify the blocking 2633factor when reading that archive, however this is not typically the 2634case. Usually, you can use '--list' ('-t') without specifying a 2635blocking factor--'tar' reports a non-default record size and then lists 2636the archive members as it would normally. To extract files from an 2637archive with a non-standard blocking factor (particularly if you're not 2638sure what the blocking factor is), you can usually use the 2639'--read-full-records' ('-B') option while specifying a blocking factor 2640larger then the blocking factor of the archive (i.e., 'tar --extract 2641--read-full-records --blocking-factor=300'). *Note list::, for more 2642information on the '--list' ('-t') operation. *Note Reading::, for a 2643more detailed explanation of that option. 2644 2645'--blocking-factor=NUMBER' 2646'-b NUMBER' 2647 Specifies the blocking factor of an archive. Can be used with any 2648 operation, but is usually not necessary with '--list' ('-t'). 2649 2650 Device blocking 2651 2652'-b BLOCKS' 2653'--blocking-factor=BLOCKS' 2654 Set record size to BLOCKS*512 bytes. 2655 2656 This option is used to specify a "blocking factor" for the archive. 2657 When reading or writing the archive, 'tar', will do reads and 2658 writes of the archive in records of BLOCK*512 bytes. This is true 2659 even when the archive is compressed. Some devices requires that 2660 all write operations be a multiple of a certain size, and so, 'tar' 2661 pads the archive out to the next record boundary. 2662 2663 The default blocking factor is set when 'tar' is compiled, and is 2664 typically 20. Blocking factors larger than 20 cannot be read by 2665 very old versions of 'tar', or by some newer versions of 'tar' 2666 running on old machines with small address spaces. 2667 2668 With a magnetic tape, larger records give faster throughput and fit 2669 more data on a tape (because there are fewer inter-record gaps). 2670 If the archive is in a disk file or a pipe, you may want to specify 2671 a smaller blocking factor, since a large one will result in a large 2672 number of null bytes at the end of the archive. 2673 2674 When writing cartridge or other streaming tapes, a much larger 2675 blocking factor (say 126 or more) will greatly increase 2676 performance. However, you must specify the same blocking factor 2677 when reading or updating the archive. 2678 2679 Apparently, Exabyte drives have a physical block size of 8K bytes. 2680 If we choose our blocksize as a multiple of 8k bytes, then the 2681 problem seems to disappear. Id est, we are using block size of 112 2682 right now, and we haven't had the problem since we switched... 2683 2684 With GNU 'tar' the blocking factor is limited only by the maximum 2685 record size of the device containing the archive, or by the amount 2686 of available virtual memory. 2687 2688 However, deblocking or reblocking is virtually avoided in a special 2689 case which often occurs in practice, but which requires all the 2690 following conditions to be simultaneously true: 2691 * the archive is subject to a compression option, 2692 * the archive is not handled through standard input or output, 2693 nor redirected nor piped, 2694 * the archive is directly handled to a local disk, instead of 2695 any special device, 2696 * '--blocking-factor' is not explicitly specified on the 'tar' 2697 invocation. 2698 2699 If the output goes directly to a local disk, and not through 2700 stdout, then the last write is not extended to a full record size. 2701 Otherwise, reblocking occurs. Here are a few other remarks on this 2702 topic: 2703 2704 * 'gzip' will complain about trailing garbage if asked to 2705 uncompress a compressed archive on tape, there is an option to 2706 turn the message off, but it breaks the regularity of simply 2707 having to use 'PROG -d' for decompression. It would be nice 2708 if gzip was silently ignoring any number of trailing zeros. 2709 I'll ask Jean-loup Gailly, by sending a copy of this message 2710 to him. 2711 2712 * 'compress' does not show this problem, but as Jean-loup 2713 pointed out to Michael, 'compress -d' silently adds garbage 2714 after the result of decompression, which tar ignores because 2715 it already recognized its end-of-file indicator. So this bug 2716 may be safely ignored. 2717 2718 * 'gzip -d -q' will be silent about the trailing zeros indeed, 2719 but will still return an exit status of 2 which tar reports in 2720 turn. 'tar' might ignore the exit status returned, but I hate 2721 doing that, as it weakens the protection 'tar' offers users 2722 against other possible problems at decompression time. If 2723 'gzip' was silently skipping trailing zeros _and_ also 2724 avoiding setting the exit status in this innocuous case, that 2725 would solve this situation. 2726 2727 * 'tar' should become more solid at not stopping to read a pipe 2728 at the first null block encountered. This inelegantly breaks 2729 the pipe. 'tar' should rather drain the pipe out before 2730 exiting itself. 2731 2732'-i' 2733'--ignore-zeros' 2734 Ignore blocks of zeros in archive (means EOF). 2735 2736 The '--ignore-zeros' ('-i') option causes 'tar' to ignore blocks of 2737 zeros in the archive. Normally a block of zeros indicates the end 2738 of the archive, but when reading a damaged archive, or one which 2739 was created by concatenating several archives together, this option 2740 allows 'tar' to read the entire archive. This option is not on by 2741 default because many versions of 'tar' write garbage after the 2742 zeroed blocks. 2743 2744 Note that this option causes 'tar' to read to the end of the 2745 archive file, which may sometimes avoid problems when multiple 2746 files are stored on a single physical tape. 2747 2748'-B' 2749'--read-full-records' 2750 Reblock as we read (for reading 4.2BSD pipes). 2751 2752 If '--read-full-records' is used, 'tar' will not panic if an 2753 attempt to read a record from the archive does not return a full 2754 record. Instead, 'tar' will keep reading until it has obtained a 2755 full record. 2756 2757 This option is turned on by default when 'tar' is reading an 2758 archive from standard input, or from a remote machine. This is 2759 because on BSD Unix systems, a read of a pipe will return however 2760 much happens to be in the pipe, even if it is less than 'tar' 2761 requested. If this option was not used, 'tar' would fail as soon 2762 as it read an incomplete record from the pipe. 2763 2764 This option is also useful with the commands for updating an 2765 archive. 2766 2767 Tape blocking 2768 2769 When handling various tapes or cartridges, you have to take care of 2770selecting a proper blocking, that is, the number of disk blocks you put 2771together as a single tape block on the tape, without intervening tape 2772gaps. A "tape gap" is a small landing area on the tape with no 2773information on it, used for decelerating the tape to a full stop, and 2774for later regaining the reading or writing speed. When the tape driver 2775starts reading a record, the record has to be read whole without 2776stopping, as a tape gap is needed to stop the tape motion without losing 2777information. 2778 2779 Using higher blocking (putting more disk blocks per tape block) will 2780use the tape more efficiently as there will be less tape gaps. But 2781reading such tapes may be more difficult for the system, as more memory 2782will be required to receive at once the whole record. Further, if there 2783is a reading error on a huge record, this is less likely that the system 2784will succeed in recovering the information. So, blocking should not be 2785too low, nor it should be too high. 'tar' uses by default a blocking of 278620 for historical reasons, and it does not really matter when reading or 2787writing to disk. Current tape technology would easily accommodate 2788higher blockings. Sun recommends a blocking of 126 for Exabytes and 96 2789for DATs. We were told that for some DLT drives, the blocking should be 2790a multiple of 4Kb, preferably 64Kb ('-b 128') or 256 for decent 2791performance. Other manufacturers may use different recommendations for 2792the same tapes. This might also depends of the buffering techniques 2793used inside modern tape controllers. Some imposes a minimum blocking, 2794or a maximum blocking. Others request blocking to be some exponent of 2795two. 2796 2797 So, there is no fixed rule for blocking. But blocking at read time 2798should ideally be the same as blocking used at write time. At one place 2799I know, with a wide variety of equipment, they found it best to use a 2800blocking of 32 to guarantee that their tapes are fully interchangeable. 2801 2802 I was also told that, for recycled tapes, prior erasure (by the same 2803drive unit that will be used to create the archives) sometimes lowers 2804the error rates observed at rewriting time. 2805 2806 I might also use '--number-blocks' instead of '--block-number', so 2807'--block' will then expand to '--blocking-factor' unambiguously. 2808 2809 2810File: tar.info, Node: Many, Next: Using Multiple Tapes, Prev: Blocking, Up: Media 2811 28129.5 Many Archives on One Tape 2813============================= 2814 2815Most tape devices have two entries in the '/dev' directory, or entries 2816that come in pairs, which differ only in the minor number for this 2817device. Let's take for example '/dev/tape', which often points to the 2818only or usual tape device of a given system. There might be a 2819corresponding '/dev/nrtape' or '/dev/ntape'. The simpler name is the 2820_rewinding_ version of the device, while the name having 'nr' in it is 2821the _no rewinding_ version of the same device. 2822 2823 A rewinding tape device will bring back the tape to its beginning 2824point automatically when this device is opened or closed. Since 'tar' 2825opens the archive file before using it and closes it afterwards, this 2826means that a simple: 2827 2828 $ tar cf /dev/tape DIRECTORY 2829 2830will reposition the tape to its beginning both prior and after saving 2831DIRECTORY contents to it, thus erasing prior tape contents and making it 2832so that any subsequent write operation will destroy what has just been 2833saved. 2834 2835 So, a rewinding device is normally meant to hold one and only one 2836file. If you want to put more than one 'tar' archive on a given tape, 2837you will need to avoid using the rewinding version of the tape device. 2838You will also have to pay special attention to tape positioning. Errors 2839in positioning may overwrite the valuable data already on your tape. 2840Many people, burnt by past experiences, will only use rewinding devices 2841and limit themselves to one file per tape, precisely to avoid the risk 2842of such errors. Be fully aware that writing at the wrong position on a 2843tape loses all information past this point and most probably until the 2844end of the tape, and this destroyed information _cannot_ be recovered. 2845 2846 To save DIRECTORY-1 as a first archive at the beginning of a tape, 2847and leave that tape ready for a second archive, you should use: 2848 2849 $ mt -f /dev/nrtape rewind 2850 $ tar cf /dev/nrtape DIRECTORY-1 2851 2852 "Tape marks" are special magnetic patterns written on the tape media, 2853which are later recognizable by the reading hardware. These marks are 2854used after each file, when there are many on a single tape. An empty 2855file (that is to say, two tape marks in a row) signal the logical end of 2856the tape, after which no file exist. Usually, non-rewinding tape device 2857drivers will react to the close request issued by 'tar' by first writing 2858two tape marks after your archive, and by backspacing over one of these. 2859So, if you remove the tape at that time from the tape drive, it is 2860properly terminated. But if you write another file at the current 2861position, the second tape mark will be erased by the new information, 2862leaving only one tape mark between files. 2863 2864 So, you may now save DIRECTORY-2 as a second archive after the first 2865on the same tape by issuing the command: 2866 2867 $ tar cf /dev/nrtape DIRECTORY-2 2868 2869and so on for all the archives you want to put on the same tape. 2870 2871 Another usual case is that you do not write all the archives the same 2872day, and you need to remove and store the tape between two archive 2873sessions. In general, you must remember how many files are already 2874saved on your tape. Suppose your tape already has 16 files on it, and 2875that you are ready to write the 17th. You have to take care of skipping 2876the first 16 tape marks before saving DIRECTORY-17, say, by using these 2877commands: 2878 2879 $ mt -f /dev/nrtape rewind 2880 $ mt -f /dev/nrtape fsf 16 2881 $ tar cf /dev/nrtape DIRECTORY-17 2882 2883 In all the previous examples, we put aside blocking considerations, 2884but you should do the proper things for that as well. *Note Blocking::. 2885 2886* Menu: 2887 2888* Tape Positioning:: Tape Positions and Tape Marks 2889* mt:: The 'mt' Utility 2890 2891 2892File: tar.info, Node: Tape Positioning, Next: mt, Up: Many 2893 28949.5.1 Tape Positions and Tape Marks 2895----------------------------------- 2896 2897 _(This message will disappear, once this node revised.)_ 2898 2899 Just as archives can store more than one file from the file system, 2900tapes can store more than one archive file. To keep track of where 2901archive files (or any other type of file stored on tape) begin and end, 2902tape archive devices write magnetic "tape marks" on the archive media. 2903Tape drives write one tape mark between files, two at the end of all the 2904file entries. 2905 2906 If you think of data as a series of records "rrrr"'s, and tape marks 2907as "*"'s, a tape might look like the following: 2908 2909 rrrr*rrrrrr*rrrrr*rr*rrrrr**------------------------- 2910 2911 Tape devices read and write tapes using a read/write "tape head"--a 2912physical part of the device which can only access one point on the tape 2913at a time. When you use 'tar' to read or write archive data from a tape 2914device, the device will begin reading or writing from wherever on the 2915tape the tape head happens to be, regardless of which archive or what 2916part of the archive the tape head is on. Before writing an archive, you 2917should make sure that no data on the tape will be overwritten (unless it 2918is no longer needed). Before reading an archive, you should make sure 2919the tape head is at the beginning of the archive you want to read. You 2920can do it manually via 'mt' utility (*note mt::). The 'restore' script 2921does that automatically (*note Scripted Restoration::). 2922 2923 If you want to add new archive file entries to a tape, you should 2924advance the tape to the end of the existing file entries, backspace over 2925the last tape mark, and write the new archive file. If you were to add 2926two archives to the example above, the tape might look like the 2927following: 2928 2929 rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- 2930 2931 2932File: tar.info, Node: mt, Prev: Tape Positioning, Up: Many 2933 29349.5.2 The 'mt' Utility 2935---------------------- 2936 2937 _(This message will disappear, once this node revised.)_ 2938 2939 *Note Blocking Factor::. 2940 2941 You can use the 'mt' utility to advance or rewind a tape past a 2942specified number of archive files on the tape. This will allow you to 2943move to the beginning of an archive before extracting or reading it, or 2944to the end of all the archives before writing a new one. 2945 2946 The syntax of the 'mt' command is: 2947 2948 mt [-f TAPENAME] OPERATION [NUMBER] 2949 2950 where TAPENAME is the name of the tape device, NUMBER is the number 2951of times an operation is performed (with a default of one), and 2952OPERATION is one of the following: 2953 2954'eof' 2955'weof' 2956 Writes NUMBER tape marks at the current position on the tape. 2957 2958'fsf' 2959 Moves tape position forward NUMBER files. 2960 2961'bsf' 2962 Moves tape position back NUMBER files. 2963 2964'rewind' 2965 Rewinds the tape. (Ignores NUMBER.) 2966 2967'offline' 2968'rewoff1' 2969 Rewinds the tape and takes the tape device off-line. (Ignores 2970 NUMBER.) 2971 2972'status' 2973 Prints status information about the tape unit. 2974 2975 If you don't specify a TAPENAME, 'mt' uses the environment variable 2976'TAPE'; if 'TAPE' is not set, 'mt' will use the default device specified 2977in your 'sys/mtio.h' file ('DEFTAPE' variable). If this is not defined, 2978the program will display a descriptive error message and exit with code 29791. 2980 2981 'mt' returns a 0 exit status when the operation(s) were successful, 1 2982if the command was unrecognized, and 2 if an operation failed. 2983 2984 2985File: tar.info, Node: Using Multiple Tapes, Next: label, Prev: Many, Up: Media 2986 29879.6 Using Multiple Tapes 2988======================== 2989 2990Often you might want to write a large archive, one larger than will fit 2991on the actual tape you are using. In such a case, you can run multiple 2992'tar' commands, but this can be inconvenient, particularly if you are 2993using options like '--exclude=PATTERN' or dumping entire file systems. 2994Therefore, 'tar' provides a special mode for creating multi-volume 2995archives. 2996 2997 "Multi-volume" archive is a single 'tar' archive, stored on several 2998media volumes of fixed size. Although in this section we will often 2999call 'volume' a "tape", there is absolutely no requirement for 3000multi-volume archives to be stored on tapes. Instead, they can use 3001whatever media type the user finds convenient, they can even be located 3002on files. 3003 3004 When creating a multi-volume archive, GNU 'tar' continues to fill 3005current volume until it runs out of space, then it switches to next 3006volume (usually the operator is queried to replace the tape on this 3007point), and continues working on the new volume. This operation 3008continues until all requested files are dumped. If GNU 'tar' detects 3009end of media while dumping a file, such a file is archived in split 3010form. Some very big files can even be split across several volumes. 3011 3012 Each volume is itself a valid GNU 'tar' archive, so it can be read 3013without any special options. Consequently any file member residing 3014entirely on one volume can be extracted or otherwise operated upon 3015without needing the other volume. Sure enough, to extract a split 3016member you would need all volumes its parts reside on. 3017 3018 Multi-volume archives suffer from several limitations. In 3019particular, they cannot be compressed. 3020 3021 GNU 'tar' is able to create multi-volume archives of two formats 3022(*note Formats::): 'GNU' and 'POSIX'. 3023 3024* Menu: 3025 3026* Multi-Volume Archives:: Archives Longer than One Tape or Disk 3027* Tape Files:: Tape Files 3028* Tarcat:: Concatenate Volumes into a Single Archive 3029 3030 3031File: tar.info, Node: Multi-Volume Archives, Next: Tape Files, Up: Using Multiple Tapes 3032 30339.6.1 Archives Longer than One Tape or Disk 3034------------------------------------------- 3035 3036To create an archive that is larger than will fit on a single unit of 3037the media, use the '--multi-volume' ('-M') option in conjunction with 3038the '--create' option (*note create::). A "multi-volume" archive can be 3039manipulated like any other archive (provided the '--multi-volume' option 3040is specified), but is stored on more than one tape or file. 3041 3042 When you specify '--multi-volume', 'tar' does not report an error 3043when it comes to the end of an archive volume (when reading), or the end 3044of the media (when writing). Instead, it prompts you to load a new 3045storage volume. If the archive is on a magnetic tape, you should change 3046tapes when you see the prompt; if the archive is on a floppy disk, you 3047should change disks; etc. 3048 3049'--multi-volume' 3050'-M' 3051 Creates a multi-volume archive, when used in conjunction with 3052 '--create' ('-c'). To perform any other operation on a 3053 multi-volume archive, specify '--multi-volume' in conjunction with 3054 that operation. For example: 3055 3056 $ tar --create --multi-volume --file=/dev/tape FILES 3057 3058 The method 'tar' uses to detect end of tape is not perfect, and fails 3059on some operating systems or on some devices. If 'tar' cannot detect 3060the end of the tape itself, you can use '--tape-length' option to inform 3061it about the capacity of the tape: 3062 3063'--tape-length=SIZE[SUF]' 3064'-L SIZE[SUF]' 3065 Set maximum length of a volume. The SUF, if given, specifies units 3066 in which SIZE is expressed, e.g. '2M' mean 2 megabytes (*note 3067 Table 9.1: size-suffixes, for a list of allowed size suffixes). 3068 Without SUF, units of 1024 bytes (kilobyte) are assumed. 3069 3070 This option selects '--multi-volume' automatically. For example: 3071 3072 $ tar --create --tape-length=41943040 --file=/dev/tape FILES 3073 3074 or, which is equivalent: 3075 3076 $ tar --create --tape-length=4G --file=/dev/tape FILES 3077 3078 When GNU 'tar' comes to the end of a storage media, it asks you to 3079change the volume. The built-in prompt for POSIX locale is(1): 3080 3081 Prepare volume #N for 'ARCHIVE' and hit return: 3082 3083where N is the ordinal number of the volume to be created and ARCHIVE is 3084archive file or device name. 3085 3086 When prompting for a new tape, 'tar' accepts any of the following 3087responses: 3088 3089'?' 3090 Request 'tar' to explain possible responses. 3091'q' 3092 Request 'tar' to exit immediately. 3093'n FILE-NAME' 3094 Request 'tar' to write the next volume on the file FILE-NAME. 3095'!' 3096 Request 'tar' to run a subshell. This option can be disabled by 3097 giving '--restrict' command line option to 'tar'(2). 3098'y' 3099 Request 'tar' to begin writing the next volume. 3100 3101 (You should only type 'y' after you have changed the tape; otherwise 3102'tar' will write over the volume it just finished.) 3103 3104 The volume number used by 'tar' in its tape-changing prompt can be 3105changed; if you give the '--volno-file=FILE-OF-NUMBER' option, then 3106FILE-OF-NUMBER should be an non-existing file to be created, or else, a 3107file already containing a decimal number. That number will be used as 3108the volume number of the first volume written. When 'tar' is finished, 3109it will rewrite the file with the now-current volume number. (This does 3110not change the volume number written on a tape label, as per *note 3111label::, it _only_ affects the number used in the prompt.) 3112 3113 If you want more elaborate behavior than this, you can write a 3114special "new volume script", that will be responsible for changing the 3115volume, and instruct 'tar' to use it instead of its normal prompting 3116procedure: 3117 3118'--info-script=COMMAND' 3119'--new-volume-script=COMMAND' 3120'-F COMMAND' 3121 Specify the command to invoke when switching volumes. The COMMAND 3122 can be used to eject cassettes, or to broadcast messages such as 3123 'Someone please come change my tape' when performing unattended 3124 backups. 3125 3126 The COMMAND can contain additional options, if such are needed. 3127*Note Running External Commands: external, for a detailed discussion of 3128the way GNU 'tar' runs external commands. It inherits 'tar''s shell 3129environment. Additional data is passed to it via the following 3130environment variables: 3131 3132'TAR_VERSION' 3133 GNU 'tar' version number. 3134 3135'TAR_ARCHIVE' 3136 The name of the archive 'tar' is processing. 3137 3138'TAR_BLOCKING_FACTOR' 3139 Current blocking factor (*note Blocking::). 3140 3141'TAR_VOLUME' 3142 Ordinal number of the volume 'tar' is about to start. 3143 3144'TAR_SUBCOMMAND' 3145 A short option describing the operation 'tar' is executing. *Note 3146 Operations::, for a complete list of subcommand options. 3147 3148'TAR_FORMAT' 3149 Format of the archive being processed. *Note Formats::, for a 3150 complete list of archive format names. 3151 3152'TAR_FD' 3153 File descriptor which can be used to communicate the new volume 3154 name to 'tar'. 3155 3156 These variables can be used in the COMMAND itself, provided that they 3157are properly quoted to prevent them from being expanded by the shell 3158that invokes 'tar'. 3159 3160 The volume script can instruct 'tar' to use new archive name, by 3161writing in to file descriptor '$TAR_FD' (see below for an example). 3162 3163 If the info script fails, 'tar' exits; otherwise, it begins writing 3164the next volume. 3165 3166 If you want 'tar' to cycle through a series of files or tape drives, 3167there are three approaches to choose from. First of all, you can give 3168'tar' multiple '--file' options. In this case the specified files will 3169be used, in sequence, as the successive volumes of the archive. Only 3170when the first one in the sequence needs to be used again will 'tar' 3171prompt for a tape change (or run the info script). For example, suppose 3172someone has two tape drives on a system named '/dev/tape0' and 3173'/dev/tape1'. For having GNU 'tar' to switch to the second drive when 3174it needs to write the second tape, and then back to the first tape, 3175etc., just do either of: 3176 3177 $ tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 FILES 3178 $ tar -cM -f /dev/tape0 -f /dev/tape1 FILES 3179 3180 The second method is to use the 'n' response to the tape-change 3181prompt. 3182 3183 Finally, the most flexible approach is to use a volume script, that 3184writes new archive name to the file descriptor '$TAR_FD'. For example, 3185the following volume script will create a series of archive files, named 3186'ARCHIVE-VOL', where ARCHIVE is the name of the archive being created 3187(as given by '--file' option) and VOL is the ordinal number of the 3188archive being created: 3189 3190 #! /bin/bash 3191 # For this script it's advisable to use a shell, such as Bash, 3192 # that supports a TAR_FD value greater than 9. 3193 3194 echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE. 3195 3196 name=`expr $TAR_ARCHIVE : '\(.*\)-.*'` 3197 case $TAR_SUBCOMMAND in 3198 -c) ;; 3199 -d|-x|-t) test -r ${name:-$TAR_ARCHIVE}-$TAR_VOLUME || exit 1 3200 ;; 3201 *) exit 1 3202 esac 3203 3204 echo ${name:-$TAR_ARCHIVE}-$TAR_VOLUME >&$TAR_FD 3205 3206 The same script can be used while listing, comparing or extracting 3207from the created archive. For example: 3208 3209 # Create a multi-volume archive: 3210 $ tar -c -L1024 -f archive.tar -F new-volume . 3211 # Extract from the created archive: 3212 $ tar -x -f archive.tar -F new-volume . 3213 3214Notice, that the first command had to use '-L' option, since otherwise 3215GNU 'tar' will end up writing everything to file 'archive.tar'. 3216 3217 You can read each individual volume of a multi-volume archive as if 3218it were an archive by itself. For example, to list the contents of one 3219volume, use '--list', without '--multi-volume' specified. To extract an 3220archive member from one volume (assuming it is described that volume), 3221use '--extract', again without '--multi-volume'. 3222 3223 If an archive member is split across volumes (i.e., its entry begins 3224on one volume of the media and ends on another), you need to specify 3225'--multi-volume' to extract it successfully. In this case, you should 3226load the volume where the archive member starts, and use 'tar --extract 3227--multi-volume'--'tar' will prompt for later volumes as it needs them. 3228*Note extracting archives::, for more information about extracting 3229archives. 3230 3231 Multi-volume archives can be modified like any other archive. To add 3232files to a multi-volume archive, you need to only mount the last volume 3233of the archive media (and new volumes, if needed). For all other 3234operations, you need to use the entire archive. 3235 3236 If a multi-volume archive was labeled using '--label=ARCHIVE-LABEL' 3237(*note label::) when it was created, 'tar' will not automatically label 3238volumes which are added later. To label subsequent volumes, specify 3239'--label=ARCHIVE-LABEL' again in conjunction with the '--append', 3240'--update' or '--concatenate' operation. 3241 3242 Notice that multi-volume support is a GNU extension and the archives 3243created in this mode should be read only using GNU 'tar'. If you 3244absolutely have to process such archives using a third-party 'tar' 3245implementation, read *note Split Recovery::. 3246 3247 ---------- Footnotes ---------- 3248 3249 (1) If you run GNU 'tar' under a different locale, the translation to 3250the locale's language will be used. 3251 3252 (2) *Note --restrict::, for more information about this option. 3253 3254 3255File: tar.info, Node: Tape Files, Next: Tarcat, Prev: Multi-Volume Archives, Up: Using Multiple Tapes 3256 32579.6.2 Tape Files 3258---------------- 3259 3260 _(This message will disappear, once this node revised.)_ 3261 3262 To give the archive a name which will be recorded in it, use the 3263'--label=VOLUME-LABEL' ('-V VOLUME-LABEL') option. This will write a 3264special block identifying VOLUME-LABEL as the name of the archive to the 3265front of the archive which will be displayed when the archive is listed 3266with '--list'. If you are creating a multi-volume archive with 3267'--multi-volume' (*note Using Multiple Tapes::), then the volume label 3268will have 'Volume NNN' appended to the name you give, where NNN is the 3269number of the volume of the archive. If you use the 3270'--label=VOLUME-LABEL' option when reading an archive, it checks to make 3271sure the label on the tape matches the one you gave. *Note label::. 3272 3273 When 'tar' writes an archive to tape, it creates a single tape file. 3274If multiple archives are written to the same tape, one after the other, 3275they each get written as separate tape files. When extracting, it is 3276necessary to position the tape at the right place before running 'tar'. 3277To do this, use the 'mt' command. For more information on the 'mt' 3278command and on the organization of tapes into a sequence of tape files, 3279see *note mt::. 3280 3281 People seem to often do: 3282 3283 --label="SOME-PREFIX `date +SOME-FORMAT`" 3284 3285 or such, for pushing a common date in all volumes or an archive set. 3286 3287 3288File: tar.info, Node: Tarcat, Prev: Tape Files, Up: Using Multiple Tapes 3289 32909.6.3 Concatenate Volumes into a Single Archive 3291----------------------------------------------- 3292 3293Sometimes it is necessary to convert existing GNU 'tar' multi-volume 3294archive to a single 'tar' archive. Simply concatenating all volumes 3295into one will not work, since each volume carries an additional 3296information at the beginning. GNU 'tar' is shipped with the shell 3297script 'tarcat' designed for this purpose. 3298 3299 The script takes a list of files comprising a multi-volume archive 3300and creates the resulting archive at the standard output. For example: 3301 3302 tarcat vol.1 vol.2 vol.3 | tar tf - 3303 3304 The script implements a simple heuristics to determine the format of 3305the first volume file and to decide how to process the rest of the 3306files. However, it makes no attempt to verify whether the files are 3307given in order or even if they are valid 'tar' archives. It uses 'dd' 3308and does not filter its standard error, so you will usually see lots of 3309spurious messages. 3310 3311 3312File: tar.info, Node: label, Next: verify, Prev: Using Multiple Tapes, Up: Media 3313 33149.7 Including a Label in the Archive 3315==================================== 3316 3317To avoid problems caused by misplaced paper labels on the archive media, 3318you can include a "label" entry -- an archive member which contains the 3319name of the archive -- in the archive itself. Use the 3320'--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') option(1) in conjunction 3321with the '--create' operation to include a label entry in the archive as 3322it is being created. 3323 3324'--label=ARCHIVE-LABEL' 3325'-V ARCHIVE-LABEL' 3326 Includes an "archive-label" at the beginning of the archive when 3327 the archive is being created, when used in conjunction with the 3328 '--create' operation. Checks to make sure the archive label 3329 matches the one specified (when used in conjunction with any other 3330 operation). 3331 3332 If you create an archive using both '--label=ARCHIVE-LABEL' ('-V 3333ARCHIVE-LABEL') and '--multi-volume' ('-M'), each volume of the archive 3334will have an archive label of the form 'ARCHIVE-LABEL Volume N', where N 3335is 1 for the first volume, 2 for the next, and so on. *Note Using 3336Multiple Tapes::, for information on creating multiple volume archives. 3337 3338 The volume label will be displayed by '--list' along with the file 3339contents. If verbose display is requested, it will also be explicitly 3340marked as in the example below: 3341 3342 $ tar --verbose --list --file=iamanarchive 3343 V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header-- 3344 -rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename 3345 3346 However, '--list' option will cause listing entire contents of the 3347archive, which may be undesirable (for example, if the archive is stored 3348on a tape). You can request checking only the volume label by 3349specifying '--test-label' option. This option reads only the first 3350block of an archive, so it can be used with slow storage devices. For 3351example: 3352 3353 $ tar --test-label --file=iamanarchive 3354 iamalabel 3355 3356 If '--test-label' is used with one or more command line arguments, 3357'tar' compares the volume label with each argument. It exits with code 33580 if a match is found, and with code 1 otherwise(2). No output is 3359displayed, unless you also used the '--verbose' option. For example: 3360 3361 $ tar --test-label --file=iamanarchive 'iamalabel' 3362 => 0 3363 $ tar --test-label --file=iamanarchive 'alabel' 3364 => 1 3365 3366 When used with the '--verbose' option, 'tar' prints the actual volume 3367label (if any), and a verbose diagnostics in case of a mismatch: 3368 3369 $ tar --test-label --verbose --file=iamanarchive 'iamalabel' 3370 iamalabel 3371 => 0 3372 $ tar --test-label --verbose --file=iamanarchive 'alabel' 3373 iamalabel 3374 tar: Archive label mismatch 3375 => 1 3376 3377 If you request any operation, other than '--create', along with using 3378'--label' option, 'tar' will first check if the archive label matches 3379the one specified and will refuse to proceed if it does not. Use this 3380as a safety precaution to avoid accidentally overwriting existing 3381archives. For example, if you wish to add files to 'archive', 3382presumably labeled with string 'My volume', you will get: 3383 3384 $ tar -rf archive --label 'My volume' . 3385 tar: Archive not labeled to match 'My volume' 3386 3387in case its label does not match. This will work even if 'archive' is 3388not labeled at all. 3389 3390 Similarly, 'tar' will refuse to list or extract the archive if its 3391label doesn't match the ARCHIVE-LABEL specified. In those cases, 3392ARCHIVE-LABEL argument is interpreted as a globbing-style pattern which 3393must match the actual magnetic volume label. *Note exclude::, for a 3394precise description of how match is attempted(3). If the switch 3395'--multi-volume' ('-M') is being used, the volume label matcher will 3396also suffix ARCHIVE-LABEL by ' Volume [1-9]*' if the initial match 3397fails, before giving up. Since the volume numbering is automatically 3398added in labels at creation time, it sounded logical to equally help the 3399user taking care of it when the archive is being read. 3400 3401 You can also use '--label' to get a common information on all tapes 3402of a series. For having this information different in each series 3403created through a single script used on a regular basis, just manage to 3404get some date string as part of the label. For example: 3405 3406 $ tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`" 3407 $ tar --create --file=/dev/tape --multi-volume \ 3408 --label="Daily backup for `date +%Y-%m-%d`" 3409 3410 Some more notes about volume labels: 3411 3412 * Each label has its own date and time, which corresponds to the time 3413 when GNU 'tar' initially attempted to write it, often soon after 3414 the operator launches 'tar' or types the carriage return telling 3415 that the next tape is ready. 3416 3417 * Comparing date labels to get an idea of tape throughput is 3418 unreliable. It gives correct results only if the delays for 3419 rewinding tapes and the operator switching them were negligible, 3420 which is usually not the case. 3421 3422 ---------- Footnotes ---------- 3423 3424 (1) Until version 1.10, that option was called '--volume', but is not 3425available under that name anymore. 3426 3427 (2) Note that GNU 'tar' versions up to 1.23 indicated mismatch with 3428an exit code 2 and printed a spurious diagnostics on stderr. 3429 3430 (3) Previous versions of 'tar' used full regular expression matching, 3431or before that, only exact string matching, instead of wildcard 3432matchers. We decided for the sake of simplicity to use a uniform 3433matching device through 'tar'. 3434 3435 3436File: tar.info, Node: verify, Next: Write Protection, Prev: label, Up: Media 3437 34389.8 Verifying Data as It is Stored 3439================================== 3440 3441'-W' 3442'--verify' 3443 Attempt to verify the archive after writing. 3444 3445 This option causes 'tar' to verify the archive after writing it. 3446Each volume is checked after it is written, and any discrepancies are 3447recorded on the standard error output. 3448 3449 Verification requires that the archive be on a back-space-able 3450medium. This means pipes, some cartridge tape drives, and some other 3451devices cannot be verified. 3452 3453 You can insure the accuracy of an archive by comparing files in the 3454system with archive members. 'tar' can compare an archive to the file 3455system as the archive is being written, to verify a write operation, or 3456can compare a previously written archive, to insure that it is up to 3457date. 3458 3459 To check for discrepancies in an archive immediately after it is 3460written, use the '--verify' ('-W') option in conjunction with the 3461'--create' operation. When this option is specified, 'tar' checks 3462archive members against their counterparts in the file system, and 3463reports discrepancies on the standard error. 3464 3465 To verify an archive, you must be able to read it from before the end 3466of the last written entry. This option is useful for detecting data 3467errors on some tapes. Archives written to pipes, some cartridge tape 3468drives, and some other devices cannot be verified. 3469 3470 One can explicitly compare an already made archive with the file 3471system by using the '--compare' ('--diff', '-d') option, instead of 3472using the more automatic '--verify' option. *Note compare::. 3473 3474 Note that these two options have a slightly different intent. The 3475'--compare' option checks how identical are the logical contents of some 3476archive with what is on your disks, while the '--verify' option is 3477really for checking if the physical contents agree and if the recording 3478media itself is of dependable quality. So, for the '--verify' 3479operation, 'tar' tries to defeat all in-memory cache pertaining to the 3480archive, while it lets the speed optimization undisturbed for the 3481'--compare' option. If you nevertheless use '--compare' for media 3482verification, you may have to defeat the in-memory cache yourself, maybe 3483by opening and reclosing the door latch of your recording unit, forcing 3484some doubt in your operating system about the fact this is really the 3485same volume as the one just written or read. 3486 3487 The '--verify' option would not be necessary if drivers were indeed 3488able to detect dependably all write failures. This sometimes require 3489many magnetic heads, some able to read after the writes occurred. One 3490would not say that drivers unable to detect all cases are necessarily 3491flawed, as long as programming is concerned. 3492 3493 The '--verify' ('-W') option will not work in conjunction with the 3494'--multi-volume' ('-M') option or the '--append' ('-r'), '--update' 3495('-u') and '--delete' operations. *Note Operations::, for more 3496information on these operations. 3497 3498 Also, since 'tar' normally strips leading '/' from file names (*note 3499absolute::), a command like 'tar --verify -cf /tmp/foo.tar /etc' will 3500work as desired only if the working directory is '/', as 'tar' uses the 3501archive's relative member names (e.g., 'etc/motd') when verifying the 3502archive. 3503 3504 3505File: tar.info, Node: Write Protection, Prev: verify, Up: Media 3506 35079.9 Write Protection 3508==================== 3509 3510Almost all tapes and diskettes, and in a few rare cases, even disks can 3511be "write protected", to protect data on them from being changed. Once 3512an archive is written, you should write protect the media to prevent the 3513archive from being accidentally overwritten or deleted. (This will 3514protect the archive from being changed with a tape or floppy drive--it 3515will not protect it from magnet fields or other physical hazards.) 3516 3517 The write protection device itself is usually an integral part of the 3518physical media, and can be a two position (write enabled/write disabled) 3519switch, a notch which can be popped out or covered, a ring which can be 3520removed from the center of a tape reel, or some other changeable 3521feature. 3522 3523 3524File: tar.info, Node: Reliability and security, Next: Changes, Prev: Media, Up: Top 3525 352610 Reliability and Security 3527*************************** 3528 3529The 'tar' command reads and writes files as any other application does, 3530and is subject to the usual caveats about reliability and security. 3531This section contains some commonsense advice on the topic. 3532 3533* Menu: 3534 3535* Reliability:: 3536* Security:: 3537 3538 3539File: tar.info, Node: Reliability, Next: Security, Up: Reliability and security 3540 354110.1 Reliability 3542================ 3543 3544Ideally, when 'tar' is creating an archive, it reads from a file system 3545that is not being modified, and encounters no errors or inconsistencies 3546while reading and writing. If this is the case, the archive should 3547faithfully reflect what was read. Similarly, when extracting from an 3548archive, ideally 'tar' ideally encounters no errors and the extracted 3549files faithfully reflect what was in the archive. 3550 3551 However, when reading or writing real-world file systems, several 3552things can go wrong; these include permissions problems, corruption of 3553data, and race conditions. 3554 3555* Menu: 3556 3557* Permissions problems:: 3558* Data corruption and repair:: 3559* Race conditions:: 3560 3561 3562File: tar.info, Node: Permissions problems, Next: Data corruption and repair, Up: Reliability 3563 356410.1.1 Permissions Problems 3565--------------------------- 3566 3567If 'tar' encounters errors while reading or writing files, it normally 3568reports an error and exits with nonzero status. The work it does may 3569therefore be incomplete. For example, when creating an archive, if 3570'tar' cannot read a file then it cannot copy the file into the archive. 3571 3572 3573File: tar.info, Node: Data corruption and repair, Next: Race conditions, Prev: Permissions problems, Up: Reliability 3574 357510.1.2 Data Corruption and Repair 3576--------------------------------- 3577 3578If an archive becomes corrupted by an I/O error, this may corrupt the 3579data in an extracted file. Worse, it may corrupt the file's metadata, 3580which may cause later parts of the archive to become misinterpreted. An 3581tar-format archive contains a checksum that most likely will detect 3582errors in the metadata, but it will not detect errors in the data. 3583 3584 If data corruption is a concern, you can compute and check your own 3585checksums of an archive by using other programs, such as 'cksum'. 3586 3587 When attempting to recover from a read error or data corruption in an 3588archive, you may need to skip past the questionable data and read the 3589rest of the archive. This requires some expertise in the archive format 3590and in other software tools. 3591 3592 3593File: tar.info, Node: Race conditions, Prev: Data corruption and repair, Up: Reliability 3594 359510.1.3 Race conditions 3596---------------------- 3597 3598If some other process is modifying the file system while 'tar' is 3599reading or writing files, the result may well be inconsistent due to 3600race conditions. For example, if another process creates some files in 3601a directory while 'tar' is creating an archive containing the 3602directory's files, 'tar' may see some of the files but not others, or it 3603may see a file that is in the process of being created. The resulting 3604archive may not be a snapshot of the file system at any point in time. 3605If an application such as a database system depends on an accurate 3606snapshot, restoring from the 'tar' archive of a live file system may 3607therefore break that consistency and may break the application. The 3608simplest way to avoid the consistency issues is to avoid making other 3609changes to the file system while tar is reading it or writing it. 3610 3611 When creating an archive, several options are available to avoid race 3612conditions. Some hosts have a way of snapshotting a file system, or of 3613temporarily suspending all changes to a file system, by (say) suspending 3614the only virtual machine that can modify a file system; if you use these 3615facilities and have 'tar -c' read from a snapshot when creating an 3616archive, you can avoid inconsistency problems. More drastically, before 3617starting 'tar' you could suspend or shut down all processes other than 3618'tar' that have access to the file system, or you could unmount the file 3619system and then mount it read-only. 3620 3621 When extracting from an archive, one approach to avoid race 3622conditions is to create a directory that no other process can write to, 3623and extract into that. 3624 3625 3626File: tar.info, Node: Security, Prev: Reliability, Up: Reliability and security 3627 362810.2 Security 3629============= 3630 3631In some cases 'tar' may be used in an adversarial situation, where an 3632untrusted user is attempting to gain information about or modify 3633otherwise-inaccessible files. Dealing with untrusted data (that is, 3634data generated by an untrusted user) typically requires extra care, 3635because even the smallest mistake in the use of 'tar' is more likely to 3636be exploited by an adversary than by a race condition. 3637 3638* Menu: 3639 3640* Privacy:: 3641* Integrity:: 3642* Live untrusted data:: 3643* Security rules of thumb:: 3644 3645 3646File: tar.info, Node: Privacy, Next: Integrity, Up: Security 3647 364810.2.1 Privacy 3649-------------- 3650 3651Standard privacy concerns apply when using 'tar'. For example, suppose 3652you are archiving your home directory into a file '/archive/myhome.tar'. 3653Any secret information in your home directory, such as your SSH secret 3654keys, are copied faithfully into the archive. Therefore, if your home 3655directory contains any file that should not be read by some other user, 3656the archive itself should be not be readable by that user. And even if 3657the archive's data are inaccessible to untrusted users, its metadata 3658(such as size or last-modified date) may reveal some information about 3659your home directory; if the metadata are intended to be private, the 3660archive's parent directory should also be inaccessible to untrusted 3661users. 3662 3663 One precaution is to create '/archive' so that it is not accessible 3664to any user, unless that user also has permission to access all the 3665files in your home directory. 3666 3667 Similarly, when extracting from an archive, take care that the 3668permissions of the extracted files are not more generous than what you 3669want. Even if the archive itself is readable only to you, files 3670extracted from it have their own permissions that may differ. 3671 3672 3673File: tar.info, Node: Integrity, Next: Live untrusted data, Prev: Privacy, Up: Security 3674 367510.2.2 Integrity 3676---------------- 3677 3678When creating archives, take care that they are not writable by a 3679untrusted user; otherwise, that user could modify the archive, and when 3680you later extract from the archive you will get incorrect data. 3681 3682 When 'tar' extracts from an archive, by default it writes into files 3683relative to the working directory. If the archive was generated by an 3684untrusted user, that user therefore can write into any file under the 3685working directory. If the working directory contains a symbolic link to 3686another directory, the untrusted user can also write into any file under 3687the referenced directory. When extracting from an untrusted archive, it 3688is therefore good practice to create an empty directory and run 'tar' in 3689that directory. 3690 3691 When extracting from two or more untrusted archives, each one should 3692be extracted independently, into different empty directories. 3693Otherwise, the first archive could create a symbolic link into an area 3694outside the working directory, and the second one could follow the link 3695and overwrite data that is not under the working directory. For 3696example, when restoring from a series of incremental dumps, the archives 3697should have been created by a trusted process, as otherwise the 3698incremental restores might alter data outside the working directory. 3699 3700 If you use the '--absolute-names' ('-P') option when extracting, 3701'tar' respects any file names in the archive, even file names that begin 3702with '/' or contain '..'. As this lets the archive overwrite any file 3703in your system that you can write, the '--absolute-names' ('-P') option 3704should be used only for trusted archives. 3705 3706 Conversely, with the '--keep-old-files' ('-k') and '--skip-old-files' 3707options, 'tar' refuses to replace existing files when extracting. The 3708difference between the two options is that the former treats existing 3709files as errors whereas the latter just silently ignores them. 3710 3711 Finally, with the '--no-overwrite-dir' option, 'tar' refuses to 3712replace the permissions or ownership of already-existing directories. 3713These options may help when extracting from untrusted archives. 3714 3715 3716File: tar.info, Node: Live untrusted data, Next: Security rules of thumb, Prev: Integrity, Up: Security 3717 371810.2.3 Dealing with Live Untrusted Data 3719--------------------------------------- 3720 3721Extra care is required when creating from or extracting into a file 3722system that is accessible to untrusted users. For example, superusers 3723who invoke 'tar' must be wary about its actions being hijacked by an 3724adversary who is reading or writing the file system at the same time 3725that 'tar' is operating. 3726 3727 When creating an archive from a live file system, 'tar' is vulnerable 3728to denial-of-service attacks. For example, an adversarial user could 3729create the illusion of an indefinitely-deep directory hierarchy 3730'd/e/f/g/...' by creating directories one step ahead of 'tar', or the 3731illusion of an indefinitely-long file by creating a sparse file but 3732arranging for blocks to be allocated just before 'tar' reads them. 3733There is no easy way for 'tar' to distinguish these scenarios from 3734legitimate uses, so you may need to monitor 'tar', just as you'd need to 3735monitor any other system service, to detect such attacks. 3736 3737 While a superuser is extracting from an archive into a live file 3738system, an untrusted user might replace a directory with a symbolic 3739link, in hopes that 'tar' will follow the symbolic link and extract data 3740into files that the untrusted user does not have access to. Even if the 3741archive was generated by the superuser, it may contain a file such as 3742'd/etc/passwd' that the untrusted user earlier created in order to break 3743in; if the untrusted user replaces the directory 'd/etc' with a symbolic 3744link to '/etc' while 'tar' is running, 'tar' will overwrite 3745'/etc/passwd'. This attack can be prevented by extracting into a 3746directory that is inaccessible to untrusted users. 3747 3748 Similar attacks via symbolic links are also possible when creating an 3749archive, if the untrusted user can modify an ancestor of a top-level 3750argument of 'tar'. For example, an untrusted user that can modify 3751'/home/eve' can hijack a running instance of 'tar -cf - 3752/home/eve/Documents/yesterday' by replacing '/home/eve/Documents' with a 3753symbolic link to some other location. Attacks like these can be 3754prevented by making sure that untrusted users cannot modify any files 3755that are top-level arguments to 'tar', or any ancestor directories of 3756these files. 3757 3758 3759File: tar.info, Node: Security rules of thumb, Prev: Live untrusted data, Up: Security 3760 376110.2.4 Security Rules of Thumb 3762------------------------------ 3763 3764This section briefly summarizes rules of thumb for avoiding security 3765pitfalls. 3766 3767 * Protect archives at least as much as you protect any of the files 3768 being archived. 3769 3770 * Extract from an untrusted archive only into an otherwise-empty 3771 directory. This directory and its parent should be accessible only 3772 to trusted users. For example: 3773 3774 $ chmod go-rwx . 3775 $ mkdir -m go-rwx dir 3776 $ cd dir 3777 $ tar -xvf /archives/got-it-off-the-net.tar.gz 3778 3779 As a corollary, do not do an incremental restore from an untrusted 3780 archive. 3781 3782 * Do not let untrusted users access files extracted from untrusted 3783 archives without checking first for problems such as setuid 3784 programs. 3785 3786 * Do not let untrusted users modify directories that are ancestors of 3787 top-level arguments of 'tar'. For example, while you are executing 3788 'tar -cf /archive/u-home.tar /u/home', do not let an untrusted user 3789 modify '/', '/archive', or '/u'. 3790 3791 * Pay attention to the diagnostics and exit status of 'tar'. 3792 3793 * When archiving live file systems, monitor running instances of 3794 'tar' to detect denial-of-service attacks. 3795 3796 * Avoid unusual options such as '--absolute-names' ('-P'), 3797 '--dereference' ('-h'), '--overwrite', '--recursive-unlink', and 3798 '--remove-files' unless you understand their security implications. 3799 3800 3801File: tar.info, Node: Changes, Next: Recipes, Prev: Reliability and security, Up: Top 3802 3803Appendix A Changes 3804****************** 3805 3806This appendix lists some important user-visible changes between various 3807versions of GNU 'tar'. An up-to-date version of this document is 3808available at the GNU 'tar' documentation page 3809(http://www.gnu.org/software/tar/manual/changes.html). 3810 3811Use of globbing patterns when listing and extracting. 3812 3813 Previous versions of GNU tar assumed shell-style globbing when 3814 extracting from or listing an archive. For example: 3815 3816 $ tar xf foo.tar '*.c' 3817 3818 would extract all files whose names end in '.c'. This behavior was 3819 not documented and was incompatible with traditional tar 3820 implementations. Therefore, starting from version 1.15.91, GNU tar 3821 no longer uses globbing by default. For example, the above 3822 invocation is now interpreted as a request to extract from the 3823 archive the file named '*.c'. 3824 3825 To facilitate transition to the new behavior for those users who 3826 got used to the previous incorrect one, 'tar' will print a warning 3827 if it finds out that a requested member was not found in the 3828 archive and its name looks like a globbing pattern. For example: 3829 3830 $ tar xf foo.tar '*.c' 3831 tar: Pattern matching characters used in file names. Please, 3832 tar: use --wildcards to enable pattern matching, or --no-wildcards to 3833 tar: suppress this warning. 3834 tar: *.c: Not found in archive 3835 tar: Error exit delayed from previous errors 3836 3837 To treat member names as globbing patterns, use the '--wildcards' 3838 option. If you want to tar to mimic the behavior of versions prior 3839 to 1.15.91, add this option to your 'TAR_OPTIONS' variable. 3840 3841 *Note wildcards::, for the detailed discussion of the use of 3842 globbing patterns by GNU 'tar'. 3843 3844Use of short option '-o'. 3845 3846 Earlier versions of GNU 'tar' understood '-o' command line option 3847 as a synonym for '--old-archive'. 3848 3849 GNU 'tar' starting from version 1.13.90 understands this option as 3850 a synonym for '--no-same-owner'. This is compatible with UNIX98 3851 'tar' implementations. 3852 3853 However, to facilitate transition, '-o' option retains its old 3854 semantics when it is used with one of archive-creation commands. 3855 Users are encouraged to use '--format=oldgnu' instead. 3856 3857 It is especially important, since versions of GNU Automake up to 3858 and including 1.8.4 invoke tar with this option to produce 3859 distribution tarballs. *Note v7: Formats, for the detailed 3860 discussion of this issue and its implications. 3861 3862 *Note tar-formats: (automake)Options, for a description on how to 3863 use various archive formats with 'automake'. 3864 3865 Future versions of GNU 'tar' will understand '-o' only as a synonym 3866 for '--no-same-owner'. 3867 3868Use of short option '-l' 3869 3870 Earlier versions of GNU 'tar' understood '-l' option as a synonym 3871 for '--one-file-system'. Since such usage contradicted to UNIX98 3872 specification and harmed compatibility with other implementations, 3873 it was declared deprecated in version 1.14. However, to facilitate 3874 transition to its new semantics, it was supported by versions 1.15 3875 and 1.15.90. The present use of '-l' as a short variant of 3876 '--check-links' was introduced in version 1.15.91. 3877 3878Use of options '--portability' and '--old-archive' 3879 3880 These options are deprecated. Please use '--format=v7' instead. 3881 3882Use of option '--posix' 3883 3884 This option is deprecated. Please use '--format=posix' instead. 3885 3886 3887File: tar.info, Node: Recipes, Next: Configuring Help Summary, Prev: Changes, Up: Top 3888 3889Appendix B Recipes 3890****************** 3891 3892This appendix provides several recipes for performing common tasks using 3893GNU 'tar'. 3894 3895* Menu: 3896 3897* copy directory hierarchy:: 3898* intermediate directories:: 3899 3900 3901File: tar.info, Node: copy directory hierarchy, Next: intermediate directories, Up: Recipes 3902 3903B.1 Copying directory hierarchies 3904================================= 3905 3906This is a traditional way to copy a directory hierarchy preserving the 3907dates, modes, owners and link-structure of all the files therein. It 3908was used back when the 'cp' command lacked the '-a' option: 3909 3910 $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -) 3911 3912You can avoid subshells by using '-C' option: 3913 3914 $ tar -C sourcedir -cf - . | tar -C targetdir -xf - 3915 3916The same command using long option forms: 3917 3918 $ (cd sourcedir; tar --create --file=- . ) \ 3919 | (cd targetdir; tar --extract --file=-) 3920 3921or 3922 3923 $ tar --directory sourcedir --create --file=- . \ 3924 | tar --directory targetdir --extract --file=- 3925 3926 3927File: tar.info, Node: intermediate directories, Prev: copy directory hierarchy, Up: Recipes 3928 3929B.2 Restoring Intermediate Directories 3930====================================== 3931 3932A common concern is how to extract permissions and ownerships of 3933intermediate directories when extracting only selected members from the 3934archive. To illustrate this, consider the following archive: 3935 3936 # tar tvf A.tar 3937 drwxr-xr-x root/root 0 2017-11-16 14:39 foo/ 3938 dr-xr-x--- gray/user 0 2017-11-16 14:39 foo/bar/ 3939 -rw-r--r-- gray/user 10 2017-11-16 14:40 foo/bar/file 3940 3941 Suppose you extract only the file 'foo/bar/file', while being 'root': 3942 3943 # tar xvf A.tar foo/bar/file 3944 foo/bar/file 3945 3946 Now, let's inspect the content of the created directories: 3947 3948 # find foo -ls 3949 427257 0 drwxr-xr-x 3 root root 16 Nov 17 16:10 foo 3950 427258 0 drwxr-xr-x 2 root root 17 Nov 17 16:10 foo/bar 3951 427259 0 -rw-r--r-- 1 gray user 10 Nov 6 14:40 foo/bar/file 3952 3953 The requested file is restored, including its ownership and 3954permissions. The intermediate directories, however, are created with 3955the default permissions, current timestamp and owned by the current 3956user. This is because by the time 'tar' has reached the requested file, 3957it had already skipped the entries for its parent directories, so it has 3958no iformation about their ownership and modes. 3959 3960 To restore meta information about the intermediate directories, 3961you'll need to specify them explicitly in the command line and use the 3962'--no-recursive' option (*note recurse::) to avoid extracting their 3963content. 3964 3965 To automate this process, 'Neal P. Murphy' proposed the following 3966shell script(1): 3967 3968 #! /bin/sh 3969 (while read path 3970 do 3971 path=`dirname $path` 3972 while [ -n "$path" -a "$path" != "." ] 3973 do 3974 echo $path 3975 path=`dirname $path` 3976 done 3977 done < $2 | sort | uniq) | 3978 tar -x --no-recursion -v -f $1 -T - -T $2 3979 3980 The script takes two arguments: the name of the archive file, and the 3981name of the file list file. 3982 3983 To complete our example, the file list will contain single line: 3984 3985 foo/bar/file 3986 3987 Supposing its name is 'file.list' and the script is named 3988'restore.sh', you can invoke it as follows: 3989 3990 # sh restore.sh A.tar file.list 3991 3992 ---------- Footnotes ---------- 3993 3994 (1) The original version of the script can be seen at 3995<http://lists.gnu.org/archive/html/bug-tar/2016-11/msg00024.html> 3996 3997 3998File: tar.info, Node: Configuring Help Summary, Next: Fixing Snapshot Files, Prev: Recipes, Up: Top 3999 4000Appendix C Configuring Help Summary 4001*********************************** 4002 4003Running 'tar --help' displays the short 'tar' option summary (*note 4004help::). This summary is organized by "groups" of semantically close 4005options. The options within each group are printed in the following 4006order: a short option, eventually followed by a list of corresponding 4007long option names, followed by a short description of the option. For 4008example, here is an excerpt from the actual 'tar --help' output: 4009 4010 Main operation mode: 4011 4012 -A, --catenate, --concatenate append tar files to an archive 4013 -c, --create create a new archive 4014 -d, --diff, --compare find differences between archive and 4015 file system 4016 --delete delete from the archive 4017 4018 The exact visual representation of the help output is configurable 4019via 'ARGP_HELP_FMT' environment variable. The value of this variable is 4020a comma-separated list of "format variable" assignments. There are two 4021kinds of format variables. An "offset variable" keeps the offset of 4022some part of help output text from the leftmost column on the screen. A 4023"boolean" variable is a flag that toggles some output feature on or off. 4024Depending on the type of the corresponding variable, there are two kinds 4025of assignments: 4026 4027Offset assignment 4028 4029 The assignment to an offset variable has the following syntax: 4030 4031 VARIABLE=VALUE 4032 4033 where VARIABLE is the variable name, and VALUE is a numeric value 4034 to be assigned to the variable. 4035 4036Boolean assignment 4037 4038 To assign 'true' value to a variable, simply put this variable 4039 name. To assign 'false' value, prefix the variable name with 4040 'no-'. For example: 4041 4042 # Assign true value: 4043 dup-args 4044 # Assign false value: 4045 no-dup-args 4046 4047 Following variables are declared: 4048 4049 -- Help Output: boolean dup-args 4050 If true, arguments for an option are shown with both short and long 4051 options, even when a given option has both forms, for example: 4052 4053 -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE 4054 4055 If false, then if an option has both short and long forms, the 4056 argument is only shown with the long one, for example: 4057 4058 -f, --file=ARCHIVE use archive file or device ARCHIVE 4059 4060 and a message indicating that the argument is applicable to both 4061 forms is printed below the options. This message can be disabled 4062 using 'dup-args-note' (see below). 4063 4064 The default is false. 4065 4066 -- Help Output: boolean dup-args-note 4067 If this variable is true, which is the default, the following 4068 notice is displayed at the end of the help output: 4069 4070 Mandatory or optional arguments to long options are also 4071 mandatory or optional for any corresponding short options. 4072 4073 Setting 'no-dup-args-note' inhibits this message. Normally, only 4074 one of variables 'dup-args' or 'dup-args-note' should be set. 4075 4076 -- Help Output: offset short-opt-col 4077 Column in which short options start. Default is 2. 4078 4079 $ tar --help|grep ARCHIVE 4080 -f, --file=ARCHIVE use archive file or device ARCHIVE 4081 $ ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE 4082 -f, --file=ARCHIVE use archive file or device ARCHIVE 4083 4084 -- Help Output: offset long-opt-col 4085 Column in which long options start. Default is 6. For example: 4086 4087 $ tar --help|grep ARCHIVE 4088 -f, --file=ARCHIVE use archive file or device ARCHIVE 4089 $ ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE 4090 -f, --file=ARCHIVE use archive file or device ARCHIVE 4091 4092 -- Help Output: offset doc-opt-col 4093 Column in which "doc options" start. A doc option isn't actually 4094 an option, but rather an arbitrary piece of documentation that is 4095 displayed in much the same manner as the options. For example, in 4096 the description of '--format' option: 4097 4098 -H, --format=FORMAT create archive of the given format. 4099 4100 FORMAT is one of the following: 4101 4102 gnu GNU tar 1.13.x format 4103 oldgnu GNU format as per tar <= 1.12 4104 pax POSIX 1003.1-2001 (pax) format 4105 posix same as pax 4106 ustar POSIX 1003.1-1988 (ustar) format 4107 v7 old V7 tar format 4108 4109 the format names are doc options. Thus, if you set 4110 'ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output 4111 will look as follows: 4112 4113 -H, --format=FORMAT create archive of the given format. 4114 4115 FORMAT is one of the following: 4116 4117 gnu GNU tar 1.13.x format 4118 oldgnu GNU format as per tar <= 1.12 4119 pax POSIX 1003.1-2001 (pax) format 4120 posix same as pax 4121 ustar POSIX 1003.1-1988 (ustar) format 4122 v7 old V7 tar format 4123 4124 -- Help Output: offset opt-doc-col 4125 Column in which option description starts. Default is 29. 4126 4127 $ tar --help|grep ARCHIVE 4128 -f, --file=ARCHIVE use archive file or device ARCHIVE 4129 $ ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE 4130 -f, --file=ARCHIVE use archive file or device ARCHIVE 4131 $ ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE 4132 -f, --file=ARCHIVE 4133 use archive file or device ARCHIVE 4134 4135 Notice, that the description starts on a separate line if 4136 'opt-doc-col' value is too small. 4137 4138 -- Help Output: offset header-col 4139 Column in which "group headers" are printed. A group header is a 4140 descriptive text preceding an option group. For example, in the 4141 following text: 4142 4143 Main operation mode: 4144 4145 -A, --catenate, --concatenate append tar files to 4146 an archive 4147 -c, --create create a new archive 4148 'Main operation mode:' is the group header. 4149 4150 The default value is 1. 4151 4152 -- Help Output: offset usage-indent 4153 Indentation of wrapped usage lines. Affects '--usage' output. 4154 Default is 12. 4155 4156 -- Help Output: offset rmargin 4157 Right margin of the text output. Used for wrapping. 4158 4159 4160File: tar.info, Node: Fixing Snapshot Files, Next: Tar Internals, Prev: Configuring Help Summary, Up: Top 4161 4162Appendix D Fixing Snapshot Files 4163******************************** 4164 4165Various situations can cause device numbers to change: upgrading your 4166kernel version, reconfiguring your hardware, loading kernel modules in a 4167different order, using virtual volumes that are assembled dynamically 4168(such as with LVM or RAID), hot-plugging drives (e.g. external USB or 4169Firewire drives), etc. In the majority of cases this change is 4170unnoticed by the users. However, it influences 'tar' incremental 4171backups: the device number is stored in tar snapshot files (*note 4172Snapshot Files::) and is used to determine whether the file has changed 4173since the last backup. If the device numbers change for some reason, by 4174default the next backup you run will be a full backup. 4175 4176 To minimize the impact in these cases, GNU 'tar' comes with the 4177'tar-snapshot-edit' utility for inspecting and updating device numbers 4178in snapshot files. (The utility, written by Dustin J. Mitchell, is also 4179available from the GNU 'tar' home page 4180(http://www.gnu.org/software/tar/utils/tar-snapshot-edit.html).) 4181 4182 To obtain a summary of the device numbers found in the snapshot file, 4183run 4184 4185 $ tar-snapshot-edit SNAPFILE 4186 4187where SNAPFILE is the name of the snapshot file (you can supply as many 4188files as you wish in a single command line). You can then compare the 4189numbers across snapshot files, or against those currently in use on the 4190live filesystem (using 'ls -l' or 'stat'). 4191 4192 Assuming the device numbers have indeed changed, it's often possible 4193to simply tell GNU 'tar' to ignore the device number when processing the 4194incremental snapshot files for these backups, using the 4195'--no-check-device' option (*note device numbers::). 4196 4197 Alternatively, you can use the 'tar-edit-snapshot' script's '-r' 4198option to update all occurrences of the given device number in the 4199snapshot file(s). It takes a single argument of the form 4200'OLDDEV-NEWDEV', where OLDDEV is the device number used in the snapshot 4201file, and NEWDEV is the corresponding new device number. Both numbers 4202may be specified in hex (e.g., '0xfe01'), decimal (e.g., '65025'), or as 4203a major:minor number pair (e.g., '254:1'). To change several device 4204numbers at once, specify them in a single comma-separated list, as in 4205'-r 0x3060-0x4500,0x307-0x4600'. 4206 4207 Before updating the snapshot file, it is a good idea to create a 4208backup copy of it. This is accomplished by '-b' option. The name of 4209the backup file is obtained by appending '~' to the original file name. 4210 4211 An example session: 4212 $ tar-snapshot-edit root_snap.0 boot_snap.0 4213 File: root_snap.0 4214 Detected snapshot file version: 2 4215 4216 Device 0x0000 occurs 1 times. 4217 Device 0x0003 occurs 1 times. 4218 Device 0x0005 occurs 1 times. 4219 Device 0x0013 occurs 1 times. 4220 Device 0x6801 occurs 1 times. 4221 Device 0x6803 occurs 6626 times. 4222 Device 0xfb00 occurs 1 times. 4223 4224 File: boot_snap.0 4225 Detected snapshot file version: 2 4226 4227 Device 0x6801 occurs 3 times. 4228 $ tar-snapshot-edit -b -r 0x6801-0x6901,0x6803-0x6903 root_snap.0 boot_snap.0 4229 File: root_snap.0 4230 Detected snapshot file version: 2 4231 4232 Updated 6627 records. 4233 4234 File: boot_snap.0 4235 Detected snapshot file version: 2 4236 4237 Updated 3 records. 4238 4239 4240File: tar.info, Node: Tar Internals, Next: Genfile, Prev: Fixing Snapshot Files, Up: Top 4241 4242Appendix E Tar Internals 4243************************ 4244 4245* Menu: 4246 4247* Standard:: Basic Tar Format 4248* Extensions:: GNU Extensions to the Archive Format 4249* Sparse Formats:: Storing Sparse Files 4250* Snapshot Files:: 4251* Dumpdir:: 4252 4253 4254File: tar.info, Node: Standard, Next: Extensions, Up: Tar Internals 4255 4256Basic Tar Format 4257================ 4258 4259 _(This message will disappear, once this node revised.)_ 4260 4261 While an archive may contain many files, the archive itself is a 4262single ordinary file. Like any other file, an archive file can be 4263written to a storage device such as a tape or disk, sent through a pipe 4264or over a network, saved on the active file system, or even stored in 4265another archive. An archive file is not easy to read or manipulate 4266without using the 'tar' utility or Tar mode in GNU Emacs. 4267 4268 Physically, an archive consists of a series of file entries 4269terminated by an end-of-archive entry, which consists of two 512 blocks 4270of zero bytes. A file entry usually describes one of the files in the 4271archive (an "archive member"), and consists of a file header and the 4272contents of the file. File headers contain file names and statistics, 4273checksum information which 'tar' uses to detect file corruption, and 4274information about file types. 4275 4276 Archives are permitted to have more than one member with the same 4277member name. One way this situation can occur is if more than one 4278version of a file has been stored in the archive. For information about 4279adding new versions of a file to an archive, see *note update::. 4280 4281 In addition to entries describing archive members, an archive may 4282contain entries which 'tar' itself uses to store information. *Note 4283label::, for an example of such an archive entry. 4284 4285 A 'tar' archive file contains a series of blocks. Each block 4286contains 'BLOCKSIZE' bytes. Although this format may be thought of as 4287being on magnetic tape, other media are often used. 4288 4289 Each file archived is represented by a header block which describes 4290the file, followed by zero or more blocks which give the contents of the 4291file. At the end of the archive file there are two 512-byte blocks 4292filled with binary zeros as an end-of-file marker. A reasonable system 4293should write such end-of-file marker at the end of an archive, but must 4294not assume that such a block exists when reading an archive. In 4295particular GNU 'tar' always issues a warning if it does not encounter 4296it. 4297 4298 The blocks may be "blocked" for physical I/O operations. Each record 4299of N blocks (where N is set by the '--blocking-factor=512-SIZE' ('-b 4300512-SIZE') option to 'tar') is written with a single 'write ()' 4301operation. On magnetic tapes, the result of such a write is a single 4302record. When writing an archive, the last record of blocks should be 4303written at the full size, with blocks after the zero block containing 4304all zeros. When reading an archive, a reasonable system should properly 4305handle an archive whose last record is shorter than the rest, or which 4306contains garbage records after a zero block. 4307 4308 The header block is defined in C as follows. In the GNU 'tar' 4309distribution, this is part of file 'src/tar.h': 4310 4311 4312 /* tar Header Block, from POSIX 1003.1-1990. */ 4313 4314 /* POSIX header. */ 4315 4316 struct posix_header 4317 { /* byte offset */ 4318 char name[100]; /* 0 */ 4319 char mode[8]; /* 100 */ 4320 char uid[8]; /* 108 */ 4321 char gid[8]; /* 116 */ 4322 char size[12]; /* 124 */ 4323 char mtime[12]; /* 136 */ 4324 char chksum[8]; /* 148 */ 4325 char typeflag; /* 156 */ 4326 char linkname[100]; /* 157 */ 4327 char magic[6]; /* 257 */ 4328 char version[2]; /* 263 */ 4329 char uname[32]; /* 265 */ 4330 char gname[32]; /* 297 */ 4331 char devmajor[8]; /* 329 */ 4332 char devminor[8]; /* 337 */ 4333 char prefix[155]; /* 345 */ 4334 /* 500 */ 4335 }; 4336 4337 #define TMAGIC "ustar" /* ustar and a null */ 4338 #define TMAGLEN 6 4339 #define TVERSION "00" /* 00 and no null */ 4340 #define TVERSLEN 2 4341 4342 /* Values used in typeflag field. */ 4343 #define REGTYPE '0' /* regular file */ 4344 #define AREGTYPE '\0' /* regular file */ 4345 #define LNKTYPE '1' /* link */ 4346 #define SYMTYPE '2' /* reserved */ 4347 #define CHRTYPE '3' /* character special */ 4348 #define BLKTYPE '4' /* block special */ 4349 #define DIRTYPE '5' /* directory */ 4350 #define FIFOTYPE '6' /* FIFO special */ 4351 #define CONTTYPE '7' /* reserved */ 4352 4353 #define XHDTYPE 'x' /* Extended header referring to the 4354 next file in the archive */ 4355 #define XGLTYPE 'g' /* Global extended header */ 4356 4357 /* Bits used in the mode field, values in octal. */ 4358 #define TSUID 04000 /* set UID on execution */ 4359 #define TSGID 02000 /* set GID on execution */ 4360 #define TSVTX 01000 /* reserved */ 4361 /* file permissions */ 4362 #define TUREAD 00400 /* read by owner */ 4363 #define TUWRITE 00200 /* write by owner */ 4364 #define TUEXEC 00100 /* execute/search by owner */ 4365 #define TGREAD 00040 /* read by group */ 4366 #define TGWRITE 00020 /* write by group */ 4367 #define TGEXEC 00010 /* execute/search by group */ 4368 #define TOREAD 00004 /* read by other */ 4369 #define TOWRITE 00002 /* write by other */ 4370 #define TOEXEC 00001 /* execute/search by other */ 4371 4372 /* tar Header Block, GNU extensions. */ 4373 4374 /* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for 4375 contiguous files, so maybe disobeying the "reserved" comment in POSIX 4376 header description. I suspect these were meant to be used this way, and 4377 should not have really been "reserved" in the published standards. */ 4378 4379 /* *BEWARE* *BEWARE* *BEWARE* that the following information is still 4380 boiling, and may change. Even if the OLDGNU format description should be 4381 accurate, the so-called GNU format is not yet fully decided. It is 4382 surely meant to use only extensions allowed by POSIX, but the sketch 4383 below repeats some ugliness from the OLDGNU format, which should rather 4384 go away. Sparse files should be saved in such a way that they do *not* 4385 require two passes at archive creation time. Huge files get some POSIX 4386 fields to overflow, alternate solutions have to be sought for this. */ 4387 4388 /* Descriptor for a single file hole. */ 4389 4390 struct sparse 4391 { /* byte offset */ 4392 char offset[12]; /* 0 */ 4393 char numbytes[12]; /* 12 */ 4394 /* 24 */ 4395 }; 4396 4397 /* Sparse files are not supported in POSIX ustar format. For sparse files 4398 with a POSIX header, a GNU extra header is provided which holds overall 4399 sparse information and a few sparse descriptors. When an old GNU header 4400 replaces both the POSIX header and the GNU extra header, it holds some 4401 sparse descriptors too. Whether POSIX or not, if more sparse descriptors 4402 are still needed, they are put into as many successive sparse headers as 4403 necessary. The following constants tell how many sparse descriptors fit 4404 in each kind of header able to hold them. */ 4405 4406 #define SPARSES_IN_EXTRA_HEADER 16 4407 #define SPARSES_IN_OLDGNU_HEADER 4 4408 #define SPARSES_IN_SPARSE_HEADER 21 4409 4410 /* Extension header for sparse files, used immediately after the GNU extra 4411 header, and used only if all sparse information cannot fit into that 4412 extra header. There might even be many such extension headers, one after 4413 the other, until all sparse information has been recorded. */ 4414 4415 struct sparse_header 4416 { /* byte offset */ 4417 struct sparse sp[SPARSES_IN_SPARSE_HEADER]; 4418 /* 0 */ 4419 char isextended; /* 504 */ 4420 /* 505 */ 4421 }; 4422 4423 /* The old GNU format header conflicts with POSIX format in such a way that 4424 POSIX archives may fool old GNU tar's, and POSIX tar's might well be 4425 fooled by old GNU tar archives. An old GNU format header uses the space 4426 used by the prefix field in a POSIX header, and cumulates information 4427 normally found in a GNU extra header. With an old GNU tar header, we 4428 never see any POSIX header nor GNU extra header. Supplementary sparse 4429 headers are allowed, however. */ 4430 4431 struct oldgnu_header 4432 { /* byte offset */ 4433 char unused_pad1[345]; /* 0 */ 4434 char atime[12]; /* 345 Incr. archive: atime of the file */ 4435 char ctime[12]; /* 357 Incr. archive: ctime of the file */ 4436 char offset[12]; /* 369 Multivolume archive: the offset of 4437 the start of this volume */ 4438 char longnames[4]; /* 381 Not used */ 4439 char unused_pad2; /* 385 */ 4440 struct sparse sp[SPARSES_IN_OLDGNU_HEADER]; 4441 /* 386 */ 4442 char isextended; /* 482 Sparse file: Extension sparse header 4443 follows */ 4444 char realsize[12]; /* 483 Sparse file: Real size*/ 4445 /* 495 */ 4446 }; 4447 4448 /* OLDGNU_MAGIC uses both magic and version fields, which are contiguous. 4449 Found in an archive, it indicates an old GNU header format, which will be 4450 hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are 4451 valid, though the header is not truly POSIX conforming. */ 4452 #define OLDGNU_MAGIC "ustar " /* 7 chars and a null */ 4453 4454 /* The standards committee allows only capital A through capital Z for 4455 user-defined expansion. Other letters in use include: 4456 4457 'A' Solaris Access Control List 4458 'E' Solaris Extended Attribute File 4459 'I' Inode only, as in 'star' 4460 'N' Obsolete GNU tar, for file names that do not fit into the main header. 4461 'X' POSIX 1003.1-2001 eXtended (VU version) */ 4462 4463 /* This is a dir entry that contains the names of files that were in the 4464 dir at the time the dump was made. */ 4465 #define GNUTYPE_DUMPDIR 'D' 4466 4467 /* Identifies the *next* file on the tape as having a long linkname. */ 4468 #define GNUTYPE_LONGLINK 'K' 4469 4470 /* Identifies the *next* file on the tape as having a long name. */ 4471 #define GNUTYPE_LONGNAME 'L' 4472 4473 /* This is the continuation of a file that began on another volume. */ 4474 #define GNUTYPE_MULTIVOL 'M' 4475 4476 /* This is for sparse files. */ 4477 #define GNUTYPE_SPARSE 'S' 4478 4479 /* This file is a tape/volume header. Ignore it on extraction. */ 4480 #define GNUTYPE_VOLHDR 'V' 4481 4482 /* Solaris extended header */ 4483 #define SOLARIS_XHDTYPE 'X' 4484 4485 /* Jörg Schilling star header */ 4486 4487 struct star_header 4488 { /* byte offset */ 4489 char name[100]; /* 0 */ 4490 char mode[8]; /* 100 */ 4491 char uid[8]; /* 108 */ 4492 char gid[8]; /* 116 */ 4493 char size[12]; /* 124 */ 4494 char mtime[12]; /* 136 */ 4495 char chksum[8]; /* 148 */ 4496 char typeflag; /* 156 */ 4497 char linkname[100]; /* 157 */ 4498 char magic[6]; /* 257 */ 4499 char version[2]; /* 263 */ 4500 char uname[32]; /* 265 */ 4501 char gname[32]; /* 297 */ 4502 char devmajor[8]; /* 329 */ 4503 char devminor[8]; /* 337 */ 4504 char prefix[131]; /* 345 */ 4505 char atime[12]; /* 476 */ 4506 char ctime[12]; /* 488 */ 4507 /* 500 */ 4508 }; 4509 4510 #define SPARSES_IN_STAR_HEADER 4 4511 #define SPARSES_IN_STAR_EXT_HEADER 21 4512 4513 struct star_in_header 4514 { 4515 char fill[345]; /* 0 Everything that is before t_prefix */ 4516 char prefix[1]; /* 345 t_name prefix */ 4517 char fill2; /* 346 */ 4518 char fill3[8]; /* 347 */ 4519 char isextended; /* 355 */ 4520 struct sparse sp[SPARSES_IN_STAR_HEADER]; /* 356 */ 4521 char realsize[12]; /* 452 Actual size of the file */ 4522 char offset[12]; /* 464 Offset of multivolume contents */ 4523 char atime[12]; /* 476 */ 4524 char ctime[12]; /* 488 */ 4525 char mfill[8]; /* 500 */ 4526 char xmagic[4]; /* 508 "tar" */ 4527 }; 4528 4529 struct star_ext_header 4530 { 4531 struct sparse sp[SPARSES_IN_STAR_EXT_HEADER]; 4532 char isextended; 4533 }; 4534 4535 4536 All characters in header blocks are represented by using 8-bit 4537characters in the local variant of ASCII. Each field within the 4538structure is contiguous; that is, there is no padding used within the 4539structure. Each character on the archive medium is stored contiguously. 4540 4541 Bytes representing the contents of files (after the header block of 4542each file) are not translated in any way and are not constrained to 4543represent characters in any character set. The 'tar' format does not 4544distinguish text files from binary files, and no translation of file 4545contents is performed. 4546 4547 The 'name', 'linkname', 'magic', 'uname', and 'gname' are 4548null-terminated character strings. All other fields are zero-filled 4549octal numbers in ASCII. Each numeric field of width W contains W minus 1 4550digits, and a null. (In the extended GNU format, the numeric fields can 4551take other forms.) 4552 4553 The 'name' field is the file name of the file, with directory names 4554(if any) preceding the file name, separated by slashes. 4555 4556 The 'mode' field provides nine bits specifying file permissions and 4557three bits to specify the Set UID, Set GID, and Save Text ("sticky") 4558modes. Values for these bits are defined above. When special 4559permissions are required to create a file with a given mode, and the 4560user restoring files from the archive does not hold such permissions, 4561the mode bit(s) specifying those special permissions are ignored. Modes 4562which are not supported by the operating system restoring files from the 4563archive will be ignored. Unsupported modes should be faked up when 4564creating or updating an archive; e.g., the group permission could be 4565copied from the _other_ permission. 4566 4567 The 'uid' and 'gid' fields are the numeric user and group ID of the 4568file owners, respectively. If the operating system does not support 4569numeric user or group IDs, these fields should be ignored. 4570 4571 The 'size' field is the size of the file in bytes; linked files are 4572archived with this field specified as zero. 4573 4574 The 'mtime' field represents the data modification time of the file 4575at the time it was archived. It represents the integer number of 4576seconds since January 1, 1970, 00:00 Coordinated Universal Time. 4577 4578 The 'chksum' field represents the simple sum of all bytes in the 4579header block. Each 8-bit byte in the header is added to an unsigned 4580integer, initialized to zero, the precision of which shall be no less 4581than seventeen bits. When calculating the checksum, the 'chksum' field 4582is treated as if it were all blanks. 4583 4584 The 'typeflag' field specifies the type of file archived. If a 4585particular implementation does not recognize or permit the specified 4586type, the file will be extracted as if it were a regular file. As this 4587action occurs, 'tar' issues a warning to the standard error. 4588 4589 The 'atime' and 'ctime' fields are used in making incremental 4590backups; they store, respectively, the particular file's access and 4591status change times. 4592 4593 The 'offset' is used by the '--multi-volume' ('-M') option, when 4594making a multi-volume archive. The offset is number of bytes into the 4595file that we need to restart at to continue the file on the next tape, 4596i.e., where we store the location that a continued file is continued at. 4597 4598 The following fields were added to deal with sparse files. A file is 4599"sparse" if it takes in unallocated blocks which end up being 4600represented as zeros, i.e., no useful data. A test to see if a file is 4601sparse is to look at the number blocks allocated for it versus the 4602number of characters in the file; if there are fewer blocks allocated 4603for the file than would normally be allocated for a file of that size, 4604then the file is sparse. This is the method 'tar' uses to detect a 4605sparse file, and once such a file is detected, it is treated differently 4606from non-sparse files. 4607 4608 Sparse files are often 'dbm' files, or other database-type files 4609which have data at some points and emptiness in the greater part of the 4610file. Such files can appear to be very large when an 'ls -l' is done on 4611them, when in truth, there may be a very small amount of important data 4612contained in the file. It is thus undesirable to have 'tar' think that 4613it must back up this entire file, as great quantities of room are wasted 4614on empty blocks, which can lead to running out of room on a tape far 4615earlier than is necessary. Thus, sparse files are dealt with so that 4616these empty blocks are not written to the tape. Instead, what is 4617written to the tape is a description, of sorts, of the sparse file: 4618where the holes are, how big the holes are, and how much data is found 4619at the end of the hole. This way, the file takes up potentially far 4620less room on the tape, and when the file is extracted later on, it will 4621look exactly the way it looked beforehand. The following is a 4622description of the fields used to handle a sparse file: 4623 4624 The 'sp' is an array of 'struct sparse'. Each 'struct sparse' 4625contains two 12-character strings which represent an offset into the 4626file and a number of bytes to be written at that offset. The offset is 4627absolute, and not relative to the offset in preceding array element. 4628 4629 The header can hold four of these 'struct sparse' at the moment; if 4630more are needed, they are not stored in the header. 4631 4632 The 'isextended' flag is set when an 'extended_header' is needed to 4633deal with a file. Note that this means that this flag can only be set 4634when dealing with a sparse file, and it is only set in the event that 4635the description of the file will not fit in the allotted room for sparse 4636structures in the header. In other words, an extended_header is needed. 4637 4638 The 'extended_header' structure is used for sparse files which need 4639more sparse structures than can fit in the header. The header can fit 4 4640such structures; if more are needed, the flag 'isextended' gets set and 4641the next block is an 'extended_header'. 4642 4643 Each 'extended_header' structure contains an array of 21 sparse 4644structures, along with a similar 'isextended' flag that the header had. 4645There can be an indeterminate number of such 'extended_header's to 4646describe a sparse file. 4647 4648'REGTYPE' 4649'AREGTYPE' 4650 These flags represent a regular file. In order to be compatible 4651 with older versions of 'tar', a 'typeflag' value of 'AREGTYPE' 4652 should be silently recognized as a regular file. New archives 4653 should be created using 'REGTYPE'. Also, for backward 4654 compatibility, 'tar' treats a regular file whose name ends with a 4655 slash as a directory. 4656 4657'LNKTYPE' 4658 This flag represents a file linked to another file, of any type, 4659 previously archived. Such files are identified in Unix by each 4660 file having the same device and inode number. The linked-to name 4661 is specified in the 'linkname' field with a trailing null. 4662 4663'SYMTYPE' 4664 This represents a symbolic link to another file. The linked-to 4665 name is specified in the 'linkname' field with a trailing null. 4666 4667'CHRTYPE' 4668'BLKTYPE' 4669 These represent character special files and block special files 4670 respectively. In this case the 'devmajor' and 'devminor' fields 4671 will contain the major and minor device numbers respectively. 4672 Operating systems may map the device specifications to their own 4673 local specification, or may ignore the entry. 4674 4675'DIRTYPE' 4676 This flag specifies a directory or sub-directory. The directory 4677 name in the 'name' field should end with a slash. On systems where 4678 disk allocation is performed on a directory basis, the 'size' field 4679 will contain the maximum number of bytes (which may be rounded to 4680 the nearest disk block allocation unit) which the directory may 4681 hold. A 'size' field of zero indicates no such limiting. Systems 4682 which do not support limiting in this manner should ignore the 4683 'size' field. 4684 4685'FIFOTYPE' 4686 This specifies a FIFO special file. Note that the archiving of a 4687 FIFO file archives the existence of this file and not its contents. 4688 4689'CONTTYPE' 4690 This specifies a contiguous file, which is the same as a normal 4691 file except that, in operating systems which support it, all its 4692 space is allocated contiguously on the disk. Operating systems 4693 which do not allow contiguous allocation should silently treat this 4694 type as a normal file. 4695 4696'A' ... 'Z' 4697 These are reserved for custom implementations. Some of these are 4698 used in the GNU modified format, as described below. 4699 4700 Other values are reserved for specification in future revisions of 4701the P1003 standard, and should not be used by any 'tar' program. 4702 4703 The 'magic' field indicates that this archive was output in the P1003 4704archive format. If this field contains 'TMAGIC', the 'uname' and 4705'gname' fields will contain the ASCII representation of the owner and 4706group of the file respectively. If found, the user and group IDs are 4707used rather than the values in the 'uid' and 'gid' fields. 4708 4709 For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, 4710pages 169-173 (section 10.1) for 'Archive/Interchange File Format'; and 4711IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940 4712(section E.4.48) for 'pax - Portable archive interchange'. 4713 4714 4715File: tar.info, Node: Extensions, Next: Sparse Formats, Prev: Standard, Up: Tar Internals 4716 4717GNU Extensions to the Archive Format 4718==================================== 4719 4720 _(This message will disappear, once this node revised.)_ 4721 4722 The GNU format uses additional file types to describe new types of 4723files in an archive. These are listed below. 4724 4725'GNUTYPE_DUMPDIR' 4726''D'' 4727 This represents a directory and a list of files created by the 4728 '--incremental' ('-G') option. The 'size' field gives the total 4729 size of the associated list of files. Each file name is preceded 4730 by either a 'Y' (the file should be in this archive) or an 'N'. 4731 (The file is a directory, or is not stored in the archive.) Each 4732 file name is terminated by a null. There is an additional null 4733 after the last file name. 4734 4735'GNUTYPE_MULTIVOL' 4736''M'' 4737 This represents a file continued from another volume of a 4738 multi-volume archive created with the '--multi-volume' ('-M') 4739 option. The original type of the file is not given here. The 4740 'size' field gives the maximum size of this piece of the file 4741 (assuming the volume does not end before the file is written out). 4742 The 'offset' field gives the offset from the beginning of the file 4743 where this part of the file begins. Thus 'size' plus 'offset' 4744 should equal the original size of the file. 4745 4746'GNUTYPE_SPARSE' 4747''S'' 4748 This flag indicates that we are dealing with a sparse file. Note 4749 that archiving a sparse file requires special operations to find 4750 holes in the file, which mark the positions of these holes, along 4751 with the number of bytes of data to be found after the hole. 4752 4753'GNUTYPE_VOLHDR' 4754''V'' 4755 This file type is used to mark the volume header that was given 4756 with the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') option when 4757 the archive was created. The 'name' field contains the 'name' 4758 given after the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') 4759 option. The 'size' field is zero. Only the first file in each 4760 volume of an archive should have this type. 4761 4762 For fields containing numbers or timestamps that are out of range for 4763the basic format, the GNU format uses a base-256 representation instead 4764of an ASCII octal number. If the leading byte is 0xff (255), all the 4765bytes of the field (including the leading byte) are concatenated in 4766big-endian order, with the result being a negative number expressed in 4767two's complement form. If the leading byte is 0x80 (128), the 4768non-leading bytes of the field are concatenated in big-endian order, 4769with the result being a positive number expressed in binary form. 4770Leading bytes other than 0xff, 0x80 and ASCII octal digits are reserved 4771for future use, as are base-256 representations of values that would be 4772in range for the basic format. 4773 4774 You may have trouble reading a GNU format archive on a non-GNU system 4775if the options '--incremental' ('-G'), '--multi-volume' ('-M'), 4776'--sparse' ('-S'), or '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') were 4777used when writing the archive. In general, if 'tar' does not use the 4778GNU-added fields of the header, other versions of 'tar' should be able 4779to read the archive. Otherwise, the 'tar' program will give an error, 4780the most likely one being a checksum error. 4781 4782 4783File: tar.info, Node: Sparse Formats, Next: Snapshot Files, Prev: Extensions, Up: Tar Internals 4784 4785Storing Sparse Files 4786==================== 4787 4788The notion of sparse file, and the ways of handling it from the point of 4789view of GNU 'tar' user have been described in detail in *note sparse::. 4790This chapter describes the internal format GNU 'tar' uses to store such 4791files. 4792 4793 The support for sparse files in GNU 'tar' has a long history. The 4794earliest version featuring this support that I was able to find was 47951.09, released in November, 1990. The format introduced back then is 4796called "old GNU" sparse format and in spite of the fact that its design 4797contained many flaws, it was the only format GNU 'tar' supported until 4798version 1.14 (May, 2004), which introduced initial support for sparse 4799archives in PAX archives (*note posix::). This format was not free from 4800design flaws, either and it was subsequently improved in versions 1.15.2 4801(November, 2005) and 1.15.92 (June, 2006). 4802 4803 In addition to GNU sparse format, GNU 'tar' is able to read and 4804extract sparse files archived by 'star'. 4805 4806 The following subsections describe each format in detail. 4807 4808* Menu: 4809 4810* Old GNU Format:: 4811* PAX 0:: PAX Format, Versions 0.0 and 0.1 4812* PAX 1:: PAX Format, Version 1.0 4813 4814 4815File: tar.info, Node: Old GNU Format, Next: PAX 0, Up: Sparse Formats 4816 4817Old GNU Format 4818-------------- 4819 4820The format introduced in November 1990 (v. 1.09) was designed on top of 4821standard 'ustar' headers in such an unfortunate way that some of its 4822fields overwrote fields required by POSIX. 4823 4824 An old GNU sparse header is designated by type 'S' ('GNUTYPE_SPARSE') 4825and has the following layout: 4826 4827Offset Size Name Data type Contents 4828---------------------------------------------------------------------------- 48290 345 N/A Not used. 4830345 12 atime Number 'atime' of the file. 4831357 12 ctime Number 'ctime' of the file . 4832369 12 offset Number For multivolume archives: 4833 the offset of the start of 4834 this volume. 4835381 4 N/A Not used. 4836385 1 N/A Not used. 4837386 96 sp 'sparse_header'(4 entries) File map. 4838482 1 isextended Bool '1' if an extension sparse 4839 header follows, '0' 4840 otherwise. 4841483 12 realsize Number Real size of the file. 4842 4843 Each of 'sparse_header' object at offset 386 describes a single data 4844chunk. It has the following structure: 4845 4846Offset Size Data type Contents 4847--------------------------------------------------------------------------- 48480 12 Number Offset of the beginning of the chunk. 484912 12 Number Size of the chunk. 4850 4851 If the member contains more than four chunks, the 'isextended' field 4852of the header has the value '1' and the main header is followed by one 4853or more "extension headers". Each such header has the following 4854structure: 4855 4856Offset Size Name Data type Contents 4857---------------------------------------------------------------------------- 48580 21 sp 'sparse_header'(21 entries) File map. 4859504 1 isextended Bool '1' if an extension sparse 4860 header follows, or '0' 4861 otherwise. 4862 4863 A header with 'isextended=0' ends the map. 4864 4865 4866File: tar.info, Node: PAX 0, Next: PAX 1, Prev: Old GNU Format, Up: Sparse Formats 4867 4868PAX Format, Versions 0.0 and 0.1 4869-------------------------------- 4870 4871There are two formats available in this branch. The version '0.0' is 4872the initial version of sparse format used by 'tar' versions 1.14-1.15.1. 4873The sparse file map is kept in extended ('x') PAX header variables: 4874 4875'GNU.sparse.size' 4876 Real size of the stored file; 4877 4878'GNU.sparse.numblocks' 4879 Number of blocks in the sparse map; 4880 4881'GNU.sparse.offset' 4882 Offset of the data block; 4883 4884'GNU.sparse.numbytes' 4885 Size of the data block. 4886 4887 The latter two variables repeat for each data block, so the overall 4888structure is like this: 4889 4890 GNU.sparse.size=SIZE 4891 GNU.sparse.numblocks=NUMBLOCKS 4892 repeat NUMBLOCKS times 4893 GNU.sparse.offset=OFFSET 4894 GNU.sparse.numbytes=NUMBYTES 4895 end repeat 4896 4897 This format presented the following two problems: 4898 4899 1. Whereas the POSIX specification allows a variable to appear 4900 multiple times in a header, it requires that only the last 4901 occurrence be meaningful. Thus, multiple occurrences of 4902 'GNU.sparse.offset' and 'GNU.sparse.numbytes' are conflicting with 4903 the POSIX specs. 4904 4905 2. Attempting to extract such archives using a third-party's 'tar' 4906 results in extraction of sparse files in _condensed form_. If the 4907 'tar' implementation in question does not support POSIX format, it 4908 will also extract a file containing extension header attributes. 4909 This file can be used to expand the file to its original state. 4910 However, posix-aware 'tar's will usually ignore the unknown 4911 variables, which makes restoring the file more difficult. *Note 4912 Extraction of sparse members in v.0.0 format: extracting sparse 4913 v0x, for the detailed description of how to restore such members 4914 using non-GNU 'tar's. 4915 4916 GNU 'tar' 1.15.2 introduced sparse format version '0.1', which 4917attempted to solve these problems. As its predecessor, this format 4918stores sparse map in the extended POSIX header. It retains 4919'GNU.sparse.size' and 'GNU.sparse.numblocks' variables, but instead of 4920'GNU.sparse.offset'/'GNU.sparse.numbytes' pairs it uses a single 4921variable: 4922 4923'GNU.sparse.map' 4924 Map of non-null data chunks. It is a string consisting of 4925 comma-separated values "OFFSET,SIZE[,OFFSET-1,SIZE-1...]" 4926 4927 To address the 2nd problem, the 'name' field in 'ustar' is replaced 4928with a special name, constructed using the following pattern: 4929 4930 %d/GNUSparseFile.%p/%f 4931 4932 The real name of the sparse file is stored in the variable 4933'GNU.sparse.name'. Thus, those 'tar' implementations that are not aware 4934of GNU extensions will at least extract the files into separate 4935directories, giving the user a possibility to expand it afterwards. 4936*Note Extraction of sparse members in v.0.1 format: extracting sparse 4937v0x, for the detailed description of how to restore such members using 4938non-GNU 'tar's. 4939 4940 The resulting 'GNU.sparse.map' string can be _very_ long. Although 4941POSIX does not impose any limit on the length of a 'x' header variable, 4942this possibly can confuse some 'tar's. 4943 4944 4945File: tar.info, Node: PAX 1, Prev: PAX 0, Up: Sparse Formats 4946 4947PAX Format, Version 1.0 4948----------------------- 4949 4950The version '1.0' of sparse format was introduced with GNU 'tar' 49511.15.92. Its main objective was to make the resulting file extractable 4952with little effort even by non-posix aware 'tar' implementations. 4953Starting from this version, the extended header preceding a sparse 4954member always contains the following variables that identify the format 4955being used: 4956 4957'GNU.sparse.major' 4958 Major version 4959 4960'GNU.sparse.minor' 4961 Minor version 4962 4963 The 'name' field in 'ustar' header contains a special name, 4964constructed using the following pattern: 4965 4966 %d/GNUSparseFile.%p/%f 4967 4968 The real name of the sparse file is stored in the variable 4969'GNU.sparse.name'. The real size of the file is stored in the variable 4970'GNU.sparse.realsize'. 4971 4972 The sparse map itself is stored in the file data block, preceding the 4973actual file data. It consists of a series of decimal numbers delimited 4974by newlines. The map is padded with nulls to the nearest block 4975boundary. 4976 4977 The first number gives the number of entries in the map. Following 4978are map entries, each one consisting of two numbers giving the offset 4979and size of the data block it describes. 4980 4981 The format is designed in such a way that non-posix aware 'tar's and 4982'tar's not supporting 'GNU.sparse.*' keywords will extract each sparse 4983file in its condensed form with the file map prepended and will place it 4984into a separate directory. Then, using a simple program it would be 4985possible to expand the file to its original form even without GNU 'tar'. 4986*Note Sparse Recovery::, for the detailed information on how to extract 4987sparse members without GNU 'tar'. 4988 4989 4990File: tar.info, Node: Snapshot Files, Next: Dumpdir, Prev: Sparse Formats, Up: Tar Internals 4991 4992Format of the Incremental Snapshot Files 4993======================================== 4994 4995A "snapshot file" (or "directory file") is created during incremental 4996backups (*note Incremental Dumps::). It contains the status of the file 4997system at the time of the dump and is used to determine which files were 4998modified since the last backup. 4999 5000 GNU 'tar' version 1.34 supports three snapshot file formats. The 5001first format, called "format 0", is the one used by GNU 'tar' versions 5002up to and including 1.15.1. The second format, called "format 1" is an 5003extended version of this format, that contains more metadata and allows 5004for further extensions. It was used by alpha release version 1.15.90. 5005For alpha version 1.15.91 and stable releases version 1.16 up through 50061.34, the "format 2" is used. 5007 5008 GNU 'tar' is able to read all three formats, but will create 5009snapshots only in format 2. 5010 5011 This appendix describes all three formats in detail. 5012 5013 0. 'Format 0' snapshot file begins with a line containing a decimal 5014 number that represents a UNIX timestamp of the beginning of the 5015 last archivation. This line is followed by directory metadata 5016 descriptions, one per line. Each description has the following 5017 format: 5018 5019 [NFS]DEV INODE NAME 5020 5021 where: 5022 5023 NFS 5024 A single plus character ('+'), if this directory is located on 5025 an NFS-mounted partition, otherwise empty. 5026 5027 (That is, for non-NFS directories, the first character on the 5028 description line contains the start of the DEV field.) 5029 5030 DEV 5031 Device number of the directory; 5032 5033 INODE 5034 I-node number of the directory; 5035 5036 NAME 5037 Name of the directory. Any special characters (white-space, 5038 backslashes, etc.) are quoted. 5039 5040 1. 'Format 1' snapshot file begins with a line specifying the format 5041 of the file. This line has the following structure: 5042 5043 'GNU tar-'TAR-VERSION'-'INCR-FORMAT-VERSION 5044 5045 where TAR-VERSION is the version number of GNU 'tar' implementation 5046 that created this snapshot, and INCR-FORMAT-VERSION is the version 5047 number of the snapshot format (in this case '1'). 5048 5049 Next line contains two decimal numbers, representing the time of 5050 the last backup. First number is the number of seconds, the second 5051 one is the number of nanoseconds, since the beginning of the epoch. 5052 5053 Lines that follow contain directory metadata, one line per 5054 directory. Each line is formatted as follows: 5055 5056 [NFS]MTIME-SEC MTIME-NSEC DEV INODE NAME 5057 5058 where MTIME-SEC and MTIME-NSEC represent last modification time of 5059 this directory with nanosecond precision; NFS, DEV, INODE and NAME 5060 have the same meaning as with 'format 0'. 5061 5062 2. 'Format 2' snapshot file begins with a format identifier, as 5063 described for version 1, e.g.: 5064 5065 GNU tar-1.34-2 5066 5067 This line is followed by newline. Rest of file consists of 5068 records, separated by null (ASCII 0) characters. Thus, in contrast 5069 to the previous formats, format 2 snapshot is a binary file. 5070 5071 First two records are decimal integers, representing the time of 5072 the last backup. First number is the number of seconds, the second 5073 one is the number of nanoseconds, since the beginning of the epoch. 5074 These are followed by arbitrary number of directory records. 5075 5076 Each "directory record" contains a set of metadata describing a 5077 particular directory. Parts of a directory record are delimited 5078 with ASCII 0 characters. The following table describes each part. 5079 The "Number" type in this table stands for a decimal integer in 5080 ASCII notation. (Negative values are preceded with a "-" 5081 character, while positive values have no leading punctuation.) 5082 5083 Field Type Description 5084 --------------------------------------------------------------------------- 5085 nfs Character '1' if the directory is located on an 5086 NFS-mounted partition, or '0' otherwise; 5087 timestamp_sec Number Modification time, seconds; 5088 timestamp_nsec Number Modification time, nanoseconds; 5089 dev Number Device number; 5090 ino Number I-node number; 5091 name String Directory name; in contrast to the 5092 previous versions it is not quoted; 5093 contents Dumpdir Contents of the directory; 5094 *Note Dumpdir::, for a description of its 5095 format. 5096 5097 Dumpdirs stored in snapshot files contain only records of types 5098 'Y', 'N' and 'D'. 5099 5100 The specific range of values allowed in each of the "Number" fields 5101 depends on the underlying C datatypes as determined when 'tar' is 5102 compiled. To see the specific ranges allowed for a particular 5103 'tar' binary, you can use the '--show-snapshot-field-ranges' 5104 option: 5105 5106 $ tar --show-snapshot-field-ranges 5107 This tar's snapshot file field ranges are 5108 (field name => [ min, max ]): 5109 5110 nfs => [ 0, 1 ], 5111 timestamp_sec => [ -9223372036854775808, 9223372036854775807 ], 5112 timestamp_nsec => [ 0, 999999999 ], 5113 dev => [ 0, 18446744073709551615 ], 5114 ino => [ 0, 18446744073709551615 ], 5115 5116 (This example is from a GNU/Linux x86_64 system.) 5117 5118 5119File: tar.info, Node: Dumpdir, Prev: Snapshot Files, Up: Tar Internals 5120 5121Dumpdir 5122======= 5123 5124Incremental archives keep information about contents of each dumped 5125directory in special data blocks called "dumpdirs". 5126 5127 Dumpdir is a sequence of entries of the following form: 5128 5129 C FILENAME \0 5130 5131where C is one of the "control codes" described below, FILENAME is the 5132name of the file C operates upon, and '\0' represents a nul character 5133(ASCII 0). The white space characters were added for readability, real 5134dumpdirs do not contain them. 5135 5136 Each dumpdir ends with a single nul character. 5137 5138 The following table describes control codes and their meanings: 5139 5140'Y' 5141 FILENAME is contained in the archive. 5142 5143'N' 5144 FILENAME was present in the directory at the time the archive was 5145 made, yet it was not dumped to the archive, because it had not 5146 changed since the last backup. 5147 5148'D' 5149 FILENAME is a directory. 5150 5151'R' 5152 This code requests renaming of the FILENAME to the name specified 5153 with the 'T' command, that immediately follows it. 5154 5155'T' 5156 Specify target file name for 'R' command (see below). 5157 5158'X' 5159 Specify "temporary directory" name for a rename operation (see 5160 below). 5161 5162 Codes 'Y', 'N' and 'D' require FILENAME argument to be a relative 5163file name to the directory this dumpdir describes, whereas codes 'R', 5164'T' and 'X' require their argument to be an absolute file name. 5165 5166 The three codes 'R', 'T' and 'X' specify a "renaming operation". In 5167the simplest case it is: 5168 5169 Rsource\0Tdest\0 5170 5171which means "rename file 'source' to file 'dest'". 5172 5173 However, there are cases that require using a "temporary directory". 5174For example, consider the following scenario: 5175 5176 1. Previous run dumped a directory 'foo' which contained the following 5177 three directories: 5178 5179 a 5180 b 5181 c 5182 5183 2. They were renamed _cyclically_, so that: 5184 5185 a became b 5186 b became c 5187 c became a 5188 5189 3. New incremental dump was made. 5190 5191 This case cannot be handled by three successive renames, since 5192renaming 'a' to 'b' will destroy the existing directory. To correctly 5193process it, GNU 'tar' needs a temporary directory, so it creates the 5194following dumpdir (newlines have been added for readability): 5195 5196 Xfoo\0 5197 Rfoo/a\0T\0 5198 Rfoo/b\0Tfoo/c\0 5199 Rfoo/c\0Tfoo/a\0 5200 R\0Tfoo/a\0 5201 5202 The first command, 'Xfoo\0', instructs the extractor to create a 5203temporary directory in the directory 'foo'. Second command, 5204'Rfoo/aT\0', says "rename file 'foo/a' to the temporary directory that 5205has just been created" (empty file name after a command means use 5206temporary directory). Third and fourth commands work as usual, and, 5207finally, the last command, 'R\0Tfoo/a\0' tells tar to rename the 5208temporary directory to 'foo/a'. 5209 5210 The exact placement of a dumpdir in the archive depends on the 5211archive format (*note Formats::): 5212 5213 * PAX archives 5214 5215 In PAX archives, dumpdir is stored in the extended header of the 5216 corresponding directory, in variable 'GNU.dumpdir'. 5217 5218 * GNU and old GNU archives 5219 5220 These formats implement special header type 'D', which is similar 5221 to ustar header '5' (directory), except that it precedes a data 5222 block containing the dumpdir. 5223 5224 5225File: tar.info, Node: Genfile, Next: GNU Free Documentation License, Prev: Tar Internals, Up: Top 5226 5227Appendix F Genfile 5228****************** 5229 5230This appendix describes 'genfile', an auxiliary program used in the GNU 5231tar testsuite. If you are not interested in developing GNU tar, skip 5232this appendix. 5233 5234 Initially, 'genfile' was used to generate data files for the 5235testsuite, hence its name. However, new operation modes were being 5236implemented as the testsuite grew more sophisticated, and now 'genfile' 5237is a multi-purpose instrument. 5238 5239 There are three basic operation modes: 5240 5241File Generation 5242 This is the default mode. In this mode, 'genfile' generates data 5243 files. 5244 5245File Status 5246 In this mode 'genfile' displays status of specified files. 5247 5248Synchronous Execution. 5249 In this mode 'genfile' executes the given program with 5250 '--checkpoint' option and executes a set of actions when specified 5251 checkpoints are reached. 5252 5253* Menu: 5254 5255* Generate Mode:: File Generation Mode. 5256* Status Mode:: File Status Mode. 5257* Exec Mode:: Synchronous Execution mode. 5258 5259 5260File: tar.info, Node: Generate Mode, Next: Status Mode, Up: Genfile 5261 5262F.1 Generate Mode 5263================= 5264 5265In this mode 'genfile' creates a data file for the test suite. The size 5266of the file is given with the '--length' ('-l') option. By default the 5267file contents is written to the standard output, this can be changed 5268using '--file' ('-f') command line option. Thus, the following two 5269commands are equivalent: 5270 5271 genfile --length 100 > outfile 5272 genfile --length 100 --file outfile 5273 5274 If '--length' is not given, 'genfile' will generate an empty 5275(zero-length) file. 5276 5277 The command line option '--seek=N' istructs 'genfile' to skip the 5278given number of bytes (N) in the output file before writing to it. It 5279is similar to the 'seek=N' of the 'dd' utility. 5280 5281 You can instruct 'genfile' to create several files at one go, by 5282giving it '--files-from' ('-T') option followed by a name of file 5283containing a list of file names. Using dash ('-') instead of the file 5284name causes 'genfile' to read file list from the standard input. For 5285example: 5286 5287 # Read file names from file file.list 5288 genfile --files-from file.list 5289 # Read file names from standard input 5290 genfile --files-from - 5291 5292 The list file is supposed to contain one file name per line. To use 5293file lists separated by ASCII NUL character, use '--null' ('-0') command 5294line option: 5295 5296 genfile --null --files-from file.list 5297 5298 The default data pattern for filling the generated file consists of 5299first 256 letters of ASCII code, repeated enough times to fill the 5300entire file. This behavior can be changed with '--pattern' option. 5301This option takes a mandatory argument, specifying pattern name to use. 5302Currently two patterns are implemented: 5303 5304'--pattern=default' 5305 The default pattern as described above. 5306 5307'--pattern=zero' 5308 Fills the file with zeroes. 5309 5310 If no file name was given, the program exits with the code '0'. 5311Otherwise, it exits with '0' only if it was able to create a file of the 5312specified length. 5313 5314 Special option '--sparse' ('-s') instructs 'genfile' to create a 5315sparse file. Sparse files consist of "data fragments", separated by 5316"holes" or blocks of zeros. On many operating systems, actual disk 5317storage is not allocated for holes, but they are counted in the length 5318of the file. To create a sparse file, 'genfile' should know where to 5319put data fragments, and what data to use to fill them. So, when 5320'--sparse' is given the rest of the command line specifies a so-called 5321"file map". 5322 5323 The file map consists of any number of "fragment descriptors". Each 5324descriptor is composed of two values: a number, specifying fragment 5325offset from the end of the previous fragment or, for the very first 5326fragment, from the beginning of the file, and "contents string", that 5327specifies the pattern to fill the fragment with. File offset can be 5328suffixed with the following quantifiers: 5329 5330'k' 5331'K' 5332 The number is expressed in kilobytes. 5333'm' 5334'M' 5335 The number is expressed in megabytes. 5336'g' 5337'G' 5338 The number is expressed in gigabytes. 5339 5340 Contents string can be either a fragment size or a pattern. Fragment 5341size is a decimal number, prefixed with an equals sign. It can be 5342suffixed with a quantifier, as discussed above. If fragment size is 5343given, the fragment of that size will be filled with the currently 5344selected pattern (*note -pattern: Generate Mode.) and written to the 5345file. 5346 5347 A pattern is a string of arbitrary ASCII characters. For each of 5348them, 'genfile' will generate a "block" of data, filled with that 5349character and will write it to the fragment. The size of block is given 5350by '--block-size' option. It defaults to 512. Thus, if pattern 5351consists of N characters, the resulting file fragment will contain 5352'N*BLOCK-SIZE' bytes of data. 5353 5354 The last fragment descriptor can have only file offset part. In this 5355case 'genfile' will create a hole at the end of the file up to the given 5356offset. 5357 5358 A dash appearing as a fragment descriptor instructs 'genfile' to read 5359file map from the standard input. Each line of input should consist of 5360fragment offset and contents string, separated by any amount of 5361whitespace. 5362 5363 For example, consider the following invocation: 5364 5365 genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K 5366 5367It will create 3101184-bytes long file of the following structure: 5368 5369Offset Length Contents 53700 4*512=2048 Four 512-byte blocks, filled 5371 with letters 'A', 'B', 'C' and 5372 'D'. 53732048 1046528 Zero bytes 53741050624 5*512=2560 Five blocks, filled with 5375 letters 'E', 'F', 'G', 'H', 5376 'I'. 53771053184 2048000 Zero bytes 5378 5379 The exit code of 'genfile --sparse' command is '0' only if created 5380file is actually sparse. If it is not, the appropriate error message is 5381displayed and the command exists with code '1'. The '--quite' ('-q') 5382option suppresses this behavior. If '--quite' is given, 'genfile 5383--sparse' exits with code '0' if it was able to create the file, whether 5384the resulting file is sparse or not. 5385 5386 5387File: tar.info, Node: Status Mode, Next: Exec Mode, Prev: Generate Mode, Up: Genfile 5388 5389F.2 Status Mode 5390=============== 5391 5392In status mode, 'genfile' prints file system status for each file 5393specified in the command line. This mode is toggled by '--stat' ('-S') 5394command line option. An optional argument to this option specifies 5395output "format": a comma-separated list of 'struct stat' fields to be 5396displayed. This list can contain following identifiers: 5397 5398name 5399 The file name. 5400 5401dev 5402st_dev 5403 Device number in decimal. 5404 5405ino 5406st_ino 5407 Inode number. 5408 5409mode[.NUMBER] 5410st_mode[.NUMBER] 5411 5412 File mode in octal. Optional NUMBER specifies octal mask to be 5413 applied to the mode before outputting. For example, '--stat 5414 mode.777' will preserve lower nine bits of it. Notice, that you 5415 can use any punctuation character in place of '.'. 5416 5417nlink 5418st_nlink 5419 Number of hard links. 5420 5421uid 5422st_uid 5423 User ID of owner. 5424 5425gid 5426st_gid 5427 Group ID of owner. 5428 5429size 5430st_size 5431 File size in decimal. 5432 5433blksize 5434st_blksize 5435 The size in bytes of each file block. 5436 5437blocks 5438st_blocks 5439 Number of blocks allocated. 5440 5441atime 5442st_atime 5443 Time of last access. 5444 5445mtime 5446st_mtime 5447 Time of last modification 5448 5449ctime 5450st_ctime 5451 Time of last status change 5452 5453sparse 5454 A boolean value indicating whether the file is 'sparse'. 5455 5456 Modification times are displayed in UTC as UNIX timestamps, unless 5457suffixed with 'H' (for "human-readable"), as in 'ctimeH', in which case 5458usual 'tar tv' output format is used. 5459 5460 The default output format is: 'name,dev,ino,mode, 5461nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime'. 5462 5463 For example, the following command will display file names and 5464corresponding times of last access for each file in the current working 5465directory: 5466 5467 genfile --stat=name,atime * 5468 5469 5470File: tar.info, Node: Exec Mode, Prev: Status Mode, Up: Genfile 5471 5472F.3 Exec Mode 5473============= 5474 5475This mode is designed for testing the behavior of 'paxutils' commands 5476when some of the files change during archiving. It supposes that the 5477command being executed supports '--checkpoint' and '--checkpoint-action' 5478options (*note Checkpoints: (tar)checkpoints.). 5479 5480 The 'Exec Mode' is enabled by '--run' command line option (or its 5481alias '-r'). The non-optional arguments supply the command line to be 5482executed. 'Genfile' modifies this command line by inserting the 5483following options between the command name and first argument: 5484 5485 --checkpoint=N 5486 --checkpoint-action "echo=genfile checkpoint %u" 5487 --checkpoint-action "wait=SIGUSR1" 5488 5489 Here, N stands for the checkpoint granularity (for GNU 'tar', it is 5490the number of archive records read or written between each pair of 5491checkpoints). The default value is 1. This value can be changed using 5492the optional argument to the '--run' option. For example, to run 5493actions on each 10th checkpoint: 5494 5495 genfile --run=10 ... 5496 5497 If the command line contains options, it must be preceded by a 5498double-dash ('--'), which will prevent these options from being 5499interpreted by 'genfile' itself. For example: 5500 5501 genfile --run --checkpoint=2 --truncate foo -- tar -c -f a.tar . 5502 5503 Notice also, that when running 'tar', its command line may not 5504contain traditional options (cluster of letters without dash). 5505 5506 A set of options is provided for defining checkpoint values and 5507actions to be executed upon reaching them. Checkpoint values are 5508introduced with the '--checkpoint' command line option. Argument to 5509this option is the number of checkpoint in decimal. 5510 5511 Any number of "actions" may be specified after a checkpoint. 5512Available actions are 5513 5514'--cut FILE' 5515'--truncate FILE' 5516 Truncate FILE to the size specified by previous '--length' option 5517 (or 0, if it is not given). 5518 5519'--append FILE' 5520 Append data to FILE. The size of data and its pattern are given by 5521 previous '--length' and 'pattern' options. 5522 5523'--touch FILE' 5524 Update the access and modification times of FILE. These timestamps 5525 are changed to the current time, unless '--date' option was given, 5526 in which case they are changed to the specified time. Argument to 5527 '--date' option is a date specification in an almost arbitrary 5528 format (*note Date input formats::). 5529 5530'--exec COMMAND' 5531 Execute given shell command. 5532 5533'--delete FILE' 5534'--unlink FILE' 5535 Delete the named file or directory. If deleting the directory, it 5536 must be empty. 5537 5538 Option '--verbose' instructs 'genfile' to print on standard output 5539notifications about checkpoints being executed and to verbosely describe 5540exit status of the command. 5541 5542 While the command is being executed its standard output remains 5543connected to descriptor 1. All messages it prints to file descriptor 2, 5544except checkpoint notifications, are forwarded to standard error. 5545 5546 In exec mode, 'genfile' exits with the exit status of the executed 5547command. 5548 5549 5550File: tar.info, Node: GNU Free Documentation License, Next: Index of Command Line Options, Prev: Genfile, Up: Top 5551 5552Appendix G GNU Free Documentation License 5553***************************************** 5554 5555 Version 1.3, 3 November 2008 5556 5557 Copyright (C) 2000-2021 Free Software Foundation, Inc. 5558 <http://fsf.org/> 5559 5560 Everyone is permitted to copy and distribute verbatim copies 5561 of this license document, but changing it is not allowed. 5562 5563 0. PREAMBLE 5564 5565 The purpose of this License is to make a manual, textbook, or other 5566 functional and useful document "free" in the sense of freedom: to 5567 assure everyone the effective freedom to copy and redistribute it, 5568 with or without modifying it, either commercially or 5569 noncommercially. Secondarily, this License preserves for the 5570 author and publisher a way to get credit for their work, while not 5571 being considered responsible for modifications made by others. 5572 5573 This License is a kind of "copyleft", which means that derivative 5574 works of the document must themselves be free in the same sense. 5575 It complements the GNU General Public License, which is a copyleft 5576 license designed for free software. 5577 5578 We have designed this License in order to use it for manuals for 5579 free software, because free software needs free documentation: a 5580 free program should come with manuals providing the same freedoms 5581 that the software does. But this License is not limited to 5582 software manuals; it can be used for any textual work, regardless 5583 of subject matter or whether it is published as a printed book. We 5584 recommend this License principally for works whose purpose is 5585 instruction or reference. 5586 5587 1. APPLICABILITY AND DEFINITIONS 5588 5589 This License applies to any manual or other work, in any medium, 5590 that contains a notice placed by the copyright holder saying it can 5591 be distributed under the terms of this License. Such a notice 5592 grants a world-wide, royalty-free license, unlimited in duration, 5593 to use that work under the conditions stated herein. The 5594 "Document", below, refers to any such manual or work. Any member 5595 of the public is a licensee, and is addressed as "you". You accept 5596 the license if you copy, modify or distribute the work in a way 5597 requiring permission under copyright law. 5598 5599 A "Modified Version" of the Document means any work containing the 5600 Document or a portion of it, either copied verbatim, or with 5601 modifications and/or translated into another language. 5602 5603 A "Secondary Section" is a named appendix or a front-matter section 5604 of the Document that deals exclusively with the relationship of the 5605 publishers or authors of the Document to the Document's overall 5606 subject (or to related matters) and contains nothing that could 5607 fall directly within that overall subject. (Thus, if the Document 5608 is in part a textbook of mathematics, a Secondary Section may not 5609 explain any mathematics.) The relationship could be a matter of 5610 historical connection with the subject or with related matters, or 5611 of legal, commercial, philosophical, ethical or political position 5612 regarding them. 5613 5614 The "Invariant Sections" are certain Secondary Sections whose 5615 titles are designated, as being those of Invariant Sections, in the 5616 notice that says that the Document is released under this License. 5617 If a section does not fit the above definition of Secondary then it 5618 is not allowed to be designated as Invariant. The Document may 5619 contain zero Invariant Sections. If the Document does not identify 5620 any Invariant Sections then there are none. 5621 5622 The "Cover Texts" are certain short passages of text that are 5623 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 5624 that says that the Document is released under this License. A 5625 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 5626 be at most 25 words. 5627 5628 A "Transparent" copy of the Document means a machine-readable copy, 5629 represented in a format whose specification is available to the 5630 general public, that is suitable for revising the document 5631 straightforwardly with generic text editors or (for images composed 5632 of pixels) generic paint programs or (for drawings) some widely 5633 available drawing editor, and that is suitable for input to text 5634 formatters or for automatic translation to a variety of formats 5635 suitable for input to text formatters. A copy made in an otherwise 5636 Transparent file format whose markup, or absence of markup, has 5637 been arranged to thwart or discourage subsequent modification by 5638 readers is not Transparent. An image format is not Transparent if 5639 used for any substantial amount of text. A copy that is not 5640 "Transparent" is called "Opaque". 5641 5642 Examples of suitable formats for Transparent copies include plain 5643 ASCII without markup, Texinfo input format, LaTeX input format, 5644 SGML or XML using a publicly available DTD, and standard-conforming 5645 simple HTML, PostScript or PDF designed for human modification. 5646 Examples of transparent image formats include PNG, XCF and JPG. 5647 Opaque formats include proprietary formats that can be read and 5648 edited only by proprietary word processors, SGML or XML for which 5649 the DTD and/or processing tools are not generally available, and 5650 the machine-generated HTML, PostScript or PDF produced by some word 5651 processors for output purposes only. 5652 5653 The "Title Page" means, for a printed book, the title page itself, 5654 plus such following pages as are needed to hold, legibly, the 5655 material this License requires to appear in the title page. For 5656 works in formats which do not have any title page as such, "Title 5657 Page" means the text near the most prominent appearance of the 5658 work's title, preceding the beginning of the body of the text. 5659 5660 The "publisher" means any person or entity that distributes copies 5661 of the Document to the public. 5662 5663 A section "Entitled XYZ" means a named subunit of the Document 5664 whose title either is precisely XYZ or contains XYZ in parentheses 5665 following text that translates XYZ in another language. (Here XYZ 5666 stands for a specific section name mentioned below, such as 5667 "Acknowledgements", "Dedications", "Endorsements", or "History".) 5668 To "Preserve the Title" of such a section when you modify the 5669 Document means that it remains a section "Entitled XYZ" according 5670 to this definition. 5671 5672 The Document may include Warranty Disclaimers next to the notice 5673 which states that this License applies to the Document. These 5674 Warranty Disclaimers are considered to be included by reference in 5675 this License, but only as regards disclaiming warranties: any other 5676 implication that these Warranty Disclaimers may have is void and 5677 has no effect on the meaning of this License. 5678 5679 2. VERBATIM COPYING 5680 5681 You may copy and distribute the Document in any medium, either 5682 commercially or noncommercially, provided that this License, the 5683 copyright notices, and the license notice saying this License 5684 applies to the Document are reproduced in all copies, and that you 5685 add no other conditions whatsoever to those of this License. You 5686 may not use technical measures to obstruct or control the reading 5687 or further copying of the copies you make or distribute. However, 5688 you may accept compensation in exchange for copies. If you 5689 distribute a large enough number of copies you must also follow the 5690 conditions in section 3. 5691 5692 You may also lend copies, under the same conditions stated above, 5693 and you may publicly display copies. 5694 5695 3. COPYING IN QUANTITY 5696 5697 If you publish printed copies (or copies in media that commonly 5698 have printed covers) of the Document, numbering more than 100, and 5699 the Document's license notice requires Cover Texts, you must 5700 enclose the copies in covers that carry, clearly and legibly, all 5701 these Cover Texts: Front-Cover Texts on the front cover, and 5702 Back-Cover Texts on the back cover. Both covers must also clearly 5703 and legibly identify you as the publisher of these copies. The 5704 front cover must present the full title with all words of the title 5705 equally prominent and visible. You may add other material on the 5706 covers in addition. Copying with changes limited to the covers, as 5707 long as they preserve the title of the Document and satisfy these 5708 conditions, can be treated as verbatim copying in other respects. 5709 5710 If the required texts for either cover are too voluminous to fit 5711 legibly, you should put the first ones listed (as many as fit 5712 reasonably) on the actual cover, and continue the rest onto 5713 adjacent pages. 5714 5715 If you publish or distribute Opaque copies of the Document 5716 numbering more than 100, you must either include a machine-readable 5717 Transparent copy along with each Opaque copy, or state in or with 5718 each Opaque copy a computer-network location from which the general 5719 network-using public has access to download using public-standard 5720 network protocols a complete Transparent copy of the Document, free 5721 of added material. If you use the latter option, you must take 5722 reasonably prudent steps, when you begin distribution of Opaque 5723 copies in quantity, to ensure that this Transparent copy will 5724 remain thus accessible at the stated location until at least one 5725 year after the last time you distribute an Opaque copy (directly or 5726 through your agents or retailers) of that edition to the public. 5727 5728 It is requested, but not required, that you contact the authors of 5729 the Document well before redistributing any large number of copies, 5730 to give them a chance to provide you with an updated version of the 5731 Document. 5732 5733 4. MODIFICATIONS 5734 5735 You may copy and distribute a Modified Version of the Document 5736 under the conditions of sections 2 and 3 above, provided that you 5737 release the Modified Version under precisely this License, with the 5738 Modified Version filling the role of the Document, thus licensing 5739 distribution and modification of the Modified Version to whoever 5740 possesses a copy of it. In addition, you must do these things in 5741 the Modified Version: 5742 5743 A. Use in the Title Page (and on the covers, if any) a title 5744 distinct from that of the Document, and from those of previous 5745 versions (which should, if there were any, be listed in the 5746 History section of the Document). You may use the same title 5747 as a previous version if the original publisher of that 5748 version gives permission. 5749 5750 B. List on the Title Page, as authors, one or more persons or 5751 entities responsible for authorship of the modifications in 5752 the Modified Version, together with at least five of the 5753 principal authors of the Document (all of its principal 5754 authors, if it has fewer than five), unless they release you 5755 from this requirement. 5756 5757 C. State on the Title page the name of the publisher of the 5758 Modified Version, as the publisher. 5759 5760 D. Preserve all the copyright notices of the Document. 5761 5762 E. Add an appropriate copyright notice for your modifications 5763 adjacent to the other copyright notices. 5764 5765 F. Include, immediately after the copyright notices, a license 5766 notice giving the public permission to use the Modified 5767 Version under the terms of this License, in the form shown in 5768 the Addendum below. 5769 5770 G. Preserve in that license notice the full lists of Invariant 5771 Sections and required Cover Texts given in the Document's 5772 license notice. 5773 5774 H. Include an unaltered copy of this License. 5775 5776 I. Preserve the section Entitled "History", Preserve its Title, 5777 and add to it an item stating at least the title, year, new 5778 authors, and publisher of the Modified Version as given on the 5779 Title Page. If there is no section Entitled "History" in the 5780 Document, create one stating the title, year, authors, and 5781 publisher of the Document as given on its Title Page, then add 5782 an item describing the Modified Version as stated in the 5783 previous sentence. 5784 5785 J. Preserve the network location, if any, given in the Document 5786 for public access to a Transparent copy of the Document, and 5787 likewise the network locations given in the Document for 5788 previous versions it was based on. These may be placed in the 5789 "History" section. You may omit a network location for a work 5790 that was published at least four years before the Document 5791 itself, or if the original publisher of the version it refers 5792 to gives permission. 5793 5794 K. For any section Entitled "Acknowledgements" or "Dedications", 5795 Preserve the Title of the section, and preserve in the section 5796 all the substance and tone of each of the contributor 5797 acknowledgements and/or dedications given therein. 5798 5799 L. Preserve all the Invariant Sections of the Document, unaltered 5800 in their text and in their titles. Section numbers or the 5801 equivalent are not considered part of the section titles. 5802 5803 M. Delete any section Entitled "Endorsements". Such a section 5804 may not be included in the Modified Version. 5805 5806 N. Do not retitle any existing section to be Entitled 5807 "Endorsements" or to conflict in title with any Invariant 5808 Section. 5809 5810 O. Preserve any Warranty Disclaimers. 5811 5812 If the Modified Version includes new front-matter sections or 5813 appendices that qualify as Secondary Sections and contain no 5814 material copied from the Document, you may at your option designate 5815 some or all of these sections as invariant. To do this, add their 5816 titles to the list of Invariant Sections in the Modified Version's 5817 license notice. These titles must be distinct from any other 5818 section titles. 5819 5820 You may add a section Entitled "Endorsements", provided it contains 5821 nothing but endorsements of your Modified Version by various 5822 parties--for example, statements of peer review or that the text 5823 has been approved by an organization as the authoritative 5824 definition of a standard. 5825 5826 You may add a passage of up to five words as a Front-Cover Text, 5827 and a passage of up to 25 words as a Back-Cover Text, to the end of 5828 the list of Cover Texts in the Modified Version. Only one passage 5829 of Front-Cover Text and one of Back-Cover Text may be added by (or 5830 through arrangements made by) any one entity. If the Document 5831 already includes a cover text for the same cover, previously added 5832 by you or by arrangement made by the same entity you are acting on 5833 behalf of, you may not add another; but you may replace the old 5834 one, on explicit permission from the previous publisher that added 5835 the old one. 5836 5837 The author(s) and publisher(s) of the Document do not by this 5838 License give permission to use their names for publicity for or to 5839 assert or imply endorsement of any Modified Version. 5840 5841 5. COMBINING DOCUMENTS 5842 5843 You may combine the Document with other documents released under 5844 this License, under the terms defined in section 4 above for 5845 modified versions, provided that you include in the combination all 5846 of the Invariant Sections of all of the original documents, 5847 unmodified, and list them all as Invariant Sections of your 5848 combined work in its license notice, and that you preserve all 5849 their Warranty Disclaimers. 5850 5851 The combined work need only contain one copy of this License, and 5852 multiple identical Invariant Sections may be replaced with a single 5853 copy. If there are multiple Invariant Sections with the same name 5854 but different contents, make the title of each such section unique 5855 by adding at the end of it, in parentheses, the name of the 5856 original author or publisher of that section if known, or else a 5857 unique number. Make the same adjustment to the section titles in 5858 the list of Invariant Sections in the license notice of the 5859 combined work. 5860 5861 In the combination, you must combine any sections Entitled 5862 "History" in the various original documents, forming one section 5863 Entitled "History"; likewise combine any sections Entitled 5864 "Acknowledgements", and any sections Entitled "Dedications". You 5865 must delete all sections Entitled "Endorsements." 5866 5867 6. COLLECTIONS OF DOCUMENTS 5868 5869 You may make a collection consisting of the Document and other 5870 documents released under this License, and replace the individual 5871 copies of this License in the various documents with a single copy 5872 that is included in the collection, provided that you follow the 5873 rules of this License for verbatim copying of each of the documents 5874 in all other respects. 5875 5876 You may extract a single document from such a collection, and 5877 distribute it individually under this License, provided you insert 5878 a copy of this License into the extracted document, and follow this 5879 License in all other respects regarding verbatim copying of that 5880 document. 5881 5882 7. AGGREGATION WITH INDEPENDENT WORKS 5883 5884 A compilation of the Document or its derivatives with other 5885 separate and independent documents or works, in or on a volume of a 5886 storage or distribution medium, is called an "aggregate" if the 5887 copyright resulting from the compilation is not used to limit the 5888 legal rights of the compilation's users beyond what the individual 5889 works permit. When the Document is included in an aggregate, this 5890 License does not apply to the other works in the aggregate which 5891 are not themselves derivative works of the Document. 5892 5893 If the Cover Text requirement of section 3 is applicable to these 5894 copies of the Document, then if the Document is less than one half 5895 of the entire aggregate, the Document's Cover Texts may be placed 5896 on covers that bracket the Document within the aggregate, or the 5897 electronic equivalent of covers if the Document is in electronic 5898 form. Otherwise they must appear on printed covers that bracket 5899 the whole aggregate. 5900 5901 8. TRANSLATION 5902 5903 Translation is considered a kind of modification, so you may 5904 distribute translations of the Document under the terms of section 5905 4. Replacing Invariant Sections with translations requires special 5906 permission from their copyright holders, but you may include 5907 translations of some or all Invariant Sections in addition to the 5908 original versions of these Invariant Sections. You may include a 5909 translation of this License, and all the license notices in the 5910 Document, and any Warranty Disclaimers, provided that you also 5911 include the original English version of this License and the 5912 original versions of those notices and disclaimers. In case of a 5913 disagreement between the translation and the original version of 5914 this License or a notice or disclaimer, the original version will 5915 prevail. 5916 5917 If a section in the Document is Entitled "Acknowledgements", 5918 "Dedications", or "History", the requirement (section 4) to 5919 Preserve its Title (section 1) will typically require changing the 5920 actual title. 5921 5922 9. TERMINATION 5923 5924 You may not copy, modify, sublicense, or distribute the Document 5925 except as expressly provided under this License. Any attempt 5926 otherwise to copy, modify, sublicense, or distribute it is void, 5927 and will automatically terminate your rights under this License. 5928 5929 However, if you cease all violation of this License, then your 5930 license from a particular copyright holder is reinstated (a) 5931 provisionally, unless and until the copyright holder explicitly and 5932 finally terminates your license, and (b) permanently, if the 5933 copyright holder fails to notify you of the violation by some 5934 reasonable means prior to 60 days after the cessation. 5935 5936 Moreover, your license from a particular copyright holder is 5937 reinstated permanently if the copyright holder notifies you of the 5938 violation by some reasonable means, this is the first time you have 5939 received notice of violation of this License (for any work) from 5940 that copyright holder, and you cure the violation prior to 30 days 5941 after your receipt of the notice. 5942 5943 Termination of your rights under this section does not terminate 5944 the licenses of parties who have received copies or rights from you 5945 under this License. If your rights have been terminated and not 5946 permanently reinstated, receipt of a copy of some or all of the 5947 same material does not give you any rights to use it. 5948 5949 10. FUTURE REVISIONS OF THIS LICENSE 5950 5951 The Free Software Foundation may publish new, revised versions of 5952 the GNU Free Documentation License from time to time. Such new 5953 versions will be similar in spirit to the present version, but may 5954 differ in detail to address new problems or concerns. See 5955 <http://www.gnu.org/copyleft/>. 5956 5957 Each version of the License is given a distinguishing version 5958 number. If the Document specifies that a particular numbered 5959 version of this License "or any later version" applies to it, you 5960 have the option of following the terms and conditions either of 5961 that specified version or of any later version that has been 5962 published (not as a draft) by the Free Software Foundation. If the 5963 Document does not specify a version number of this License, you may 5964 choose any version ever published (not as a draft) by the Free 5965 Software Foundation. If the Document specifies that a proxy can 5966 decide which future versions of this License can be used, that 5967 proxy's public statement of acceptance of a version permanently 5968 authorizes you to choose that version for the Document. 5969 5970 11. RELICENSING 5971 5972 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 5973 World Wide Web server that publishes copyrightable works and also 5974 provides prominent facilities for anybody to edit those works. A 5975 public wiki that anybody can edit is an example of such a server. 5976 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 5977 site means any set of copyrightable works thus published on the MMC 5978 site. 5979 5980 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 5981 license published by Creative Commons Corporation, a not-for-profit 5982 corporation with a principal place of business in San Francisco, 5983 California, as well as future copyleft versions of that license 5984 published by that same organization. 5985 5986 "Incorporate" means to publish or republish a Document, in whole or 5987 in part, as part of another Document. 5988 5989 An MMC is "eligible for relicensing" if it is licensed under this 5990 License, and if all works that were first published under this 5991 License somewhere other than this MMC, and subsequently 5992 incorporated in whole or in part into the MMC, (1) had no cover 5993 texts or invariant sections, and (2) were thus incorporated prior 5994 to November 1, 2008. 5995 5996 The operator of an MMC Site may republish an MMC contained in the 5997 site under CC-BY-SA on the same site at any time before August 1, 5998 2009, provided the MMC is eligible for relicensing. 5999 6000ADDENDUM: How to use this License for your documents 6001==================================================== 6002 6003To use this License in a document you have written, include a copy of 6004the License in the document and put the following copyright and license 6005notices just after the title page: 6006 6007 Copyright (C) YEAR YOUR NAME. 6008 Permission is granted to copy, distribute and/or modify this document 6009 under the terms of the GNU Free Documentation License, Version 1.3 6010 or any later version published by the Free Software Foundation; 6011 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 6012 Texts. A copy of the license is included in the section entitled ``GNU 6013 Free Documentation License''. 6014 6015 If you have Invariant Sections, Front-Cover Texts and Back-Cover 6016Texts, replace the "with...Texts." line with this: 6017 6018 with the Invariant Sections being LIST THEIR TITLES, with 6019 the Front-Cover Texts being LIST, and with the Back-Cover Texts 6020 being LIST. 6021 6022 If you have Invariant Sections without Cover Texts, or some other 6023combination of the three, merge those two alternatives to suit the 6024situation. 6025 6026 If your document contains nontrivial examples of program code, we 6027recommend releasing these examples in parallel under your choice of free 6028software license, such as the GNU General Public License, to permit 6029their use in free software. 6030 6031 6032File: tar.info, Node: Index of Command Line Options, Next: Index, Prev: GNU Free Documentation License, Up: Top 6033 6034Appendix H Index of Command Line Options 6035**************************************** 6036 6037This appendix contains an index of all GNU 'tar' long command line 6038options. The options are listed without the preceding double-dash. For 6039a cross-reference of short command line options, see *note Short Option 6040Summary::. 6041 6042[index] 6043* Menu: 6044 6045* absolute-names: absolute. (line 10) 6046* absolute-names, summary: Option Summary. (line 6) 6047* acls, summary: Option Summary. (line 14) 6048* add-file: files. (line 83) 6049* after-date: after. (line 24) 6050* after-date, summary: Option Summary. (line 17) 6051* anchored: controlling pattern-matching. 6052 (line 78) 6053* anchored, summary: Option Summary. (line 21) 6054* append: append. (line 6) 6055* append <1>: appending files. (line 6) 6056* append, summary: Operation Summary. (line 6) 6057* atime-preserve: Attributes. (line 10) 6058* atime-preserve, summary: Option Summary. (line 25) 6059* auto-compress: gzip. (line 161) 6060* auto-compress, summary: Option Summary. (line 71) 6061* backup: backup. (line 41) 6062* backup, summary: Option Summary. (line 78) 6063* block-number: verbose. (line 112) 6064* block-number, summary: Option Summary. (line 84) 6065* blocking-factor: Blocking Factor. (line 8) 6066* blocking-factor, summary: Option Summary. (line 91) 6067* bzip2, summary: Option Summary. (line 97) 6068* catenate: concatenate. (line 6) 6069* catenate, summary: Operation Summary. (line 11) 6070* check-device, described: Incremental Dumps. (line 107) 6071* check-device, summary: Option Summary. (line 103) 6072* check-links, described: hard links. (line 31) 6073* check-links, summary: Option Summary. (line 161) 6074* checkpoint: checkpoints. (line 6) 6075* checkpoint, defined: checkpoints. (line 13) 6076* checkpoint, summary: Option Summary. (line 108) 6077* checkpoint-action: checkpoints. (line 6) 6078* checkpoint-action, defined: checkpoints. (line 22) 6079* checkpoint-action, summary: Option Summary. (line 117) 6080* clamp-mtime, summary: Option Summary. (line 178) 6081* compare: compare. (line 6) 6082* compare, summary: Operation Summary. (line 16) 6083* compress: gzip. (line 124) 6084* compress, summary: Option Summary. (line 170) 6085* concatenate: concatenate. (line 6) 6086* concatenate, summary: Operation Summary. (line 23) 6087* confirmation, summary: Option Summary. (line 182) 6088* create, additional options: create options. (line 6) 6089* create, complementary notes: Basic tar. (line 11) 6090* create, introduced: Creating the archive. 6091 (line 6) 6092* create, summary: Operation Summary. (line 29) 6093* create, using with --verbose: create verbose. (line 6) 6094* create, using with --verify: verify. (line 24) 6095* delay-directory-restore: Directory Modification Times and Permissions. 6096 (line 62) 6097* delay-directory-restore, summary: Option Summary. (line 186) 6098* delete: delete. (line 6) 6099* delete, summary: Operation Summary. (line 34) 6100* delete, using before -append: append. (line 47) 6101* dereference: dereference. (line 6) 6102* dereference, summary: Option Summary. (line 192) 6103* diff, summary: Operation Summary. (line 39) 6104* directory: directory. (line 11) 6105* directory, summary: Option Summary. (line 199) 6106* exclude: exclude. (line 6) 6107* exclude <1>: exclude. (line 9) 6108* exclude, potential problems with: problems with exclude. 6109 (line 6) 6110* exclude, summary: Option Summary. (line 207) 6111* exclude-backups: exclude. (line 114) 6112* exclude-backups, summary: Option Summary. (line 212) 6113* exclude-caches: exclude. (line 134) 6114* exclude-caches, summary: Option Summary. (line 221) 6115* exclude-caches-all: exclude. (line 142) 6116* exclude-caches-all, summary: Option Summary. (line 236) 6117* exclude-caches-under: exclude. (line 138) 6118* exclude-caches-under, summary: Option Summary. (line 229) 6119* exclude-from: exclude. (line 6) 6120* exclude-from <1>: exclude. (line 20) 6121* exclude-from, summary: Option Summary. (line 215) 6122* exclude-ignore: exclude. (line 76) 6123* exclude-ignore, summary: Option Summary. (line 241) 6124* exclude-ignore-recursive: exclude. (line 81) 6125* exclude-ignore-recursive, summary: Option Summary. (line 246) 6126* exclude-tag: exclude. (line 151) 6127* exclude-tag, summary: Option Summary. (line 251) 6128* exclude-tag-all: exclude. (line 159) 6129* exclude-tag-all, summary: Option Summary. (line 263) 6130* exclude-tag-under: exclude. (line 155) 6131* exclude-tag-under, summary: Option Summary. (line 257) 6132* exclude-vcs: exclude. (line 85) 6133* exclude-vcs, summary: Option Summary. (line 268) 6134* exclude-vcs-ignores: exclude. (line 42) 6135* exclude-vcs-ignores, summary: Option Summary. (line 275) 6136* extract: extract. (line 6) 6137* extract, additional options: extract options. (line 6) 6138* extract, complementary notes: Basic tar. (line 49) 6139* extract, summary: Operation Summary. (line 44) 6140* extract, using with --listed-incremental: Incremental Dumps. 6141 (line 120) 6142* file: file. (line 6) 6143* file, short description: file. (line 15) 6144* file, summary: Option Summary. (line 283) 6145* file, tutorial: file tutorial. (line 6) 6146* files-from: files. (line 14) 6147* files-from, summary: Option Summary. (line 290) 6148* force-local, short description: Device. (line 70) 6149* force-local, summary: Option Summary. (line 297) 6150* format, summary: Option Summary. (line 303) 6151* full-time, summary: Option Summary. (line 328) 6152* get, summary: Operation Summary. (line 50) 6153* group: override. (line 99) 6154* group, summary: Option Summary. (line 346) 6155* group-map, summary: Option Summary. (line 356) 6156* gunzip, summary: Option Summary. (line 366) 6157* gzip: gzip. (line 99) 6158* gzip, summary: Option Summary. (line 366) 6159* hard-dereference, described: hard links. (line 59) 6160* hard-dereference, summary: Option Summary. (line 375) 6161* help: help tutorial. (line 6) 6162* help, introduction: help. (line 26) 6163* help, summary: Option Summary. (line 381) 6164* hole-detection: sparse. (line 66) 6165* hole-detection, summary: Option Summary. (line 387) 6166* ignore-case: controlling pattern-matching. 6167 (line 85) 6168* ignore-case, summary: Option Summary. (line 392) 6169* ignore-command-error: Writing to an External Program. 6170 (line 111) 6171* ignore-command-error, summary: Option Summary. (line 396) 6172* ignore-failed-read: Ignore Failed Read. (line 7) 6173* ignore-failed-read, summary: Option Summary. (line 400) 6174* ignore-zeros: Ignore Zeros. (line 6) 6175* ignore-zeros, short description: Blocking Factor. (line 152) 6176* ignore-zeros, summary: Option Summary. (line 405) 6177* incremental, summary: Option Summary. (line 411) 6178* incremental, using with --list: Incremental Dumps. (line 185) 6179* index-file, summary: Option Summary. (line 419) 6180* info-script: Multi-Volume Archives. 6181 (line 83) 6182* info-script, short description: Device. (line 121) 6183* info-script, summary: Option Summary. (line 423) 6184* interactive: interactive. (line 14) 6185* interactive, summary: Option Summary. (line 432) 6186* keep-directory-symlink, summary: Option Summary. (line 440) 6187* keep-newer-files: Keep Newer Files. (line 6) 6188* keep-newer-files, summary: Option Summary. (line 454) 6189* keep-old-files: Keep Old Files. (line 9) 6190* keep-old-files, introduced: Dealing with Old Files. 6191 (line 16) 6192* keep-old-files, summary: Option Summary. (line 459) 6193* label: Tape Files. (line 6) 6194* label <1>: label. (line 6) 6195* label, summary: Option Summary. (line 468) 6196* level, described: Incremental Dumps. (line 75) 6197* level, summary: Option Summary. (line 476) 6198* list: list. (line 6) 6199* list, summary: Operation Summary. (line 55) 6200* list, using with --incremental: Incremental Dumps. (line 185) 6201* list, using with --listed-incremental: Incremental Dumps. (line 185) 6202* list, using with --verbose: list. (line 34) 6203* list, using with file name arguments: list. (line 25) 6204* listed-incremental, described: Incremental Dumps. (line 14) 6205* listed-incremental, summary: Option Summary. (line 486) 6206* listed-incremental, using with --extract: Incremental Dumps. 6207 (line 120) 6208* listed-incremental, using with --list: Incremental Dumps. (line 185) 6209* lzip: gzip. (line 112) 6210* lzip, summary: Option Summary. (line 495) 6211* lzma: gzip. (line 115) 6212* lzma, summary: Option Summary. (line 500) 6213* lzop: gzip. (line 118) 6214* mode: override. (line 14) 6215* mode, summary: Option Summary. (line 510) 6216* mtime: override. (line 30) 6217* mtime, summary: Option Summary. (line 517) 6218* multi-volume: Multi-Volume Archives. 6219 (line 6) 6220* multi-volume, short description: Device. (line 88) 6221* multi-volume, summary: Option Summary. (line 532) 6222* new-volume-script: Multi-Volume Archives. 6223 (line 83) 6224* new-volume-script, short description: Device. (line 121) 6225* new-volume-script, summary: Option Summary. (line 423) 6226* new-volume-script, summary <1>: Option Summary. (line 538) 6227* newer: after. (line 24) 6228* newer, summary: Option Summary. (line 542) 6229* newer-mtime: after. (line 35) 6230* newer-mtime, summary: Option Summary. (line 551) 6231* no-acls, summary: Option Summary. (line 557) 6232* no-anchored: controlling pattern-matching. 6233 (line 78) 6234* no-anchored, summary: Option Summary. (line 561) 6235* no-auto-compress, summary: Option Summary. (line 565) 6236* no-check-device, described: Incremental Dumps. (line 103) 6237* no-check-device, summary: Option Summary. (line 570) 6238* no-delay-directory-restore: Directory Modification Times and Permissions. 6239 (line 68) 6240* no-delay-directory-restore, summary: Option Summary. (line 575) 6241* no-ignore-case: controlling pattern-matching. 6242 (line 85) 6243* no-ignore-case, summary: Option Summary. (line 581) 6244* no-ignore-command-error: Writing to an External Program. 6245 (line 116) 6246* no-ignore-command-error, summary: Option Summary. (line 584) 6247* no-null, described: nul. (line 15) 6248* no-null, summary: Option Summary. (line 588) 6249* no-overwrite-dir, summary: Option Summary. (line 594) 6250* no-quote-chars, summary: Option Summary. (line 599) 6251* no-recursion: recurse. (line 11) 6252* no-recursion, summary: Option Summary. (line 604) 6253* no-same-owner: Attributes. (line 63) 6254* no-same-owner, summary: Option Summary. (line 609) 6255* no-same-permissions, summary: Option Summary. (line 616) 6256* no-seek, summary: Option Summary. (line 622) 6257* no-selinux, summary: Option Summary. (line 628) 6258* no-unquote: Selecting Archive Members. 6259 (line 42) 6260* no-unquote, summary: Option Summary. (line 632) 6261* no-verbatim-files-from: files. (line 79) 6262* no-verbatim-files-from, summary: Option Summary. (line 636) 6263* no-wildcards: controlling pattern-matching. 6264 (line 41) 6265* no-wildcards, summary: Option Summary. (line 650) 6266* no-wildcards-match-slash: controlling pattern-matching. 6267 (line 91) 6268* no-wildcards-match-slash, summary: Option Summary. (line 653) 6269* no-xattrs, summary: Option Summary. (line 656) 6270* null, described: nul. (line 11) 6271* null, summary: Option Summary. (line 660) 6272* numeric-owner: Attributes. (line 69) 6273* numeric-owner, summary: Option Summary. (line 673) 6274* occurrence, described: append. (line 34) 6275* occurrence, summary: Option Summary. (line 691) 6276* old-archive, summary: Option Summary. (line 706) 6277* one-file-system: one. (line 14) 6278* one-file-system, summary: Option Summary. (line 709) 6279* one-top-level, summary: Option Summary. (line 714) 6280* overwrite: Overwrite Old Files. 6281 (line 6) 6282* overwrite, introduced: Dealing with Old Files. 6283 (line 32) 6284* overwrite, summary: Option Summary. (line 725) 6285* overwrite-dir: Overwrite Old Files. 6286 (line 28) 6287* overwrite-dir, introduced: Dealing with Old Files. 6288 (line 6) 6289* overwrite-dir, summary: Option Summary. (line 730) 6290* owner: override. (line 67) 6291* owner, summary: Option Summary. (line 735) 6292* owner-map, summary: Option Summary. (line 745) 6293* pax-option: PAX keywords. (line 6) 6294* pax-option, summary: Option Summary. (line 755) 6295* portability, summary: Option Summary. (line 761) 6296* posix, summary: Option Summary. (line 765) 6297* preserve-order: Same Order. (line 6) 6298* preserve-order, summary: Option Summary. (line 768) 6299* preserve-permissions: Setting Access Permissions. 6300 (line 10) 6301* preserve-permissions, short description: Attributes. (line 109) 6302* preserve-permissions, summary: Option Summary. (line 772) 6303* quote-chars, summary: Option Summary. (line 783) 6304* quoting-style: quoting styles. (line 36) 6305* quoting-style, summary: Option Summary. (line 787) 6306* read-full-records: Reading. (line 6) 6307* read-full-records <1>: read full records. (line 6) 6308* read-full-records, short description: Blocking Factor. (line 168) 6309* read-full-records, summary: Option Summary. (line 794) 6310* record-size, summary: Option Summary. (line 800) 6311* recursion: recurse. (line 22) 6312* recursion, summary: Option Summary. (line 808) 6313* recursive-unlink: Recursive Unlink. (line 6) 6314* recursive-unlink, summary: Option Summary. (line 813) 6315* remove-files: remove files. (line 6) 6316* remove-files, summary: Option Summary. (line 818) 6317* restrict, summary: Option Summary. (line 823) 6318* rmt-command, summary: Option Summary. (line 829) 6319* rsh-command: Device. (line 73) 6320* rsh-command, summary: Option Summary. (line 834) 6321* same-order: Same Order. (line 6) 6322* same-order, summary: Option Summary. (line 839) 6323* same-owner: Attributes. (line 44) 6324* same-owner, summary: Option Summary. (line 848) 6325* same-permissions: Setting Access Permissions. 6326 (line 10) 6327* same-permissions, short description: Attributes. (line 109) 6328* same-permissions, summary: Option Summary. (line 772) 6329* same-permissions, summary <1>: Option Summary. (line 855) 6330* seek, summary: Option Summary. (line 859) 6331* selinux, summary: Option Summary. (line 869) 6332* show-defaults: defaults. (line 6) 6333* show-defaults, summary: Option Summary. (line 873) 6334* show-omitted-dirs: verbose. (line 105) 6335* show-omitted-dirs, summary: Option Summary. (line 886) 6336* show-snapshot-field-ranges: Snapshot Files. (line 111) 6337* show-snapshot-field-ranges, summary: Option Summary. (line 891) 6338* show-stored-names: list. (line 68) 6339* show-stored-names, summary: Option Summary. (line 897) 6340* show-transformed-names: transform. (line 45) 6341* show-transformed-names, summary: Option Summary. (line 897) 6342* skip-old-files, introduced: Dealing with Old Files. 6343 (line 28) 6344* skip-old-files, summary: Option Summary. (line 906) 6345* sort, summary: Option Summary. (line 919) 6346* sparse: sparse. (line 24) 6347* sparse, summary: Option Summary. (line 936) 6348* sparse-version: sparse. (line 59) 6349* sparse-version, summary: Option Summary. (line 942) 6350* starting-file: Starting File. (line 6) 6351* starting-file, summary: Option Summary. (line 948) 6352* strip-components: transform. (line 25) 6353* strip-components, summary: Option Summary. (line 955) 6354* suffix: backup. (line 67) 6355* suffix, summary: Option Summary. (line 966) 6356* tape-length: Multi-Volume Archives. 6357 (line 33) 6358* tape-length, short description: Device. (line 96) 6359* tape-length, summary: Option Summary. (line 971) 6360* test-label: label. (line 35) 6361* test-label, summary: Option Summary. (line 982) 6362* to-command: Writing to an External Program. 6363 (line 9) 6364* to-command, summary: Option Summary. (line 987) 6365* to-stdout: Writing to Standard Output. 6366 (line 14) 6367* to-stdout, summary: Option Summary. (line 992) 6368* totals: verbose. (line 45) 6369* totals, summary: Option Summary. (line 998) 6370* touch: Data Modification Times. 6371 (line 15) 6372* touch <1>: Attributes. (line 33) 6373* touch, summary: Option Summary. (line 1004) 6374* transform: transform. (line 74) 6375* transform, summary: Option Summary. (line 1011) 6376* uncompress: gzip. (line 124) 6377* uncompress, summary: Option Summary. (line 170) 6378* uncompress, summary <1>: Option Summary. (line 1025) 6379* ungzip: gzip. (line 99) 6380* ungzip, summary: Option Summary. (line 366) 6381* ungzip, summary <1>: Option Summary. (line 1029) 6382* unlink-first: Unlink First. (line 6) 6383* unlink-first, introduced: Dealing with Old Files. 6384 (line 51) 6385* unlink-first, summary: Option Summary. (line 1033) 6386* unquote: Selecting Archive Members. 6387 (line 39) 6388* unquote, summary: Option Summary. (line 1039) 6389* update: update. (line 6) 6390* update <1>: how to update. (line 6) 6391* update, summary: Operation Summary. (line 60) 6392* usage: help. (line 53) 6393* use-compress-program: gzip. (line 185) 6394* use-compress-program, summary: Option Summary. (line 1043) 6395* utc, summary: Option Summary. (line 1049) 6396* verbatim-files-from: files. (line 74) 6397* verbatim-files-from, summary: Option Summary. (line 1054) 6398* verbose: verbose. (line 18) 6399* verbose, introduced: verbose tutorial. (line 6) 6400* verbose, summary: Option Summary. (line 1076) 6401* verbose, using with --create: create verbose. (line 6) 6402* verbose, using with --list: list. (line 34) 6403* verify, short description: verify. (line 8) 6404* verify, summary: Option Summary. (line 1084) 6405* verify, using with --create: verify. (line 24) 6406* version: help. (line 6) 6407* version, summary: Option Summary. (line 1090) 6408* volno-file: Multi-Volume Archives. 6409 (line 74) 6410* volno-file, summary: Option Summary. (line 1096) 6411* warning, explained: warnings. (line 12) 6412* warning, summary: Option Summary. (line 1102) 6413* wildcards: controlling pattern-matching. 6414 (line 38) 6415* wildcards, summary: Option Summary. (line 1108) 6416* wildcards-match-slash: controlling pattern-matching. 6417 (line 91) 6418* wildcards-match-slash, summary: Option Summary. (line 1112) 6419* xattrs, summary: Option Summary. (line 1115) 6420* xattrs-exclude, summary: Option Summary. (line 1119) 6421* xattrs-include, summary: Option Summary. (line 1123) 6422* xform: transform. (line 74) 6423* xform, summary: Option Summary. (line 1011) 6424* xz: gzip. (line 104) 6425* xz, summary: Option Summary. (line 1129) 6426* zstd: gzip. (line 121) 6427 6428 6429File: tar.info, Node: Index, Prev: Index of Command Line Options, Up: Top 6430 6431Appendix I Index 6432**************** 6433 6434[index] 6435* Menu: 6436 6437* %s: Directory has been renamed from %s, warning message: warnings. 6438 (line 100) 6439* %s: Directory has been renamed, warning message: warnings. (line 100) 6440* %s: Directory is new, warning message: warnings. (line 102) 6441* %s: directory is on a different device: not purging, warning message: warnings. 6442 (line 104) 6443* %s: skipping existing file, warning message: warnings. (line 66) 6444* -after-date and -update compared: after. (line 19) 6445* -newer-mtime and -update compared: after. (line 19) 6446* -quite, option: Generate Mode. (line 120) 6447* .bzrignore: exclude. (line 63) 6448* .cvsignore: exclude. (line 50) 6449* .gitignore: exclude. (line 55) 6450* .hgignore: exclude. (line 70) 6451* A lone zero block at, warning message: warnings. (line 33) 6452* abbreviations for months: Calendar date items. (line 36) 6453* absolute file names: absolute. (line 6) 6454* absolute file names <1>: Remote Tape Server. (line 17) 6455* Adding archives to an archive: concatenate. (line 6) 6456* Adding files to an Archive: appending files. (line 6) 6457* ADMINISTRATOR: General-Purpose Variables. 6458 (line 6) 6459* Age, excluding files by: after. (line 6) 6460* ago in date strings: Relative items in date strings. 6461 (line 23) 6462* all: warnings. (line 28) 6463* alone-zero-block: warnings. (line 33) 6464* alternative decompression programs: gzip. (line 62) 6465* am in date strings: Time of day items. (line 21) 6466* Appending files to an Archive: appending files. (line 6) 6467* appending files to existing archive: append. (line 6) 6468* Arch, excluding files: exclude. (line 85) 6469* archive: Definitions. (line 6) 6470* Archive creation: file. (line 34) 6471* archive member: Definitions. (line 15) 6472* Archive Name: file. (line 6) 6473* Archive, creation of: create. (line 6) 6474* Archives, Appending files to: appending files. (line 6) 6475* archives, binary equivalent: PAX keywords. (line 148) 6476* Archiving Directories: create dir. (line 6) 6477* archiving files: Top. (line 23) 6478* ARGP_HELP_FMT, environment variable: Configuring Help Summary. 6479 (line 21) 6480* arguments to long options: Long Options. (line 31) 6481* arguments to old options: Old Options. (line 26) 6482* arguments to short options: Short Options. (line 13) 6483* Attempting extraction of symbolic links as hard links, warning message: warnings. 6484 (line 72) 6485* attributes, files: Attributes. (line 6) 6486* authors of parse_datetime: Authors of parse_datetime. 6487 (line 6) 6488* Avoiding recursion in directories: recurse. (line 6) 6489* backup options: backup. (line 6) 6490* backup suffix: backup. (line 67) 6491* backups: backup. (line 41) 6492* backups <1>: Backups. (line 6) 6493* BACKUP_DIRS: General-Purpose Variables. 6494 (line 30) 6495* BACKUP_FILES: General-Purpose Variables. 6496 (line 58) 6497* BACKUP_HOUR: General-Purpose Variables. 6498 (line 10) 6499* bad-dumpdir: warnings. (line 106) 6500* basic operations: Operations. (line 6) 6501* Bazaar, excluding files: exclude. (line 85) 6502* Bazaar, ignore files: exclude. (line 37) 6503* beginning of time, for POSIX: Seconds since the Epoch. 6504 (line 13) 6505* bell, checkpoint action: checkpoints. (line 106) 6506* Bellovin, Steven M.: Authors of parse_datetime. 6507 (line 6) 6508* Berets, Jim: Authors of parse_datetime. 6509 (line 6) 6510* Berry, K.: Authors of parse_datetime. 6511 (line 19) 6512* binary equivalent archives, creating: PAX keywords. (line 148) 6513* block: Blocking. (line 6) 6514* Block number where error occurred: verbose. (line 112) 6515* BLOCKING: General-Purpose Variables. 6516 (line 25) 6517* Blocking Factor: Blocking Factor. (line 6) 6518* blocking factor: Blocking Factor. (line 189) 6519* Blocks per record: Blocking Factor. (line 6) 6520* bug reports: Reports. (line 6) 6521* Bytes per record: Blocking Factor. (line 6) 6522* bzip2: gzip. (line 6) 6523* cachedir: warnings. (line 40) 6524* calendar date item: Calendar date items. (line 6) 6525* case, ignored in dates: General date syntax. (line 60) 6526* cat vs concatenate: concatenate. (line 63) 6527* Changing directory mid-stream: directory. (line 6) 6528* Character class, excluding characters from: wildcards. (line 34) 6529* checkpoints, defined: checkpoints. (line 6) 6530* Choosing an archive file: file. (line 6) 6531* combined date and time of day item: Combined date and time of day items. 6532 (line 6) 6533* comments, in dates: General date syntax. (line 60) 6534* compress: gzip. (line 6) 6535* Compressed archives: gzip. (line 6) 6536* concatenate vs cat: concatenate. (line 63) 6537* Concatenating Archives: concatenate. (line 6) 6538* contains a cache directory tag, warning message: warnings. (line 40) 6539* contiguous-cast: warnings. (line 70) 6540* corrupted archives: Full Dumps. (line 8) 6541* corrupted archives <1>: gzip. (line 151) 6542* Creation of the archive: create. (line 6) 6543* Current %s is newer or same age, warning message: warnings. (line 76) 6544* CVS, excluding files: exclude. (line 85) 6545* CVS, ignore files: exclude. (line 37) 6546* Darcs, excluding files: exclude. (line 85) 6547* DAT blocking: Blocking Factor. (line 199) 6548* Data Modification time, excluding files by: after. (line 6) 6549* Data modification times of extracted files: Data Modification Times. 6550 (line 6) 6551* date and time of day format, ISO 8601: Combined date and time of day items. 6552 (line 6) 6553* date format, ISO 8601: Calendar date items. (line 28) 6554* date input formats: Date input formats. (line 6) 6555* day in date strings: Relative items in date strings. 6556 (line 15) 6557* day in date strings <1>: Relative items in date strings. 6558 (line 29) 6559* day of week item: Day of week items. (line 6) 6560* decompress-program: warnings. (line 80) 6561* Deleting files from an archive: delete. (line 6) 6562* Deleting from tape archives: delete. (line 17) 6563* dereferencing hard links: hard links. (line 6) 6564* Descending directories, avoiding: recurse. (line 6) 6565* Device numbers, changing: Fixing Snapshot Files. 6566 (line 6) 6567* Device numbers, using in incremental backups: Incremental Dumps. 6568 (line 89) 6569* Directories, Archiving: create dir. (line 6) 6570* Directories, avoiding recursion: recurse. (line 6) 6571* Directory, changing mid-stream: directory. (line 6) 6572* DIRLIST: General-Purpose Variables. 6573 (line 53) 6574* displacement of dates: Relative items in date strings. 6575 (line 6) 6576* doc-opt-col: Configuring Help Summary. 6577 (line 95) 6578* door ignored, warning message: warnings. (line 45) 6579* dot, checkpoint action: checkpoints. (line 130) 6580* Double-checking a write operation: verify. (line 6) 6581* dumps, full: Full Dumps. (line 8) 6582* DUMP_BEGIN: User Hooks. (line 31) 6583* DUMP_END: User Hooks. (line 35) 6584* DUMP_REMIND_SCRIPT: General-Purpose Variables. 6585 (line 112) 6586* dup-args: Configuring Help Summary. 6587 (line 52) 6588* dup-args-note: Configuring Help Summary. 6589 (line 69) 6590* echo, checkpoint action: checkpoints. (line 25) 6591* Eggert, Paul: Authors of parse_datetime. 6592 (line 6) 6593* End-of-archive blocks, ignoring: Ignore Zeros. (line 6) 6594* End-of-archive info script: Multi-Volume Archives. 6595 (line 83) 6596* entry: Naming tar Archives. (line 11) 6597* Epoch, for POSIX: Seconds since the Epoch. 6598 (line 13) 6599* Error message, block number of: verbose. (line 122) 6600* Exabyte blocking: Blocking Factor. (line 199) 6601* exclude: exclude. (line 12) 6602* exclude-caches: exclude. (line 122) 6603* exclude-from: exclude. (line 25) 6604* exclude-tag: exclude. (line 145) 6605* Excluding characters from a character class: wildcards. (line 34) 6606* Excluding file by age: after. (line 6) 6607* Excluding files by file system: exclude. (line 6) 6608* Excluding files by name and pattern: exclude. (line 6) 6609* Exec Mode, genfile: Exec Mode. (line 6) 6610* exec, checkpoint action: checkpoints. (line 166) 6611* existing backup method: backup. (line 59) 6612* existing-file: warnings. (line 66) 6613* exit status: Synopsis. (line 67) 6614* Extracting contiguous files as regular files, warning message: warnings. 6615 (line 70) 6616* extracting Nth copy of the file: append. (line 34) 6617* extraction: Definitions. (line 22) 6618* Extraction: extract. (line 6) 6619* file archival: Top. (line 23) 6620* file attributes: Attributes. (line 6) 6621* file changed as we read it, warning message: warnings. (line 55) 6622* file is on a different filesystem, warning message: warnings. 6623 (line 43) 6624* file is the archive; not dumped, warning message: warnings. (line 51) 6625* file is the archive; not dumped, warning message <1>: warnings. 6626 (line 51) 6627* file is unchanged; not dumped, warning message: warnings. (line 49) 6628* File lists separated by NUL characters: Generate Mode. (line 33) 6629* file name: Definitions. (line 15) 6630* File Name arguments, alternatives: files. (line 6) 6631* File name arguments, using --list with: list. (line 25) 6632* file name read contains nul character, warning message: warnings. 6633 (line 31) 6634* file names, absolute: absolute. (line 6) 6635* File names, excluding files by: exclude. (line 6) 6636* File names, terminated by NUL: nul. (line 6) 6637* File names, using hard links: hard links. (line 6) 6638* File names, using symbolic links: dereference. (line 6) 6639* File removed before we read it, warning message: warnings. (line 53) 6640* File shrank by %s bytes, warning message: warnings. (line 41) 6641* File system boundaries, not crossing: one. (line 6) 6642* file-changed: warnings. (line 55) 6643* file-ignored: warnings. (line 45) 6644* file-removed: warnings. (line 53) 6645* file-shrank: warnings. (line 41) 6646* file-unchanged: warnings. (line 49) 6647* FILELIST: General-Purpose Variables. 6648 (line 69) 6649* filename-with-nuls: warnings. (line 31) 6650* find, using with tar: files. (line 6) 6651* find, using with tar <1>: recurse. (line 11) 6652* first in date strings: General date syntax. (line 22) 6653* format 0, snapshot file: Snapshot Files. (line 24) 6654* format 1, snapshot file: Snapshot Files. (line 51) 6655* format 2, snapshot file: Snapshot Files. (line 73) 6656* Format Options: Format Variations. (line 6) 6657* Format Parameters: Format Variations. (line 6) 6658* Format, old style: old. (line 6) 6659* fortnight in date strings: Relative items in date strings. 6660 (line 15) 6661* full dumps: Full Dumps. (line 8) 6662* future time stamps: Large or Negative Values. 6663 (line 6) 6664* general date syntax: General date syntax. (line 6) 6665* Generate Mode, genfile: Generate Mode. (line 6) 6666* genfile: Genfile. (line 6) 6667* genfile, create file: Generate Mode. (line 6) 6668* genfile, creating sparse files: Generate Mode. (line 55) 6669* genfile, generate mode: Generate Mode. (line 6) 6670* genfile, reading a list of file names: Generate Mode. (line 22) 6671* genfile, seeking to a given offset: Generate Mode. (line 18) 6672* Getting program version number: help. (line 6) 6673* git, excluding files: exclude. (line 85) 6674* Git, ignore files: exclude. (line 37) 6675* GNU archive format: gnu. (line 6) 6676* GNU.sparse.major, extended header variable: PAX 1. (line 14) 6677* GNU.sparse.map, extended header variable: PAX 0. (line 59) 6678* GNU.sparse.minor, extended header variable: PAX 1. (line 17) 6679* GNU.sparse.name, extended header variable: PAX 0. (line 67) 6680* GNU.sparse.name, extended header variable, in v.1.0: PAX 1. (line 24) 6681* GNU.sparse.numblocks, extended header variable: PAX 0. (line 14) 6682* GNU.sparse.numbytes, extended header variable: PAX 0. (line 20) 6683* GNU.sparse.offset, extended header variable: PAX 0. (line 17) 6684* GNU.sparse.realsize, extended header variable: PAX 1. (line 24) 6685* GNU.sparse.size, extended header variable: PAX 0. (line 10) 6686* gnupg, using with tar: gzip. (line 209) 6687* gpg, using with tar: gzip. (line 209) 6688* gzip: gzip. (line 6) 6689* hard links, dereferencing: hard links. (line 6) 6690* header-col: Configuring Help Summary. 6691 (line 141) 6692* hole detection: sparse. (line 66) 6693* hook: User Hooks. (line 12) 6694* hour in date strings: Relative items in date strings. 6695 (line 15) 6696* ignore-archive: warnings. (line 51) 6697* ignore-archive <1>: warnings. (line 51) 6698* ignore-newer: warnings. (line 76) 6699* Ignoring end-of-archive blocks: Ignore Zeros. (line 6) 6700* Ignoring unknown extended header keyword '%s', warning message: warnings. 6701 (line 78) 6702* implausibly old time stamp %s, warning message: warnings. (line 67) 6703* Info script: Multi-Volume Archives. 6704 (line 83) 6705* Interactive operation: interactive. (line 6) 6706* ISO 8601 date and time of day format: Combined date and time of day items. 6707 (line 6) 6708* ISO 8601 date format: Calendar date items. (line 28) 6709* items in date strings: General date syntax. (line 6) 6710* Labeling an archive: label. (line 6) 6711* labeling archives: Tape Files. (line 6) 6712* Labeling multi-volume archives: label. (line 6) 6713* Labels on the archive media: label. (line 6) 6714* language, in dates: General date syntax. (line 36) 6715* language, in dates <1>: General date syntax. (line 40) 6716* Large lists of file names on small machines: Same Order. (line 6) 6717* large values: Large or Negative Values. 6718 (line 6) 6719* last DAY: Day of week items. (line 15) 6720* last in date strings: General date syntax. (line 22) 6721* Laszlo Ersek: lbzip2. (line 6) 6722* lbzip2: lbzip2. (line 6) 6723* leap seconds: General date syntax. (line 65) 6724* leap seconds <1>: Time of day items. (line 14) 6725* leap seconds <2>: Seconds since the Epoch. 6726 (line 27) 6727* Listing all tar options: help. (line 26) 6728* listing member and file names: list. (line 45) 6729* Listing volume label: label. (line 27) 6730* Lists of file names: files. (line 6) 6731* Local and remote archives: file. (line 70) 6732* long options: Long Options. (line 6) 6733* long options with mandatory arguments: Long Options. (line 31) 6734* long options with optional arguments: Long Options. (line 39) 6735* long-opt-col: Configuring Help Summary. 6736 (line 87) 6737* lzip: gzip. (line 6) 6738* lzma: gzip. (line 6) 6739* lzop: gzip. (line 6) 6740* MacKenzie, David: Authors of parse_datetime. 6741 (line 6) 6742* Malformed dumpdir: 'X' never used, warning message: warnings. 6743 (line 106) 6744* member: Definitions. (line 15) 6745* member name: Definitions. (line 15) 6746* members, multiple: multiple. (line 6) 6747* Members, replacing with other members: append. (line 47) 6748* Mercurial, excluding files: exclude. (line 85) 6749* Mercurial, ignore files: exclude. (line 37) 6750* Meyering, Jim: Authors of parse_datetime. 6751 (line 6) 6752* Middle of the archive, starting in the: Starting File. (line 11) 6753* midnight in date strings: Time of day items. (line 21) 6754* minute in date strings: Relative items in date strings. 6755 (line 15) 6756* minutes, time zone correction by: Time of day items. (line 29) 6757* Modes of extracted files: Setting Access Permissions. 6758 (line 6) 6759* Modification time, excluding files by: after. (line 6) 6760* Modification times of extracted files: Data Modification Times. 6761 (line 6) 6762* month in date strings: Relative items in date strings. 6763 (line 15) 6764* month names in date strings: Calendar date items. (line 36) 6765* months, written-out: General date syntax. (line 32) 6766* MT: General-Purpose Variables. 6767 (line 74) 6768* MT_BEGIN: Magnetic Tape Control. 6769 (line 10) 6770* MT_OFFLINE: Magnetic Tape Control. 6771 (line 30) 6772* MT_REWIND: Magnetic Tape Control. 6773 (line 20) 6774* MT_STATUS: Magnetic Tape Control. 6775 (line 40) 6776* Multi-volume archives: Multi-Volume Archives. 6777 (line 6) 6778* Multi-volume archives in PAX format, extracting using non-GNU tars: Split Recovery. 6779 (line 17) 6780* Multi-volume archives, extracting using non-GNU tars: Split Recovery. 6781 (line 6) 6782* multiple members: multiple. (line 6) 6783* Naming an archive: file. (line 6) 6784* negative time stamps: Large or Negative Values. 6785 (line 6) 6786* new-directory: warnings. (line 102) 6787* next DAY: Day of week items. (line 15) 6788* next in date strings: General date syntax. (line 22) 6789* none: warnings. (line 29) 6790* noon in date strings: Time of day items. (line 21) 6791* now in date strings: Relative items in date strings. 6792 (line 33) 6793* ntape device: Many. (line 6) 6794* NUL-terminated file names: nul. (line 6) 6795* Number of blocks per record: Blocking Factor. (line 6) 6796* Number of bytes per record: Blocking Factor. (line 6) 6797* numbered backup method: backup. (line 55) 6798* numbers, written-out: General date syntax. (line 22) 6799* Obtaining help: help. (line 26) 6800* Obtaining total status information: verbose. (line 45) 6801* Old GNU archive format: gnu. (line 6) 6802* Old GNU sparse format: Old GNU Format. (line 6) 6803* old option style: Old Options. (line 6) 6804* old options with mandatory arguments: Old Options. (line 26) 6805* Old style archives: old. (line 6) 6806* Old style format: old. (line 6) 6807* opt-doc-col: Configuring Help Summary. 6808 (line 127) 6809* option syntax, traditional: Old Options. (line 6) 6810* optional arguments to long options: Long Options. (line 39) 6811* optional arguments to short options: Short Options. (line 22) 6812* options for use with --extract: extract options. (line 6) 6813* Options when reading archives: Reading. (line 6) 6814* Options, archive format specifying: Format Variations. (line 6) 6815* Options, format specifying: Format Variations. (line 6) 6816* options, GNU style: Long Options. (line 6) 6817* options, long style: Long Options. (line 6) 6818* options, mixing different styles: Mixing. (line 6) 6819* options, mnemonic names: Long Options. (line 6) 6820* options, old style: Old Options. (line 6) 6821* options, short style: Short Options. (line 6) 6822* options, traditional: Short Options. (line 6) 6823* ordinal numbers: General date syntax. (line 22) 6824* Overwriting old files, prevention: Dealing with Old Files. 6825 (line 16) 6826* parse_datetime: Date input formats. (line 6) 6827* pattern, genfile: Generate Mode. (line 39) 6828* PAX archive format: posix. (line 6) 6829* Permissions of extracted files: Setting Access Permissions. 6830 (line 6) 6831* Pinard, F.: Authors of parse_datetime. 6832 (line 19) 6833* pm in date strings: Time of day items. (line 21) 6834* POSIX archive format: posix. (line 6) 6835* Progress information: verbose. (line 82) 6836* Protecting old files: Dealing with Old Files. 6837 (line 36) 6838* pure numbers in date strings: Pure numbers in date strings. 6839 (line 6) 6840* RCS, excluding files: exclude. (line 85) 6841* Reading file names from a file: files. (line 6) 6842* Reading incomplete records: Reading. (line 6) 6843* record: Blocking. (line 6) 6844* Record Size: Blocking Factor. (line 6) 6845* Record size = %lu blocks, warning message: warnings. (line 93) 6846* record-size: warnings. (line 93) 6847* Records, incomplete: Reading. (line 6) 6848* Recursion in directories, avoiding: recurse. (line 6) 6849* relative items in date strings: Relative items in date strings. 6850 (line 6) 6851* Remote devices: file. (line 60) 6852* remote tape drive: Remote Tape Server. (line 6) 6853* Removing files from an archive: delete. (line 6) 6854* rename-directory: warnings. (line 100) 6855* Replacing members with other members: append. (line 47) 6856* reporting bugs: Reports. (line 6) 6857* RESTORE_BEGIN: User Hooks. (line 38) 6858* RESTORE_END: User Hooks. (line 41) 6859* Resurrecting files from an archive: extract. (line 6) 6860* Retrieving files from an archive: extract. (line 6) 6861* return status: Synopsis. (line 67) 6862* rmargin: Configuring Help Summary. 6863 (line 159) 6864* rmt: Remote Tape Server. (line 6) 6865* RSH: General-Purpose Variables. 6866 (line 78) 6867* RSH_COMMAND: General-Purpose Variables. 6868 (line 83) 6869* Running out of space: Scarce. (line 8) 6870* Salz, Rich: Authors of parse_datetime. 6871 (line 6) 6872* SCCS, excluding files: exclude. (line 85) 6873* short options: Short Options. (line 6) 6874* short options with mandatory arguments: Short Options. (line 13) 6875* short options with optional arguments: Short Options. (line 22) 6876* short-opt-col: Configuring Help Summary. 6877 (line 79) 6878* simple backup method: backup. (line 64) 6879* SIMPLE_BACKUP_SUFFIX: backup. (line 67) 6880* sleep, checkpoint action: checkpoints. (line 145) 6881* SLEEP_MESSAGE: General-Purpose Variables. 6882 (line 121) 6883* SLEEP_TIME: General-Purpose Variables. 6884 (line 106) 6885* Small memory: Scarce. (line 8) 6886* snapshot file field ranges: Snapshot Files. (line 111) 6887* snapshot file, format 0: Snapshot Files. (line 24) 6888* snapshot file, format 1: Snapshot Files. (line 51) 6889* snapshot file, format 2: Snapshot Files. (line 73) 6890* snapshot files, editing: Fixing Snapshot Files. 6891 (line 6) 6892* snapshot files, fixing device numbers: Fixing Snapshot Files. 6893 (line 6) 6894* socket ignored, warning message: warnings. (line 45) 6895* Sparse Files: sparse. (line 6) 6896* sparse files v.0.0, extracting with non-GNU tars: Sparse Recovery. 6897 (line 92) 6898* sparse files v.0.1, extracting with non-GNU tars: Sparse Recovery. 6899 (line 92) 6900* sparse files v.1.0, extracting with non-GNU tars: Sparse Recovery. 6901 (line 17) 6902* Sparse files, creating using genfile: Generate Mode. (line 55) 6903* sparse files, extracting with non-GNU tars: Sparse Recovery. 6904 (line 6) 6905* sparse formats: Sparse Formats. (line 6) 6906* sparse formats, defined: sparse. (line 52) 6907* sparse formats, Old GNU: Old GNU Format. (line 6) 6908* sparse formats, v.0.0: PAX 0. (line 6) 6909* sparse formats, v.0.1: PAX 0. (line 51) 6910* sparse formats, v.1.0: PAX 1. (line 6) 6911* sparse versions: Sparse Formats. (line 6) 6912* Specifying archive members: Selecting Archive Members. 6913 (line 6) 6914* Specifying files to act on: Selecting Archive Members. 6915 (line 6) 6916* Standard input and output: file. (line 39) 6917* Standard output, writing extracted files to: Writing to Standard Output. 6918 (line 6) 6919* Storing archives in compressed format: gzip. (line 6) 6920* SVN, excluding files: exclude. (line 85) 6921* Symbolic link as file name: dereference. (line 6) 6922* symlink-cast: warnings. (line 72) 6923* TAPE: file tutorial. (line 14) 6924* tape blocking: Blocking Factor. (line 189) 6925* tape marks: Many. (line 43) 6926* tape positioning: Many. (line 26) 6927* Tapes, using --delete and: delete. (line 17) 6928* TAPE_FILE: General-Purpose Variables. 6929 (line 18) 6930* tar: What tar Does. (line 6) 6931* TAR: General-Purpose Variables. 6932 (line 126) 6933* tar archive: Definitions. (line 6) 6934* Tar archive formats: Formats. (line 6) 6935* tar entry: Naming tar Archives. (line 11) 6936* tar file: Naming tar Archives. (line 11) 6937* tar to a remote device: file. (line 60) 6938* tar to standard input and output: file. (line 39) 6939* tar-snapshot-edit: Fixing Snapshot Files. 6940 (line 17) 6941* tarcat: Tarcat. (line 6) 6942* TAR_ARCHIVE, checkpoint script environment: checkpoints. (line 182) 6943* TAR_ARCHIVE, info script environment variable: Multi-Volume Archives. 6944 (line 105) 6945* TAR_ARCHIVE, to-command environment: Writing to an External Program. 6946 (line 79) 6947* TAR_ATIME, to-command environment: Writing to an External Program. 6948 (line 52) 6949* TAR_BLOCKING_FACTOR, checkpoint script environment: checkpoints. 6950 (line 185) 6951* TAR_BLOCKING_FACTOR, info script environment variable: Multi-Volume Archives. 6952 (line 108) 6953* TAR_BLOCKING_FACTOR, to-command environment: Writing to an External Program. 6954 (line 82) 6955* TAR_CHECKPOINT, checkpoint script environment: checkpoints. (line 188) 6956* TAR_CTIME, to-command environment: Writing to an External Program. 6957 (line 61) 6958* TAR_FD, info script environment variable: Multi-Volume Archives. 6959 (line 122) 6960* TAR_FILENAME, to-command environment: Writing to an External Program. 6961 (line 40) 6962* TAR_FILETYPE, to-command environment: Writing to an External Program. 6963 (line 24) 6964* TAR_FORMAT, checkpoint script environment: checkpoints. (line 195) 6965* TAR_FORMAT, info script environment variable: Multi-Volume Archives. 6966 (line 118) 6967* TAR_FORMAT, to-command environment: Writing to an External Program. 6968 (line 88) 6969* TAR_GID, to-command environment: Writing to an External Program. 6970 (line 70) 6971* TAR_GNAME, to-command environment: Writing to an External Program. 6972 (line 49) 6973* TAR_MODE, to-command environment: Writing to an External Program. 6974 (line 37) 6975* TAR_MTIME, to-command environment: Writing to an External Program. 6976 (line 58) 6977* TAR_OPTIONS, environment variable: using tar options. (line 30) 6978* TAR_REALNAME, to-command environment: Writing to an External Program. 6979 (line 43) 6980* TAR_SIZE, to-command environment: Writing to an External Program. 6981 (line 64) 6982* TAR_SUBCOMMAND, checkpoint script environment: checkpoints. (line 191) 6983* TAR_SUBCOMMAND, info script environment variable: Multi-Volume Archives. 6984 (line 114) 6985* TAR_UID, to-command environment: Writing to an External Program. 6986 (line 67) 6987* TAR_UNAME, to-command environment: Writing to an External Program. 6988 (line 46) 6989* TAR_VERSION, checkpoint script environment: checkpoints. (line 179) 6990* TAR_VERSION, info script environment variable: Multi-Volume Archives. 6991 (line 102) 6992* TAR_VERSION, to-command environment: Writing to an External Program. 6993 (line 76) 6994* TAR_VOLUME, info script environment variable: Multi-Volume Archives. 6995 (line 111) 6996* TAR_VOLUME, to-command environment: Writing to an External Program. 6997 (line 85) 6998* this in date strings: Relative items in date strings. 6999 (line 33) 7000* time of day item: Time of day items. (line 6) 7001* time stamp %s is %s s in the future, warning message: warnings. 7002 (line 67) 7003* time zone correction: Time of day items. (line 29) 7004* time zone item: General date syntax. (line 40) 7005* time zone item <1>: Time zone items. (line 6) 7006* timestamp: warnings. (line 67) 7007* today in date strings: Relative items in date strings. 7008 (line 33) 7009* tomorrow in date strings: Relative items in date strings. 7010 (line 29) 7011* totals, checkpoint action: checkpoints. (line 140) 7012* ttyout, checkpoint action: checkpoints. (line 111) 7013* TZ: Specifying time zone rules. 7014 (line 6) 7015* Ultrix 3.1 and write failure: Remote Tape Server. (line 40) 7016* Unknown file type '%c', extracted as normal file, warning message: warnings. 7017 (line 74) 7018* Unknown file type; file ignored, warning message: warnings. (line 45) 7019* unknown-cast: warnings. (line 74) 7020* unknown-keyword: warnings. (line 78) 7021* unpacking: Definitions. (line 22) 7022* Updating an archive: update. (line 6) 7023* usage-indent: Configuring Help Summary. 7024 (line 155) 7025* Using encrypted archives: gzip. (line 209) 7026* ustar archive format: ustar. (line 6) 7027* v7 archive format: old. (line 6) 7028* VCS, excluding files: exclude. (line 85) 7029* VCS, excluding patterns from ignore files: exclude. (line 37) 7030* VCS, ignore files: exclude. (line 37) 7031* Verbose operation: verbose. (line 18) 7032* Verifying a write operation: verify. (line 6) 7033* Verifying the currency of an archive: compare. (line 6) 7034* version control system, excluding files: exclude. (line 85) 7035* Version of the tar program: help. (line 6) 7036* version-control Emacs variable: backup. (line 49) 7037* VERSION_CONTROL: backup. (line 41) 7038* volno file: Multi-Volume Archives. 7039 (line 74) 7040* VOLNO_FILE: General-Purpose Variables. 7041 (line 89) 7042* Volume label, listing: label. (line 27) 7043* Volume number file: Multi-Volume Archives. 7044 (line 74) 7045* wait, checkpoint action: checkpoints. (line 151) 7046* week in date strings: Relative items in date strings. 7047 (line 15) 7048* Where is the archive?: file. (line 6) 7049* Working directory, specifying: directory. (line 6) 7050* Writing extracted files to standard output: Writing to Standard Output. 7051 (line 6) 7052* Writing new archives: file. (line 34) 7053* xdev: warnings. (line 43) 7054* xdev <1>: warnings. (line 104) 7055* XLIST: General-Purpose Variables. 7056 (line 95) 7057* xsparse: Sparse Recovery. (line 13) 7058* year in date strings: Relative items in date strings. 7059 (line 15) 7060* yesterday in date strings: Relative items in date strings. 7061 (line 29) 7062* zstd: gzip. (line 6) 7063 7064