1This is tar.info, produced by makeinfo version 4.8 from tar.texi. 2 3 This manual is for GNU `tar' (version 1.17, 8 June 2007), which 4creates and extracts files from archives. 5 6 Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003, 72004, 2005, 2006, 2007 Free Software 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.1 or any later version published by the Free Software 12 Foundation; with no Invariant Sections, with the Front-Cover Texts 13 being "A GNU Manual," and with the Back-Cover Texts as in (a) 14 below. A copy of the license is included in the section entitled 15 "GNU Free Documentation License". 16 17 (a) The FSF's Back-Cover Text is: "You are free to copy and modify 18 this GNU Manual. Buying copies from GNU Press supports the FSF in 19 developing GNU and promoting software freedom." 20 21INFO-DIR-SECTION Archiving 22START-INFO-DIR-ENTRY 23* Tar: (tar). Making tape (or disk) archives. 24END-INFO-DIR-ENTRY 25 26INFO-DIR-SECTION Individual utilities 27START-INFO-DIR-ENTRY 28* tar: (tar)tar invocation. Invoking GNU `tar'. 29END-INFO-DIR-ENTRY 30 31 32File: tar.info, Node: Portability, Next: cpio, Prev: Attributes, Up: Formats 33 348.3 Making `tar' Archives More Portable 35======================================= 36 37Creating a `tar' archive on a particular system that is meant to be 38useful later on many other machines and with other versions of `tar' is 39more challenging than you might think. `tar' archive formats have been 40evolving since the first versions of Unix. Many such formats are 41around, and are not always compatible with each other. This section 42discusses a few problems, and gives some advice about making `tar' 43archives more portable. 44 45 One golden rule is simplicity. For example, limit your `tar' 46archives to contain only regular files and directories, avoiding other 47kind of special files. Do not attempt to save sparse files or 48contiguous files as such. Let's discuss a few more problems, in turn. 49 50* Menu: 51 52* Portable Names:: Portable Names 53* dereference:: Symbolic Links 54* old:: Old V7 Archives 55* ustar:: Ustar Archives 56* gnu:: GNU and old GNU format archives. 57* posix:: POSIX archives 58* Checksumming:: Checksumming Problems 59* Large or Negative Values:: Large files, negative time stamps, etc. 60* Other Tars:: How to Extract GNU-Specific Data Using 61 Other `tar' Implementations 62 63 64File: tar.info, Node: Portable Names, Next: dereference, Up: Portability 65 668.3.1 Portable Names 67-------------------- 68 69Use portable file and member names. A name is portable if it contains 70only ASCII letters and digits, `/', `.', `_', and `-'; it cannot be 71empty, start with `-' or `//', or contain `/-'. Avoid deep directory 72nesting. For portability to old Unix hosts, limit your file name 73components to 14 characters or less. 74 75 If you intend to have your `tar' archives to be read under MSDOS, 76you should not rely on case distinction for file names, and you might 77use the GNU `doschk' program for helping you further diagnosing illegal 78MSDOS names, which are even more limited than System V's. 79 80 81File: tar.info, Node: dereference, Next: old, Prev: Portable Names, Up: Portability 82 838.3.2 Symbolic Links 84-------------------- 85 86Normally, when `tar' archives a symbolic link, it writes a block to the 87archive naming the target of the link. In that way, the `tar' archive 88is a faithful record of the file system contents. `--dereference' 89(`-h') is used with `--create' (`-c'), and causes `tar' to archive the 90files symbolic links point to, instead of the links themselves. When 91this option is used, when `tar' encounters a symbolic link, it will 92archive the linked-to file, instead of simply recording the presence of 93a symbolic link. 94 95 The name under which the file is stored in the file system is not 96recorded in the archive. To record both the symbolic link name and the 97file name in the system, archive the file under both names. If all 98links were recorded automatically by `tar', an extracted file might be 99linked to a file name that no longer exists in the file system. 100 101 If a linked-to file is encountered again by `tar' while creating the 102same archive, an entire second copy of it will be stored. (This 103_might_ be considered a bug.) 104 105 So, for portable archives, do not archive symbolic links as such, 106and use `--dereference' (`-h'): many systems do not support symbolic 107links, and moreover, your distribution might be unusable if it contains 108unresolved symbolic links. 109 110 111File: tar.info, Node: old, Next: ustar, Prev: dereference, Up: Portability 112 1138.3.3 Old V7 Archives 114--------------------- 115 116Certain old versions of `tar' cannot handle additional information 117recorded by newer `tar' programs. To create an archive in V7 format 118(not ANSI), which can be read by these old versions, specify the 119`--format=v7' option in conjunction with the `--create' (`-c') (`tar' 120also accepts `--portability' or `--old-archive' for this option). When 121you specify it, `tar' leaves out information about directories, pipes, 122fifos, contiguous files, and device files, and specifies file ownership 123by group and user IDs instead of group and user names. 124 125 When updating an archive, do not use `--format=v7' unless the 126archive was created using this option. 127 128 In most cases, a _new_ format archive can be read by an _old_ `tar' 129program without serious trouble, so this option should seldom be 130needed. On the other hand, most modern `tar's are able to read old 131format archives, so it might be safer for you to always use 132`--format=v7' for your distributions. Notice, however, that `ustar' 133format is a better alternative, as it is free from many of `v7''s 134drawbacks. 135 136 137File: tar.info, Node: ustar, Next: gnu, Prev: old, Up: Portability 138 1398.3.4 Ustar Archive Format 140-------------------------- 141 142Archive format defined by POSIX.1-1988 specification is called `ustar'. 143Although it is more flexible than the V7 format, it still has many 144restrictions (*Note ustar: Formats, for the detailed description of 145`ustar' format). Along with V7 format, `ustar' format is a good choice 146for archives intended to be read with other implementations of `tar'. 147 148 To create archive in `ustar' format, use `--format=ustar' option in 149conjunction with the `--create' (`-c'). 150 151 152File: tar.info, Node: gnu, Next: posix, Prev: ustar, Up: Portability 153 1548.3.5 GNU and old GNU `tar' format 155---------------------------------- 156 157GNU `tar' was based on an early draft of the POSIX 1003.1 `ustar' 158standard. GNU extensions to `tar', such as the support for file names 159longer than 100 characters, use portions of the `tar' header record 160which were specified in that POSIX draft as unused. Subsequent changes 161in POSIX have allocated the same parts of the header record for other 162purposes. As a result, GNU `tar' format is incompatible with the 163current POSIX specification, and with `tar' programs that follow it. 164 165 In the majority of cases, `tar' will be configured to create this 166format by default. This will change in future releases, since we plan 167to make `POSIX' format the default. 168 169 To force creation a GNU `tar' archive, use option `--format=gnu'. 170 171 172File: tar.info, Node: posix, Next: Checksumming, Prev: gnu, Up: Portability 173 1748.3.6 GNU `tar' and POSIX `tar' 175------------------------------- 176 177Starting from version 1.14 GNU `tar' features full support for 178POSIX.1-2001 archives. 179 180 A POSIX conformant archive will be created if `tar' was given 181`--format=posix' (`--format=pax') option. No special option is 182required to read and extract from a POSIX archive. 183 184* Menu: 185 186* PAX keywords:: Controlling Extended Header Keywords. 187 188 189File: tar.info, Node: PAX keywords, Up: posix 190 1918.3.6.1 Controlling Extended Header Keywords 192............................................ 193 194`--pax-option=KEYWORD-LIST' 195 Handle keywords in PAX extended headers. This option is 196 equivalent to `-o' option of the `pax' utility. 197 198 KEYWORD-LIST is a comma-separated list of keyword options, each 199keyword option taking one of the following forms: 200 201`delete=PATTERN' 202 When used with one of archive-creation commands, this option 203 instructs `tar' to omit from extended header records that it 204 produces any keywords matching the string PATTERN. 205 206 When used in extract or list mode, this option instructs tar to 207 ignore any keywords matching the given PATTERN in the extended 208 header records. In both cases, matching is performed using the 209 pattern matching notation described in POSIX 1003.2, 3.13 (*note 210 wildcards::). For example: 211 212 --pax-option delete=security.* 213 214 would suppress security-related information. 215 216`exthdr.name=STRING' 217 This keyword allows user control over the name that is written 218 into the ustar header blocks for the extended headers. The name 219 is obtained from STRING after making the following substitutions: 220 221 Meta-character Replaced By 222 -------------------------------------------------------- 223 %d The directory name of the file, 224 equivalent to the result of the 225 `dirname' utility on the translated 226 file name. 227 %f The name of the file with the 228 directory information stripped, 229 equivalent to the result of the 230 `basename' utility on the translated 231 file name. 232 %p The process ID of the `tar' process. 233 %% A `%' character. 234 235 Any other `%' characters in STRING produce undefined results. 236 237 If no option `exthdr.name=string' is specified, `tar' will use the 238 following default value: 239 240 %d/PaxHeaders.%p/%f 241 242`globexthdr.name=STRING' 243 This keyword allows user control over the name that is written into 244 the ustar header blocks for global extended header records. The 245 name is obtained from the contents of STRING, after making the 246 following substitutions: 247 248 Meta-character Replaced By 249 -------------------------------------------------------- 250 %n An integer that represents the 251 sequence number of the global 252 extended header record in the 253 archive, starting at 1. 254 %p The process ID of the `tar' process. 255 %% A `%' character. 256 257 Any other `%' characters in STRING produce undefined results. 258 259 If no option `globexthdr.name=string' is specified, `tar' will use 260 the following default value: 261 262 $TMPDIR/GlobalHead.%p.%n 263 264 where `$TMPDIR' represents the value of the TMPDIR environment 265 variable. If TMPDIR is not set, `tar' uses `/tmp'. 266 267`KEYWORD=VALUE' 268 When used with one of archive-creation commands, these 269 keyword/value pairs will be included at the beginning of the 270 archive in a global extended header record. When used with one of 271 archive-reading commands, `tar' will behave as if it has 272 encountered these keyword/value pairs at the beginning of the 273 archive in a global extended header record. 274 275`KEYWORD:=VALUE' 276 When used with one of archive-creation commands, these 277 keyword/value pairs will be included as records at the beginning 278 of an extended header for each file. This is effectively 279 equivalent to KEYWORD=VALUE form except that it creates no global 280 extended header records. 281 282 When used with one of archive-reading commands, `tar' will behave 283 as if these keyword/value pairs were included as records at the 284 end of each extended header; thus, they will override any global or 285 file-specific extended header record keywords of the same names. 286 For example, in the command: 287 288 tar --format=posix --create \ 289 --file archive --pax-option gname:=user . 290 291 the group name will be forced to a new value for all files stored 292 in the archive. 293 294 295File: tar.info, Node: Checksumming, Next: Large or Negative Values, Prev: posix, Up: Portability 296 2978.3.7 Checksumming Problems 298--------------------------- 299 300SunOS and HP-UX `tar' fail to accept archives created using GNU `tar' 301and containing non-ASCII file names, that is, file names having 302characters with the eight bit set, because they use signed checksums, 303while GNU `tar' uses unsigned checksums while creating archives, as per 304POSIX standards. On reading, GNU `tar' computes both checksums and 305accept any. It is somewhat worrying that a lot of people may go around 306doing backup of their files using faulty (or at least non-standard) 307software, not learning about it until it's time to restore their 308missing files with an incompatible file extractor, or vice versa. 309 310 GNU `tar' compute checksums both ways, and accept any on read, so 311GNU tar can read Sun tapes even with their wrong checksums. GNU `tar' 312produces the standard checksum, however, raising incompatibilities with 313Sun. That is to say, GNU `tar' has not been modified to _produce_ 314incorrect archives to be read by buggy `tar''s. I've been told that 315more recent Sun `tar' now read standard archives, so maybe Sun did a 316similar patch, after all? 317 318 The story seems to be that when Sun first imported `tar' sources on 319their system, they recompiled it without realizing that the checksums 320were computed differently, because of a change in the default signing 321of `char''s in their compiler. So they started computing checksums 322wrongly. When they later realized their mistake, they merely decided 323to stay compatible with it, and with themselves afterwards. 324Presumably, but I do not really know, HP-UX has chosen that their `tar' 325archives to be compatible with Sun's. The current standards do not 326favor Sun `tar' format. In any case, it now falls on the shoulders of 327SunOS and HP-UX users to get a `tar' able to read the good archives 328they receive. 329 330 331File: tar.info, Node: Large or Negative Values, Next: Other Tars, Prev: Checksumming, Up: Portability 332 3338.3.8 Large or Negative Values 334------------------------------ 335 336 _(This message will disappear, once this node revised.)_ 337 338The above sections suggest to use `oldest possible' archive format if 339in doubt. However, sometimes it is not possible. If you attempt to 340archive a file whose metadata cannot be represented using required 341format, GNU `tar' will print error message and ignore such a file. You 342will than have to switch to a format that is able to handle such 343values. The format summary table (*note Formats::) will help you to do 344so. 345 346 In particular, when trying to archive files larger than 8GB or with 347timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16 34812:56:31 UTC, you will have to chose between GNU and POSIX archive 349formats. When considering which format to choose, bear in mind that 350the GNU format uses two's-complement base-256 notation to store values 351that do not fit into standard ustar range. Such archives can generally 352be read only by a GNU `tar' implementation. Moreover, they sometimes 353cannot be correctly restored on another hosts even by GNU `tar'. For 354example, using two's complement representation for negative time stamps 355that assumes a signed 32-bit `time_t' generates archives that are not 356portable to hosts with differing `time_t' representations. 357 358 On the other hand, POSIX archives, generally speaking, can be 359extracted by any tar implementation that understands older ustar 360format. The only exception are files larger than 8GB. 361 362 363File: tar.info, Node: Other Tars, Prev: Large or Negative Values, Up: Portability 364 3658.3.9 How to Extract GNU-Specific Data Using Other `tar' Implementations 366------------------------------------------------------------------------ 367 368In previous sections you became acquainted with various quirks 369necessary to make your archives portable. Sometimes you may need to 370extract archives containing GNU-specific members using some third-party 371`tar' implementation or an older version of GNU `tar'. Of course your 372best bet is to have GNU `tar' installed, but if it is for some reason 373impossible, this section will explain how to cope without it. 374 375 When we speak about "GNU-specific" members we mean two classes of 376them: members split between the volumes of a multi-volume archive and 377sparse members. You will be able to always recover such members if the 378archive is in PAX format. In addition split members can be recovered 379from archives in old GNU format. The following subsections describe 380the required procedures in detail. 381 382* Menu: 383 384* Split Recovery:: Members Split Between Volumes 385* Sparse Recovery:: Sparse Members 386 387 388File: tar.info, Node: Split Recovery, Next: Sparse Recovery, Up: Other Tars 389 3908.3.9.1 Extracting Members Split Between Volumes 391................................................ 392 393If a member is split between several volumes of an old GNU format 394archive most third party `tar' implementation will fail to extract it. 395To extract it, use `tarcat' program (*note Tarcat::). This program is 396available from GNU `tar' home page 397(http://www.gnu.org/software/tar/utils/tarcat.html). It concatenates 398several archive volumes into a single valid archive. For example, if 399you have three volumes named from `vol-1.tar' to `vol-3.tar', you can 400do the following to extract them using a third-party `tar': 401 402 $ tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf - 403 404 You could use this approach for most (although not all) PAX format 405archives as well. However, extracting split members from a PAX archive 406is a much easier task, because PAX volumes are constructed in such a 407way that each part of a split member is extracted to a different file 408by `tar' implementations that are not aware of GNU extensions. More 409specifically, the very first part retains its original name, and all 410subsequent parts are named using the pattern: 411 412 %d/GNUFileParts.%p/%f.%n 413 414where symbols preceeded by `%' are "macro characters" that have the 415following meaning: 416 417Meta-character Replaced By 418------------------------------------------------------------ 419%d The directory name of the file, 420 equivalent to the result of the 421 `dirname' utility on its full name. 422%f The file name of the file, equivalent 423 to the result of the `basename' utility 424 on its full name. 425%p The process ID of the `tar' process that 426 created the archive. 427%n Ordinal number of this particular part. 428 429 For example, if the file `var/longfile' was split during archive 430creation between three volumes, and the creator `tar' process had 431process ID `27962', then the member names will be: 432 433 var/longfile 434 var/GNUFileParts.27962/longfile.1 435 var/GNUFileParts.27962/longfile.2 436 437 When you extract your archive using a third-party `tar', these files 438will be created on your disk, and the only thing you will need to do to 439restore your file in its original form is concatenate them in the 440proper order, for example: 441 442 $ cd var 443 $ cat GNUFileParts.27962/longfile.1 \ 444 GNUFileParts.27962/longfile.2 >> longfile 445 $ rm -f GNUFileParts.27962 446 447 Notice, that if the `tar' implementation you use supports PAX format 448archives, it will probably emit warnings about unknown keywords during 449extraction. They will look like this: 450 451 Tar file too small 452 Unknown extended header keyword 'GNU.volume.filename' ignored. 453 Unknown extended header keyword 'GNU.volume.size' ignored. 454 Unknown extended header keyword 'GNU.volume.offset' ignored. 455 456You can safely ignore these warnings. 457 458 If your `tar' implementation is not PAX-aware, you will get more 459warnings and more files generated on your disk, e.g.: 460 461 $ tar xf vol-1.tar 462 var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as 463 normal file 464 Unexpected EOF in archive 465 $ tar xf vol-2.tar 466 tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file 467 GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type 468 'x', extracted as normal file 469 470 Ignore these warnings. The `PaxHeaders.*' directories created will 471contain files with "extended header keywords" describing the extracted 472files. You can delete them, unless they describe sparse members. Read 473further to learn more about them. 474 475 476File: tar.info, Node: Sparse Recovery, Prev: Split Recovery, Up: Other Tars 477 4788.3.9.2 Extracting Sparse Members 479................................. 480 481Any `tar' implementation will be able to extract sparse members from a 482PAX archive. However, the extracted files will be "condensed", i.e., 483any zero blocks will be removed from them. When we restore such a 484condensed file to its original form, by adding zero blocks (or "holes") 485back to their original locations, we call this process "expanding" a 486compressed sparse file. 487 488 To expand a file, you will need a simple auxiliary program called 489`xsparse'. It is available in source form from GNU `tar' home page 490(http://www.gnu.org/software/tar/utils/xsparse.html). 491 492 Let's begin with archive members in "sparse format version 1.0"(1), 493which are the easiest to expand. The condensed file will contain both 494file map and file data, so no additional data will be needed to restore 495it. If the original file name was `DIR/NAME', then the condensed file 496will be named `DIR/GNUSparseFile.N/NAME', where N is a decimal 497number(2). 498 499 To expand a version 1.0 file, run `xsparse' as follows: 500 501 $ xsparse `cond-file' 502 503where `cond-file' is the name of the condensed file. The utility will 504deduce the name for the resulting expanded file using the following 505algorithm: 506 507 1. If `cond-file' does not contain any directories, `../cond-file' 508 will be used; 509 510 2. If `cond-file' has the form `DIR/T/NAME', where both T and NAME 511 are simple names, with no `/' characters in them, the output file 512 name will be `DIR/NAME'. 513 514 3. Otherwise, if `cond-file' has the form `DIR/NAME', the output file 515 name will be `NAME'. 516 517 In the unlikely case when this algorithm does not suit your needs, 518you can explicitly specify output file name as a second argument to the 519command: 520 521 $ xsparse `cond-file' `out-file' 522 523 It is often a good idea to run `xsparse' in "dry run" mode first. 524In this mode, the command does not actually expand the file, but 525verbosely lists all actions it would be taking to do so. The dry run 526mode is enabled by `-n' command line argument: 527 528 $ xsparse -n /home/gray/GNUSparseFile.6058/sparsefile 529 Reading v.1.0 sparse map 530 Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to 531 `/home/gray/sparsefile' 532 Finished dry run 533 534 To actually expand the file, you would run: 535 536 $ xsparse /home/gray/GNUSparseFile.6058/sparsefile 537 538The program behaves the same way all UNIX utilities do: it will keep 539quiet unless it has simething important to tell you (e.g. an error 540condition or something). If you wish it to produce verbose output, 541similar to that from the dry run mode, use `-v' option: 542 543 $ xsparse -v /home/gray/GNUSparseFile.6058/sparsefile 544 Reading v.1.0 sparse map 545 Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to 546 `/home/gray/sparsefile' 547 Done 548 549 Additionally, if your `tar' implementation has extracted the 550"extended headers" for this file, you can instruct `xstar' to use them 551in order to verify the integrity of the expanded file. The option `-x' 552sets the name of the extended header file to use. Continuing our 553example: 554 555 $ xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \ 556 /home/gray/GNUSparseFile.6058/sparsefile 557 Reading extended header file 558 Found variable GNU.sparse.major = 1 559 Found variable GNU.sparse.minor = 0 560 Found variable GNU.sparse.name = sparsefile 561 Found variable GNU.sparse.realsize = 217481216 562 Reading v.1.0 sparse map 563 Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to 564 `/home/gray/sparsefile' 565 Done 566 567 An "extended header" is a special `tar' archive header that precedes 568an archive member and contains a set of "variables", describing the 569member properties that cannot be stored in the standard `ustar' header. 570While optional for expanding sparse version 1.0 members, the use of 571extended headers is mandatory when expanding sparse members in older 572sparse formats: v.0.0 and v.0.1 (The sparse formats are described in 573detail in *note Sparse Formats::.) So, for these formats, the question 574is: how to obtain extended headers from the archive? 575 576 If you use a `tar' implementation that does not support PAX format, 577extended headers for each member will be extracted as a separate file. 578If we represent the member name as `DIR/NAME', then the extended header 579file will be named `DIR/PaxHeaders.N/NAME', where N is an integer 580number. 581 582 Things become more difficult if your `tar' implementation does 583support PAX headers, because in this case you will have to manually 584extract the headers. We recommend the following algorithm: 585 586 1. Consult the documentation of your `tar' implementation for an 587 option that prints "block numbers" along with the archive listing 588 (analogous to GNU `tar''s `-R' option). For example, `star' has 589 `-block-number'. 590 591 2. Obtain verbose listing using the `block number' option, and find 592 block numbers of the sparse member in question and the member 593 immediately following it. For example, running `star' on our 594 archive we obtain: 595 596 $ star -t -v -block-number -f arc.tar 597 ... 598 star: Unknown extended header keyword 'GNU.sparse.size' ignored. 599 star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored. 600 star: Unknown extended header keyword 'GNU.sparse.name' ignored. 601 star: Unknown extended header keyword 'GNU.sparse.map' ignored. 602 block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile 603 block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README 604 ... 605 606 (as usual, ignore the warnings about unknown keywords.) 607 608 3. Let SIZE be the size of the sparse member, BS be its block number 609 and BN be the block number of the next member. Compute: 610 611 N = BS - BN - SIZE/512 - 2 612 613 This number gives the size of the extended header part in tar 614 "blocks". In our example, this formula gives: `897 - 56 - 425984 615 / 512 - 2 = 7'. 616 617 4. Use `dd' to extract the headers: 618 619 dd if=ARCHIVE of=HNAME bs=512 skip=BS count=N 620 621 where ARCHIVE is the archive name, HNAME is a name of the file to 622 store the extended header in, BS and N are computed in previous 623 steps. 624 625 In our example, this command will be 626 627 $ dd if=arc.tar of=xhdr bs=512 skip=56 count=7 628 629 Finally, you can expand the condensed file, using the obtained 630header: 631 632 $ xsparse -v -x xhdr GNUSparseFile.6058/sparsefile 633 Reading extended header file 634 Found variable GNU.sparse.size = 217481216 635 Found variable GNU.sparse.numblocks = 208 636 Found variable GNU.sparse.name = sparsefile 637 Found variable GNU.sparse.map = 0,2048,1050624,2048,... 638 Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile' 639 Done 640 641 ---------- Footnotes ---------- 642 643 (1) *Note PAX 1::. 644 645 (2) technically speaking, N is a "process ID" of the `tar' process 646which created the archive (*note PAX keywords::). 647 648 649File: tar.info, Node: cpio, Prev: Portability, Up: Formats 650 6518.4 Comparison of `tar' and `cpio' 652================================== 653 654 _(This message will disappear, once this node revised.)_ 655 656The `cpio' archive formats, like `tar', do have maximum file name 657lengths. The binary and old ASCII formats have a maximum file length 658of 256, and the new ASCII and CRC ASCII formats have a max file length 659of 1024. GNU `cpio' can read and write archives with arbitrary file 660name lengths, but other `cpio' implementations may crash unexplainedly 661trying to read them. 662 663 `tar' handles symbolic links in the form in which it comes in BSD; 664`cpio' doesn't handle symbolic links in the form in which it comes in 665System V prior to SVR4, and some vendors may have added symlinks to 666their system without enhancing `cpio' to know about them. Others may 667have enhanced it in a way other than the way I did it at Sun, and which 668was adopted by AT&T (and which is, I think, also present in the `cpio' 669that Berkeley picked up from AT&T and put into a later BSD release--I 670think I gave them my changes). 671 672 (SVR4 does some funny stuff with `tar'; basically, its `cpio' can 673handle `tar' format input, and write it on output, and it probably 674handles symbolic links. They may not have bothered doing anything to 675enhance `tar' as a result.) 676 677 `cpio' handles special files; traditional `tar' doesn't. 678 679 `tar' comes with V7, System III, System V, and BSD source; `cpio' 680comes only with System III, System V, and later BSD (4.3-tahoe and 681later). 682 683 `tar''s way of handling multiple hard links to a file can handle 684file systems that support 32-bit inumbers (e.g., the BSD file system); 685`cpio's way requires you to play some games (in its "binary" format, 686i-numbers are only 16 bits, and in its "portable ASCII" format, they're 68718 bits--it would have to play games with the "file system ID" field of 688the header to make sure that the file system ID/i-number pairs of 689different files were always different), and I don't know which `cpio's, 690if any, play those games. Those that don't might get confused and 691think two files are the same file when they're not, and make hard links 692between them. 693 694 `tar's way of handling multiple hard links to a file places only one 695copy of the link on the tape, but the name attached to that copy is the 696_only_ one you can use to retrieve the file; `cpio's way puts one copy 697for every link, but you can retrieve it using any of the names. 698 699 What type of check sum (if any) is used, and how is this 700 calculated. 701 702 See the attached manual pages for `tar' and `cpio' format. `tar' 703uses a checksum which is the sum of all the bytes in the `tar' header 704for a file; `cpio' uses no checksum. 705 706 If anyone knows why `cpio' was made when `tar' was present at the 707 unix scene, 708 709 It wasn't. `cpio' first showed up in PWB/UNIX 1.0; no 710generally-available version of UNIX had `tar' at the time. I don't 711know whether any version that was generally available _within AT&T_ had 712`tar', or, if so, whether the people within AT&T who did `cpio' knew 713about it. 714 715 On restore, if there is a corruption on a tape `tar' will stop at 716that point, while `cpio' will skip over it and try to restore the rest 717of the files. 718 719 The main difference is just in the command syntax and header format. 720 721 `tar' is a little more tape-oriented in that everything is blocked 722to start on a record boundary. 723 724 Is there any differences between the ability to recover crashed 725 archives between the two of them. (Is there any chance of 726 recovering crashed archives at all.) 727 728 Theoretically it should be easier under `tar' since the blocking 729lets you find a header with some variation of `dd skip=NN'. However, 730modern `cpio''s and variations have an option to just search for the 731next file header after an error with a reasonable chance of resyncing. 732However, lots of tape driver software won't allow you to continue past 733a media error which should be the only reason for getting out of sync 734unless a file changed sizes while you were writing the archive. 735 736 If anyone knows why `cpio' was made when `tar' was present at the 737 unix scene, please tell me about this too. 738 739 Probably because it is more media efficient (by not blocking 740everything and using only the space needed for the headers where `tar' 741always uses 512 bytes per file header) and it knows how to archive 742special files. 743 744 You might want to look at the freely available alternatives. The 745major ones are `afio', GNU `tar', and `pax', each of which have their 746own extensions with some backwards compatibility. 747 748 Sparse files were `tar'red as sparse files (which you can easily 749test, because the resulting archive gets smaller, and GNU `cpio' can no 750longer read it). 751 752 753File: tar.info, Node: Media, Next: Changes, Prev: Formats, Up: Top 754 7559 Tapes and Other Archive Media 756******************************* 757 758 _(This message will disappear, once this node revised.)_ 759 760A few special cases about tape handling warrant more detailed 761description. These special cases are discussed below. 762 763 Many complexities surround the use of `tar' on tape drives. Since 764the creation and manipulation of archives located on magnetic tape was 765the original purpose of `tar', it contains many features making such 766manipulation easier. 767 768 Archives are usually written on dismountable media--tape cartridges, 769mag tapes, or floppy disks. 770 771 The amount of data a tape or disk holds depends not only on its size, 772but also on how it is formatted. A 2400 foot long reel of mag tape 773holds 40 megabytes of data when formatted at 1600 bits per inch. The 774physically smaller EXABYTE tape cartridge holds 2.3 gigabytes. 775 776 Magnetic media are re-usable--once the archive on a tape is no longer 777needed, the archive can be erased and the tape or disk used over. 778Media quality does deteriorate with use, however. Most tapes or disks 779should be discarded when they begin to produce data errors. EXABYTE 780tape cartridges should be discarded when they generate an "error count" 781(number of non-usable bits) of more than 10k. 782 783 Magnetic media are written and erased using magnetic fields, and 784should be protected from such fields to avoid damage to stored data. 785Sticking a floppy disk to a filing cabinet using a magnet is probably 786not a good idea. 787 788* Menu: 789 790* Device:: Device selection and switching 791* Remote Tape Server:: 792* Common Problems and Solutions:: 793* Blocking:: Blocking 794* Many:: Many archives on one tape 795* Using Multiple Tapes:: Using Multiple Tapes 796* label:: Including a Label in the Archive 797* verify:: 798* Write Protection:: 799 800 801File: tar.info, Node: Device, Next: Remote Tape Server, Up: Media 802 8039.1 Device Selection and Switching 804================================== 805 806 _(This message will disappear, once this node revised.)_ 807 808`-f [HOSTNAME:]FILE' 809`--file=[HOSTNAME:]FILE' 810 Use archive file or device FILE on HOSTNAME. 811 812 This option is used to specify the file name of the archive `tar' 813works on. 814 815 If the file name is `-', `tar' reads the archive from standard input 816(when listing or extracting), or writes it to standard output (when 817creating). If the `-' file name is given when updating an archive, 818`tar' will read the original archive from its standard input, and will 819write the entire new archive to its standard output. 820 821 If the file name contains a `:', it is interpreted as `hostname:file 822name'. If the HOSTNAME contains an "at" sign (`@'), it is treated as 823`user@hostname:file name'. In either case, `tar' will invoke the 824command `rsh' (or `remsh') to start up an `/usr/libexec/rmt' on the 825remote machine. If you give an alternate login name, it will be given 826to the `rsh'. Naturally, the remote machine must have an executable 827`/usr/libexec/rmt'. This program is free software from the University 828of California, and a copy of the source code can be found with the 829sources for `tar'; it's compiled and installed by default. The exact 830path to this utility is determined when configuring the package. It is 831`PREFIX/libexec/rmt', where PREFIX stands for your installation prefix. 832This location may also be overridden at runtime by using 833`rmt-command=COMMAND' option (*Note --rmt-command: Option Summary, for 834detailed description of this option. *Note Remote Tape Server::, for 835the description of `rmt' command). 836 837 If this option is not given, but the environment variable `TAPE' is 838set, its value is used; otherwise, old versions of `tar' used a default 839archive name (which was picked when `tar' was compiled). The default 840is normally set up to be the "first" tape drive or other transportable 841I/O medium on the system. 842 843 Starting with version 1.11.5, GNU `tar' uses standard input and 844standard output as the default device, and I will not try anymore 845supporting automatic device detection at installation time. This was 846failing really in too many cases, it was hopeless. This is now 847completely left to the installer to override standard input and 848standard output for default device, if this seems preferable. Further, 849I think _most_ actual usages of `tar' are done with pipes or disks, not 850really tapes, cartridges or diskettes. 851 852 Some users think that using standard input and output is running 853after trouble. This could lead to a nasty surprise on your screen if 854you forget to specify an output file name--especially if you are going 855through a network or terminal server capable of buffering large amounts 856of output. We had so many bug reports in that area of configuring 857default tapes automatically, and so many contradicting requests, that 858we finally consider the problem to be portably intractable. We could 859of course use something like `/dev/tape' as a default, but this is 860_also_ running after various kind of trouble, going from hung processes 861to accidental destruction of real tapes. After having seen all this 862mess, using standard input and output as a default really sounds like 863the only clean choice left, and a very useful one too. 864 865 GNU `tar' reads and writes archive in records, I suspect this is the 866main reason why block devices are preferred over character devices. 867Most probably, block devices are more efficient too. The installer 868could also check for `DEFTAPE' in `<sys/mtio.h>'. 869 870`--force-local' 871 Archive file is local even if it contains a colon. 872 873`--rsh-command=COMMAND' 874 Use remote COMMAND instead of `rsh'. This option exists so that 875 people who use something other than the standard `rsh' (e.g., a 876 Kerberized `rsh') can access a remote device. 877 878 When this command is not used, the shell command found when the 879 `tar' program was installed is used instead. This is the first 880 found of `/usr/ucb/rsh', `/usr/bin/remsh', `/usr/bin/rsh', 881 `/usr/bsd/rsh' or `/usr/bin/nsh'. The installer may have 882 overridden this by defining the environment variable `RSH' _at 883 installation time_. 884 885`-[0-7][lmh]' 886 Specify drive and density. 887 888`-M' 889`--multi-volume' 890 Create/list/extract multi-volume archive. 891 892 This option causes `tar' to write a "multi-volume" archive--one 893 that may be larger than will fit on the medium used to hold it. 894 *Note Multi-Volume Archives::. 895 896`-L NUM' 897`--tape-length=NUM' 898 Change tape after writing NUM x 1024 bytes. 899 900 This option might be useful when your tape drivers do not properly 901 detect end of physical tapes. By being slightly conservative on 902 the maximum tape length, you might avoid the problem entirely. 903 904`-F FILE' 905`--info-script=FILE' 906`--new-volume-script=FILE' 907 Execute `file' at end of each tape. This implies `--multi-volume' 908 (`-M'). *Note info-script::, for a detailed description of this 909 option. 910 911 912File: tar.info, Node: Remote Tape Server, Next: Common Problems and Solutions, Prev: Device, Up: Media 913 9149.2 The Remote Tape Server 915========================== 916 917In order to access the tape drive on a remote machine, `tar' uses the 918remote tape server written at the University of California at Berkeley. 919The remote tape server must be installed as `PREFIX/libexec/rmt' on 920any machine whose tape drive you want to use. `tar' calls `rmt' by 921running an `rsh' or `remsh' to the remote machine, optionally using a 922different login name if one is supplied. 923 924 A copy of the source for the remote tape server is provided. It is 925Copyright (C) 1983 by the Regents of the University of California, but 926can be freely distributed. It is compiled and installed by default. 927 928 Unless you use the `--absolute-names' (`-P') option, GNU `tar' will 929not allow you to create an archive that contains absolute file names (a 930file name beginning with `/'.) If you try, `tar' will automatically 931remove the leading `/' from the file names it stores in the archive. 932It will also type a warning message telling you what it is doing. 933 934 When reading an archive that was created with a different `tar' 935program, GNU `tar' automatically extracts entries in the archive which 936have absolute file names as if the file names were not absolute. This 937is an important feature. A visitor here once gave a `tar' tape to an 938operator to restore; the operator used Sun `tar' instead of GNU `tar', 939and the result was that it replaced large portions of our `/bin' and 940friends with versions from the tape; needless to say, we were unhappy 941about having to recover the file system from backup tapes. 942 943 For example, if the archive contained a file `/usr/bin/computoy', 944GNU `tar' would extract the file to `usr/bin/computoy', relative to the 945current directory. If you want to extract the files in an archive to 946the same absolute names that they had when the archive was created, you 947should do a `cd /' before extracting the files from the archive, or you 948should either use the `--absolute-names' option, or use the command 949`tar -C / ...'. 950 951 Some versions of Unix (Ultrix 3.1 is known to have this problem), 952can claim that a short write near the end of a tape succeeded, when it 953actually failed. This will result in the -M option not working 954correctly. The best workaround at the moment is to use a significantly 955larger blocking factor than the default 20. 956 957 In order to update an archive, `tar' must be able to backspace the 958archive in order to reread or rewrite a record that was just read (or 959written). This is currently possible only on two kinds of files: normal 960disk files (or any other file that can be backspaced with `lseek'), and 961industry-standard 9-track magnetic tape (or any other kind of tape that 962can be backspaced with the `MTIOCTOP' `ioctl'. 963 964 This means that the `--append', `--concatenate', and `--delete' 965commands will not work on any other kind of file. Some media simply 966cannot be backspaced, which means these commands and options will never 967be able to work on them. These non-backspacing media include pipes and 968cartridge tape drives. 969 970 Some other media can be backspaced, and `tar' will work on them once 971`tar' is modified to do so. 972 973 Archives created with the `--multi-volume', `--label', and 974`--incremental' (`-G') options may not be readable by other version of 975`tar'. In particular, restoring a file that was split over a volume 976boundary will require some careful work with `dd', if it can be done at 977all. Other versions of `tar' may also create an empty file whose name 978is that of the volume header. Some versions of `tar' may create normal 979files instead of directories archived with the `--incremental' (`-G') 980option. 981 982 983File: tar.info, Node: Common Problems and Solutions, Next: Blocking, Prev: Remote Tape Server, Up: Media 984 9859.3 Some Common Problems and their Solutions 986============================================ 987 988errors from system: 989permission denied 990no such file or directory 991not owner 992 993errors from `tar': 994directory checksum error 995header format error 996 997errors from media/system: 998i/o error 999device busy 1000 1001 1002File: tar.info, Node: Blocking, Next: Many, Prev: Common Problems and Solutions, Up: Media 1003 10049.4 Blocking 1005============ 1006 1007 _(This message will disappear, once this node revised.)_ 1008 1009"Block" and "record" terminology is rather confused, and it is also 1010confusing to the expert reader. On the other hand, readers who are new 1011to the field have a fresh mind, and they may safely skip the next two 1012paragraphs, as the remainder of this manual uses those two terms in a 1013quite consistent way. 1014 1015 John Gilmore, the writer of the public domain `tar' from which GNU 1016`tar' was originally derived, wrote (June 1995): 1017 1018 The nomenclature of tape drives comes from IBM, where I believe 1019 they were invented for the IBM 650 or so. On IBM mainframes, what 1020 is recorded on tape are tape blocks. The logical organization of 1021 data is into records. There are various ways of putting records 1022 into blocks, including `F' (fixed sized records), `V' (variable 1023 sized records), `FB' (fixed blocked: fixed size records, N to a 1024 block), `VB' (variable size records, N to a block), `VSB' 1025 (variable spanned blocked: variable sized records that can occupy 1026 more than one block), etc. The `JCL' `DD RECFORM=' parameter 1027 specified this to the operating system. 1028 1029 The Unix man page on `tar' was totally confused about this. When 1030 I wrote `PD TAR', I used the historically correct terminology 1031 (`tar' writes data records, which are grouped into blocks). It 1032 appears that the bogus terminology made it into POSIX (no surprise 1033 here), and now Franc,ois has migrated that terminology back into 1034 the source code too. 1035 1036 The term "physical block" means the basic transfer chunk from or to 1037a device, after which reading or writing may stop without anything 1038being lost. In this manual, the term "block" usually refers to a disk 1039physical block, _assuming_ that each disk block is 512 bytes in length. 1040It is true that some disk devices have different physical blocks, but 1041`tar' ignore these differences in its own format, which is meant to be 1042portable, so a `tar' block is always 512 bytes in length, and "block" 1043always mean a `tar' block. The term "logical block" often represents 1044the basic chunk of allocation of many disk blocks as a single entity, 1045which the operating system treats somewhat atomically; this concept is 1046only barely used in GNU `tar'. 1047 1048 The term "physical record" is another way to speak of a physical 1049block, those two terms are somewhat interchangeable. In this manual, 1050the term "record" usually refers to a tape physical block, _assuming_ 1051that the `tar' archive is kept on magnetic tape. It is true that 1052archives may be put on disk or used with pipes, but nevertheless, `tar' 1053tries to read and write the archive one "record" at a time, whatever 1054the medium in use. One record is made up of an integral number of 1055blocks, and this operation of putting many disk blocks into a single 1056tape block is called "reblocking", or more simply, "blocking". The 1057term "logical record" refers to the logical organization of many 1058characters into something meaningful to the application. The term 1059"unit record" describes a small set of characters which are transmitted 1060whole to or by the application, and often refers to a line of text. 1061Those two last terms are unrelated to what we call a "record" in GNU 1062`tar'. 1063 1064 When writing to tapes, `tar' writes the contents of the archive in 1065chunks known as "records". To change the default blocking factor, use 1066the `--blocking-factor=512-SIZE' (`-b 512-SIZE') option. Each record 1067will then be composed of 512-SIZE blocks. (Each `tar' block is 512 1068bytes. *Note Standard::.) Each file written to the archive uses at 1069least one full record. As a result, using a larger record size can 1070result in more wasted space for small files. On the other hand, a 1071larger record size can often be read and written much more efficiently. 1072 1073 Further complicating the problem is that some tape drives ignore the 1074blocking entirely. For these, a larger record size can still improve 1075performance (because the software layers above the tape drive still 1076honor the blocking), but not as dramatically as on tape drives that 1077honor blocking. 1078 1079 When reading an archive, `tar' can usually figure out the record 1080size on itself. When this is the case, and a non-standard record size 1081was used when the archive was created, `tar' will print a message about 1082a non-standard blocking factor, and then operate normally. On some 1083tape devices, however, `tar' cannot figure out the record size itself. 1084On most of those, you can specify a blocking factor (with 1085`--blocking-factor') larger than the actual blocking factor, and then 1086use the `--read-full-records' (`-B') option. (If you specify a 1087blocking factor with `--blocking-factor' and don't use the 1088`--read-full-records' option, then `tar' will not attempt to figure out 1089the recording size itself.) On some devices, you must always specify 1090the record size exactly with `--blocking-factor' when reading, because 1091`tar' cannot figure it out. In any case, use `--list' (`-t') before 1092doing any extractions to see whether `tar' is reading the archive 1093correctly. 1094 1095 `tar' blocks are all fixed size (512 bytes), and its scheme for 1096putting them into records is to put a whole number of them (one or 1097more) into each record. `tar' records are all the same size; at the 1098end of the file there's a block containing all zeros, which is how you 1099tell that the remainder of the last record(s) are garbage. 1100 1101 In a standard `tar' file (no options), the block size is 512 and the 1102record size is 10240, for a blocking factor of 20. What the 1103`--blocking-factor' option does is sets the blocking factor, changing 1104the record size while leaving the block size at 512 bytes. 20 was fine 1105for ancient 800 or 1600 bpi reel-to-reel tape drives; most tape drives 1106these days prefer much bigger records in order to stream and not waste 1107tape. When writing tapes for myself, some tend to use a factor of the 1108order of 2048, say, giving a record size of around one megabyte. 1109 1110 If you use a blocking factor larger than 20, older `tar' programs 1111might not be able to read the archive, so we recommend this as a limit 1112to use in practice. GNU `tar', however, will support arbitrarily large 1113record sizes, limited only by the amount of virtual memory or the 1114physical characteristics of the tape device. 1115 1116* Menu: 1117 1118* Format Variations:: Format Variations 1119* Blocking Factor:: The Blocking Factor of an Archive 1120 1121 1122File: tar.info, Node: Format Variations, Next: Blocking Factor, Up: Blocking 1123 11249.4.1 Format Variations 1125----------------------- 1126 1127 _(This message will disappear, once this node revised.)_ 1128 1129Format parameters specify how an archive is written on the archive 1130media. The best choice of format parameters will vary depending on the 1131type and number of files being archived, and on the media used to store 1132the archive. 1133 1134 To specify format parameters when accessing or creating an archive, 1135you can use the options described in the following sections. If you do 1136not specify any format parameters, `tar' uses default parameters. You 1137cannot modify a compressed archive. If you create an archive with the 1138`--blocking-factor' option specified (*note Blocking Factor::), you 1139must specify that blocking-factor when operating on the archive. *Note 1140Formats::, for other examples of format parameter considerations. 1141 1142 1143File: tar.info, Node: Blocking Factor, Prev: Format Variations, Up: Blocking 1144 11459.4.2 The Blocking Factor of an Archive 1146--------------------------------------- 1147 1148 _(This message will disappear, once this node revised.)_ 1149 1150The data in an archive is grouped into blocks, which are 512 bytes. 1151Blocks are read and written in whole number multiples called "records". 1152The number of blocks in a record (i.e., the size of a record in units 1153of 512 bytes) is called the "blocking factor". The 1154`--blocking-factor=512-SIZE' (`-b 512-SIZE') option specifies the 1155blocking factor of an archive. The default blocking factor is 1156typically 20 (i.e., 10240 bytes), but can be specified at installation. 1157To find out the blocking factor of an existing archive, use `tar 1158--list --file=ARCHIVE-NAME'. This may not work on some devices. 1159 1160 Records are separated by gaps, which waste space on the archive 1161media. If you are archiving on magnetic tape, using a larger blocking 1162factor (and therefore larger records) provides faster throughput and 1163allows you to fit more data on a tape (because there are fewer gaps). 1164If you are archiving on cartridge, a very large blocking factor (say 1165126 or more) greatly increases performance. A smaller blocking factor, 1166on the other hand, may be useful when archiving small files, to avoid 1167archiving lots of nulls as `tar' fills out the archive to the end of 1168the record. In general, the ideal record size depends on the size of 1169the inter-record gaps on the tape you are using, and the average size 1170of the files you are archiving. *Note create::, for information on 1171writing archives. 1172 1173 Archives with blocking factors larger than 20 cannot be read by very 1174old versions of `tar', or by some newer versions of `tar' running on 1175old machines with small address spaces. With GNU `tar', the blocking 1176factor of an archive is limited only by the maximum record size of the 1177device containing the archive, or by the amount of available virtual 1178memory. 1179 1180 Also, on some systems, not using adequate blocking factors, as 1181sometimes imposed by the device drivers, may yield unexpected 1182diagnostics. For example, this has been reported: 1183 1184 Cannot write to /dev/dlt: Invalid argument 1185 1186In such cases, it sometimes happen that the `tar' bundled by the system 1187is aware of block size idiosyncrasies, while GNU `tar' requires an 1188explicit specification for the block size, which it cannot guess. This 1189yields some people to consider GNU `tar' is misbehaving, because by 1190comparison, `the bundle `tar' works OK'. Adding `-b 256', for example, 1191might resolve the problem. 1192 1193 If you use a non-default blocking factor when you create an archive, 1194you must specify the same blocking factor when you modify that archive. 1195Some archive devices will also require you to specify the blocking 1196factor when reading that archive, however this is not typically the 1197case. Usually, you can use `--list' (`-t') without specifying a 1198blocking factor--`tar' reports a non-default record size and then lists 1199the archive members as it would normally. To extract files from an 1200archive with a non-standard blocking factor (particularly if you're not 1201sure what the blocking factor is), you can usually use the 1202`--read-full-records' (`-B') option while specifying a blocking factor 1203larger then the blocking factor of the archive (i.e., `tar --extract 1204--read-full-records --blocking-factor=300'. *Note list::, for more 1205information on the `--list' (`-t') operation. *Note Reading::, for a 1206more detailed explanation of that option. 1207 1208`--blocking-factor=NUMBER' 1209`-b NUMBER' 1210 Specifies the blocking factor of an archive. Can be used with any 1211 operation, but is usually not necessary with `--list' (`-t'). 1212 1213 Device blocking 1214 1215`-b BLOCKS' 1216`--blocking-factor=BLOCKS' 1217 Set record size to BLOCKS * 512 bytes. 1218 1219 This option is used to specify a "blocking factor" for the archive. 1220 When reading or writing the archive, `tar', will do reads and 1221 writes of the archive in records of BLOCK*512 bytes. This is true 1222 even when the archive is compressed. Some devices requires that 1223 all write operations be a multiple of a certain size, and so, `tar' 1224 pads the archive out to the next record boundary. 1225 1226 The default blocking factor is set when `tar' is compiled, and is 1227 typically 20. Blocking factors larger than 20 cannot be read by 1228 very old versions of `tar', or by some newer versions of `tar' 1229 running on old machines with small address spaces. 1230 1231 With a magnetic tape, larger records give faster throughput and fit 1232 more data on a tape (because there are fewer inter-record gaps). 1233 If the archive is in a disk file or a pipe, you may want to specify 1234 a smaller blocking factor, since a large one will result in a large 1235 number of null bytes at the end of the archive. 1236 1237 When writing cartridge or other streaming tapes, a much larger 1238 blocking factor (say 126 or more) will greatly increase 1239 performance. However, you must specify the same blocking factor 1240 when reading or updating the archive. 1241 1242 Apparently, Exabyte drives have a physical block size of 8K bytes. 1243 If we choose our blocksize as a multiple of 8k bytes, then the 1244 problem seems to disappear. Id est, we are using block size of 1245 112 right now, and we haven't had the problem since we switched... 1246 1247 With GNU `tar' the blocking factor is limited only by the maximum 1248 record size of the device containing the archive, or by the amount 1249 of available virtual memory. 1250 1251 However, deblocking or reblocking is virtually avoided in a special 1252 case which often occurs in practice, but which requires all the 1253 following conditions to be simultaneously true: 1254 * the archive is subject to a compression option, 1255 1256 * the archive is not handled through standard input or output, 1257 nor redirected nor piped, 1258 1259 * the archive is directly handled to a local disk, instead of 1260 any special device, 1261 1262 * `--blocking-factor' is not explicitly specified on the `tar' 1263 invocation. 1264 1265 If the output goes directly to a local disk, and not through 1266 stdout, then the last write is not extended to a full record size. 1267 Otherwise, reblocking occurs. Here are a few other remarks on this 1268 topic: 1269 1270 * `gzip' will complain about trailing garbage if asked to 1271 uncompress a compressed archive on tape, there is an option 1272 to turn the message off, but it breaks the regularity of 1273 simply having to use `PROG -d' for decompression. It would 1274 be nice if gzip was silently ignoring any number of trailing 1275 zeros. I'll ask Jean-loup Gailly, by sending a copy of this 1276 message to him. 1277 1278 * `compress' does not show this problem, but as Jean-loup 1279 pointed out to Michael, `compress -d' silently adds garbage 1280 after the result of decompression, which tar ignores because 1281 it already recognized its end-of-file indicator. So this bug 1282 may be safely ignored. 1283 1284 * `gzip -d -q' will be silent about the trailing zeros indeed, 1285 but will still return an exit status of 2 which tar reports 1286 in turn. `tar' might ignore the exit status returned, but I 1287 hate doing that, as it weakens the protection `tar' offers 1288 users against other possible problems at decompression time. 1289 If `gzip' was silently skipping trailing zeros _and_ also 1290 avoiding setting the exit status in this innocuous case, that 1291 would solve this situation. 1292 1293 * `tar' should become more solid at not stopping to read a pipe 1294 at the first null block encountered. This inelegantly breaks 1295 the pipe. `tar' should rather drain the pipe out before 1296 exiting itself. 1297 1298`-i' 1299`--ignore-zeros' 1300 Ignore blocks of zeros in archive (means EOF). 1301 1302 The `--ignore-zeros' (`-i') option causes `tar' to ignore blocks 1303 of zeros in the archive. Normally a block of zeros indicates the 1304 end of the archive, but when reading a damaged archive, or one 1305 which was created by concatenating several archives together, this 1306 option allows `tar' to read the entire archive. This option is 1307 not on by default because many versions of `tar' write garbage 1308 after the zeroed blocks. 1309 1310 Note that this option causes `tar' to read to the end of the 1311 archive file, which may sometimes avoid problems when multiple 1312 files are stored on a single physical tape. 1313 1314`-B' 1315`--read-full-records' 1316 Reblock as we read (for reading 4.2BSD pipes). 1317 1318 If `--read-full-records' is used, `tar' will not panic if an 1319 attempt to read a record from the archive does not return a full 1320 record. Instead, `tar' will keep reading until it has obtained a 1321 full record. 1322 1323 This option is turned on by default when `tar' is reading an 1324 archive from standard input, or from a remote machine. This is 1325 because on BSD Unix systems, a read of a pipe will return however 1326 much happens to be in the pipe, even if it is less than `tar' 1327 requested. If this option was not used, `tar' would fail as soon 1328 as it read an incomplete record from the pipe. 1329 1330 This option is also useful with the commands for updating an 1331 archive. 1332 1333 1334 Tape blocking 1335 1336 When handling various tapes or cartridges, you have to take care of 1337selecting a proper blocking, that is, the number of disk blocks you put 1338together as a single tape block on the tape, without intervening tape 1339gaps. A "tape gap" is a small landing area on the tape with no 1340information on it, used for decelerating the tape to a full stop, and 1341for later regaining the reading or writing speed. When the tape driver 1342starts reading a record, the record has to be read whole without 1343stopping, as a tape gap is needed to stop the tape motion without 1344loosing information. 1345 1346 Using higher blocking (putting more disk blocks per tape block) will 1347use the tape more efficiently as there will be less tape gaps. But 1348reading such tapes may be more difficult for the system, as more memory 1349will be required to receive at once the whole record. Further, if 1350there is a reading error on a huge record, this is less likely that the 1351system will succeed in recovering the information. So, blocking should 1352not be too low, nor it should be too high. `tar' uses by default a 1353blocking of 20 for historical reasons, and it does not really matter 1354when reading or writing to disk. Current tape technology would easily 1355accommodate higher blockings. Sun recommends a blocking of 126 for 1356Exabytes and 96 for DATs. We were told that for some DLT drives, the 1357blocking should be a multiple of 4Kb, preferably 64Kb (`-b 128') or 256 1358for decent performance. Other manufacturers may use different 1359recommendations for the same tapes. This might also depends of the 1360buffering techniques used inside modern tape controllers. Some imposes 1361a minimum blocking, or a maximum blocking. Others request blocking to 1362be some exponent of two. 1363 1364 So, there is no fixed rule for blocking. But blocking at read time 1365should ideally be the same as blocking used at write time. At one place 1366I know, with a wide variety of equipment, they found it best to use a 1367blocking of 32 to guarantee that their tapes are fully interchangeable. 1368 1369 I was also told that, for recycled tapes, prior erasure (by the same 1370drive unit that will be used to create the archives) sometimes lowers 1371the error rates observed at rewriting time. 1372 1373 I might also use `--number-blocks' instead of `--block-number', so 1374`--block' will then expand to `--blocking-factor' unambiguously. 1375 1376 1377File: tar.info, Node: Many, Next: Using Multiple Tapes, Prev: Blocking, Up: Media 1378 13799.5 Many Archives on One Tape 1380============================= 1381 1382Most tape devices have two entries in the `/dev' directory, or entries 1383that come in pairs, which differ only in the minor number for this 1384device. Let's take for example `/dev/tape', which often points to the 1385only or usual tape device of a given system. There might be a 1386corresponding `/dev/nrtape' or `/dev/ntape'. The simpler name is the 1387_rewinding_ version of the device, while the name having `nr' in it is 1388the _no rewinding_ version of the same device. 1389 1390 A rewinding tape device will bring back the tape to its beginning 1391point automatically when this device is opened or closed. Since `tar' 1392opens the archive file before using it and closes it afterwards, this 1393means that a simple: 1394 1395 $ tar cf /dev/tape DIRECTORY 1396 1397will reposition the tape to its beginning both prior and after saving 1398DIRECTORY contents to it, thus erasing prior tape contents and making 1399it so that any subsequent write operation will destroy what has just 1400been saved. 1401 1402 So, a rewinding device is normally meant to hold one and only one 1403file. If you want to put more than one `tar' archive on a given tape, 1404you will need to avoid using the rewinding version of the tape device. 1405You will also have to pay special attention to tape positioning. 1406Errors in positioning may overwrite the valuable data already on your 1407tape. Many people, burnt by past experiences, will only use rewinding 1408devices and limit themselves to one file per tape, precisely to avoid 1409the risk of such errors. Be fully aware that writing at the wrong 1410position on a tape loses all information past this point and most 1411probably until the end of the tape, and this destroyed information 1412_cannot_ be recovered. 1413 1414 To save DIRECTORY-1 as a first archive at the beginning of a tape, 1415and leave that tape ready for a second archive, you should use: 1416 1417 $ mt -f /dev/nrtape rewind 1418 $ tar cf /dev/nrtape DIRECTORY-1 1419 1420 "Tape marks" are special magnetic patterns written on the tape 1421media, which are later recognizable by the reading hardware. These 1422marks are used after each file, when there are many on a single tape. 1423An empty file (that is to say, two tape marks in a row) signal the 1424logical end of the tape, after which no file exist. Usually, 1425non-rewinding tape device drivers will react to the close request issued 1426by `tar' by first writing two tape marks after your archive, and by 1427backspacing over one of these. So, if you remove the tape at that time 1428from the tape drive, it is properly terminated. But if you write 1429another file at the current position, the second tape mark will be 1430erased by the new information, leaving only one tape mark between files. 1431 1432 So, you may now save DIRECTORY-2 as a second archive after the first 1433on the same tape by issuing the command: 1434 1435 $ tar cf /dev/nrtape DIRECTORY-2 1436 1437and so on for all the archives you want to put on the same tape. 1438 1439 Another usual case is that you do not write all the archives the same 1440day, and you need to remove and store the tape between two archive 1441sessions. In general, you must remember how many files are already 1442saved on your tape. Suppose your tape already has 16 files on it, and 1443that you are ready to write the 17th. You have to take care of skipping 1444the first 16 tape marks before saving DIRECTORY-17, say, by using these 1445commands: 1446 1447 $ mt -f /dev/nrtape rewind 1448 $ mt -f /dev/nrtape fsf 16 1449 $ tar cf /dev/nrtape DIRECTORY-17 1450 1451 In all the previous examples, we put aside blocking considerations, 1452but you should do the proper things for that as well. *Note Blocking::. 1453 1454* Menu: 1455 1456* Tape Positioning:: Tape Positions and Tape Marks 1457* mt:: The `mt' Utility 1458 1459 1460File: tar.info, Node: Tape Positioning, Next: mt, Up: Many 1461 14629.5.1 Tape Positions and Tape Marks 1463----------------------------------- 1464 1465 _(This message will disappear, once this node revised.)_ 1466 1467Just as archives can store more than one file from the file system, 1468tapes can store more than one archive file. To keep track of where 1469archive files (or any other type of file stored on tape) begin and end, 1470tape archive devices write magnetic "tape marks" on the archive media. 1471Tape drives write one tape mark between files, two at the end of all 1472the file entries. 1473 1474 If you think of data as a series of records "rrrr"'s, and tape marks 1475as "*"'s, a tape might look like the following: 1476 1477 rrrr*rrrrrr*rrrrr*rr*rrrrr**------------------------- 1478 1479 Tape devices read and write tapes using a read/write "tape head"--a 1480physical part of the device which can only access one point on the tape 1481at a time. When you use `tar' to read or write archive data from a 1482tape device, the device will begin reading or writing from wherever on 1483the tape the tape head happens to be, regardless of which archive or 1484what part of the archive the tape head is on. Before writing an 1485archive, you should make sure that no data on the tape will be 1486overwritten (unless it is no longer needed). Before reading an 1487archive, you should make sure the tape head is at the beginning of the 1488archive you want to read. You can do it manually via `mt' utility 1489(*note mt::). The `restore' script does that automatically (*note 1490Scripted Restoration::). 1491 1492 If you want to add new archive file entries to a tape, you should 1493advance the tape to the end of the existing file entries, backspace 1494over the last tape mark, and write the new archive file. If you were 1495to add two archives to the example above, the tape might look like the 1496following: 1497 1498 rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- 1499 1500 1501File: tar.info, Node: mt, Prev: Tape Positioning, Up: Many 1502 15039.5.2 The `mt' Utility 1504---------------------- 1505 1506 _(This message will disappear, once this node revised.)_ 1507 1508*Note Blocking Factor::. 1509 1510 You can use the `mt' utility to advance or rewind a tape past a 1511specified number of archive files on the tape. This will allow you to 1512move to the beginning of an archive before extracting or reading it, or 1513to the end of all the archives before writing a new one. 1514 1515 The syntax of the `mt' command is: 1516 1517 mt [-f TAPENAME] OPERATION [NUMBER] 1518 1519 where TAPENAME is the name of the tape device, NUMBER is the number 1520of times an operation is performed (with a default of one), and 1521OPERATION is one of the following: 1522 1523`eof' 1524`weof' 1525 Writes NUMBER tape marks at the current position on the tape. 1526 1527`fsf' 1528 Moves tape position forward NUMBER files. 1529 1530`bsf' 1531 Moves tape position back NUMBER files. 1532 1533`rewind' 1534 Rewinds the tape. (Ignores NUMBER). 1535 1536`offline' 1537`rewoff1' 1538 Rewinds the tape and takes the tape device off-line. (Ignores 1539 NUMBER). 1540 1541`status' 1542 Prints status information about the tape unit. 1543 1544 1545 If you don't specify a TAPENAME, `mt' uses the environment variable 1546`TAPE'; if `TAPE' is not set, `mt' will use the default device 1547specified in your `sys/mtio.h' file (`DEFTAPE' variable). If this is 1548not defined, the program will display a descriptive error message and 1549exit with code 1. 1550 1551 `mt' returns a 0 exit status when the operation(s) were successful, 15521 if the command was unrecognized, and 2 if an operation failed. 1553 1554 1555File: tar.info, Node: Using Multiple Tapes, Next: label, Prev: Many, Up: Media 1556 15579.6 Using Multiple Tapes 1558======================== 1559 1560Often you might want to write a large archive, one larger than will fit 1561on the actual tape you are using. In such a case, you can run multiple 1562`tar' commands, but this can be inconvenient, particularly if you are 1563using options like `--exclude=PATTERN' or dumping entire file systems. 1564Therefore, `tar' provides a special mode for creating multi-volume 1565archives. 1566 1567 "Multi-volume" archive is a single `tar' archive, stored on several 1568media volumes of fixed size. Although in this section we will often 1569call `volume' a "tape", there is absolutely no requirement for 1570multi-volume archives to be stored on tapes. Instead, they can use 1571whatever media type the user finds convenient, they can even be located 1572on files. 1573 1574 When creating a multi-volume archive, GNU `tar' continues to fill 1575current volume until it runs out of space, then it switches to next 1576volume (usually the operator is queried to replace the tape on this 1577point), and continues working on the new volume. This operation 1578continues until all requested files are dumped. If GNU `tar' detects 1579end of media while dumping a file, such a file is archived in split 1580form. Some very big files can even be split across several volumes. 1581 1582 Each volume is itself a valid GNU `tar' archive, so it can be read 1583without any special options. Consequently any file member residing 1584entirely on one volume can be extracted or otherwise operated upon 1585without needing the other volume. Sure enough, to extract a split 1586member you would need all volumes its parts reside on. 1587 1588 Multi-volume archives suffer from several limitations. In 1589particular, they cannot be compressed. 1590 1591 GNU `tar' is able to create multi-volume archives of two formats 1592(*note Formats::): `GNU' and `POSIX'. 1593 1594* Menu: 1595 1596* Multi-Volume Archives:: Archives Longer than One Tape or Disk 1597* Tape Files:: Tape Files 1598* Tarcat:: Concatenate Volumes into a Single Archive 1599 1600 1601File: tar.info, Node: Multi-Volume Archives, Next: Tape Files, Up: Using Multiple Tapes 1602 16039.6.1 Archives Longer than One Tape or Disk 1604------------------------------------------- 1605 1606To create an archive that is larger than will fit on a single unit of 1607the media, use the `--multi-volume' (`-M') option in conjunction with 1608the `--create' option (*note create::). A "multi-volume" archive can 1609be manipulated like any other archive (provided the `--multi-volume' 1610option is specified), but is stored on more than one tape or disk. 1611 1612 When you specify `--multi-volume', `tar' does not report an error 1613when it comes to the end of an archive volume (when reading), or the 1614end of the media (when writing). Instead, it prompts you to load a new 1615storage volume. If the archive is on a magnetic tape, you should 1616change tapes when you see the prompt; if the archive is on a floppy 1617disk, you should change disks; etc. 1618 1619`--multi-volume' 1620`-M' 1621 Creates a multi-volume archive, when used in conjunction with 1622 `--create' (`-c'). To perform any other operation on a 1623 multi-volume archive, specify `--multi-volume' in conjunction with 1624 that operation. For example: 1625 1626 $ tar --create --multi-volume --file=/dev/tape FILES 1627 1628 The method `tar' uses to detect end of tape is not perfect, and 1629fails on some operating systems or on some devices. If `tar' cannot 1630detect the end of the tape itself, you can use `--tape-length' option 1631to inform it about the capacity of the tape: 1632 1633`--tape-length=SIZE' 1634`-L SIZE' 1635 Set maximum length of a volume. The SIZE argument should then be 1636 the usable size of the tape in units of 1024 bytes. This option 1637 selects `--multi-volume' automatically. For example: 1638 1639 $ tar --create --tape-length=41943040 --file=/dev/tape FILES 1640 1641 When GNU `tar' comes to the end of a storage media, it asks you to 1642change the volume. The built-in prompt for POSIX locale is(1): 1643 1644 Prepare volume #N for `ARCHIVE' and hit return: 1645 1646where N is the ordinal number of the volume to be created and ARCHIVE 1647is archive file or device name. 1648 1649 When prompting for a new tape, `tar' accepts any of the following 1650responses: 1651 1652`?' 1653 Request `tar' to explain possible responses 1654 1655`q' 1656 Request `tar' to exit immediately. 1657 1658`n FILE-NAME' 1659 Request `tar' to write the next volume on the file FILE-NAME. 1660 1661`!' 1662 Request `tar' to run a subshell. This option can be disabled by 1663 giving `--restrict' command line option to `tar'(2). 1664 1665`y' 1666 Request `tar' to begin writing the next volume. 1667 1668 (You should only type `y' after you have changed the tape; otherwise 1669`tar' will write over the volume it just finished.) 1670 1671 The volume number used by `tar' in its tape-changing prompt can be 1672changed; if you give the `--volno-file=FILE-OF-NUMBER' option, then 1673FILE-OF-NUMBER should be an non-existing file to be created, or else, a 1674file already containing a decimal number. That number will be used as 1675the volume number of the first volume written. When `tar' is finished, 1676it will rewrite the file with the now-current volume number. (This does 1677not change the volume number written on a tape label, as per *note 1678label::, it _only_ affects the number used in the prompt.) 1679 1680 If you want more elaborate behavior than this, you can write a 1681special "new volume script", that will be responsible for changing the 1682volume, and instruct `tar' to use it instead of its normal prompting 1683procedure: 1684 1685`--info-script=SCRIPT-NAME' 1686`--new-volume-script=SCRIPT-NAME' 1687`-F SCRIPT-NAME' 1688 Specify the full name of the volume script to use. The script can 1689 be used to eject cassettes, or to broadcast messages such as 1690 `Someone please come change my tape' when performing unattended 1691 backups. 1692 1693 The SCRIPT-NAME is executed without any command line arguments. It 1694inherits `tar''s shell environment. Additional data is passed to it 1695via the following environment variables: 1696 1697`TAR_VERSION' 1698 GNU `tar' version number. 1699 1700`TAR_ARCHIVE' 1701 The name of the archive `tar' is processing. 1702 1703`TAR_VOLUME' 1704 Ordinal number of the volume `tar' is about to start. 1705 1706`TAR_SUBCOMMAND' 1707 Short option describing the operation `tar' is executing *Note 1708 Operations::, for a complete list of subcommand options. 1709 1710`TAR_FORMAT' 1711 Format of the archive being processed. *Note Formats::, for a 1712 complete list of archive format names. 1713 1714`TAR_FD' 1715 File descriptor which can be used to communicate the new volume 1716 name to `tar'. 1717 1718 The volume script can instruct `tar' to use new archive name, by 1719writing in to file descriptor `$TAR_FD' (see below for an example). 1720 1721 If the info script fails, `tar' exits; otherwise, it begins writing 1722the next volume. 1723 1724 If you want `tar' to cycle through a series of files or tape drives, 1725there are three approaches to choose from. First of all, you can give 1726`tar' multiple `--file' options. In this case the specified files will 1727be used, in sequence, as the successive volumes of the archive. Only 1728when the first one in the sequence needs to be used again will `tar' 1729prompt for a tape change (or run the info script). For example, 1730suppose someone has two tape drives on a system named `/dev/tape0' and 1731`/dev/tape1'. For having GNU `tar' to switch to the second drive when 1732it needs to write the second tape, and then back to the first tape, 1733etc., just do either of: 1734 1735 $ tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 FILES 1736 $ tar cMff /dev/tape0 /dev/tape1 FILES 1737 1738 The second method is to use the `n' response to the tape-change 1739prompt. 1740 1741 Finally, the most flexible approach is to use a volume script, that 1742writes new archive name to the file descriptor `$TAR_FD'. For example, 1743the following volume script will create a series of archive files, named 1744`ARCHIVE-VOL', where ARCHIVE is the name of the archive being created 1745(as given by `--file' option) and VOL is the ordinal number of the 1746archive being created: 1747 1748 #! /bin/sh 1749 echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE. 1750 1751 name=`expr $TAR_ARCHIVE : '\(.*\)-.*'` 1752 case $TAR_SUBCOMMAND in 1753 -c) ;; 1754 -d|-x|-t) test -r ${name:-$TAR_ARCHIVE}-$TAR_VOLUME || exit 1 1755 ;; 1756 *) exit 1 1757 esac 1758 1759 echo ${name:-$TAR_ARCHIVE}-$TAR_VOLUME >&$TAR_FD 1760 1761 The same script cant be used while listing, comparing or extracting 1762from the created archive. For example: 1763 1764 # Create a multi-volume archive: 1765 $ tar -c -L1024 -f archive.tar -F new-volume . 1766 # Extract from the created archive: 1767 $ tar -x -f archive.tar -F new-volume . 1768 1769Notice, that the first command had to use `-L' option, since otherwise 1770GNU `tar' will end up writing everything to file `archive.tar'. 1771 1772 You can read each individual volume of a multi-volume archive as if 1773it were an archive by itself. For example, to list the contents of one 1774volume, use `--list', without `--multi-volume' specified. To extract 1775an archive member from one volume (assuming it is described that 1776volume), use `--extract', again without `--multi-volume'. 1777 1778 If an archive member is split across volumes (i.e., its entry begins 1779on one volume of the media and ends on another), you need to specify 1780`--multi-volume' to extract it successfully. In this case, you should 1781load the volume where the archive member starts, and use `tar --extract 1782--multi-volume'--`tar' will prompt for later volumes as it needs them. 1783*Note extracting archives::, for more information about extracting 1784archives. 1785 1786 Multi-volume archives can be modified like any other archive. To add 1787files to a multi-volume archive, you need to only mount the last volume 1788of the archive media (and new volumes, if needed). For all other 1789operations, you need to use the entire archive. 1790 1791 If a multi-volume archive was labeled using `--label=ARCHIVE-LABEL' 1792(*note label::) when it was created, `tar' will not automatically label 1793volumes which are added later. To label subsequent volumes, specify 1794`--label=ARCHIVE-LABEL' again in conjunction with the `--append', 1795`--update' or `--concatenate' operation. 1796 1797 Notice that multi-volume support is a GNU extension and the archives 1798created in this mode should be read only using GNU `tar'. If you 1799absolutely have to process such archives using a third-party `tar' 1800implementation, read *note Split Recovery::. 1801 1802 ---------- Footnotes ---------- 1803 1804 (1) If you run GNU `tar' under a different locale, the translation 1805to the locale's language will be used. 1806 1807 (2) *Note --restrict::, for more information about this option 1808 1809 1810File: tar.info, Node: Tape Files, Next: Tarcat, Prev: Multi-Volume Archives, Up: Using Multiple Tapes 1811 18129.6.2 Tape Files 1813---------------- 1814 1815 _(This message will disappear, once this node revised.)_ 1816 1817To give the archive a name which will be recorded in it, use the 1818`--label=VOLUME-LABEL' (`-V VOLUME-LABEL') option. This will write a 1819special block identifying VOLUME-LABEL as the name of the archive to 1820the front of the archive which will be displayed when the archive is 1821listed with `--list'. If you are creating a multi-volume archive with 1822`--multi-volume' (*note Using Multiple Tapes::), then the volume label 1823will have `Volume NNN' appended to the name you give, where NNN is the 1824number of the volume of the archive. (If you use the 1825`--label=VOLUME-LABEL') option when reading an archive, it checks to 1826make sure the label on the tape matches the one you give. *Note label::. 1827 1828 When `tar' writes an archive to tape, it creates a single tape file. 1829If multiple archives are written to the same tape, one after the 1830other, they each get written as separate tape files. When extracting, 1831it is necessary to position the tape at the right place before running 1832`tar'. To do this, use the `mt' command. For more information on the 1833`mt' command and on the organization of tapes into a sequence of tape 1834files, see *note mt::. 1835 1836 People seem to often do: 1837 1838 --label="SOME-PREFIX `date +SOME-FORMAT`" 1839 1840 or such, for pushing a common date in all volumes or an archive set. 1841 1842 1843File: tar.info, Node: Tarcat, Prev: Tape Files, Up: Using Multiple Tapes 1844 18459.6.3 Concatenate Volumes into a Single Archive 1846----------------------------------------------- 1847 1848Sometimes it is necessary to convert existing GNU `tar' multi-volume 1849archive to a single `tar' archive. Simply concatenating all volumes 1850into one will not work, since each volume carries an additional 1851information at the beginning. GNU `tar' is shipped with the shell 1852script `tarcat' designed for this purpose. 1853 1854 The script takes a list of files comprising a multi-volume archive 1855and creates the resulting archive at the standard output. For example: 1856 1857 tarcat vol.1 vol.2 vol.3 | tar tf - 1858 1859 The script implements a simple heuristics to determine the format of 1860the first volume file and to decide how to process the rest of the 1861files. However, it makes no attempt to verify whether the files are 1862given in order or even if they are valid `tar' archives. It uses `dd' 1863and does not filter its standard error, so you will usually see lots of 1864spurious messages. 1865 1866 1867File: tar.info, Node: label, Next: verify, Prev: Using Multiple Tapes, Up: Media 1868 18699.7 Including a Label in the Archive 1870==================================== 1871 1872 _(This message will disappear, once this node revised.)_ 1873 1874To avoid problems caused by misplaced paper labels on the archive 1875media, you can include a "label" entry--an archive member which 1876contains the name of the archive--in the archive itself. Use the 1877`--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') option in conjunction with 1878the `--create' operation to include a label entry in the archive as it 1879is being created. 1880 1881`--label=ARCHIVE-LABEL' 1882`-V ARCHIVE-LABEL' 1883 Includes an "archive-label" at the beginning of the archive when 1884 the archive is being created, when used in conjunction with the 1885 `--create' operation. Checks to make sure the archive label 1886 matches the one specified (when used in conjunction with any other 1887 operation. 1888 1889 If you create an archive using both `--label=ARCHIVE-LABEL' (`-V 1890ARCHIVE-LABEL') and `--multi-volume' (`-M'), each volume of the archive 1891will have an archive label of the form `ARCHIVE-LABEL Volume N', where 1892N is 1 for the first volume, 2 for the next, and so on. *Note Using 1893Multiple Tapes::, for information on creating multiple volume archives. 1894 1895 The volume label will be displayed by `--list' along with the file 1896contents. If verbose display is requested, it will also be explicitly 1897marked as in the example below: 1898 1899 $ tar --verbose --list --file=iamanarchive 1900 V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header-- 1901 -rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename 1902 1903 However, `--list' option will cause listing entire contents of the 1904archive, which may be undesirable (for example, if the archive is 1905stored on a tape). You can request checking only the volume by 1906specifying `--test-label' option. This option reads only the first 1907block of an archive, so it can be used with slow storage devices. For 1908example: 1909 1910 $ tar --test-label --file=iamanarchive 1911 iamalabel 1912 1913 If `--test-label' is used with a single command line argument, `tar' 1914compares the volume label with the argument. It exits with code 0 if 1915the two strings match, and with code 2 otherwise. In this case no 1916output is displayed. For example: 1917 1918 $ tar --test-label --file=iamanarchive 'iamalable' 1919 => 0 1920 $ tar --test-label --file=iamanarchive 'iamalable' alabel 1921 => 1 1922 1923 If you request any operation, other than `--create', along with 1924using `--label' option, `tar' will first check if the archive label 1925matches the one specified and will refuse to proceed if it does not. 1926Use this as a safety precaution to avoid accidentally overwriting 1927existing archives. For example, if you wish to add files to `archive', 1928presumably labeled with string `My volume', you will get: 1929 1930 $ tar -rf archive --label 'My volume' . 1931 tar: Archive not labeled to match `My volume' 1932 1933in case its label does not match. This will work even if `archive' is 1934not labeled at all. 1935 1936 Similarly, `tar' will refuse to list or extract the archive if its 1937label doesn't match the ARCHIVE-LABEL specified. In those cases, 1938ARCHIVE-LABEL argument is interpreted as a globbing-style pattern which 1939must match the actual magnetic volume label. *Note exclude::, for a 1940precise description of how match is attempted(1). If the switch 1941`--multi-volume' (`-M') is being used, the volume label matcher will 1942also suffix ARCHIVE-LABEL by ` Volume [1-9]*' if the initial match 1943fails, before giving up. Since the volume numbering is automatically 1944added in labels at creation time, it sounded logical to equally help 1945the user taking care of it when the archive is being read. 1946 1947 The `--label' was once called `--volume', but is not available under 1948that name anymore. 1949 1950 You can also use `--label' to get a common information on all tapes 1951of a series. For having this information different in each series 1952created through a single script used on a regular basis, just manage to 1953get some date string as part of the label. For example: 1954 1955 $ tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`" 1956 $ tar --create --file=/dev/tape --multi-volume \ 1957 --volume="Daily backup for `date +%Y-%m-%d`" 1958 1959 Also note that each label has its own date and time, which 1960corresponds to when GNU `tar' initially attempted to write it, often 1961soon after the operator launches `tar' or types the carriage return 1962telling that the next tape is ready. Comparing date labels does give 1963an idea of tape throughput only if the delays for rewinding tapes and 1964the operator switching them were negligible, which is usually not the 1965case. 1966 1967 ---------- Footnotes ---------- 1968 1969 (1) Previous versions of `tar' used full regular expression 1970matching, or before that, only exact string matching, instead of 1971wildcard matchers. We decided for the sake of simplicity to use a 1972uniform matching device through `tar'. 1973 1974 1975File: tar.info, Node: verify, Next: Write Protection, Prev: label, Up: Media 1976 19779.8 Verifying Data as It is Stored 1978================================== 1979 1980`-W' 1981`--verify' 1982 Attempt to verify the archive after writing. 1983 1984 This option causes `tar' to verify the archive after writing it. 1985Each volume is checked after it is written, and any discrepancies are 1986recorded on the standard error output. 1987 1988 Verification requires that the archive be on a back-space-able 1989medium. This means pipes, some cartridge tape drives, and some other 1990devices cannot be verified. 1991 1992 You can insure the accuracy of an archive by comparing files in the 1993system with archive members. `tar' can compare an archive to the file 1994system as the archive is being written, to verify a write operation, or 1995can compare a previously written archive, to insure that it is up to 1996date. 1997 1998 To check for discrepancies in an archive immediately after it is 1999written, use the `--verify' (`-W') option in conjunction with the 2000`--create' operation. When this option is specified, `tar' checks 2001archive members against their counterparts in the file system, and 2002reports discrepancies on the standard error. 2003 2004 To verify an archive, you must be able to read it from before the end 2005of the last written entry. This option is useful for detecting data 2006errors on some tapes. Archives written to pipes, some cartridge tape 2007drives, and some other devices cannot be verified. 2008 2009 One can explicitly compare an already made archive with the file 2010system by using the `--compare' (`--diff', `-d') option, instead of 2011using the more automatic `--verify' option. *Note compare::. 2012 2013 Note that these two options have a slightly different intent. The 2014`--compare' option checks how identical are the logical contents of some 2015archive with what is on your disks, while the `--verify' option is 2016really for checking if the physical contents agree and if the recording 2017media itself is of dependable quality. So, for the `--verify' 2018operation, `tar' tries to defeat all in-memory cache pertaining to the 2019archive, while it lets the speed optimization undisturbed for the 2020`--compare' option. If you nevertheless use `--compare' for media 2021verification, you may have to defeat the in-memory cache yourself, 2022maybe by opening and reclosing the door latch of your recording unit, 2023forcing some doubt in your operating system about the fact this is 2024really the same volume as the one just written or read. 2025 2026 The `--verify' option would not be necessary if drivers were indeed 2027able to detect dependably all write failures. This sometimes require 2028many magnetic heads, some able to read after the writes occurred. One 2029would not say that drivers unable to detect all cases are necessarily 2030flawed, as long as programming is concerned. 2031 2032 The `--verify' (`-W') option will not work in conjunction with the 2033`--multi-volume' (`-M') option or the `--append' (`-r'), `--update' 2034(`-u') and `--delete' operations. *Note Operations::, for more 2035information on these operations. 2036 2037 Also, since `tar' normally strips leading `/' from file names (*note 2038absolute::), a command like `tar --verify -cf /tmp/foo.tar /etc' will 2039work as desired only if the working directory is `/', as `tar' uses the 2040archive's relative member names (e.g., `etc/motd') when verifying the 2041archive. 2042 2043 2044File: tar.info, Node: Write Protection, Prev: verify, Up: Media 2045 20469.9 Write Protection 2047==================== 2048 2049Almost all tapes and diskettes, and in a few rare cases, even disks can 2050be "write protected", to protect data on them from being changed. Once 2051an archive is written, you should write protect the media to prevent 2052the archive from being accidentally overwritten or deleted. (This will 2053protect the archive from being changed with a tape or floppy drive--it 2054will not protect it from magnet fields or other physical hazards). 2055 2056 The write protection device itself is usually an integral part of the 2057physical media, and can be a two position (write enabled/write 2058disabled) switch, a notch which can be popped out or covered, a ring 2059which can be removed from the center of a tape reel, or some other 2060changeable feature. 2061 2062 2063File: tar.info, Node: Changes, Next: Configuring Help Summary, Prev: Media, Up: Top 2064 2065Appendix A Changes 2066****************** 2067 2068This appendix lists some important user-visible changes between version 2069GNU `tar' 1.17 and previous versions. An up-to-date version of this 2070document is available at the GNU `tar' documentation page 2071(http://www.gnu.org/software/tar/manual/changes.html). 2072 2073Use of globbing patterns when listing and extracting. 2074 Previous versions of GNU tar assumed shell-style globbing when 2075 extracting from or listing an archive. For example: 2076 2077 $ tar xf foo.tar '*.c' 2078 2079 would extract all files whose names end in `.c'. This behavior 2080 was not documented and was incompatible with traditional tar 2081 implementations. Therefore, starting from version 1.15.91, GNU tar 2082 no longer uses globbing by default. For example, the above 2083 invocation is now interpreted as a request to extract from the 2084 archive the file named `*.c'. 2085 2086 To facilitate transition to the new behavior for those users who 2087 got used to the previous incorrect one, `tar' will print a warning 2088 if it finds out that a requested member was not found in the 2089 archive and its name looks like a globbing pattern. For example: 2090 2091 $ tar xf foo.tar '*.c' 2092 tar: Pattern matching characters used in file names. Please, 2093 tar: use --wildcards to enable pattern matching, or --no-wildcards to 2094 tar: suppress this warning. 2095 tar: *.c: Not found in archive 2096 tar: Error exit delayed from previous errors 2097 2098 To treat member names as globbing patterns, use -wildcards option. 2099 If you want to tar to mimic the behavior of versions prior to 2100 1.15.91, add this option to your `TAR_OPTIONS' variable. 2101 2102 *Note wildcards::, for the detailed discussion of the use of 2103 globbing patterns by GNU `tar'. 2104 2105Use of short option `-o'. 2106 Earlier versions of GNU `tar' understood `-o' command line option 2107 as a synonym for `--old-archive'. 2108 2109 GNU `tar' starting from version 1.13.90 understands this option as 2110 a synonym for `--no-same-owner'. This is compatible with UNIX98 2111 `tar' implementations. 2112 2113 However, to facilitate transition, `-o' option retains its old 2114 semantics when it is used with one of archive-creation commands. 2115 Users are encouraged to use `--format=oldgnu' instead. 2116 2117 It is especially important, since versions of GNU Automake up to 2118 and including 1.8.4 invoke tar with this option to produce 2119 distribution tarballs. *Note v7: Formats, for the detailed 2120 discussion of this issue and its implications. 2121 2122 . *Note tar-v7: (automake)Options, for a description on how to 2123 use various archive formats with `automake'. 2124 2125 Future versions of GNU `tar' will understand `-o' only as a 2126 synonym for `--no-same-owner'. 2127 2128Use of short option `-l' 2129 Earlier versions of GNU `tar' understood `-l' option as a synonym 2130 for `--one-file-system'. Since such usage contradicted to UNIX98 2131 specification and harmed compatibility with other implementation, 2132 it was declared deprecated in version 1.14. However, to 2133 facilitate transition to its new semantics, it was supported by 2134 versions 1.15 and 1.15.90. The present use of `-l' as a short 2135 variant of `--check-links' was introduced in version 1.15.91. 2136 2137Use of options `--portability' and `--old-archive' 2138 These options are deprecated. Please use `--format=v7' instead. 2139 2140Use of option `--posix' 2141 This option is deprecated. Please use `--format=posix' instead. 2142 2143 2144File: tar.info, Node: Configuring Help Summary, Next: Tar Internals, Prev: Changes, Up: Top 2145 2146Appendix B Configuring Help Summary 2147*********************************** 2148 2149Running `tar --help' displays the short `tar' option summary (*note 2150help::). This summary is organized by "groups" of semantically close 2151options. The options within each group are printed in the following 2152order: a short option, eventually followed by a list of corresponding 2153long option names, followed by a short description of the option. For 2154example, here is an excerpt from the actual `tar --help' output: 2155 2156 2157 Main operation mode: 2158 2159 -A, --catenate, --concatenate append tar files to an archive 2160 -c, --create create a new archive 2161 -d, --diff, --compare find differences between archive and 2162 file system 2163 --delete delete from the archive 2164 2165 The exact visual representation of the help output is configurable 2166via `ARGP_HELP_FMT' environment variable. The value of this variable is 2167a comma-separated list of "format variable" assignments. There are two 2168kinds of format variables. An "offset variable" keeps the offset of 2169some part of help output text from the leftmost column on the screen. A 2170"boolean" variable is a flag that toggles some output feature on or 2171off. Depending on the type of the corresponding variable, there are two 2172kinds of assignments: 2173 2174Offset assignment 2175 The assignment to an offset variable has the following syntax: 2176 2177 VARIABLE=VALUE 2178 2179 where VARIABLE is the variable name, and VALUE is a numeric value 2180 to be assigned to the variable. 2181 2182Boolean assignment 2183 To assign `true' value to a variable, simply put this variable 2184 name. To assign `false' value, prefix the variable name with 2185 `no-'. For example: 2186 2187 # Assign `true' value: 2188 dup-args 2189 # Assign `false' value: 2190 no-dup-args 2191 2192 Following variables are declared: 2193 2194 -- Help Output: boolean dup-args 2195 If true, arguments for an option are shown with both short and long 2196 options, even when a given option has both forms, for example: 2197 2198 -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE 2199 2200 If false, then if an option has both short and long forms, the 2201 argument is only shown with the long one, for example: 2202 2203 -f, --file=ARCHIVE use archive file or device ARCHIVE 2204 2205 and a message indicating that the argument is applicable to both 2206 forms is printed below the options. This message can be disabled 2207 using `dup-args-note' (see below). 2208 2209 The default is false. 2210 2211 -- Help Output: boolean dup-args-note 2212 If this variable is true, which is the default, the following 2213 notice is displayed at the end of the help output: 2214 2215 Mandatory or optional arguments to long options are also 2216 mandatory or optional for any corresponding short options. 2217 2218 Setting `no-dup-args-note' inhibits this message. Normally, only 2219 one of variables `dup-args' or `dup-args-note' should be set. 2220 2221 -- Help Output: offset short-opt-col 2222 Column in which short options start. Default is 2. 2223 2224 $ tar --help|grep ARCHIVE 2225 -f, --file=ARCHIVE use archive file or device ARCHIVE 2226 $ ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE 2227 -f, --file=ARCHIVE use archive file or device ARCHIVE 2228 2229 -- Help Output: offset long-opt-col 2230 Column in which long options start. Default is 6. For example: 2231 2232 $ tar --help|grep ARCHIVE 2233 -f, --file=ARCHIVE use archive file or device ARCHIVE 2234 $ ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE 2235 -f, --file=ARCHIVE use archive file or device ARCHIVE 2236 2237 -- Help Output: offset doc-opt-col 2238 Column in which "doc options" start. A doc option isn't actually 2239 an option, but rather an arbitrary piece of documentation that is 2240 displayed in much the same manner as the options. For example, in 2241 the description of `--format' option: 2242 2243 -H, --format=FORMAT create archive of the given format. 2244 2245 FORMAT is one of the following: 2246 2247 gnu GNU tar 1.13.x format 2248 oldgnu GNU format as per tar <= 1.12 2249 pax POSIX 1003.1-2001 (pax) format 2250 posix same as pax 2251 ustar POSIX 1003.1-1988 (ustar) format 2252 v7 old V7 tar format 2253 2254 the format names are doc options. Thus, if you set 2255 `ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output 2256 will look as follows: 2257 2258 -H, --format=FORMAT create archive of the given format. 2259 2260 FORMAT is one of the following: 2261 2262 gnu GNU tar 1.13.x format 2263 oldgnu GNU format as per tar <= 1.12 2264 pax POSIX 1003.1-2001 (pax) format 2265 posix same as pax 2266 ustar POSIX 1003.1-1988 (ustar) format 2267 v7 old V7 tar format 2268 2269 -- Help Output: offset opt-doc-col 2270 Column in which option description starts. Default is 29. 2271 2272 $ tar --help|grep ARCHIVE 2273 -f, --file=ARCHIVE use archive file or device ARCHIVE 2274 $ ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE 2275 -f, --file=ARCHIVE use archive file or device ARCHIVE 2276 $ ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE 2277 -f, --file=ARCHIVE 2278 use archive file or device ARCHIVE 2279 2280 Notice, that the description starts on a separate line if 2281 `opt-doc-col' value is too small. 2282 2283 -- Help Output: offset header-col 2284 Column in which "group headers" are printed. A group header is a 2285 descriptive text preceding an option group. For example, in the 2286 following text: 2287 2288 2289 Main operation mode: 2290 2291 -A, --catenate, --concatenate append tar files to 2292 an archive 2293 -c, --create create a new archive 2294 `Main operation mode:' is the group header. 2295 2296 The default value is 1. 2297 2298 -- Help Output: offset usage-indent 2299 Indentation of wrapped usage lines. Affects `--usage' output. 2300 Default is 12. 2301 2302 -- Help Output: offset rmargin 2303 Right margin of the text output. Used for wrapping. 2304 2305 2306File: tar.info, Node: Tar Internals, Next: Genfile, Prev: Configuring Help Summary, Up: Top 2307 2308Appendix C Tar Internals 2309************************ 2310 2311* Menu: 2312 2313* Standard:: Basic Tar Format 2314* Extensions:: GNU Extensions to the Archive Format 2315* Sparse Formats:: Storing Sparse Files 2316* Snapshot Files:: 2317* Dumpdir:: 2318 2319 2320File: tar.info, Node: Standard, Next: Extensions, Up: Tar Internals 2321 2322Basic Tar Format 2323================ 2324 2325 _(This message will disappear, once this node revised.)_ 2326 2327While an archive may contain many files, the archive itself is a single 2328ordinary file. Like any other file, an archive file can be written to 2329a storage device such as a tape or disk, sent through a pipe or over a 2330network, saved on the active file system, or even stored in another 2331archive. An archive file is not easy to read or manipulate without 2332using the `tar' utility or Tar mode in GNU Emacs. 2333 2334 Physically, an archive consists of a series of file entries 2335terminated by an end-of-archive entry, which consists of two 512 blocks 2336of zero bytes. A file entry usually describes one of the files in the 2337archive (an "archive member"), and consists of a file header and the 2338contents of the file. File headers contain file names and statistics, 2339checksum information which `tar' uses to detect file corruption, and 2340information about file types. 2341 2342 Archives are permitted to have more than one member with the same 2343member name. One way this situation can occur is if more than one 2344version of a file has been stored in the archive. For information 2345about adding new versions of a file to an archive, see *note update::. 2346 2347 In addition to entries describing archive members, an archive may 2348contain entries which `tar' itself uses to store information. *Note 2349label::, for an example of such an archive entry. 2350 2351 A `tar' archive file contains a series of blocks. Each block 2352contains `BLOCKSIZE' bytes. Although this format may be thought of as 2353being on magnetic tape, other media are often used. 2354 2355 Each file archived is represented by a header block which describes 2356the file, followed by zero or more blocks which give the contents of 2357the file. At the end of the archive file there are two 512-byte blocks 2358filled with binary zeros as an end-of-file marker. A reasonable system 2359should write such end-of-file marker at the end of an archive, but must 2360not assume that such a block exists when reading an archive. In 2361particular GNU `tar' always issues a warning if it does not encounter 2362it. 2363 2364 The blocks may be "blocked" for physical I/O operations. Each 2365record of N blocks (where N is set by the `--blocking-factor=512-SIZE' 2366(`-b 512-SIZE') option to `tar') is written with a single `write ()' 2367operation. On magnetic tapes, the result of such a write is a single 2368record. When writing an archive, the last record of blocks should be 2369written at the full size, with blocks after the zero block containing 2370all zeros. When reading an archive, a reasonable system should 2371properly handle an archive whose last record is shorter than the rest, 2372or which contains garbage records after a zero block. 2373 2374 The header block is defined in C as follows. In the GNU `tar' 2375distribution, this is part of file `src/tar.h': 2376 2377 2378 /* tar Header Block, from POSIX 1003.1-1990. */ 2379 2380 /* POSIX header. */ 2381 2382 struct posix_header 2383 { /* byte offset */ 2384 char name[100]; /* 0 */ 2385 char mode[8]; /* 100 */ 2386 char uid[8]; /* 108 */ 2387 char gid[8]; /* 116 */ 2388 char size[12]; /* 124 */ 2389 char mtime[12]; /* 136 */ 2390 char chksum[8]; /* 148 */ 2391 char typeflag; /* 156 */ 2392 char linkname[100]; /* 157 */ 2393 char magic[6]; /* 257 */ 2394 char version[2]; /* 263 */ 2395 char uname[32]; /* 265 */ 2396 char gname[32]; /* 297 */ 2397 char devmajor[8]; /* 329 */ 2398 char devminor[8]; /* 337 */ 2399 char prefix[155]; /* 345 */ 2400 /* 500 */ 2401 }; 2402 2403 #define TMAGIC "ustar" /* ustar and a null */ 2404 #define TMAGLEN 6 2405 #define TVERSION "00" /* 00 and no null */ 2406 #define TVERSLEN 2 2407 2408 /* Values used in typeflag field. */ 2409 #define REGTYPE '0' /* regular file */ 2410 #define AREGTYPE '\0' /* regular file */ 2411 #define LNKTYPE '1' /* link */ 2412 #define SYMTYPE '2' /* reserved */ 2413 #define CHRTYPE '3' /* character special */ 2414 #define BLKTYPE '4' /* block special */ 2415 #define DIRTYPE '5' /* directory */ 2416 #define FIFOTYPE '6' /* FIFO special */ 2417 #define CONTTYPE '7' /* reserved */ 2418 2419 #define XHDTYPE 'x' /* Extended header referring to the 2420 next file in the archive */ 2421 #define XGLTYPE 'g' /* Global extended header */ 2422 2423 /* Bits used in the mode field, values in octal. */ 2424 #define TSUID 04000 /* set UID on execution */ 2425 #define TSGID 02000 /* set GID on execution */ 2426 #define TSVTX 01000 /* reserved */ 2427 /* file permissions */ 2428 #define TUREAD 00400 /* read by owner */ 2429 #define TUWRITE 00200 /* write by owner */ 2430 #define TUEXEC 00100 /* execute/search by owner */ 2431 #define TGREAD 00040 /* read by group */ 2432 #define TGWRITE 00020 /* write by group */ 2433 #define TGEXEC 00010 /* execute/search by group */ 2434 #define TOREAD 00004 /* read by other */ 2435 #define TOWRITE 00002 /* write by other */ 2436 #define TOEXEC 00001 /* execute/search by other */ 2437 2438 /* tar Header Block, GNU extensions. */ 2439 2440 /* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for 2441 contiguous files, so maybe disobeying the `reserved' comment in POSIX 2442 header description. I suspect these were meant to be used this way, and 2443 should not have really been `reserved' in the published standards. */ 2444 2445 /* *BEWARE* *BEWARE* *BEWARE* that the following information is still 2446 boiling, and may change. Even if the OLDGNU format description should be 2447 accurate, the so-called GNU format is not yet fully decided. It is 2448 surely meant to use only extensions allowed by POSIX, but the sketch 2449 below repeats some ugliness from the OLDGNU format, which should rather 2450 go away. Sparse files should be saved in such a way that they do *not* 2451 require two passes at archive creation time. Huge files get some POSIX 2452 fields to overflow, alternate solutions have to be sought for this. */ 2453 2454 /* Descriptor for a single file hole. */ 2455 2456 struct sparse 2457 { /* byte offset */ 2458 char offset[12]; /* 0 */ 2459 char numbytes[12]; /* 12 */ 2460 /* 24 */ 2461 }; 2462 2463 /* Sparse files are not supported in POSIX ustar format. For sparse files 2464 with a POSIX header, a GNU extra header is provided which holds overall 2465 sparse information and a few sparse descriptors. When an old GNU header 2466 replaces both the POSIX header and the GNU extra header, it holds some 2467 sparse descriptors too. Whether POSIX or not, if more sparse descriptors 2468 are still needed, they are put into as many successive sparse headers as 2469 necessary. The following constants tell how many sparse descriptors fit 2470 in each kind of header able to hold them. */ 2471 2472 #define SPARSES_IN_EXTRA_HEADER 16 2473 #define SPARSES_IN_OLDGNU_HEADER 4 2474 #define SPARSES_IN_SPARSE_HEADER 21 2475 2476 /* Extension header for sparse files, used immediately after the GNU extra 2477 header, and used only if all sparse information cannot fit into that 2478 extra header. There might even be many such extension headers, one after 2479 the other, until all sparse information has been recorded. */ 2480 2481 struct sparse_header 2482 { /* byte offset */ 2483 struct sparse sp[SPARSES_IN_SPARSE_HEADER]; 2484 /* 0 */ 2485 char isextended; /* 504 */ 2486 /* 505 */ 2487 }; 2488 2489 /* The old GNU format header conflicts with POSIX format in such a way that 2490 POSIX archives may fool old GNU tar's, and POSIX tar's might well be 2491 fooled by old GNU tar archives. An old GNU format header uses the space 2492 used by the prefix field in a POSIX header, and cumulates information 2493 normally found in a GNU extra header. With an old GNU tar header, we 2494 never see any POSIX header nor GNU extra header. Supplementary sparse 2495 headers are allowed, however. */ 2496 2497 struct oldgnu_header 2498 { /* byte offset */ 2499 char unused_pad1[345]; /* 0 */ 2500 char atime[12]; /* 345 Incr. archive: atime of the file */ 2501 char ctime[12]; /* 357 Incr. archive: ctime of the file */ 2502 char offset[12]; /* 369 Multivolume archive: the offset of 2503 the start of this volume */ 2504 char longnames[4]; /* 381 Not used */ 2505 char unused_pad2; /* 385 */ 2506 struct sparse sp[SPARSES_IN_OLDGNU_HEADER]; 2507 /* 386 */ 2508 char isextended; /* 482 Sparse file: Extension sparse header 2509 follows */ 2510 char realsize[12]; /* 483 Sparse file: Real size*/ 2511 /* 495 */ 2512 }; 2513 2514 /* OLDGNU_MAGIC uses both magic and version fields, which are contiguous. 2515 Found in an archive, it indicates an old GNU header format, which will be 2516 hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are 2517 valid, though the header is not truly POSIX conforming. */ 2518 #define OLDGNU_MAGIC "ustar " /* 7 chars and a null */ 2519 2520 /* The standards committee allows only capital A through capital Z for 2521 user-defined expansion. Other letters in use include: 2522 2523 'A' Solaris Access Control List 2524 'E' Solaris Extended Attribute File 2525 'I' Inode only, as in 'star' 2526 'N' Obsolete GNU tar, for file names that do not fit into the main header. 2527 'X' POSIX 1003.1-2001 eXtended (VU version) */ 2528 2529 /* This is a dir entry that contains the names of files that were in the 2530 dir at the time the dump was made. */ 2531 #define GNUTYPE_DUMPDIR 'D' 2532 2533 /* Identifies the *next* file on the tape as having a long linkname. */ 2534 #define GNUTYPE_LONGLINK 'K' 2535 2536 /* Identifies the *next* file on the tape as having a long name. */ 2537 #define GNUTYPE_LONGNAME 'L' 2538 2539 /* This is the continuation of a file that began on another volume. */ 2540 #define GNUTYPE_MULTIVOL 'M' 2541 2542 /* This is for sparse files. */ 2543 #define GNUTYPE_SPARSE 'S' 2544 2545 /* This file is a tape/volume header. Ignore it on extraction. */ 2546 #define GNUTYPE_VOLHDR 'V' 2547 2548 /* Solaris extended header */ 2549 #define SOLARIS_XHDTYPE 'X' 2550 2551 /* Jo"rg Schilling star header */ 2552 2553 struct star_header 2554 { /* byte offset */ 2555 char name[100]; /* 0 */ 2556 char mode[8]; /* 100 */ 2557 char uid[8]; /* 108 */ 2558 char gid[8]; /* 116 */ 2559 char size[12]; /* 124 */ 2560 char mtime[12]; /* 136 */ 2561 char chksum[8]; /* 148 */ 2562 char typeflag; /* 156 */ 2563 char linkname[100]; /* 157 */ 2564 char magic[6]; /* 257 */ 2565 char version[2]; /* 263 */ 2566 char uname[32]; /* 265 */ 2567 char gname[32]; /* 297 */ 2568 char devmajor[8]; /* 329 */ 2569 char devminor[8]; /* 337 */ 2570 char prefix[131]; /* 345 */ 2571 char atime[12]; /* 476 */ 2572 char ctime[12]; /* 488 */ 2573 /* 500 */ 2574 }; 2575 2576 #define SPARSES_IN_STAR_HEADER 4 2577 #define SPARSES_IN_STAR_EXT_HEADER 21 2578 2579 struct star_in_header 2580 { 2581 char fill[345]; /* 0 Everything that is before t_prefix */ 2582 char prefix[1]; /* 345 t_name prefix */ 2583 char fill2; /* 346 */ 2584 char fill3[8]; /* 347 */ 2585 char isextended; /* 355 */ 2586 struct sparse sp[SPARSES_IN_STAR_HEADER]; /* 356 */ 2587 char realsize[12]; /* 452 Actual size of the file */ 2588 char offset[12]; /* 464 Offset of multivolume contents */ 2589 char atime[12]; /* 476 */ 2590 char ctime[12]; /* 488 */ 2591 char mfill[8]; /* 500 */ 2592 char xmagic[4]; /* 508 "tar" */ 2593 }; 2594 2595 struct star_ext_header 2596 { 2597 struct sparse sp[SPARSES_IN_STAR_EXT_HEADER]; 2598 char isextended; 2599 }; 2600 2601 All characters in header blocks are represented by using 8-bit 2602characters in the local variant of ASCII. Each field within the 2603structure is contiguous; that is, there is no padding used within the 2604structure. Each character on the archive medium is stored contiguously. 2605 2606 Bytes representing the contents of files (after the header block of 2607each file) are not translated in any way and are not constrained to 2608represent characters in any character set. The `tar' format does not 2609distinguish text files from binary files, and no translation of file 2610contents is performed. 2611 2612 The `name', `linkname', `magic', `uname', and `gname' are 2613null-terminated character strings. All other fields are zero-filled 2614octal numbers in ASCII. Each numeric field of width W contains W minus 26151 digits, and a null. 2616 2617 The `name' field is the file name of the file, with directory names 2618(if any) preceding the file name, separated by slashes. 2619 2620 The `mode' field provides nine bits specifying file permissions and 2621three bits to specify the Set UID, Set GID, and Save Text ("sticky") 2622modes. Values for these bits are defined above. When special 2623permissions are required to create a file with a given mode, and the 2624user restoring files from the archive does not hold such permissions, 2625the mode bit(s) specifying those special permissions are ignored. 2626Modes which are not supported by the operating system restoring files 2627from the archive will be ignored. Unsupported modes should be faked up 2628when creating or updating an archive; e.g., the group permission could 2629be copied from the _other_ permission. 2630 2631 The `uid' and `gid' fields are the numeric user and group ID of the 2632file owners, respectively. If the operating system does not support 2633numeric user or group IDs, these fields should be ignored. 2634 2635 The `size' field is the size of the file in bytes; linked files are 2636archived with this field specified as zero. 2637 2638 The `mtime' field is the data modification time of the file at the 2639time it was archived. It is the ASCII representation of the octal 2640value of the last time the file's contents were modified, represented 2641as an integer number of seconds since January 1, 1970, 00:00 2642Coordinated Universal Time. 2643 2644 The `chksum' field is the ASCII representation of the octal value of 2645the simple sum of all bytes in the header block. Each 8-bit byte in 2646the header is added to an unsigned integer, initialized to zero, the 2647precision of which shall be no less than seventeen bits. When 2648calculating the checksum, the `chksum' field is treated as if it were 2649all blanks. 2650 2651 The `typeflag' field specifies the type of file archived. If a 2652particular implementation does not recognize or permit the specified 2653type, the file will be extracted as if it were a regular file. As this 2654action occurs, `tar' issues a warning to the standard error. 2655 2656 The `atime' and `ctime' fields are used in making incremental 2657backups; they store, respectively, the particular file's access and 2658status change times. 2659 2660 The `offset' is used by the `--multi-volume' (`-M') option, when 2661making a multi-volume archive. The offset is number of bytes into the 2662file that we need to restart at to continue the file on the next tape, 2663i.e., where we store the location that a continued file is continued at. 2664 2665 The following fields were added to deal with sparse files. A file 2666is "sparse" if it takes in unallocated blocks which end up being 2667represented as zeros, i.e., no useful data. A test to see if a file is 2668sparse is to look at the number blocks allocated for it versus the 2669number of characters in the file; if there are fewer blocks allocated 2670for the file than would normally be allocated for a file of that size, 2671then the file is sparse. This is the method `tar' uses to detect a 2672sparse file, and once such a file is detected, it is treated 2673differently from non-sparse files. 2674 2675 Sparse files are often `dbm' files, or other database-type files 2676which have data at some points and emptiness in the greater part of the 2677file. Such files can appear to be very large when an `ls -l' is done 2678on them, when in truth, there may be a very small amount of important 2679data contained in the file. It is thus undesirable to have `tar' think 2680that it must back up this entire file, as great quantities of room are 2681wasted on empty blocks, which can lead to running out of room on a tape 2682far earlier than is necessary. Thus, sparse files are dealt with so 2683that these empty blocks are not written to the tape. Instead, what is 2684written to the tape is a description, of sorts, of the sparse file: 2685where the holes are, how big the holes are, and how much data is found 2686at the end of the hole. This way, the file takes up potentially far 2687less room on the tape, and when the file is extracted later on, it will 2688look exactly the way it looked beforehand. The following is a 2689description of the fields used to handle a sparse file: 2690 2691 The `sp' is an array of `struct sparse'. Each `struct sparse' 2692contains two 12-character strings which represent an offset into the 2693file and a number of bytes to be written at that offset. The offset is 2694absolute, and not relative to the offset in preceding array element. 2695 2696 The header can hold four of these `struct sparse' at the moment; if 2697more are needed, they are not stored in the header. 2698 2699 The `isextended' flag is set when an `extended_header' is needed to 2700deal with a file. Note that this means that this flag can only be set 2701when dealing with a sparse file, and it is only set in the event that 2702the description of the file will not fit in the allotted room for 2703sparse structures in the header. In other words, an extended_header is 2704needed. 2705 2706 The `extended_header' structure is used for sparse files which need 2707more sparse structures than can fit in the header. The header can fit 27084 such structures; if more are needed, the flag `isextended' gets set 2709and the next block is an `extended_header'. 2710 2711 Each `extended_header' structure contains an array of 21 sparse 2712structures, along with a similar `isextended' flag that the header had. 2713There can be an indeterminate number of such `extended_header's to 2714describe a sparse file. 2715 2716`REGTYPE' 2717`AREGTYPE' 2718 These flags represent a regular file. In order to be compatible 2719 with older versions of `tar', a `typeflag' value of `AREGTYPE' 2720 should be silently recognized as a regular file. New archives 2721 should be created using `REGTYPE'. Also, for backward 2722 compatibility, `tar' treats a regular file whose name ends with a 2723 slash as a directory. 2724 2725`LNKTYPE' 2726 This flag represents a file linked to another file, of any type, 2727 previously archived. Such files are identified in Unix by each 2728 file having the same device and inode number. The linked-to name 2729 is specified in the `linkname' field with a trailing null. 2730 2731`SYMTYPE' 2732 This represents a symbolic link to another file. The linked-to 2733 name is specified in the `linkname' field with a trailing null. 2734 2735`CHRTYPE' 2736`BLKTYPE' 2737 These represent character special files and block special files 2738 respectively. In this case the `devmajor' and `devminor' fields 2739 will contain the major and minor device numbers respectively. 2740 Operating systems may map the device specifications to their own 2741 local specification, or may ignore the entry. 2742 2743`DIRTYPE' 2744 This flag specifies a directory or sub-directory. The directory 2745 name in the `name' field should end with a slash. On systems where 2746 disk allocation is performed on a directory basis, the `size' field 2747 will contain the maximum number of bytes (which may be rounded to 2748 the nearest disk block allocation unit) which the directory may 2749 hold. A `size' field of zero indicates no such limiting. Systems 2750 which do not support limiting in this manner should ignore the 2751 `size' field. 2752 2753`FIFOTYPE' 2754 This specifies a FIFO special file. Note that the archiving of a 2755 FIFO file archives the existence of this file and not its contents. 2756 2757`CONTTYPE' 2758 This specifies a contiguous file, which is the same as a normal 2759 file except that, in operating systems which support it, all its 2760 space is allocated contiguously on the disk. Operating systems 2761 which do not allow contiguous allocation should silently treat this 2762 type as a normal file. 2763 2764`A' ... `Z' 2765 These are reserved for custom implementations. Some of these are 2766 used in the GNU modified format, as described below. 2767 2768 2769 Other values are reserved for specification in future revisions of 2770the P1003 standard, and should not be used by any `tar' program. 2771 2772 The `magic' field indicates that this archive was output in the 2773P1003 archive format. If this field contains `TMAGIC', the `uname' and 2774`gname' fields will contain the ASCII representation of the owner and 2775group of the file respectively. If found, the user and group IDs are 2776used rather than the values in the `uid' and `gid' fields. 2777 2778 For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, 2779pages 169-173 (section 10.1) for `Archive/Interchange File Format'; and 2780IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940 2781(section E.4.48) for `pax - Portable archive interchange'. 2782 2783 2784File: tar.info, Node: Extensions, Next: Sparse Formats, Prev: Standard, Up: Tar Internals 2785 2786GNU Extensions to the Archive Format 2787==================================== 2788 2789 _(This message will disappear, once this node revised.)_ 2790 2791The GNU format uses additional file types to describe new types of 2792files in an archive. These are listed below. 2793 2794`GNUTYPE_DUMPDIR' 2795`'D'' 2796 This represents a directory and a list of files created by the 2797 `--incremental' (`-G') option. The `size' field gives the total 2798 size of the associated list of files. Each file name is preceded 2799 by either a `Y' (the file should be in this archive) or an `N'. 2800 (The file is a directory, or is not stored in the archive.) Each 2801 file name is terminated by a null. There is an additional null 2802 after the last file name. 2803 2804`GNUTYPE_MULTIVOL' 2805`'M'' 2806 This represents a file continued from another volume of a 2807 multi-volume archive created with the `--multi-volume' (`-M') 2808 option. The original type of the file is not given here. The 2809 `size' field gives the maximum size of this piece of the file 2810 (assuming the volume does not end before the file is written out). 2811 The `offset' field gives the offset from the beginning of the 2812 file where this part of the file begins. Thus `size' plus 2813 `offset' should equal the original size of the file. 2814 2815`GNUTYPE_SPARSE' 2816`'S'' 2817 This flag indicates that we are dealing with a sparse file. Note 2818 that archiving a sparse file requires special operations to find 2819 holes in the file, which mark the positions of these holes, along 2820 with the number of bytes of data to be found after the hole. 2821 2822`GNUTYPE_VOLHDR' 2823`'V'' 2824 This file type is used to mark the volume header that was given 2825 with the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') option when 2826 the archive was created. The `name' field contains the `name' 2827 given after the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') 2828 option. The `size' field is zero. Only the first file in each 2829 volume of an archive should have this type. 2830 2831 2832 You may have trouble reading a GNU format archive on a non-GNU 2833system if the options `--incremental' (`-G'), `--multi-volume' (`-M'), 2834`--sparse' (`-S'), or `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') were 2835used when writing the archive. In general, if `tar' does not use the 2836GNU-added fields of the header, other versions of `tar' should be able 2837to read the archive. Otherwise, the `tar' program will give an error, 2838the most likely one being a checksum error. 2839 2840 2841File: tar.info, Node: Sparse Formats, Next: Snapshot Files, Prev: Extensions, Up: Tar Internals 2842 2843Storing Sparse Files 2844==================== 2845 2846The notion of sparse file, and the ways of handling it from the point 2847of view of GNU `tar' user have been described in detail in *note 2848sparse::. This chapter describes the internal format GNU `tar' uses to 2849store such files. 2850 2851 The support for sparse files in GNU `tar' has a long history. The 2852earliest version featuring this support that I was able to find was 28531.09, released in November, 1990. The format introduced back then is 2854called "old GNU" sparse format and in spite of the fact that its design 2855contained many flaws, it was the only format GNU `tar' supported until 2856version 1.14 (May, 2004), which introduced initial support for sparse 2857archives in PAX archives (*note posix::). This format was not free 2858from design flows, either and it was subsequently improved in versions 28591.15.2 (November, 2005) and 1.15.92 (June, 2006). 2860 2861 In addition to GNU sparse format, GNU `tar' is able to read and 2862extract sparse files archived by `star'. 2863 2864 The following subsections describe each format in detail. 2865 2866* Menu: 2867 2868* Old GNU Format:: 2869* PAX 0:: PAX Format, Versions 0.0 and 0.1 2870* PAX 1:: PAX Format, Version 1.0 2871 2872 2873File: tar.info, Node: Old GNU Format, Next: PAX 0, Up: Sparse Formats 2874 2875C.0.1 Old GNU Format 2876-------------------- 2877 2878The format introduced some time around 1990 (v. 1.09). It was designed 2879on top of standard `ustar' headers in such an unfortunate way that some 2880of its fields overwrote fields required by POSIX. 2881 2882 An old GNU sparse header is designated by type `S' 2883(`GNUTYPE_SPARSE') and has the following layout: 2884 2885Offset Size Name Data type Contents 2886---------------------------------------------------------------------------- 28870 345 N/A Not used. 2888345 12 atime Number `atime' of the file. 2889357 12 ctime Number `ctime' of the file . 2890369 12 offset Number For multivolume archives: 2891 the offset of the start of 2892 this volume. 2893381 4 N/A Not used. 2894385 1 N/A Not used. 2895386 96 sp `sparse_header'(4 entries) File map. 2896482 1 isextended Bool `1' if an extension sparse 2897 header follows, `0' 2898 otherwise. 2899483 12 realsize Number Real size of the file. 2900 2901 Each of `sparse_header' object at offset 386 describes a single data 2902chunk. It has the following structure: 2903 2904Offset Size Data type Contents 2905--------------------------------------------------------------------------- 29060 12 Number Offset of the beginning of the chunk. 290712 12 Number Size of the chunk. 2908 2909 If the member contains more than four chunks, the `isextended' field 2910of the header has the value `1' and the main header is followed by one 2911or more "extension headers". Each such header has the following 2912structure: 2913 2914Offset Size Name Data type Contents 2915---------------------------------------------------------------------------- 29160 21 sp `sparse_header' (21 entires) File map. 2917504 1 isextended Bool `1' if an extension sparse 2918 header follows, or `0' 2919 otherwise. 2920 2921 A header with `isextended=0' ends the map. 2922 2923 2924File: tar.info, Node: PAX 0, Next: PAX 1, Prev: Old GNU Format, Up: Sparse Formats 2925 2926C.0.2 PAX Format, Versions 0.0 and 0.1 2927-------------------------------------- 2928 2929There are two formats available in this branch. The version `0.0' is 2930the initial version of sparse format used by `tar' versions 29311.14-1.15.1. The sparse file map is kept in extended (`x') PAX header 2932variables: 2933 2934`GNU.sparse.size' 2935 Real size of the stored file 2936 2937`GNU.sparse.numblocks' 2938 Number of blocks in the sparse map 2939 2940`GNU.sparse.offset' 2941 Offset of the data block 2942 2943`GNU.sparse.numbytes' 2944 Size of the data block 2945 2946 The latter two variables repeat for each data block, so the overall 2947structure is like this: 2948 2949 GNU.sparse.size=SIZE 2950 GNU.sparse.numblocks=NUMBLOCKS 2951 repeat NUMBLOCKS times 2952 GNU.sparse.offset=OFFSET 2953 GNU.sparse.numbytes=NUMBYTES 2954 end repeat 2955 2956 This format presented the following two problems: 2957 2958 1. Whereas the POSIX specification allows a variable to appear 2959 multiple times in a header, it requires that only the last 2960 occurrence be meaningful. Thus, multiple occurrences of 2961 `GNU.sparse.offset' and `GNU.sparse.numbytes' are conflicting with 2962 the POSIX specs. 2963 2964 2. Attempting to extract such archives using a third-party `tar's 2965 results in extraction of sparse files in _compressed form_. If 2966 the `tar' implementation in question does not support POSIX 2967 format, it will also extract a file containing extension header 2968 attributes. This file can be used to expand the file to its 2969 original state. However, posix-aware `tar's will usually ignore 2970 the unknown variables, which makes restoring the file more 2971 difficult. *Note Extraction of sparse members in v.0.0 format: 2972 extracting sparse v.0.x, for the detailed description of how to 2973 restore such members using non-GNU `tar's. 2974 2975 GNU `tar' 1.15.2 introduced sparse format version `0.1', which 2976attempted to solve these problems. As its predecessor, this format 2977stores sparse map in the extended POSIX header. It retains 2978`GNU.sparse.size' and `GNU.sparse.numblocks' variables, but instead of 2979`GNU.sparse.offset'/`GNU.sparse.numbytes' pairs it uses a single 2980variable: 2981 2982`GNU.sparse.map' 2983 Map of non-null data chunks. It is a string consisting of 2984 comma-separated values "OFFSET,SIZE[,OFFSET-1,SIZE-1...]" 2985 2986 To address the 2nd problem, the `name' field in `ustar' is replaced 2987with a special name, constructed using the following pattern: 2988 2989 %d/GNUSparseFile.%p/%f 2990 2991 The real name of the sparse file is stored in the variable 2992`GNU.sparse.name'. Thus, those `tar' implementations that are not 2993aware of GNU extensions will at least extract the files into separate 2994directories, giving the user a possibility to expand it afterwards. 2995*Note Extraction of sparse members in v.0.1 format: extracting sparse 2996v.0.x, for the detailed description of how to restore such members 2997using non-GNU `tar's. 2998 2999 The resulting `GNU.sparse.map' string can be _very_ long. Although 3000POSIX does not impose any limit on the length of a `x' header variable, 3001this possibly can confuse some tars. 3002 3003 3004File: tar.info, Node: PAX 1, Prev: PAX 0, Up: Sparse Formats 3005 3006C.0.3 PAX Format, Version 1.0 3007----------------------------- 3008 3009The version `1.0' of sparse format was introduced with GNU `tar' 30101.15.92. Its main objective was to make the resulting file extractable 3011with little effort even by non-posix aware `tar' implementations. 3012Starting from this version, the extended header preceding a sparse 3013member always contains the following variables that identify the format 3014being used: 3015 3016`GNU.sparse.major' 3017 Major version 3018 3019`GNU.sparse.minor' 3020 Minor version 3021 3022 The `name' field in `ustar' header contains a special name, 3023constructed using the following pattern: 3024 3025 %d/GNUSparseFile.%p/%f 3026 3027 The real name of the sparse file is stored in the variable 3028`GNU.sparse.name'. The real size of the file is stored in the variable 3029`GNU.sparse.realsize'. 3030 3031 The sparse map itself is stored in the file data block, preceding 3032the actual file data. It consists of a series of octal numbers of 3033arbitrary length, delimited by newlines. The map is padded with nulls 3034to the nearest block boundary. 3035 3036 The first number gives the number of entries in the map. Following 3037are map entries, each one consisting of two numbers giving the offset 3038and size of the data block it describes. 3039 3040 The format is designed in such a way that non-posix aware tars and 3041tars not supporting `GNU.sparse.*' keywords will extract each sparse 3042file in its condensed form with the file map prepended and will place it 3043into a separate directory. Then, using a simple program it would be 3044possible to expand the file to its original form even without GNU `tar'. 3045*Note Sparse Recovery::, for the detailed information on how to extract 3046sparse members without GNU `tar'. 3047 3048 3049File: tar.info, Node: Snapshot Files, Next: Dumpdir, Prev: Sparse Formats, Up: Tar Internals 3050 3051Format of the Incremental Snapshot Files 3052======================================== 3053 3054A "snapshot file" (or "directory file") is created during incremental 3055backups (*note Incremental Dumps::). It contains the status of the 3056file system at the time of the dump and is used to determine which 3057files were modified since the last backup. 3058 3059 GNU `tar' version 1.17 supports two snapshot file formats. The 3060first format, called "format 0", is the one used by GNU `tar' versions 3061up to 1.15.1. The second format, called "format 1" is an extended 3062version of this format, that contains more metadata and allows for 3063further extensions. 3064 3065 `Format 0' snapshot file begins with a line containing a decimal 3066number that represents the UNIX timestamp of the beginning of the last 3067archivation. This line is followed by directory metadata descriptions, 3068one per line. Each description has the following format: 3069 3070 [NFS]DEV INODE NAME 3071 3072where optional NFS is a single plus character (`+') if this directory 3073is located on an NFS-mounted partition, DEV and INODE are the device 3074and inode numbers of the directory, and NAME is the directory name. 3075 3076 `Format 1' snapshot file begins with a line specifying the format of 3077the file. This line has the following structure: 3078 3079 `GNU tar-'TAR-VERSION`-'INCR-FORMAT-VERSION 3080 3081where TAR-VERSION is the version of GNU `tar' implementation that 3082created this snapshot, and INCR-FORMAT-VERSION is the version number of 3083the snapshot format (in this case `1'). 3084 3085 The following line contains two decimal numbers, representing the 3086time of the last backup. First number is the number of seconds, the 3087second one is the number of nanoseconds, since the beginning of the 3088epoch. 3089 3090 Following lines contain directory metadata, one line per directory. 3091The line format is: 3092 3093 [NFS]MTIME-SEC MTIME-NSEC DEV INODE NAME 3094 3095where MTIME-SEC and MTIME-NSEC represent the last modification time of 3096this directory with nanosecond precision; NFS, DEV, INODE and NAME have 3097the same meaning as with `format 0'. 3098 3099 3100File: tar.info, Node: Dumpdir, Prev: Snapshot Files, Up: Tar Internals 3101 3102Dumpdir 3103======= 3104 3105Incremental archives keep information about contents of each dumped 3106directory in special data blocks called "dumpdirs". 3107 3108 Dumpdir is a sequence of entries of the following form: 3109 3110 C FILENAME \0 3111 3112where C is one of the "control codes" described below, FILENAME is the 3113name of the file C operates upon, and `\0' represents a nul character 3114(ASCII 0). The white space characters were added for readability, real 3115dumpdirs do not contain them. 3116 3117 Each dumpdir ends with a single nul character. 3118 3119 The following table describes control codes and their meanings: 3120 3121`Y' 3122 FILENAME is contained in the archive. 3123 3124`N' 3125 FILENAME was present in the directory at the time the archive was 3126 made, yet it was not dumped to the archive, because it had not 3127 changed since the last backup. 3128 3129`D' 3130 FILENAME is a directory. 3131 3132`R' 3133 This code requests renaming of the FILENAME to the name specified 3134 with the following `T' command. 3135 3136`T' 3137 Specify target file name for `R' command (see below). 3138 3139`X' 3140 Specify "temporary directory" name for a rename operation (see 3141 below). 3142 3143 Codes `Y', `N' and `D' require FILENAME argument to be a relative 3144file name to the directory this dumpdir describes, whereas codes `R', 3145`T' and `X' require their argument to be an absolute file name. 3146 3147 The three codes `R', `T' and `X' specify a "renaming operation". In 3148the simplest case it is: 3149 3150 R`source'\0T`dest'\0 3151 3152which means "rename file `source' to file `dest'". 3153 3154 However, there are cases that require using a "temporary directory". 3155For example, consider the following scenario: 3156 3157 1. Previous run dumped a directory `foo' which contained the 3158 following three directories: 3159 3160 a 3161 b 3162 c 3163 3164 2. They were renamed _cyclically_, so that: 3165 3166 `a' became `b' 3167 `b' became `c' 3168 `c' became `a' 3169 3170 3. New incremental dump was made. 3171 3172 This case cannot be handled by three successive renames, since 3173renaming `a' to `b' will destroy existing directory. To handle such 3174case a temporary directory is required. GNU `tar' will create the 3175following dumpdir (newlines have been added for readability): 3176 3177 Xfoo\0 3178 Rfoo/a\0T\0 3179 Rfoo/b\0Tfoo/c\0 3180 Rfoo/c\0Tfoo/a\0 3181 R\0Tfoo/a\0 3182 3183 The first command, `Xfoo\0', instructs the extractor to create a 3184temporary directory in the directory `foo'. Second command, 3185`Rfoo/aT\0', says "rename file `foo/a' to the temporary directory that 3186has just been created" (empty file name after a command means use 3187temporary directory). Third and fourth commands work as usual, and, 3188finally, the last command, `R\0Tfoo/a\0' tells tar to rename the 3189temporary directory to `foo/a'. 3190 3191 The exact placement of a dumpdir in the archive depends on the 3192archive format (*note Formats::): 3193 3194 * PAX archives 3195 3196 In PAX archives, dumpdir is stored in the extended header of the 3197 corresponding directory, in variable `GNU.dumpdir'. 3198 3199 * GNU and old GNU archives 3200 3201 These formats implement special header type `D', which is similar 3202 to ustar header `5' (directory), except that it precedes a data 3203 block containing the dumpdir. 3204 3205 3206File: tar.info, Node: Genfile, Next: Free Software Needs Free Documentation, Prev: Tar Internals, Up: Top 3207 3208Appendix D Genfile 3209****************** 3210 3211This appendix describes `genfile', an auxiliary program used in the GNU 3212tar testsuite. If you are not interested in developing GNU tar, skip 3213this appendix. 3214 3215 Initially, `genfile' was used to generate data files for the 3216testsuite, hence its name. However, new operation modes were being 3217implemented as the testsuite grew more sophisticated, and now `genfile' 3218is a multi-purpose instrument. 3219 3220 There are three basic operation modes: 3221 3222File Generation 3223 This is the default mode. In this mode, `genfile' generates data 3224 files. 3225 3226File Status 3227 In this mode `genfile' displays status of specified files. 3228 3229Synchronous Execution. 3230 In this mode `genfile' executes the given program with 3231 `--checkpoint' option and executes a set of actions when specified 3232 checkpoints are reached. 3233 3234* Menu: 3235 3236* Generate Mode:: File Generation Mode. 3237* Status Mode:: File Status Mode. 3238* Exec Mode:: Synchronous Execution mode. 3239 3240 3241File: tar.info, Node: Generate Mode, Next: Status Mode, Up: Genfile 3242 3243D.1 Generate Mode 3244================= 3245 3246In this mode `genfile' creates a data file for the test suite. The size 3247of the file is given with the `--length' (`-l') option. By default the 3248file contents is written to the standard output, this can be changed 3249using `--file' (`-f') command line option. Thus, the following two 3250commands are equivalent: 3251 3252 genfile --length 100 > outfile 3253 genfile --length 100 --file outfile 3254 3255 If `--length' is not given, `genfile' will generate an empty 3256(zero-length) file. 3257 3258 The command line option `--seek=N' istructs `genfile' to skip the 3259given number of bytes (N) in the output file before writing to it. It 3260is similar to the `seek=N' of the `dd' utility. 3261 3262 You can instruct `genfile' to create several files at one go, by 3263giving it `--files-from' (`-T') option followed by a name of file 3264containing a list of file names. Using dash (`-') instead of the file 3265name causes `genfile' to read file list from the standard input. For 3266example: 3267 3268 # Read file names from file `file.list' 3269 genfile --files-from file.list 3270 # Read file names from standard input 3271 genfile --files-from - 3272 3273 The list file is supposed to contain one file name per line. To use 3274file lists separated by ASCII NUL character, use `--null' (`-0') 3275command line option: 3276 3277 genfile --null --files-from file.list 3278 3279 The default data pattern for filling the generated file consists of 3280first 256 letters of ASCII code, repeated enough times to fill the 3281entire file. This behavior can be changed with `--pattern' option. This 3282option takes a mandatory argument, specifying pattern name to use. 3283Currently two patterns are implemented: 3284 3285`--pattern=default' 3286 The default pattern as described above. 3287 3288`--pattern=zero' 3289 Fills the file with zeroes. 3290 3291 If no file name was given, the program exits with the code `0'. 3292Otherwise, it exits with `0' only if it was able to create a file of 3293the specified length. 3294 3295 Special option `--sparse' (`-s') instructs `genfile' to create a 3296sparse file. Sparse files consist of "data fragments", separated by 3297"holes" or blocks of zeros. On many operating systems, actual disk 3298storage is not allocated for holes, but they are counted in the length 3299of the file. To create a sparse file, `genfile' should know where to 3300put data fragments, and what data to use to fill them. So, when 3301`--sparse' is given the rest of the command line specifies a so-called 3302"file map". 3303 3304 The file map consists of any number of "fragment descriptors". Each 3305descriptor is composed of two values: a number, specifying fragment 3306offset from the end of the previous fragment or, for the very first 3307fragment, from the beginning of the file, and "contents string", i.e., 3308a string of characters, specifying the pattern to fill the fragment 3309with. File offset can be suffixed with the following quantifiers: 3310 3311`k' 3312`K' 3313 The number is expressed in kilobytes. 3314 3315`m' 3316`M' 3317 The number is expressed in megabytes. 3318 3319`g' 3320`G' 3321 The number is expressed in gigabytes. 3322 3323 For each letter in contents string `genfile' will generate a "block" 3324of data, filled with this letter and will write it to the fragment. The 3325size of block is given by `--block-size' option. It defaults to 512. 3326Thus, if the string consists of N characters, the resulting file 3327fragment will contain `N*BLOCK-SIZE' of data. 3328 3329 Last fragment descriptor can have only file offset part. In this 3330case `genfile' will create a hole at the end of the file up to the 3331given offset. 3332 3333 For example, consider the following invocation: 3334 3335 genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K 3336 3337It will create 3101184-bytes long file of the following structure: 3338 3339Offset Length Contents 33400 4*512=2048 Four 512-byte blocks, filled 3341 with letters `A', `B', `C' and 3342 `D'. 33432048 1046528 Zero bytes 33441050624 5*512=2560 Five blocks, filled with letters 3345 `E', `F', `G', `H', `I'. 33461053184 2048000 Zero bytes 3347 3348 The exit code of `genfile --status' command is `0' only if created 3349file is actually sparse. 3350 3351 3352File: tar.info, Node: Status Mode, Next: Exec Mode, Prev: Generate Mode, Up: Genfile 3353 3354D.2 Status Mode 3355=============== 3356 3357In status mode, `genfile' prints file system status for each file 3358specified in the command line. This mode is toggled by `--stat' (`-S') 3359command line option. An optional argument to this option specifies 3360output "format": a comma-separated list of `struct stat' fields to be 3361displayed. This list can contain following identifiers : 3362 3363name 3364 The file name. 3365 3366dev 3367st_dev 3368 Device number in decimal. 3369 3370ino 3371st_ino 3372 Inode number. 3373 3374mode[.NUMBER] 3375st_mode[.NUMBER] 3376 File mode in octal. Optional NUMBER specifies octal mask to be 3377 applied to the mode before outputting. For example, `--stat 3378 mode.777' will preserve lower nine bits of it. Notice, that you 3379 can use any punctuation character in place of `.'. 3380 3381nlink 3382st_nlink 3383 Number of hard links. 3384 3385uid 3386st_uid 3387 User ID of owner. 3388 3389gid 3390st_gid 3391 Group ID of owner. 3392 3393size 3394st_size 3395 File size in decimal. 3396 3397blksize 3398st_blksize 3399 The size in bytes of each file block. 3400 3401blocks 3402st_blocks 3403 Number of blocks allocated. 3404 3405atime 3406st_atime 3407 Time of last access. 3408 3409mtime 3410st_mtime 3411 Time of last modification 3412 3413ctime 3414st_ctime 3415 Time of last status change 3416 3417sparse 3418 A boolean value indicating whether the file is `sparse'. 3419 3420 Modification times are displayed in UTC as UNIX timestamps, unless 3421suffixed with `H' (for "human-readable"), as in `ctimeH', in which case 3422usual `tar tv' output format is used. 3423 3424 The default output format is: `name,dev,ino,mode, 3425nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime'. 3426 3427 For example, the following command will display file names and 3428corresponding times of last access for each file in the current working 3429directory: 3430 3431 genfile --stat=name,atime * 3432 3433 3434File: tar.info, Node: Exec Mode, Prev: Status Mode, Up: Genfile 3435 3436D.3 Exec Mode 3437============= 3438 3439This mode is designed for testing the behavior of `paxutils' commands 3440when some of the files change during archiving. It is an experimental 3441mode. 3442 3443 The `Exec Mode' is toggled by `--run' command line option (or its 3444alias `-r'). The argument to this option gives the command line to be 3445executed. The actual command line is constructed by inserting 3446`--checkpoint' option between the command name and its first argument 3447(if any). Due to this, the argument to `--run' may not use traditional 3448`tar' option syntax, i.e., the following is wrong: 3449 3450 # Wrong! 3451 genfile --run 'tar cf foo bar' 3452 3453Use the following syntax instead: 3454 3455 genfile --run 'tar -cf foo bar' 3456 3457 The rest of command line after `--run' or its equivalent specifies 3458checkpoint values and actions to be executed upon reaching them. 3459Checkpoint values are introduced with `--checkpoint' command line 3460option. Argument to this option is the number of checkpoint in decimal. 3461 3462 Any number of "actions" may be specified after a checkpoint. 3463Available actions are 3464 3465`--cut FILE' 3466`--truncate FILE' 3467 Truncate FILE to the size specified by previous `--length' option 3468 (or 0, if it is not given). 3469 3470`--append FILE' 3471 Append data to FILE. The size of data and its pattern are given by 3472 previous `--length' and `pattern' options. 3473 3474`--touch FILE' 3475 Update the access and modification times of FILE. These timestamps 3476 are changed to the current time, unless `--date' option was given, 3477 in which case they are changed to the specified time. Argument to 3478 `--date' option is a date specification in an almost arbitrary 3479 format (*note Date input formats::). 3480 3481`--exec COMMAND' 3482 Execute given shell command. 3483 3484 3485 Option `--verbose' instructs `genfile' to print on standard output 3486notifications about checkpoints being executed and to verbosely 3487describe exit status of the command. 3488 3489 While the command is being executed its standard output remains 3490connected to descriptor 1. All messages it prints to file descriptor 2, 3491except checkpoint notifications, are forwarded to standard error. 3492 3493 `Genfile' exits with the exit status of the executed command. 3494 3495 3496File: tar.info, Node: Free Software Needs Free Documentation, Next: Copying This Manual, Prev: Genfile, Up: Top 3497 3498Appendix E Free Software Needs Free Documentation 3499************************************************* 3500 3501The biggest deficiency in the free software community today is not in 3502the software--it is the lack of good free documentation that we can 3503include with the free software. Many of our most important programs do 3504not come with free reference manuals and free introductory texts. 3505Documentation is an essential part of any software package; when an 3506important free software package does not come with a free manual and a 3507free tutorial, that is a major gap. We have many such gaps today. 3508 3509 Consider Perl, for instance. The tutorial manuals that people 3510normally use are non-free. How did this come about? Because the 3511authors of those manuals published them with restrictive terms--no 3512copying, no modification, source files not available--which exclude 3513them from the free software world. 3514 3515 That wasn't the first time this sort of thing happened, and it was 3516far from the last. Many times we have heard a GNU user eagerly 3517describe a manual that he is writing, his intended contribution to the 3518community, only to learn that he had ruined everything by signing a 3519publication contract to make it non-free. 3520 3521 Free documentation, like free software, is a matter of freedom, not 3522price. The problem with the non-free manual is not that publishers 3523charge a price for printed copies--that in itself is fine. (The Free 3524Software Foundation sells printed copies of manuals, too.) The problem 3525is the restrictions on the use of the manual. Free manuals are 3526available in source code form, and give you permission to copy and 3527modify. Non-free manuals do not allow this. 3528 3529 The criteria of freedom for a free manual are roughly the same as for 3530free software. Redistribution (including the normal kinds of 3531commercial redistribution) must be permitted, so that the manual can 3532accompany every copy of the program, both on-line and on paper. 3533 3534 Permission for modification of the technical content is crucial too. 3535When people modify the software, adding or changing features, if they 3536are conscientious they will change the manual too--so they can provide 3537accurate and clear documentation for the modified program. A manual 3538that leaves you no choice but to write a new manual to document a 3539changed version of the program is not really available to our community. 3540 3541 Some kinds of limits on the way modification is handled are 3542acceptable. For example, requirements to preserve the original 3543author's copyright notice, the distribution terms, or the list of 3544authors, are ok. It is also no problem to require modified versions to 3545include notice that they were modified. Even entire sections that may 3546not be deleted or changed are acceptable, as long as they deal with 3547nontechnical topics (like this one). These kinds of restrictions are 3548acceptable because they don't obstruct the community's normal use of 3549the manual. 3550 3551 However, it must be possible to modify all the _technical_ content 3552of the manual, and then distribute the result in all the usual media, 3553through all the usual channels. Otherwise, the restrictions obstruct 3554the use of the manual, it is not free, and we need another manual to 3555replace it. 3556 3557 Please spread the word about this issue. Our community continues to 3558lose manuals to proprietary publishing. If we spread the word that 3559free software needs free reference manuals and free tutorials, perhaps 3560the next person who wants to contribute by writing documentation will 3561realize, before it is too late, that only free manuals contribute to 3562the free software community. 3563 3564 If you are writing documentation, please insist on publishing it 3565under the GNU Free Documentation License or another free documentation 3566license. Remember that this decision requires your approval--you don't 3567have to let the publisher decide. Some commercial publishers will use 3568a free license if you insist, but they will not propose the option; it 3569is up to you to raise the issue and say firmly that this is what you 3570want. If the publisher you are dealing with refuses, please try other 3571publishers. If you're not sure whether a proposed license is free, 3572write to <licensing@gnu.org>. 3573 3574 You can encourage commercial publishers to sell more free, copylefted 3575manuals and tutorials by buying them, and particularly by buying copies 3576from the publishers that paid for their writing or for major 3577improvements. Meanwhile, try to avoid buying non-free documentation at 3578all. Check the distribution terms of a manual before you buy it, and 3579insist that whoever seeks your business must respect your freedom. 3580Check the history of the book, and try reward the publishers that have 3581paid or pay the authors to work on it. 3582 3583 The Free Software Foundation maintains a list of free documentation 3584published by other publishers, at 3585`http://www.fsf.org/doc/other-free-books.html'. 3586 3587 3588File: tar.info, Node: Copying This Manual, Next: Index of Command Line Options, Prev: Free Software Needs Free Documentation, Up: Top 3589 3590Appendix F Copying This Manual 3591****************************** 3592 3593* Menu: 3594 3595* GNU Free Documentation License:: License for copying this manual 3596 3597 3598File: tar.info, Node: GNU Free Documentation License, Up: Copying This Manual 3599 3600F.1 GNU Free Documentation License 3601================================== 3602 3603 Version 1.2, November 2002 3604 3605 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 3606 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA 3607 3608 Everyone is permitted to copy and distribute verbatim copies 3609 of this license document, but changing it is not allowed. 3610 3611 0. PREAMBLE 3612 3613 The purpose of this License is to make a manual, textbook, or other 3614 functional and useful document "free" in the sense of freedom: to 3615 assure everyone the effective freedom to copy and redistribute it, 3616 with or without modifying it, either commercially or 3617 noncommercially. Secondarily, this License preserves for the 3618 author and publisher a way to get credit for their work, while not 3619 being considered responsible for modifications made by others. 3620 3621 This License is a kind of "copyleft", which means that derivative 3622 works of the document must themselves be free in the same sense. 3623 It complements the GNU General Public License, which is a copyleft 3624 license designed for free software. 3625 3626 We have designed this License in order to use it for manuals for 3627 free software, because free software needs free documentation: a 3628 free program should come with manuals providing the same freedoms 3629 that the software does. But this License is not limited to 3630 software manuals; it can be used for any textual work, regardless 3631 of subject matter or whether it is published as a printed book. 3632 We recommend this License principally for works whose purpose is 3633 instruction or reference. 3634 3635 1. APPLICABILITY AND DEFINITIONS 3636 3637 This License applies to any manual or other work, in any medium, 3638 that contains a notice placed by the copyright holder saying it 3639 can be distributed under the terms of this License. Such a notice 3640 grants a world-wide, royalty-free license, unlimited in duration, 3641 to use that work under the conditions stated herein. The 3642 "Document", below, refers to any such manual or work. Any member 3643 of the public is a licensee, and is addressed as "you". You 3644 accept the license if you copy, modify or distribute the work in a 3645 way requiring permission under copyright law. 3646 3647 A "Modified Version" of the Document means any work containing the 3648 Document or a portion of it, either copied verbatim, or with 3649 modifications and/or translated into another language. 3650 3651 A "Secondary Section" is a named appendix or a front-matter section 3652 of the Document that deals exclusively with the relationship of the 3653 publishers or authors of the Document to the Document's overall 3654 subject (or to related matters) and contains nothing that could 3655 fall directly within that overall subject. (Thus, if the Document 3656 is in part a textbook of mathematics, a Secondary Section may not 3657 explain any mathematics.) The relationship could be a matter of 3658 historical connection with the subject or with related matters, or 3659 of legal, commercial, philosophical, ethical or political position 3660 regarding them. 3661 3662 The "Invariant Sections" are certain Secondary Sections whose 3663 titles are designated, as being those of Invariant Sections, in 3664 the notice that says that the Document is released under this 3665 License. If a section does not fit the above definition of 3666 Secondary then it is not allowed to be designated as Invariant. 3667 The Document may contain zero Invariant Sections. If the Document 3668 does not identify any Invariant Sections then there are none. 3669 3670 The "Cover Texts" are certain short passages of text that are 3671 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 3672 that says that the Document is released under this License. A 3673 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 3674 be at most 25 words. 3675 3676 A "Transparent" copy of the Document means a machine-readable copy, 3677 represented in a format whose specification is available to the 3678 general public, that is suitable for revising the document 3679 straightforwardly with generic text editors or (for images 3680 composed of pixels) generic paint programs or (for drawings) some 3681 widely available drawing editor, and that is suitable for input to 3682 text formatters or for automatic translation to a variety of 3683 formats suitable for input to text formatters. A copy made in an 3684 otherwise Transparent file format whose markup, or absence of 3685 markup, has been arranged to thwart or discourage subsequent 3686 modification by readers is not Transparent. An image format is 3687 not Transparent if used for any substantial amount of text. A 3688 copy that is not "Transparent" is called "Opaque". 3689 3690 Examples of suitable formats for Transparent copies include plain 3691 ASCII without markup, Texinfo input format, LaTeX input format, 3692 SGML or XML using a publicly available DTD, and 3693 standard-conforming simple HTML, PostScript or PDF designed for 3694 human modification. Examples of transparent image formats include 3695 PNG, XCF and JPG. Opaque formats include proprietary formats that 3696 can be read and edited only by proprietary word processors, SGML or 3697 XML for which the DTD and/or processing tools are not generally 3698 available, and the machine-generated HTML, PostScript or PDF 3699 produced by some word processors for output purposes only. 3700 3701 The "Title Page" means, for a printed book, the title page itself, 3702 plus such following pages as are needed to hold, legibly, the 3703 material this License requires to appear in the title page. For 3704 works in formats which do not have any title page as such, "Title 3705 Page" means the text near the most prominent appearance of the 3706 work's title, preceding the beginning of the body of the text. 3707 3708 A section "Entitled XYZ" means a named subunit of the Document 3709 whose title either is precisely XYZ or contains XYZ in parentheses 3710 following text that translates XYZ in another language. (Here XYZ 3711 stands for a specific section name mentioned below, such as 3712 "Acknowledgements", "Dedications", "Endorsements", or "History".) 3713 To "Preserve the Title" of such a section when you modify the 3714 Document means that it remains a section "Entitled XYZ" according 3715 to this definition. 3716 3717 The Document may include Warranty Disclaimers next to the notice 3718 which states that this License applies to the Document. These 3719 Warranty Disclaimers are considered to be included by reference in 3720 this License, but only as regards disclaiming warranties: any other 3721 implication that these Warranty Disclaimers may have is void and 3722 has no effect on the meaning of this License. 3723 3724 2. VERBATIM COPYING 3725 3726 You may copy and distribute the Document in any medium, either 3727 commercially or noncommercially, provided that this License, the 3728 copyright notices, and the license notice saying this License 3729 applies to the Document are reproduced in all copies, and that you 3730 add no other conditions whatsoever to those of this License. You 3731 may not use technical measures to obstruct or control the reading 3732 or further copying of the copies you make or distribute. However, 3733 you may accept compensation in exchange for copies. If you 3734 distribute a large enough number of copies you must also follow 3735 the conditions in section 3. 3736 3737 You may also lend copies, under the same conditions stated above, 3738 and you may publicly display copies. 3739 3740 3. COPYING IN QUANTITY 3741 3742 If you publish printed copies (or copies in media that commonly 3743 have printed covers) of the Document, numbering more than 100, and 3744 the Document's license notice requires Cover Texts, you must 3745 enclose the copies in covers that carry, clearly and legibly, all 3746 these Cover Texts: Front-Cover Texts on the front cover, and 3747 Back-Cover Texts on the back cover. Both covers must also clearly 3748 and legibly identify you as the publisher of these copies. The 3749 front cover must present the full title with all words of the 3750 title equally prominent and visible. You may add other material 3751 on the covers in addition. Copying with changes limited to the 3752 covers, as long as they preserve the title of the Document and 3753 satisfy these conditions, can be treated as verbatim copying in 3754 other respects. 3755 3756 If the required texts for either cover are too voluminous to fit 3757 legibly, you should put the first ones listed (as many as fit 3758 reasonably) on the actual cover, and continue the rest onto 3759 adjacent pages. 3760 3761 If you publish or distribute Opaque copies of the Document 3762 numbering more than 100, you must either include a 3763 machine-readable Transparent copy along with each Opaque copy, or 3764 state in or with each Opaque copy a computer-network location from 3765 which the general network-using public has access to download 3766 using public-standard network protocols a complete Transparent 3767 copy of the Document, free of added material. If you use the 3768 latter option, you must take reasonably prudent steps, when you 3769 begin distribution of Opaque copies in quantity, to ensure that 3770 this Transparent copy will remain thus accessible at the stated 3771 location until at least one year after the last time you 3772 distribute an Opaque copy (directly or through your agents or 3773 retailers) of that edition to the public. 3774 3775 It is requested, but not required, that you contact the authors of 3776 the Document well before redistributing any large number of 3777 copies, to give them a chance to provide you with an updated 3778 version of the Document. 3779 3780 4. MODIFICATIONS 3781 3782 You may copy and distribute a Modified Version of the Document 3783 under the conditions of sections 2 and 3 above, provided that you 3784 release the Modified Version under precisely this License, with 3785 the Modified Version filling the role of the Document, thus 3786 licensing distribution and modification of the Modified Version to 3787 whoever possesses a copy of it. In addition, you must do these 3788 things in the Modified Version: 3789 3790 A. Use in the Title Page (and on the covers, if any) a title 3791 distinct from that of the Document, and from those of 3792 previous versions (which should, if there were any, be listed 3793 in the History section of the Document). You may use the 3794 same title as a previous version if the original publisher of 3795 that version gives permission. 3796 3797 B. List on the Title Page, as authors, one or more persons or 3798 entities responsible for authorship of the modifications in 3799 the Modified Version, together with at least five of the 3800 principal authors of the Document (all of its principal 3801 authors, if it has fewer than five), unless they release you 3802 from this requirement. 3803 3804 C. State on the Title page the name of the publisher of the 3805 Modified Version, as the publisher. 3806 3807 D. Preserve all the copyright notices of the Document. 3808 3809 E. Add an appropriate copyright notice for your modifications 3810 adjacent to the other copyright notices. 3811 3812 F. Include, immediately after the copyright notices, a license 3813 notice giving the public permission to use the Modified 3814 Version under the terms of this License, in the form shown in 3815 the Addendum below. 3816 3817 G. Preserve in that license notice the full lists of Invariant 3818 Sections and required Cover Texts given in the Document's 3819 license notice. 3820 3821 H. Include an unaltered copy of this License. 3822 3823 I. Preserve the section Entitled "History", Preserve its Title, 3824 and add to it an item stating at least the title, year, new 3825 authors, and publisher of the Modified Version as given on 3826 the Title Page. If there is no section Entitled "History" in 3827 the Document, create one stating the title, year, authors, 3828 and publisher of the Document as given on its Title Page, 3829 then add an item describing the Modified Version as stated in 3830 the previous sentence. 3831 3832 J. Preserve the network location, if any, given in the Document 3833 for public access to a Transparent copy of the Document, and 3834 likewise the network locations given in the Document for 3835 previous versions it was based on. These may be placed in 3836 the "History" section. You may omit a network location for a 3837 work that was published at least four years before the 3838 Document itself, or if the original publisher of the version 3839 it refers to gives permission. 3840 3841 K. For any section Entitled "Acknowledgements" or "Dedications", 3842 Preserve the Title of the section, and preserve in the 3843 section all the substance and tone of each of the contributor 3844 acknowledgements and/or dedications given therein. 3845 3846 L. Preserve all the Invariant Sections of the Document, 3847 unaltered in their text and in their titles. Section numbers 3848 or the equivalent are not considered part of the section 3849 titles. 3850 3851 M. Delete any section Entitled "Endorsements". Such a section 3852 may not be included in the Modified Version. 3853 3854 N. Do not retitle any existing section to be Entitled 3855 "Endorsements" or to conflict in title with any Invariant 3856 Section. 3857 3858 O. Preserve any Warranty Disclaimers. 3859 3860 If the Modified Version includes new front-matter sections or 3861 appendices that qualify as Secondary Sections and contain no 3862 material copied from the Document, you may at your option 3863 designate some or all of these sections as invariant. To do this, 3864 add their titles to the list of Invariant Sections in the Modified 3865 Version's license notice. These titles must be distinct from any 3866 other section titles. 3867 3868 You may add a section Entitled "Endorsements", provided it contains 3869 nothing but endorsements of your Modified Version by various 3870 parties--for example, statements of peer review or that the text 3871 has been approved by an organization as the authoritative 3872 definition of a standard. 3873 3874 You may add a passage of up to five words as a Front-Cover Text, 3875 and a passage of up to 25 words as a Back-Cover Text, to the end 3876 of the list of Cover Texts in the Modified Version. Only one 3877 passage of Front-Cover Text and one of Back-Cover Text may be 3878 added by (or through arrangements made by) any one entity. If the 3879 Document already includes a cover text for the same cover, 3880 previously added by you or by arrangement made by the same entity 3881 you are acting on behalf of, you may not add another; but you may 3882 replace the old one, on explicit permission from the previous 3883 publisher that added the old one. 3884 3885 The author(s) and publisher(s) of the Document do not by this 3886 License give permission to use their names for publicity for or to 3887 assert or imply endorsement of any Modified Version. 3888 3889 5. COMBINING DOCUMENTS 3890 3891 You may combine the Document with other documents released under 3892 this License, under the terms defined in section 4 above for 3893 modified versions, provided that you include in the combination 3894 all of the Invariant Sections of all of the original documents, 3895 unmodified, and list them all as Invariant Sections of your 3896 combined work in its license notice, and that you preserve all 3897 their Warranty Disclaimers. 3898 3899 The combined work need only contain one copy of this License, and 3900 multiple identical Invariant Sections may be replaced with a single 3901 copy. If there are multiple Invariant Sections with the same name 3902 but different contents, make the title of each such section unique 3903 by adding at the end of it, in parentheses, the name of the 3904 original author or publisher of that section if known, or else a 3905 unique number. Make the same adjustment to the section titles in 3906 the list of Invariant Sections in the license notice of the 3907 combined work. 3908 3909 In the combination, you must combine any sections Entitled 3910 "History" in the various original documents, forming one section 3911 Entitled "History"; likewise combine any sections Entitled 3912 "Acknowledgements", and any sections Entitled "Dedications". You 3913 must delete all sections Entitled "Endorsements." 3914 3915 6. COLLECTIONS OF DOCUMENTS 3916 3917 You may make a collection consisting of the Document and other 3918 documents released under this License, and replace the individual 3919 copies of this License in the various documents with a single copy 3920 that is included in the collection, provided that you follow the 3921 rules of this License for verbatim copying of each of the 3922 documents in all other respects. 3923 3924 You may extract a single document from such a collection, and 3925 distribute it individually under this License, provided you insert 3926 a copy of this License into the extracted document, and follow 3927 this License in all other respects regarding verbatim copying of 3928 that document. 3929 3930 7. AGGREGATION WITH INDEPENDENT WORKS 3931 3932 A compilation of the Document or its derivatives with other 3933 separate and independent documents or works, in or on a volume of 3934 a storage or distribution medium, is called an "aggregate" if the 3935 copyright resulting from the compilation is not used to limit the 3936 legal rights of the compilation's users beyond what the individual 3937 works permit. When the Document is included in an aggregate, this 3938 License does not apply to the other works in the aggregate which 3939 are not themselves derivative works of the Document. 3940 3941 If the Cover Text requirement of section 3 is applicable to these 3942 copies of the Document, then if the Document is less than one half 3943 of the entire aggregate, the Document's Cover Texts may be placed 3944 on covers that bracket the Document within the aggregate, or the 3945 electronic equivalent of covers if the Document is in electronic 3946 form. Otherwise they must appear on printed covers that bracket 3947 the whole aggregate. 3948 3949 8. TRANSLATION 3950 3951 Translation is considered a kind of modification, so you may 3952 distribute translations of the Document under the terms of section 3953 4. Replacing Invariant Sections with translations requires special 3954 permission from their copyright holders, but you may include 3955 translations of some or all Invariant Sections in addition to the 3956 original versions of these Invariant Sections. You may include a 3957 translation of this License, and all the license notices in the 3958 Document, and any Warranty Disclaimers, provided that you also 3959 include the original English version of this License and the 3960 original versions of those notices and disclaimers. In case of a 3961 disagreement between the translation and the original version of 3962 this License or a notice or disclaimer, the original version will 3963 prevail. 3964 3965 If a section in the Document is Entitled "Acknowledgements", 3966 "Dedications", or "History", the requirement (section 4) to 3967 Preserve its Title (section 1) will typically require changing the 3968 actual title. 3969 3970 9. TERMINATION 3971 3972 You may not copy, modify, sublicense, or distribute the Document 3973 except as expressly provided for under this License. Any other 3974 attempt to copy, modify, sublicense or distribute the Document is 3975 void, and will automatically terminate your rights under this 3976 License. However, parties who have received copies, or rights, 3977 from you under this License will not have their licenses 3978 terminated so long as such parties remain in full compliance. 3979 3980 10. FUTURE REVISIONS OF THIS LICENSE 3981 3982 The Free Software Foundation may publish new, revised versions of 3983 the GNU Free Documentation License from time to time. Such new 3984 versions will be similar in spirit to the present version, but may 3985 differ in detail to address new problems or concerns. See 3986 `http://www.gnu.org/copyleft/'. 3987 3988 Each version of the License is given a distinguishing version 3989 number. If the Document specifies that a particular numbered 3990 version of this License "or any later version" applies to it, you 3991 have the option of following the terms and conditions either of 3992 that specified version or of any later version that has been 3993 published (not as a draft) by the Free Software Foundation. If 3994 the Document does not specify a version number of this License, 3995 you may choose any version ever published (not as a draft) by the 3996 Free Software Foundation. 3997 3998F.1.1 ADDENDUM: How to use this License for your documents 3999---------------------------------------------------------- 4000 4001To use this License in a document you have written, include a copy of 4002the License in the document and put the following copyright and license 4003notices just after the title page: 4004 4005 Copyright (C) YEAR YOUR NAME. 4006 Permission is granted to copy, distribute and/or modify this document 4007 under the terms of the GNU Free Documentation License, Version 1.2 4008 or any later version published by the Free Software Foundation; 4009 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 4010 Texts. A copy of the license is included in the section entitled ``GNU 4011 Free Documentation License''. 4012 4013 If you have Invariant Sections, Front-Cover Texts and Back-Cover 4014Texts, replace the "with...Texts." line with this: 4015 4016 with the Invariant Sections being LIST THEIR TITLES, with 4017 the Front-Cover Texts being LIST, and with the Back-Cover Texts 4018 being LIST. 4019 4020 If you have Invariant Sections without Cover Texts, or some other 4021combination of the three, merge those two alternatives to suit the 4022situation. 4023 4024 If your document contains nontrivial examples of program code, we 4025recommend releasing these examples in parallel under your choice of 4026free software license, such as the GNU General Public License, to 4027permit their use in free software. 4028 4029 4030File: tar.info, Node: Index of Command Line Options, Next: Index, Prev: Copying This Manual, Up: Top 4031 4032Appendix G Index of Command Line Options 4033**************************************** 4034 4035This appendix contains an index of all GNU `tar' long command line 4036options. The options are listed without the preceding double-dash. For 4037a cross-reference of short command line options, *note Short Option 4038Summary::. 4039 4040[index] 4041* Menu: 4042 4043* absolute-names: absolute. (line 8) 4044* absolute-names, summary: Option Summary. (line 6) 4045* add-file: files. (line 84) 4046* after-date: after. (line 26) 4047* after-date, summary: Option Summary. (line 12) 4048* anchored: controlling pattern-matching. 4049 (line 79) 4050* anchored, summary: Option Summary. (line 15) 4051* append: append. (line 8) 4052* append, summary: Operation Summary. (line 6) 4053* atime-preserve: Attributes. (line 14) 4054* atime-preserve, summary: Option Summary. (line 19) 4055* backup: backup. (line 41) 4056* backup, summary: Option Summary. (line 65) 4057* block-number: verbose. (line 111) 4058* block-number, summary: Option Summary. (line 70) 4059* blocking-factor: Blocking Factor. (line 8) 4060* blocking-factor, summary: Option Summary. (line 76) 4061* bzip2: gzip. (line 88) 4062* bzip2, summary: Option Summary. (line 81) 4063* catenate: concatenate. (line 6) 4064* catenate, summary: Operation Summary. (line 10) 4065* check-links, summary: Option Summary. (line 93) 4066* checkpoint: verbose. (line 83) 4067* checkpoint, summary: Option Summary. (line 86) 4068* compare: compare. (line 8) 4069* compare, summary: Operation Summary. (line 14) 4070* compress: gzip. (line 92) 4071* compress, summary: Option Summary. (line 100) 4072* concatenate: concatenate. (line 6) 4073* concatenate, summary: Operation Summary. (line 20) 4074* confirmation, summary: Option Summary. (line 107) 4075* create, additional options: create options. (line 6) 4076* create, complementary notes: Basic tar. (line 11) 4077* create, introduced: Creating the archive. 4078 (line 6) 4079* create, summary: Operation Summary. (line 25) 4080* create, using with --verbose: create verbose. (line 6) 4081* create, using with --verify: verify. (line 24) 4082* delay-directory-restore: Directory Modification Times and Permissions. 4083 (line 62) 4084* delay-directory-restore, summary: Option Summary. (line 110) 4085* delete: delete. (line 8) 4086* delete, summary: Operation Summary. (line 29) 4087* dereference: dereference. (line 6) 4088* dereference, summary: Option Summary. (line 115) 4089* diff, summary: Operation Summary. (line 33) 4090* directory: directory. (line 11) 4091* directory, summary: Option Summary. (line 121) 4092* directory, using in --files-from argument: files. (line 60) 4093* exclude: exclude. (line 11) 4094* exclude, potential problems with: problems with exclude. 4095 (line 6) 4096* exclude, summary: Option Summary. (line 128) 4097* exclude-caches: exclude. (line 45) 4098* exclude-caches, summary: Option Summary. (line 137) 4099* exclude-caches-all: exclude. (line 53) 4100* exclude-caches-all, summary: Option Summary. (line 150) 4101* exclude-caches-under: exclude. (line 49) 4102* exclude-caches-under, summary: Option Summary. (line 144) 4103* exclude-from: exclude. (line 22) 4104* exclude-from, summary: Option Summary. (line 132) 4105* exclude-tag: exclude. (line 62) 4106* exclude-tag, summary: Option Summary. (line 154) 4107* exclude-tag-all: exclude. (line 70) 4108* exclude-tag-all, summary: Option Summary. (line 162) 4109* exclude-tag-under: exclude. (line 66) 4110* exclude-tag-under, summary: Option Summary. (line 158) 4111* extract: extract. (line 8) 4112* extract, additional options: extract options. (line 8) 4113* extract, complementary notes: Basic tar. (line 48) 4114* extract, summary: Operation Summary. (line 37) 4115* extract, using with --listed-incremental: Incremental Dumps. 4116 (line 93) 4117* file, short description: file. (line 17) 4118* file, summary: Option Summary. (line 166) 4119* file, tutorial: file tutorial. (line 6) 4120* files-from: files. (line 14) 4121* files-from, summary: Option Summary. (line 172) 4122* force-local, short description: Device. (line 70) 4123* force-local, summary: Option Summary. (line 178) 4124* format, summary: Option Summary. (line 183) 4125* get, summary: Operation Summary. (line 42) 4126* group: override. (line 73) 4127* group, summary: Option Summary. (line 208) 4128* gunzip, summary: Option Summary. (line 216) 4129* gzip: gzip. (line 54) 4130* gzip, summary: Option Summary. (line 216) 4131* help: help tutorial. (line 6) 4132* help, introduction: help. (line 26) 4133* help, summary: Option Summary. (line 224) 4134* ignore-case: controlling pattern-matching. 4135 (line 86) 4136* ignore-case, summary: Option Summary. (line 229) 4137* ignore-command-error: Writing to an External Program. 4138 (line 82) 4139* ignore-command-error, summary: Option Summary. (line 233) 4140* ignore-failed-read: Ignore Failed Read. (line 7) 4141* ignore-failed-read, summary: Option Summary. (line 237) 4142* ignore-zeros: Ignore Zeros. (line 6) 4143* ignore-zeros, short description: Blocking Factor. (line 156) 4144* ignore-zeros, summary: Option Summary. (line 241) 4145* incremental, summary: Option Summary. (line 246) 4146* incremental, using with --list: Incremental Dumps. (line 158) 4147* index-file, summary: Option Summary. (line 253) 4148* info-script: Multi-Volume Archives. 4149 (line 80) 4150* info-script, short description: Device. (line 104) 4151* info-script, summary: Option Summary. (line 256) 4152* interactive: interactive. (line 14) 4153* interactive, summary: Option Summary. (line 264) 4154* keep-newer-files: Keep Newer Files. (line 6) 4155* keep-newer-files, summary: Option Summary. (line 271) 4156* keep-old-files: Keep Old Files. (line 6) 4157* keep-old-files, introduced: Dealing with Old Files. 4158 (line 16) 4159* keep-old-files, summary: Option Summary. (line 275) 4160* label: label. (line 8) 4161* label, summary: Option Summary. (line 280) 4162* list: list. (line 6) 4163* list, summary: Operation Summary. (line 46) 4164* list, using with --incremental: Incremental Dumps. (line 158) 4165* list, using with --listed-incremental: Incremental Dumps. (line 158) 4166* list, using with --verbose: list. (line 30) 4167* list, using with file name arguments: list. (line 68) 4168* listed-incremental: Incremental Dumps. (line 14) 4169* listed-incremental, summary: Option Summary. (line 287) 4170* listed-incremental, using with --extract: Incremental Dumps. 4171 (line 93) 4172* listed-incremental, using with --list: Incremental Dumps. (line 158) 4173* mode: override. (line 14) 4174* mode, summary: Option Summary. (line 295) 4175* mtime: override. (line 29) 4176* mtime, summary: Option Summary. (line 301) 4177* multi-volume: Multi-Volume Archives. 4178 (line 6) 4179* multi-volume, short description: Device. (line 88) 4180* multi-volume, summary: Option Summary. (line 310) 4181* new-volume-script: Multi-Volume Archives. 4182 (line 80) 4183* new-volume-script, short description: Device. (line 104) 4184* new-volume-script, summary: Option Summary. (line 256) 4185* newer: after. (line 26) 4186* newer, summary: Option Summary. (line 318) 4187* newer-mtime: after. (line 37) 4188* newer-mtime, summary: Option Summary. (line 326) 4189* no-anchored: controlling pattern-matching. 4190 (line 79) 4191* no-anchored, summary: Option Summary. (line 331) 4192* no-delay-directory-restore: Directory Modification Times and Permissions. 4193 (line 68) 4194* no-delay-directory-restore, summary: Option Summary. (line 335) 4195* no-ignore-case: controlling pattern-matching. 4196 (line 86) 4197* no-ignore-case, summary: Option Summary. (line 341) 4198* no-ignore-command-error: Writing to an External Program. 4199 (line 87) 4200* no-ignore-command-error, summary: Option Summary. (line 344) 4201* no-overwrite-dir, summary: Option Summary. (line 348) 4202* no-quote-chars, summary: Option Summary. (line 352) 4203* no-recursion: recurse. (line 13) 4204* no-recursion, summary: Option Summary. (line 357) 4205* no-same-owner: Attributes. (line 67) 4206* no-same-owner, summary: Option Summary. (line 361) 4207* no-same-permissions, summary: Option Summary. (line 367) 4208* no-unquote: Selecting Archive Members. 4209 (line 42) 4210* no-unquote, summary: Option Summary. (line 372) 4211* no-wildcards: controlling pattern-matching. 4212 (line 41) 4213* no-wildcards, summary: Option Summary. (line 376) 4214* no-wildcards-match-slash: controlling pattern-matching. 4215 (line 92) 4216* no-wildcards-match-slash, summary: Option Summary. (line 379) 4217* null: nul. (line 11) 4218* null, summary: Option Summary. (line 382) 4219* numeric-owner: Attributes. (line 73) 4220* numeric-owner, summary: Option Summary. (line 388) 4221* occurrence, summary: Option Summary. (line 405) 4222* old-archive, summary: Option Summary. (line 419) 4223* one-file-system: one. (line 16) 4224* one-file-system, summary: Option Summary. (line 422) 4225* overwrite: Overwrite Old Files. (line 6) 4226* overwrite, introduced: Dealing with Old Files. 4227 (line 22) 4228* overwrite, summary: Option Summary. (line 427) 4229* overwrite-dir: Overwrite Old Files. (line 28) 4230* overwrite-dir, introduced: Dealing with Old Files. 4231 (line 6) 4232* overwrite-dir, summary: Option Summary. (line 431) 4233* owner: override. (line 57) 4234* owner, summary: Option Summary. (line 435) 4235* pax-option: PAX keywords. (line 6) 4236* pax-option, summary: Option Summary. (line 444) 4237* portability, summary: Option Summary. (line 450) 4238* posix, summary: Option Summary. (line 454) 4239* preserve: Attributes. (line 126) 4240* preserve, summary: Option Summary. (line 457) 4241* preserve-order: Same Order. (line 6) 4242* preserve-order, summary: Option Summary. (line 461) 4243* preserve-permissions: Setting Access Permissions. 4244 (line 10) 4245* preserve-permissions, short description: Attributes. (line 113) 4246* preserve-permissions, summary: Option Summary. (line 464) 4247* quote-chars, summary: Option Summary. (line 474) 4248* quoting-style: quoting styles. (line 39) 4249* quoting-style, summary: Option Summary. (line 478) 4250* read-full-records <1>: read full records. (line 6) 4251* read-full-records: Reading. (line 8) 4252* read-full-records, short description: Blocking Factor. (line 172) 4253* read-full-records, summary: Option Summary. (line 485) 4254* record-size, summary: Option Summary. (line 490) 4255* recursion: recurse. (line 24) 4256* recursion, summary: Option Summary. (line 494) 4257* recursive-unlink: Recursive Unlink. (line 6) 4258* recursive-unlink, summary: Option Summary. (line 498) 4259* remove-files: remove files. (line 6) 4260* remove-files, summary: Option Summary. (line 503) 4261* restrict, summary: Option Summary. (line 507) 4262* rmt-command, summary: Option Summary. (line 512) 4263* rsh-command: Device. (line 73) 4264* rsh-command, summary: Option Summary. (line 516) 4265* same-order: Same Order. (line 6) 4266* same-order, summary: Option Summary. (line 520) 4267* same-owner: Attributes. (line 48) 4268* same-owner, summary: Option Summary. (line 528) 4269* same-permissions: Setting Access Permissions. 4270 (line 10) 4271* same-permissions, short description: Attributes. (line 113) 4272* same-permissions, summary: Option Summary. (line 464) 4273* seek, summary: Option Summary. (line 537) 4274* show-defaults: defaults. (line 6) 4275* show-defaults, summary: Option Summary. (line 544) 4276* show-omitted-dirs: verbose. (line 103) 4277* show-omitted-dirs, summary: Option Summary. (line 553) 4278* show-stored-names: list. (line 60) 4279* show-stored-names, summary: Option Summary. (line 557) 4280* show-transformed-names: transform. (line 45) 4281* show-transformed-names, summary: Option Summary. (line 557) 4282* sparse: sparse. (line 22) 4283* sparse, summary: Option Summary. (line 565) 4284* sparse-version: sparse. (line 57) 4285* sparse-version, summary: Option Summary. (line 570) 4286* starting-file: Starting File. (line 6) 4287* starting-file, summary: Option Summary. (line 575) 4288* strip-components: transform. (line 25) 4289* strip-components, summary: Option Summary. (line 581) 4290* suffix: backup. (line 68) 4291* suffix, summary: Option Summary. (line 590) 4292* tape-length: Multi-Volume Archives. 4293 (line 33) 4294* tape-length, short description: Device. (line 96) 4295* tape-length, summary: Option Summary. (line 596) 4296* test-label: label. (line 37) 4297* test-label, summary: Option Summary. (line 601) 4298* to-command: Writing to an External Program. 4299 (line 9) 4300* to-command, summary: Option Summary. (line 605) 4301* to-stdout: Writing to Standard Output. 4302 (line 14) 4303* to-stdout, summary: Option Summary. (line 609) 4304* totals: verbose. (line 46) 4305* totals, summary: Option Summary. (line 614) 4306* touch <1>: Attributes. (line 37) 4307* touch: Data Modification Times. 4308 (line 15) 4309* touch, summary: Option Summary. (line 619) 4310* transform: transform. (line 74) 4311* transform, summary: Option Summary. (line 625) 4312* uncompress: gzip. (line 92) 4313* uncompress, summary: Option Summary. (line 100) 4314* ungzip: gzip. (line 54) 4315* ungzip, summary: Option Summary. (line 216) 4316* unlink-first: Unlink First. (line 6) 4317* unlink-first, introduced: Dealing with Old Files. 4318 (line 42) 4319* unlink-first, summary: Option Summary. (line 644) 4320* unquote: Selecting Archive Members. 4321 (line 39) 4322* unquote, summary: Option Summary. (line 650) 4323* update: update. (line 8) 4324* update, summary: Operation Summary. (line 50) 4325* usage: help. (line 53) 4326* use-compress-program: gzip. (line 101) 4327* use-compress-program, summary: Option Summary. (line 654) 4328* utc, summary: Option Summary. (line 658) 4329* verbose: verbose. (line 18) 4330* verbose, introduced: verbose tutorial. (line 6) 4331* verbose, summary: Option Summary. (line 662) 4332* verbose, using with --create: create verbose. (line 6) 4333* verbose, using with --list: list. (line 30) 4334* verify, short description: verify. (line 8) 4335* verify, summary: Option Summary. (line 669) 4336* verify, using with --create: verify. (line 24) 4337* version: help. (line 6) 4338* version, summary: Option Summary. (line 674) 4339* volno-file: Multi-Volume Archives. 4340 (line 71) 4341* volno-file, summary: Option Summary. (line 679) 4342* wildcards: controlling pattern-matching. 4343 (line 38) 4344* wildcards, summary: Option Summary. (line 684) 4345* wildcards-match-slash: controlling pattern-matching. 4346 (line 92) 4347* wildcards-match-slash, summary: Option Summary. (line 688) 4348 4349 4350File: tar.info, Node: Index, Prev: Index of Command Line Options, Up: Top 4351 4352Appendix H Index 4353**************** 4354 4355[index] 4356* Menu: 4357 4358* abbreviations for months: Calendar date items. (line 38) 4359* absolute file names: Remote Tape Server. (line 17) 4360* Adding archives to an archive: concatenate. (line 6) 4361* Adding files to an Archive: appending files. (line 8) 4362* ADMINISTRATOR: General-Purpose Variables. 4363 (line 7) 4364* Age, excluding files by: after. (line 8) 4365* ago in date strings: Relative items in date strings. 4366 (line 23) 4367* am in date strings: Time of day items. (line 22) 4368* Appending files to an Archive: appending files. (line 8) 4369* archive: Definitions. (line 6) 4370* Archive creation: file. (line 36) 4371* archive member: Definitions. (line 15) 4372* Archive Name: file. (line 8) 4373* Archive, creation of: create. (line 8) 4374* Archives, Appending files to: appending files. (line 8) 4375* Archiving Directories: create dir. (line 6) 4376* archiving files: Top. (line 24) 4377* ARGP_HELP_FMT, environment variable: Configuring Help Summary. 4378 (line 22) 4379* authors of get_date: Authors of get_date. (line 6) 4380* Avoiding recursion in directories: recurse. (line 8) 4381* backup options: backup. (line 6) 4382* backup suffix: backup. (line 68) 4383* BACKUP_DIRS: General-Purpose Variables. 4384 (line 29) 4385* BACKUP_FILES: General-Purpose Variables. 4386 (line 55) 4387* BACKUP_HOUR: General-Purpose Variables. 4388 (line 11) 4389* backups: backup. (line 41) 4390* beginning of time, for POSIX: Seconds since the Epoch. 4391 (line 13) 4392* Bellovin, Steven M.: Authors of get_date. (line 6) 4393* Berets, Jim: Authors of get_date. (line 6) 4394* Berry, K.: Authors of get_date. (line 14) 4395* Block number where error occurred: verbose. (line 111) 4396* BLOCKING: General-Purpose Variables. 4397 (line 25) 4398* blocking factor: Blocking Factor. (line 194) 4399* Blocking Factor: Blocking Factor. (line 6) 4400* Blocks per record: Blocking Factor. (line 6) 4401* bug reports: Reports. (line 6) 4402* Bytes per record: Blocking Factor. (line 6) 4403* calendar date item: Calendar date items. (line 6) 4404* case, ignored in dates: General date syntax. (line 64) 4405* cat vs concatenate: concatenate. (line 63) 4406* Changing directory mid-stream: directory. (line 6) 4407* Character class, excluding characters from: wildcards. (line 34) 4408* Choosing an archive file: file. (line 8) 4409* comments, in dates: General date syntax. (line 64) 4410* Compressed archives: gzip. (line 6) 4411* concatenate vs cat: concatenate. (line 63) 4412* Concatenating Archives: concatenate. (line 6) 4413* corrupted archives <1>: gzip. (line 73) 4414* corrupted archives: Full Dumps. (line 8) 4415* Creation of the archive: create. (line 8) 4416* DAT blocking: Blocking Factor. (line 204) 4417* Data Modification time, excluding files by: after. (line 8) 4418* Data modification times of extracted files: Data Modification Times. 4419 (line 6) 4420* date format, ISO 8601: Calendar date items. (line 30) 4421* date input formats: Date input formats. (line 6) 4422* day in date strings: Relative items in date strings. 4423 (line 15) 4424* day of week item: Day of week items. (line 6) 4425* Deleting files from an archive: delete. (line 8) 4426* Deleting from tape archives: delete. (line 19) 4427* Descending directories, avoiding: recurse. (line 8) 4428* Directories, Archiving: create dir. (line 6) 4429* Directories, avoiding recursion: recurse. (line 8) 4430* Directory, changing mid-stream: directory. (line 6) 4431* DIRLIST: General-Purpose Variables. 4432 (line 51) 4433* displacement of dates: Relative items in date strings. 4434 (line 6) 4435* doc-opt-col: Configuring Help Summary. 4436 (line 95) 4437* Double-checking a write operation: verify. (line 6) 4438* DUMP_BEGIN: User Hooks. (line 32) 4439* DUMP_END: User Hooks. (line 36) 4440* DUMP_REMIND_SCRIPT: General-Purpose Variables. 4441 (line 102) 4442* dumps, full: Full Dumps. (line 8) 4443* dup-args: Configuring Help Summary. 4444 (line 52) 4445* dup-args-note: Configuring Help Summary. 4446 (line 69) 4447* Eggert, Paul: Authors of get_date. (line 6) 4448* End-of-archive blocks, ignoring: Ignore Zeros. (line 6) 4449* End-of-archive info script: Multi-Volume Archives. 4450 (line 80) 4451* entry: Naming tar Archives. (line 11) 4452* epoch, for POSIX: Seconds since the Epoch. 4453 (line 13) 4454* Error message, block number of: verbose. (line 121) 4455* Exabyte blocking: Blocking Factor. (line 204) 4456* exclude: exclude. (line 14) 4457* exclude-caches: exclude. (line 33) 4458* exclude-from: exclude. (line 27) 4459* exclude-tag: exclude. (line 56) 4460* Excluding characters from a character class: wildcards. (line 34) 4461* Excluding file by age: after. (line 8) 4462* Excluding files by file system: exclude. (line 8) 4463* Excluding files by name and pattern: exclude. (line 8) 4464* Exec Mode, genfile: Exec Mode. (line 6) 4465* existing backup method: backup. (line 59) 4466* exit status: Synopsis. (line 67) 4467* Extraction: extract. (line 8) 4468* extraction: Definitions. (line 22) 4469* FDL, GNU Free Documentation License: GNU Free Documentation License. 4470 (line 6) 4471* file archival: Top. (line 24) 4472* File lists separated by NUL characters: Generate Mode. (line 33) 4473* file name: Definitions. (line 15) 4474* File Name arguments, alternatives: files. (line 6) 4475* File name arguments, using --list with: list. (line 68) 4476* File names, excluding files by: exclude. (line 8) 4477* File names, terminated by NUL: nul. (line 6) 4478* File names, using symbolic links: dereference. (line 6) 4479* File system boundaries, not crossing: one. (line 6) 4480* FILELIST: General-Purpose Variables. 4481 (line 65) 4482* first in date strings: General date syntax. (line 26) 4483* Format Options: Format Variations. (line 6) 4484* Format Parameters: Format Variations. (line 6) 4485* Format, old style: old. (line 6) 4486* fortnight in date strings: Relative items in date strings. 4487 (line 15) 4488* free documentation: Free Software Needs Free Documentation. 4489 (line 6) 4490* full dumps: Full Dumps. (line 8) 4491* future time stamps: Large or Negative Values. 4492 (line 6) 4493* general date syntax: General date syntax. (line 6) 4494* Generate Mode, genfile: Generate Mode. (line 6) 4495* genfile: Genfile. (line 6) 4496* genfile, create file: Generate Mode. (line 6) 4497* genfile, creating sparse files: Generate Mode. (line 55) 4498* genfile, generate mode: Generate Mode. (line 6) 4499* genfile, reading a list of file names: Generate Mode. (line 22) 4500* genfile, seeking to a given offset: Generate Mode. (line 18) 4501* get_date: Date input formats. (line 6) 4502* Getting program version number: help. (line 6) 4503* GNU archive format: gnu. (line 6) 4504* GNU.sparse.major, extended header variable: PAX 1. (line 14) 4505* GNU.sparse.map, extended header variable: PAX 0. (line 60) 4506* GNU.sparse.minor, extended header variable: PAX 1. (line 17) 4507* GNU.sparse.name, extended header variable: PAX 0. (line 68) 4508* GNU.sparse.name, extended header variable, in v.1.0: PAX 1. (line 24) 4509* GNU.sparse.numblocks, extended header variable: PAX 0. (line 15) 4510* GNU.sparse.numbytes, extended header variable: PAX 0. (line 21) 4511* GNU.sparse.offset, extended header variable: PAX 0. (line 18) 4512* GNU.sparse.realsize, extended header variable: PAX 1. (line 24) 4513* GNU.sparse.size, extended header variable: PAX 0. (line 11) 4514* gnupg, using with tar: gzip. (line 113) 4515* gpg, using with tar: gzip. (line 113) 4516* header-col: Configuring Help Summary. 4517 (line 141) 4518* hook: User Hooks. (line 13) 4519* hour in date strings: Relative items in date strings. 4520 (line 15) 4521* Ignoring end-of-archive blocks: Ignore Zeros. (line 6) 4522* Info script: Multi-Volume Archives. 4523 (line 80) 4524* Interactive operation: interactive. (line 6) 4525* ISO 8601 date format: Calendar date items. (line 30) 4526* items in date strings: General date syntax. (line 6) 4527* Labeling an archive: label. (line 6) 4528* Labeling multi-volume archives: label. (line 6) 4529* Labels on the archive media: label. (line 6) 4530* language, in dates: General date syntax. (line 40) 4531* Large lists of file names on small machines: Same Order. (line 6) 4532* large values: Large or Negative Values. 4533 (line 6) 4534* last DAY: Day of week items. (line 15) 4535* last in date strings: General date syntax. (line 26) 4536* Listing all tar options: help. (line 26) 4537* listing member and file names: list. (line 41) 4538* Listing volume label: label. (line 29) 4539* Lists of file names: files. (line 6) 4540* Local and remote archives: file. (line 73) 4541* long-opt-col: Configuring Help Summary. 4542 (line 87) 4543* MacKenzie, David: Authors of get_date. (line 6) 4544* member: Definitions. (line 15) 4545* member name: Definitions. (line 15) 4546* Members, replacing with other members: append. (line 49) 4547* Meyering, Jim: Authors of get_date. (line 6) 4548* Middle of the archive, starting in the: Starting File. (line 11) 4549* midnight in date strings: Time of day items. (line 22) 4550* minute in date strings: Relative items in date strings. 4551 (line 15) 4552* minutes, time zone correction by: Time of day items. (line 30) 4553* Modes of extracted files: Setting Access Permissions. 4554 (line 6) 4555* Modification time, excluding files by: after. (line 8) 4556* Modification times of extracted files: Data Modification Times. 4557 (line 6) 4558* month in date strings: Relative items in date strings. 4559 (line 15) 4560* month names in date strings: Calendar date items. (line 38) 4561* months, written-out: General date syntax. (line 36) 4562* MT: General-Purpose Variables. 4563 (line 69) 4564* MT_BEGIN: Magnetic Tape Control. 4565 (line 11) 4566* MT_OFFLINE: Magnetic Tape Control. 4567 (line 32) 4568* MT_REWIND: Magnetic Tape Control. 4569 (line 21) 4570* MT_STATUS: Magnetic Tape Control. 4571 (line 42) 4572* Multi-volume archives: Multi-Volume Archives. 4573 (line 6) 4574* Mutli-volume archives in PAX format, extracting using non-GNU tars: Split Recovery. 4575 (line 17) 4576* Mutli-volume archives, extracting using non-GNU tars: Split Recovery. 4577 (line 6) 4578* Naming an archive: file. (line 8) 4579* negative time stamps: Large or Negative Values. 4580 (line 6) 4581* next DAY: Day of week items. (line 15) 4582* next in date strings: General date syntax. (line 26) 4583* noon in date strings: Time of day items. (line 22) 4584* now in date strings: Relative items in date strings. 4585 (line 33) 4586* ntape device: Many. (line 6) 4587* NUL terminated file names: nul. (line 6) 4588* Number of blocks per record: Blocking Factor. (line 6) 4589* Number of bytes per record: Blocking Factor. (line 6) 4590* numbered backup method: backup. (line 55) 4591* numbers, written-out: General date syntax. (line 26) 4592* Obtaining help: help. (line 26) 4593* Obtaining total status information: verbose. (line 46) 4594* Old GNU archive format: gnu. (line 6) 4595* Old GNU sparse format: Old GNU Format. (line 6) 4596* Old style archives: old. (line 6) 4597* Old style format: old. (line 6) 4598* opt-doc-col: Configuring Help Summary. 4599 (line 127) 4600* option syntax, traditional: Old Options. (line 60) 4601* Options when reading archives: Reading. (line 6) 4602* Options, archive format specifying: Format Variations. (line 6) 4603* Options, format specifying: Format Variations. (line 6) 4604* ordinal numbers: General date syntax. (line 26) 4605* Overwriting old files, prevention: Dealing with Old Files. 4606 (line 16) 4607* pattern, genfile: Generate Mode. (line 39) 4608* PAX archive format: posix. (line 6) 4609* Permissions of extracted files: Setting Access Permissions. 4610 (line 6) 4611* Pinard, F.: Authors of get_date. (line 14) 4612* pm in date strings: Time of day items. (line 22) 4613* POSIX archive format: posix. (line 6) 4614* Progress information: verbose. (line 83) 4615* Protecting old files: Dealing with Old Files. 4616 (line 26) 4617* pure numbers in date strings: Pure numbers in date strings. 4618 (line 6) 4619* Reading file names from a file: files. (line 6) 4620* Reading incomplete records: Reading. (line 8) 4621* Record Size: Blocking Factor. (line 6) 4622* Records, incomplete: Reading. (line 8) 4623* Recursion in directories, avoiding: recurse. (line 8) 4624* relative items in date strings: Relative items in date strings. 4625 (line 6) 4626* Remote devices: file. (line 62) 4627* remote tape drive: Remote Tape Server. (line 6) 4628* Removing files from an archive: delete. (line 8) 4629* Replacing members with other members: append. (line 49) 4630* reporting bugs: Reports. (line 6) 4631* RESTORE_BEGIN: User Hooks. (line 39) 4632* RESTORE_END: User Hooks. (line 42) 4633* Resurrecting files from an archive: extract. (line 8) 4634* Retrieving files from an archive: extract. (line 8) 4635* return status: Synopsis. (line 67) 4636* rmargin: Configuring Help Summary. 4637 (line 160) 4638* rmt: Remote Tape Server. (line 6) 4639* RSH: General-Purpose Variables. 4640 (line 72) 4641* RSH_COMMAND: General-Purpose Variables. 4642 (line 77) 4643* Running out of space: Scarce. (line 8) 4644* Salz, Rich: Authors of get_date. (line 6) 4645* short-opt-col: Configuring Help Summary. 4646 (line 79) 4647* simple backup method: backup. (line 64) 4648* SIMPLE_BACKUP_SUFFIX: backup. (line 68) 4649* SLEEP_MESSAGE: General-Purpose Variables. 4650 (line 111) 4651* SLEEP_TIME: General-Purpose Variables. 4652 (line 97) 4653* Small memory: Scarce. (line 8) 4654* Sparse Files: sparse. (line 6) 4655* sparse files v.0.0, extracting with non-GNU tars: Sparse Recovery. 4656 (line 92) 4657* sparse files v.0.1, extracting with non-GNU tars: Sparse Recovery. 4658 (line 92) 4659* sparse files v.1.0, extracting with non-GNU tars: Sparse Recovery. 4660 (line 17) 4661* Sparse files, creating using genfile: Generate Mode. (line 55) 4662* sparse files, extracting with non-GNU tars: Sparse Recovery. 4663 (line 6) 4664* sparse formats: Sparse Formats. (line 6) 4665* sparse formats, defined: sparse. (line 50) 4666* sparse formats, Old GNU: Old GNU Format. (line 6) 4667* sparse formats, v.0.0: PAX 0. (line 6) 4668* sparse formats, v.0.1: PAX 0. (line 52) 4669* sparse formats, v.1.0: PAX 1. (line 6) 4670* sparse versions: Sparse Formats. (line 6) 4671* Specifying archive members: Selecting Archive Members. 4672 (line 6) 4673* Specifying files to act on: Selecting Archive Members. 4674 (line 6) 4675* Standard input and output: file. (line 41) 4676* Standard output, writing extracted files to: Writing to Standard Output. 4677 (line 6) 4678* Storing archives in compressed format: gzip. (line 6) 4679* Symbolic link as file name: dereference. (line 6) 4680* TAPE: file tutorial. (line 14) 4681* tape blocking: Blocking Factor. (line 194) 4682* tape marks: Many. (line 44) 4683* tape positioning: Many. (line 26) 4684* TAPE_FILE: General-Purpose Variables. 4685 (line 19) 4686* Tapes, using --delete and: delete. (line 19) 4687* TAR: General-Purpose Variables. 4688 (line 115) 4689* tar: What tar Does. (line 6) 4690* tar archive: Definitions. (line 6) 4691* Tar archive formats: Formats. (line 6) 4692* tar entry: Naming tar Archives. (line 11) 4693* tar file: Naming tar Archives. (line 11) 4694* tar to a remote device: file. (line 62) 4695* tar to standard input and output: file. (line 41) 4696* TAR_ARCHIVE, info script environment variable: Multi-Volume Archives. 4697 (line 100) 4698* TAR_ATIME, to-command environment: Writing to an External Program. 4699 (line 49) 4700* TAR_CTIME, to-command environment: Writing to an External Program. 4701 (line 58) 4702* TAR_FD, info script environment variable: Multi-Volume Archives. 4703 (line 114) 4704* TAR_FILENAME, to-command environment: Writing to an External Program. 4705 (line 37) 4706* TAR_FILETYPE, to-command environment: Writing to an External Program. 4707 (line 22) 4708* TAR_FORMAT, info script environment variable: Multi-Volume Archives. 4709 (line 110) 4710* TAR_GID, to-command environment: Writing to an External Program. 4711 (line 67) 4712* TAR_GNAME, to-command environment: Writing to an External Program. 4713 (line 46) 4714* TAR_MODE, to-command environment: Writing to an External Program. 4715 (line 34) 4716* TAR_MTIME, to-command environment: Writing to an External Program. 4717 (line 55) 4718* TAR_OPTIONS, environment variable: using tar options. (line 30) 4719* TAR_REALNAME, to-command environment: Writing to an External Program. 4720 (line 40) 4721* TAR_SIZE, to-command environment: Writing to an External Program. 4722 (line 61) 4723* TAR_SUBCOMMAND, info script environment variable: Multi-Volume Archives. 4724 (line 106) 4725* TAR_UID, to-command environment: Writing to an External Program. 4726 (line 64) 4727* TAR_UNAME, to-command environment: Writing to an External Program. 4728 (line 43) 4729* TAR_VERSION, info script environment variable: Multi-Volume Archives. 4730 (line 97) 4731* TAR_VOLUME, info script environment variable: Multi-Volume Archives. 4732 (line 103) 4733* tarcat: Tarcat. (line 6) 4734* this in date strings: Relative items in date strings. 4735 (line 33) 4736* time of day item: Time of day items. (line 6) 4737* time zone correction: Time of day items. (line 30) 4738* time zone item <1>: Time zone items. (line 6) 4739* time zone item: General date syntax. (line 44) 4740* today in date strings: Relative items in date strings. 4741 (line 33) 4742* tomorrow in date strings: Relative items in date strings. 4743 (line 29) 4744* TZ: Specifying time zone rules. 4745 (line 6) 4746* Ultrix 3.1 and write failure: Remote Tape Server. (line 40) 4747* unpacking: Definitions. (line 22) 4748* Updating an archive: update. (line 8) 4749* usage-indent: Configuring Help Summary. 4750 (line 156) 4751* Using encrypted archives: gzip. (line 113) 4752* ustar archive format: ustar. (line 6) 4753* uuencode: Applications. (line 8) 4754* v7 archive format: old. (line 6) 4755* Verbose operation: verbose. (line 18) 4756* Verifying a write operation: verify. (line 6) 4757* Verifying the currency of an archive: compare. (line 6) 4758* Version of the tar program: help. (line 6) 4759* version-control Emacs variable: backup. (line 49) 4760* VERSION_CONTROL: backup. (line 41) 4761* volno file: Multi-Volume Archives. 4762 (line 71) 4763* VOLNO_FILE: General-Purpose Variables. 4764 (line 82) 4765* Volume label, listing: label. (line 29) 4766* Volume number file: Multi-Volume Archives. 4767 (line 71) 4768* week in date strings: Relative items in date strings. 4769 (line 15) 4770* Where is the archive?: file. (line 8) 4771* Working directory, specifying: directory. (line 6) 4772* Writing extracted files to standard output: Writing to Standard Output. 4773 (line 6) 4774* Writing new archives: file. (line 36) 4775* XLIST: General-Purpose Variables. 4776 (line 87) 4777* xsparse: Sparse Recovery. (line 13) 4778* year in date strings: Relative items in date strings. 4779 (line 15) 4780* yesterday in date strings: Relative items in date strings. 4781 (line 29) 4782 4783 4784