1This is tar.info, produced by makeinfo version 4.13 from tar.texi. 2 3This manual is for GNU `tar' (version 1.15.92, 26 June 2006), which 4creates and extracts files from archives. 5 6 Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003, 72004, 2005, 2006 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 25INFO-DIR-SECTION Individual utilities 26START-INFO-DIR-ENTRY 27* tar: (tar)tar invocation. Invoking GNU `tar'. 28END-INFO-DIR-ENTRY 29 30 31File: tar.info, Node: Top, Next: Introduction, Up: (dir) 32 33GNU tar: an archiver tool 34************************* 35 36This manual is for GNU `tar' (version 1.15.92, 26 June 2006), which 37creates and extracts files from archives. 38 39 Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003, 402004, 2005, 2006 Free Software Foundation, Inc. 41 42 Permission is granted to copy, distribute and/or modify this 43 document under the terms of the GNU Free Documentation License, 44 Version 1.1 or any later version published by the Free Software 45 Foundation; with no Invariant Sections, with the Front-Cover Texts 46 being "A GNU Manual," and with the Back-Cover Texts as in (a) 47 below. A copy of the license is included in the section entitled 48 "GNU Free Documentation License". 49 50 (a) The FSF's Back-Cover Text is: "You are free to copy and modify 51 this GNU Manual. Buying copies from GNU Press supports the FSF in 52 developing GNU and promoting software freedom." 53 54 The first part of this master menu lists the major nodes in this Info 55document. The rest of the menu lists all the lower level nodes. 56 57* Menu: 58 59* Introduction:: 60* Tutorial:: 61* tar invocation:: 62* operations:: 63* Backups:: 64* Choosing:: 65* Date input formats:: 66* Formats:: 67* Media:: 68 69Appendices 70 71* Changes:: 72* Configuring Help Summary:: 73* Tar Internals:: 74* Genfile:: 75* Free Software Needs Free Documentation:: 76* Copying This Manual:: 77* Index of Command Line Options:: 78* Index:: 79 80 -- The Detailed Node Listing -- 81 82Introduction 83 84* Book Contents:: What this Book Contains 85* Definitions:: Some Definitions 86* What tar Does:: What `tar' Does 87* Naming tar Archives:: How `tar' Archives are Named 88* Authors:: GNU `tar' Authors 89* Reports:: Reporting bugs or suggestions 90 91Tutorial Introduction to `tar' 92 93* assumptions:: 94* stylistic conventions:: 95* basic tar options:: Basic `tar' Operations and Options 96* frequent operations:: 97* Two Frequent Options:: 98* create:: How to Create Archives 99* list:: How to List Archives 100* extract:: How to Extract Members from an Archive 101* going further:: 102 103Two Frequently Used Options 104 105* file tutorial:: 106* verbose tutorial:: 107* help tutorial:: 108 109How to Create Archives 110 111* prepare for examples:: 112* Creating the archive:: 113* create verbose:: 114* short create:: 115* create dir:: 116 117How to List Archives 118 119* list dir:: 120 121How to Extract Members from an Archive 122 123* extracting archives:: 124* extracting files:: 125* extract dir:: 126* extracting untrusted archives:: 127* failing commands:: 128 129Invoking GNU `tar' 130 131* Synopsis:: 132* using tar options:: 133* Styles:: 134* All Options:: 135* help:: 136* defaults:: 137* verbose:: 138* interactive:: 139 140The Three Option Styles 141 142* Long Options:: Long Option Style 143* Short Options:: Short Option Style 144* Old Options:: Old Option Style 145* Mixing:: Mixing Option Styles 146 147All `tar' Options 148 149* Operation Summary:: 150* Option Summary:: 151* Short Option Summary:: 152 153GNU `tar' Operations 154 155* Basic tar:: 156* Advanced tar:: 157* create options:: 158* extract options:: 159* backup:: 160* Applications:: 161* looking ahead:: 162 163Advanced GNU `tar' Operations 164 165* Operations:: 166* append:: 167* update:: 168* concatenate:: 169* delete:: 170* compare:: 171 172How to Add Files to Existing Archives: `--append' 173 174* appending files:: Appending Files to an Archive 175* multiple:: 176 177Updating an Archive 178 179* how to update:: 180 181Options Used by `--create' 182 183* override:: Overriding File Metadata. 184* Ignore Failed Read:: 185 186Options Used by `--extract' 187 188* Reading:: Options to Help Read Archives 189* Writing:: Changing How `tar' Writes Files 190* Scarce:: Coping with Scarce Resources 191 192Options to Help Read Archives 193 194* read full records:: 195* Ignore Zeros:: 196 197Changing How `tar' Writes Files 198 199* Dealing with Old Files:: 200* Overwrite Old Files:: 201* Keep Old Files:: 202* Keep Newer Files:: 203* Unlink First:: 204* Recursive Unlink:: 205* Data Modification Times:: 206* Setting Access Permissions:: 207* Directory Modification Times and Permissions:: 208* Writing to Standard Output:: 209* Writing to an External Program:: 210* remove files:: 211 212Coping with Scarce Resources 213 214* Starting File:: 215* Same Order:: 216 217Performing Backups and Restoring Files 218 219* Full Dumps:: Using `tar' to Perform Full Dumps 220* Incremental Dumps:: Using `tar' to Perform Incremental Dumps 221* Backup Levels:: Levels of Backups 222* Backup Parameters:: Setting Parameters for Backups and Restoration 223* Scripted Backups:: Using the Backup Scripts 224* Scripted Restoration:: Using the Restore Script 225 226Setting Parameters for Backups and Restoration 227 228* General-Purpose Variables:: 229* Magnetic Tape Control:: 230* User Hooks:: 231* backup-specs example:: An Example Text of `Backup-specs' 232 233Choosing Files and Names for `tar' 234 235* file:: Choosing the Archive's Name 236* Selecting Archive Members:: 237* files:: Reading Names from a File 238* exclude:: Excluding Some Files 239* wildcards:: Wildcards Patterns and Matching 240* quoting styles:: Ways of Quoting Special Characters in Names 241* transform:: Modifying File and Member Names 242* after:: Operating Only on New Files 243* recurse:: Descending into Directories 244* one:: Crossing File System Boundaries 245 246Reading Names from a File 247 248* nul:: 249 250Excluding Some Files 251 252* problems with exclude:: 253 254Wildcards Patterns and Matching 255 256* controlling pattern-matching:: 257 258Crossing File System Boundaries 259 260* directory:: Changing Directory 261* absolute:: Absolute File Names 262 263Date input formats 264 265* General date syntax:: Common rules. 266* Calendar date items:: 19 Dec 1994. 267* Time of day items:: 9:20pm. 268* Time zone items:: EST, PDT, GMT. 269* Day of week items:: Monday and others. 270* Relative items in date strings:: next tuesday, 2 years ago. 271* Pure numbers in date strings:: 19931219, 1440. 272* Seconds since the Epoch:: @1078100502. 273* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". 274* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al. 275 276Controlling the Archive Format 277 278* Portability:: Making `tar' Archives More Portable 279* Compression:: Using Less Space through Compression 280* Attributes:: Handling File Attributes 281* cpio:: Comparison of `tar' and `cpio' 282 283Making `tar' Archives More Portable 284 285* Portable Names:: Portable Names 286* dereference:: Symbolic Links 287* old:: Old V7 Archives 288* ustar:: Ustar Archives 289* gnu:: GNU and old GNU format archives. 290* posix:: POSIX archives 291* Checksumming:: Checksumming Problems 292* Large or Negative Values:: Large files, negative time stamps, etc. 293* Other Tars:: How to Extract GNU-Specific Data Using 294 Other `tar' Implementations 295 296GNU `tar' and POSIX `tar' 297 298* PAX keywords:: Controlling Extended Header Keywords. 299 300How to Extract GNU-Specific Data Using Other `tar' Implementations 301 302* Split Recovery:: Members Split Between Volumes 303* Sparse Recovery:: Sparse Members 304 305Using Less Space through Compression 306 307* gzip:: Creating and Reading Compressed Archives 308* sparse:: Archiving Sparse Files 309 310Tapes and Other Archive Media 311 312* Device:: Device selection and switching 313* Remote Tape Server:: 314* Common Problems and Solutions:: 315* Blocking:: Blocking 316* Many:: Many archives on one tape 317* Using Multiple Tapes:: Using Multiple Tapes 318* label:: Including a Label in the Archive 319* verify:: 320* Write Protection:: 321 322Blocking 323 324* Format Variations:: Format Variations 325* Blocking Factor:: The Blocking Factor of an Archive 326 327Many Archives on One Tape 328 329* Tape Positioning:: Tape Positions and Tape Marks 330* mt:: The `mt' Utility 331 332Using Multiple Tapes 333 334* Multi-Volume Archives:: Archives Longer than One Tape or Disk 335* Tape Files:: Tape Files 336* Tarcat:: Concatenate Volumes into a Single Archive 337 338 339Tar Internals 340 341* Standard:: Basic Tar Format 342* Extensions:: GNU Extensions to the Archive Format 343* Sparse Formats:: Storing Sparse Files 344* Snapshot Files:: 345* Dumpdir:: 346 347Storing Sparse Files 348 349* Old GNU Format:: 350* PAX 0:: PAX Format, Versions 0.0 and 0.1 351* PAX 1:: PAX Format, Version 1.0 352 353Genfile 354 355* Generate Mode:: File Generation Mode. 356* Status Mode:: File Status Mode. 357* Exec Mode:: Synchronous Execution mode. 358 359Copying This Manual 360 361* GNU Free Documentation License:: License for copying this manual 362 363 364File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top 365 3661 Introduction 367************** 368 369GNU `tar' creates and manipulates "archives" which are actually 370collections of many other files; the program provides users with an 371organized and systematic method for controlling a large amount of data. 372The name "tar" originally came from the phrase "Tape ARchive", but 373archives need not (and these days, typically do not) reside on tapes. 374 375* Menu: 376 377* Book Contents:: What this Book Contains 378* Definitions:: Some Definitions 379* What tar Does:: What `tar' Does 380* Naming tar Archives:: How `tar' Archives are Named 381* Authors:: GNU `tar' Authors 382* Reports:: Reporting bugs or suggestions 383 384 385File: tar.info, Node: Book Contents, Next: Definitions, Up: Introduction 386 3871.1 What this Book Contains 388=========================== 389 390The first part of this chapter introduces you to various terms that will 391recur throughout the book. It also tells you who has worked on GNU 392`tar' and its documentation, and where you should send bug reports or 393comments. 394 395 The second chapter is a tutorial (*note Tutorial::) which provides a 396gentle introduction for people who are new to using `tar'. It is meant 397to be self contained, not requiring any reading from subsequent chapters 398to make sense. It moves from topic to topic in a logical, progressive 399order, building on information already explained. 400 401 Although the tutorial is paced and structured to allow beginners to 402learn how to use `tar', it is not intended solely for beginners. The 403tutorial explains how to use the three most frequently used operations 404(`create', `list', and `extract') as well as two frequently used options 405(`file' and `verbose'). The other chapters do not refer to the tutorial 406frequently; however, if a section discusses something which is a complex 407variant of a basic concept, there may be a cross reference to that basic 408concept. (The entire book, including the tutorial, assumes that the 409reader understands some basic concepts of using a Unix-type operating 410system; *note Tutorial::.) 411 412 The third chapter presents the remaining five operations, and 413information about using `tar' options and option syntax. 414 415 The other chapters are meant to be used as a reference. Each chapter 416presents everything that needs to be said about a specific topic. 417 418 One of the chapters (*note Date input formats::) exists in its 419entirety in other GNU manuals, and is mostly self-contained. In 420addition, one section of this manual (*note Standard::) contains a big 421quote which is taken directly from `tar' sources. 422 423 In general, we give both long and short (abbreviated) option names at 424least once in each section where the relevant option is covered, so that 425novice readers will become familiar with both styles. (A few options 426have no short versions, and the relevant sections will indicate this.) 427 428 429File: tar.info, Node: Definitions, Next: What tar Does, Prev: Book Contents, Up: Introduction 430 4311.2 Some Definitions 432==================== 433 434The `tar' program is used to create and manipulate `tar' archives. An 435"archive" is a single file which contains the contents of many files, 436while still identifying the names of the files, their owner(s), and so 437forth. (In addition, archives record access permissions, user and 438group, size in bytes, and data modification time. Some archives also 439record the file names in each archived directory, as well as other file 440and directory information.) You can use `tar' to "create" a new archive 441in a specified directory. 442 443 The files inside an archive are called "members". Within this 444manual, we use the term "file" to refer only to files accessible in the 445normal ways (by `ls', `cat', and so forth), and the term "member" to 446refer only to the members of an archive. Similarly, a "file name" is 447the name of a file, as it resides in the file system, and a "member 448name" is the name of an archive member within the archive. 449 450 The term "extraction" refers to the process of copying an archive 451member (or multiple members) into a file in the file system. Extracting 452all the members of an archive is often called "extracting the archive". 453The term "unpack" can also be used to refer to the extraction of many or 454all the members of an archive. Extracting an archive does not destroy 455the archive's structure, just as creating an archive does not destroy 456the copies of the files that exist outside of the archive. You may also 457"list" the members in a given archive (this is often thought of as 458"printing" them to the standard output, or the command line), or 459"append" members to a pre-existing archive. All of these operations can 460be performed using `tar'. 461 462 463File: tar.info, Node: What tar Does, Next: Naming tar Archives, Prev: Definitions, Up: Introduction 464 4651.3 What `tar' Does 466=================== 467 468The `tar' program provides the ability to create `tar' archives, as well 469as various other kinds of manipulation. For example, you can use `tar' 470on previously created archives to extract files, to store additional 471files, or to update or list files which were already stored. 472 473 Initially, `tar' archives were used to store files conveniently on 474magnetic tape. The name `tar' comes from this use; it stands for `t'ape 475`ar'chiver. Despite the utility's name, `tar' can direct its output to 476available devices, files, or other programs (using pipes). `tar' may 477even access remote devices or files (as archives). 478 479 You can use `tar' archives in many ways. We want to stress a few of 480them: storage, backup, and transportation. 481 482Storage 483 Often, `tar' archives are used to store related files for 484 convenient file transfer over a network. For example, the GNU 485 Project distributes its software bundled into `tar' archives, so 486 that all the files relating to a particular program (or set of 487 related programs) can be transferred as a single unit. 488 489 A magnetic tape can store several files in sequence. However, the 490 tape has no names for these files; it only knows their relative 491 position on the tape. One way to store several files on one tape 492 and retain their names is by creating a `tar' archive. Even when 493 the basic transfer mechanism can keep track of names, as FTP can, 494 the nuisance of handling multiple files, directories, and multiple 495 links makes `tar' archives useful. 496 497 Archive files are also used for long-term storage. You can think 498 of this as transportation from the present into the future. (It is 499 a science-fiction idiom that you can move through time as well as 500 in space; the idea here is that `tar' can be used to move archives 501 in all dimensions, even time!) 502 503Backup 504 Because the archive created by `tar' is capable of preserving file 505 information and directory structure, `tar' is commonly used for 506 performing full and incremental backups of disks. A backup puts a 507 collection of files (possibly pertaining to many users and 508 projects) together on a disk or a tape. This guards against 509 accidental destruction of the information in those files. GNU 510 `tar' has special features that allow it to be used to make 511 incremental and full dumps of all the files in a file system. 512 513Transportation 514 You can create an archive on one system, transfer it to another 515 system, and extract the contents there. This allows you to 516 transport a group of files from one system to another. 517 518 519File: tar.info, Node: Naming tar Archives, Next: Authors, Prev: What tar Does, Up: Introduction 520 5211.4 How `tar' Archives are Named 522================================ 523 524Conventionally, `tar' archives are given names ending with `.tar'. This 525is not necessary for `tar' to operate properly, but this manual follows 526that convention in order to accustom readers to it and to make examples 527more clear. 528 529 Often, people refer to `tar' archives as "`tar' files," and archive 530members as "files" or "entries". For people familiar with the operation 531of `tar', this causes no difficulty. However, in this manual, we 532consistently refer to "archives" and "archive members" to make learning 533to use `tar' easier for novice users. 534 535 536File: tar.info, Node: Authors, Next: Reports, Prev: Naming tar Archives, Up: Introduction 537 5381.5 GNU `tar' Authors 539===================== 540 541GNU `tar' was originally written by John Gilmore, and modified by many 542people. The GNU enhancements were written by Jay Fenlason, then Joy 543Kendall, and the whole package has been further maintained by Thomas 544Bushnell, n/BSG, Franc,ois Pinard, Paul Eggert, and finally Sergey 545Poznyakoff with the help of numerous and kind users. 546 547 We wish to stress that `tar' is a collective work, and owes much to 548all those people who reported problems, offered solutions and other 549insights, or shared their thoughts and suggestions. An impressive, yet 550partial list of those contributors can be found in the `THANKS' file 551from the GNU `tar' distribution. 552 553 Jay Fenlason put together a draft of a GNU `tar' manual, borrowing 554notes from the original man page from John Gilmore. This was withdrawn 555in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a 556tutorial and manual for GNU `tar'. Franc,ois Pinard put version 1.11.8 557of the manual together by taking information from all these sources and 558merging them. Melissa Weisshaus finally edited and redesigned the book 559to create version 1.12. The book for versions from 1.14 up to 1.15.92 560were edited by the current maintainer, Sergey Poznyakoff. 561 562 For version 1.12, Daniel Hagerty contributed a great deal of 563technical consulting. In particular, he is the primary author of *note 564Backups::. 565 566 In July, 2003 GNU `tar' was put on CVS at savannah.gnu.org (see 567`http://savannah.gnu.org/projects/tar'), and active development and 568maintenance work has started again. Currently GNU `tar' is being 569maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey. 570 571 Support for POSIX archives was added by Sergey Poznyakoff. 572 573 574File: tar.info, Node: Reports, Prev: Authors, Up: Introduction 575 5761.6 Reporting bugs or suggestions 577================================= 578 579If you find problems or have suggestions about this program or manual, 580please report them to `bug-tar@gnu.org'. 581 582 When reporting a bug, please be sure to include as much detail as 583possible, in order to reproduce it. . 584 585 586File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top 587 5882 Tutorial Introduction to `tar' 589******************************** 590 591This chapter guides you through some basic examples of three `tar' 592operations: `--create', `--list', and `--extract'. If you already know 593how to use some other version of `tar', then you may not need to read 594this chapter. This chapter omits most complicated details about how 595`tar' works. 596 597* Menu: 598 599* assumptions:: 600* stylistic conventions:: 601* basic tar options:: Basic `tar' Operations and Options 602* frequent operations:: 603* Two Frequent Options:: 604* create:: How to Create Archives 605* list:: How to List Archives 606* extract:: How to Extract Members from an Archive 607* going further:: 608 609 610File: tar.info, Node: assumptions, Next: stylistic conventions, Up: Tutorial 611 6122.1 Assumptions this Tutorial Makes 613=================================== 614 615This chapter is paced to allow beginners to learn about `tar' slowly. 616At the same time, we will try to cover all the basic aspects of these 617three operations. In order to accomplish both of these tasks, we have 618made certain assumptions about your knowledge before reading this 619manual, and the hardware you will be using: 620 621 * Before you start to work through this tutorial, you should 622 understand what the terms "archive" and "archive member" mean 623 (*note Definitions::). In addition, you should understand 624 something about how Unix-type operating systems work, and you 625 should know how to use some basic utilities. For example, you 626 should know how to create, list, copy, rename, edit, and delete 627 files and directories; how to change between directories; and how 628 to figure out where you are in the file system. You should have 629 some basic understanding of directory structure and how files are 630 named according to which directory they are in. You should 631 understand concepts such as standard output and standard input, 632 what various definitions of the term "argument" mean, and the 633 differences between relative and absolute path names. 634 635 * This manual assumes that you are working from your own home 636 directory (unless we state otherwise). In this tutorial, you will 637 create a directory to practice `tar' commands in. When we show 638 path names, we will assume that those paths are relative to your 639 home directory. For example, my home directory path is 640 `/home/fsf/melissa'. All of my examples are in a subdirectory of 641 the directory named by that path name; the subdirectory is called 642 `practice'. 643 644 * In general, we show examples of archives which exist on (or can be 645 written to, or worked with from) a directory on a hard disk. In 646 most cases, you could write those archives to, or work with them on 647 any other device, such as a tape drive. However, some of the later 648 examples in the tutorial and next chapter will not work on tape 649 drives. Additionally, working with tapes is much more complicated 650 than working with hard disks. For these reasons, the tutorial does 651 not cover working with tape drives. *Note Media::, for complete 652 information on using `tar' archives with tape drives. 653 654 655File: tar.info, Node: stylistic conventions, Next: basic tar options, Prev: assumptions, Up: Tutorial 656 6572.2 Stylistic Conventions 658========================= 659 660In the examples, `$' represents a typical shell prompt. It precedes 661lines you should type; to make this more clear, those lines are shown in 662`this font', as opposed to lines which represent the computer's 663response; those lines are shown in `this font', or sometimes `like 664this'. 665 666 667File: tar.info, Node: basic tar options, Next: frequent operations, Prev: stylistic conventions, Up: Tutorial 668 6692.3 Basic `tar' Operations and Options 670====================================== 671 672`tar' can take a wide variety of arguments which specify and define the 673actions it will have on the particular set of files or the archive. The 674main types of arguments to `tar' fall into one of two classes: 675operations, and options. 676 677 Some arguments fall into a class called "operations"; exactly one of 678these is both allowed and required for any instance of using `tar'; you 679may _not_ specify more than one. People sometimes speak of "operating 680modes". You are in a particular operating mode when you have specified 681the operation which specifies it; there are eight operations in total, 682and thus there are eight operating modes. 683 684 The other arguments fall into the class known as "options". You are 685not required to specify any options, and you are allowed to specify more 686than one at a time (depending on the way you are using `tar' at that 687time). Some options are used so frequently, and are so useful for 688helping you type commands more carefully that they are effectively 689"required". We will discuss them in this chapter. 690 691 You can write most of the `tar' operations and options in any of 692three forms: long (mnemonic) form, short form, and old style. Some of 693the operations and options have no short or "old" forms; however, the 694operations and options which we will cover in this tutorial have 695corresponding abbreviations. We will indicate those abbreviations 696appropriately to get you used to seeing them. (Note that the "old 697style" option forms exist in GNU `tar' for compatibility with Unix 698`tar'. In this book we present a full discussion of this way of writing 699options and operations (*note Old Options::), and we discuss the other 700two styles of writing options (*Note Long Options::, and *note Short 701Options::). 702 703 In the examples and in the text of this tutorial, we usually use the 704long forms of operations and options; but the "short" forms produce the 705same result and can make typing long `tar' commands easier. For 706example, instead of typing 707 708 `tar --create --verbose --file=afiles.tar apple angst aspic' 709 710you can type 711 `tar -c -v -f afiles.tar apple angst aspic' 712 713or even 714 `tar -cvf afiles.tar apple angst aspic' 715 716For more information on option syntax, see *note Advanced tar::. In 717discussions in the text, when we name an option by its long form, we 718also give the corresponding short option in parentheses. 719 720 The term, "option", can be confusing at times, since "operations" are 721often lumped in with the actual, _optional_ "options" in certain general 722class statements. For example, we just talked about "short and long 723forms of options and operations". However, experienced `tar' users 724often refer to these by shorthand terms such as, "short and long 725options". This term assumes that the "operations" are included, also. 726Context will help you determine which definition of "options" to use. 727 728 Similarly, the term "command" can be confusing, as it is often used 729in two different ways. People sometimes refer to `tar' "commands". A 730`tar' "command" is the entire command line of user input which tells 731`tar' what to do -- including the operation, options, and any arguments 732(file names, pipes, other commands, etc). However, you will also 733sometimes hear the term "the `tar' command". When the word "command" is 734used specifically like this, a person is usually referring to the `tar' 735_operation_, not the whole line. Again, use context to figure out which 736of the meanings the speaker intends. 737 738 739File: tar.info, Node: frequent operations, Next: Two Frequent Options, Prev: basic tar options, Up: Tutorial 740 7412.4 The Three Most Frequently Used Operations 742============================================= 743 744Here are the three most frequently used operations (both short and long 745forms), as well as a brief description of their meanings. The rest of 746this chapter will cover how to use these operations in detail. We will 747present the rest of the operations in the next chapter. 748 749`--create' 750`-c' 751 Create a new `tar' archive. 752 753`--list' 754`-t' 755 List the contents of an archive. 756 757`--extract' 758`-x' 759 Extract one or more members from an archive. 760 761 762File: tar.info, Node: Two Frequent Options, Next: create, Prev: frequent operations, Up: Tutorial 763 7642.5 Two Frequently Used Options 765=============================== 766 767To understand how to run `tar' in the three operating modes listed 768previously, you also need to understand how to use two of the options to 769`tar': `--file' (which takes an archive file as an argument) and 770`--verbose'. (You are usually not _required_ to specify either of these 771options when you run `tar', but they can be very useful in making things 772more clear and helping you avoid errors.) 773 774* Menu: 775 776* file tutorial:: 777* verbose tutorial:: 778* help tutorial:: 779 780 781File: tar.info, Node: file tutorial, Next: verbose tutorial, Up: Two Frequent Options 782 783The `--file' Option 784------------------- 785 786`--file=ARCHIVE-NAME' 787`-f ARCHIVE-NAME' 788 Specify the name of an archive file. 789 790 You can specify an argument for the `--file=ARCHIVE-NAME' (`-f 791ARCHIVE-NAME') option whenever you use `tar'; this option determines the 792name of the archive file that `tar' will work on. 793 794 If you don't specify this argument, then `tar' will examine the 795environment variable `TAPE'. If it is set, its value will be used as 796the archive name. Otherwise, `tar' will use the default archive, 797determined at the compile time. Usually it is standard output or some 798physical tape drive attached to your machine (you can verify what the 799default is by running `tar --show-defaults', *note defaults::). If 800there is no tape drive attached, or the default is not meaningful, then 801`tar' will print an error message. The error message might look roughly 802like one of the following: 803 804 tar: can't open /dev/rmt8 : No such device or address 805 tar: can't open /dev/rsmt0 : I/O error 806 807To avoid confusion, we recommend that you always specify an archive file 808name by using `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') when writing 809your `tar' commands. For more information on using the 810`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option, see *note file::. 811 812 813File: tar.info, Node: verbose tutorial, Next: help tutorial, Prev: file tutorial, Up: Two Frequent Options 814 815The `--verbose' Option 816---------------------- 817 818`--verbose' 819`-v' 820 Show the files being worked on as `tar' is running. 821 822 `--verbose' (`-v') shows details about the results of running `tar'. 823This can be especially useful when the results might not be obvious. 824For example, if you want to see the progress of `tar' as it writes files 825into the archive, you can use the `--verbose' option. In the beginning, 826you may find it useful to use `--verbose' at all times; when you are 827more accustomed to `tar', you will likely want to use it at certain 828times but not at others. We will use `--verbose' at times to help make 829something clear, and we will give many examples both using and not using 830`--verbose' to show the differences. 831 832 Each instance of `--verbose' on the command line increases the 833verbosity level by one, so if you need more details on the output, 834specify it twice. 835 836 When reading archives (`--list', `--extract', `--diff'), `tar' by 837default prints only the names of the members being extracted. Using 838`--verbose' will show a full, `ls' style member listing. 839 840 In contrast, when writing archives (`--create', `--append', 841`--update'), `tar' does not print file names by default. So, a single 842`--verbose' option shows the file names being added to the archive, 843while two `--verbose' options enable the full listing. 844 845 For example, to create an archive in verbose mode: 846 847 $ `tar -cvf afiles.tar apple angst aspic' 848 apple 849 angst 850 aspic 851 852Creating the same archive with the verbosity level 2 could give: 853 854 $ `tar -cvvf afiles.tar apple angst aspic' 855 -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple 856 -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst 857 -rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic 858 859This works equally well using short or long forms of options. Using 860long forms, you would simply write out the mnemonic form of the option 861twice, like this: 862 863 $ `tar --create --verbose --verbose ...' 864 865Note that you must double the hyphens properly each time. 866 867 Later in the tutorial, we will give examples using 868`--verbose --verbose'. 869 870 The full output consists of six fields: 871 872 * File type and permissions in symbolic form. These are displayed in 873 the same format as the first column of `ls -l' output (*note 874 format=verbose: (fileutils)What information is listed.). 875 876 * Owner name and group separated by a slash character. If these data 877 are not available (for example, when listing a `v7' format 878 archive), numeric ID values are printed instead. 879 880 * Size of the file, in bytes. 881 882 * File modification date in ISO 8601 format. 883 884 * File modification time. 885 886 * File name. If the name contains any special characters (white 887 space, newlines, etc.) these are displayed in an unambiguous form 888 using so called "quoting style". For the detailed discussion of 889 available styles and on how to use them, see *note quoting 890 styles::. 891 892 Depending on the file type, the name can be followed by some 893 additional information, described in the following table: 894 895 `-> LINK-NAME' 896 The file or archive member is a "symbolic link" and LINK-NAME 897 is the name of file it links to. 898 899 `link to LINK-NAME' 900 The file or archive member is a "hard link" and LINK-NAME is 901 the name of file it links to. 902 903 `--Long Link--' 904 The archive member is an old GNU format long link. You will 905 normally not encounter this. 906 907 `--Long Name--' 908 The archive member is an old GNU format long name. You will 909 normally not encounter this. 910 911 `--Volume Header--' 912 The archive member is a GNU "volume header" (*note Tape 913 Files::). 914 915 `--Continued at byte N--' 916 Encountered only at the beginning of a multy-volume archive 917 (*note Using Multiple Tapes::). This archive member is a 918 continuation from the previous volume. The number N gives the 919 offset where the original file was split. 920 921 `--Mangled file names--' 922 This archive member contains "mangled file names" 923 declarations, a special member type that was used by early 924 versions of GNU `tar'. You probably will never encounter 925 this, unless you are reading a very old archive. 926 927 `unknown file type C' 928 An archive member of unknown type. C is the type character 929 from the archive header. If you encounter such a message, it 930 means that either your archive contains proprietary member 931 types GNU `tar' is not able to handle, or the archive is 932 corrupted. 933 934 For example, here is an archive listing containing most of the 935special suffixes explained above: 936 937 V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header-- 938 -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at 939 byte 32456-- 940 -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple 941 lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple 942 -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues 943 hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues 944 945 946File: tar.info, Node: help tutorial, Prev: verbose tutorial, Up: Two Frequent Options 947 948Getting Help: Using the `--help' Option 949--------------------------------------- 950 951`--help' 952 The `--help' option to `tar' prints out a very brief list of all 953 operations and option available for the current version of `tar' 954 available on your system. 955 956 957File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial 958 9592.6 How to Create Archives 960========================== 961 962 _(This message will disappear, once this node revised.)_ 963 964 One of the basic operations of `tar' is `--create' (`-c'), which you 965use to create a `tar' archive. We will explain `--create' first 966because, in order to learn about the other operations, you will find it 967useful to have an archive available to practice on. 968 969 To make this easier, in this section you will first create a 970directory containing three files. Then, we will show you how to create 971an _archive_ (inside the new directory). Both the directory, and the 972archive are specifically for you to practice on. The rest of this 973chapter and the next chapter will show many examples using this 974directory and the files you will create: some of those files may be 975other directories and other archives. 976 977 The three files you will archive in this example are called `blues', 978`folk', and `jazz'. The archive is called `collection.tar'. 979 980 This section will proceed slowly, detailing how to use `--create' in 981`verbose' mode, and showing examples using both short and long forms. 982In the rest of the tutorial, and in the examples in the next chapter, we 983will proceed at a slightly quicker pace. This section moves more slowly 984to allow beginning users to understand how `tar' works. 985 986* Menu: 987 988* prepare for examples:: 989* Creating the archive:: 990* create verbose:: 991* short create:: 992* create dir:: 993 994 995File: tar.info, Node: prepare for examples, Next: Creating the archive, Up: create 996 9972.6.1 Preparing a Practice Directory for Examples 998------------------------------------------------- 999 1000To follow along with this and future examples, create a new directory 1001called `practice' containing files called `blues', `folk' and `jazz'. 1002The files can contain any information you like: ideally, they should 1003contain information which relates to their names, and be of different 1004lengths. Our examples assume that `practice' is a subdirectory of your 1005home directory. 1006 1007 Now `cd' to the directory named `practice'; `practice' is now your 1008"working directory". (_Please note_: Although the full path name of 1009this directory is `/HOMEDIR/practice', in our examples we will refer to 1010this directory as `practice'; the HOMEDIR is presumed. 1011 1012 In general, you should check that the files to be archived exist 1013where you think they do (in the working directory) by running `ls'. 1014Because you just created the directory and the files and have changed to 1015that directory, you probably don't need to do that this time. 1016 1017 It is very important to make sure there isn't already a file in the 1018working directory with the archive name you intend to use (in this case, 1019`collection.tar'), or that you don't care about its contents. Whenever 1020you use `create', `tar' will erase the current contents of the file 1021named by `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') if it exists. `tar' 1022will not tell you if you are about to overwrite an archive unless you 1023specify an option which does this (*note backup::, for the information 1024on how to do so). To add files to an existing archive, you need to use 1025a different option, such as `--append' (`-r'); see *note append:: for 1026information on how to do this. 1027 1028 1029File: tar.info, Node: Creating the archive, Next: create verbose, Prev: prepare for examples, Up: create 1030 10312.6.2 Creating the Archive 1032-------------------------- 1033 1034To place the files `blues', `folk', and `jazz' into an archive named 1035`collection.tar', use the following command: 1036 1037 $ `tar --create --file=collection.tar blues folk jazz' 1038 1039 The order of the arguments is not very important, _when using long 1040option forms_. You could also say: 1041 1042 $ `tar blues --create folk --file=collection.tar jazz' 1043 1044However, you can see that this order is harder to understand; this is 1045why we will list the arguments in the order that makes the commands 1046easiest to understand (and we encourage you to do the same when you use 1047`tar', to avoid errors). 1048 1049 Note that the sequence `--file=collection.tar' is considered to be 1050_one_ argument. If you substituted any other string of characters for 1051`collection.tar', then that string would become the name of the archive 1052file you create. 1053 1054 The order of the options becomes more important when you begin to use 1055short forms. With short forms, if you type commands in the wrong order 1056(even if you type them correctly in all other ways), you may end up with 1057results you don't expect. For this reason, it is a good idea to get 1058into the habit of typing options in the order that makes inherent sense. 1059*Note short create::, for more information on this. 1060 1061 In this example, you type the command as shown above: `--create' is 1062the operation which creates the new archive (`collection.tar'), and 1063`--file' is the option which lets you give it the name you chose. The 1064files, `blues', `folk', and `jazz', are now members of the archive, 1065`collection.tar' (they are "file name arguments" to the `--create' 1066operation. *Note Choosing::, for the detailed discussion on these.) Now 1067that they are in the archive, they are called _archive members_, not 1068files. (*note members: Definitions.). 1069 1070 When you create an archive, you _must_ specify which files you want 1071placed in the archive. If you do not specify any archive members, GNU 1072`tar' will complain. 1073 1074 If you now list the contents of the working directory (`ls'), you 1075will find the archive file listed as well as the files you saw 1076previously: 1077 1078 blues folk jazz collection.tar 1079 1080Creating the archive `collection.tar' did not destroy the copies of the 1081files in the directory. 1082 1083 Keep in mind that if you don't indicate an operation, `tar' will not 1084run and will prompt you for one. If you don't name any files, `tar' 1085will complain. You must have write access to the working directory, or 1086else you will not be able to create an archive in that directory. 1087 1088 _Caution_: Do not attempt to use `--create' (`-c') to add files to an 1089existing archive; it will delete the archive and write a new one. Use 1090`--append' (`-r') instead. *Note append::. 1091 1092 1093File: tar.info, Node: create verbose, Next: short create, Prev: Creating the archive, Up: create 1094 10952.6.3 Running `--create' with `--verbose' 1096----------------------------------------- 1097 1098If you include the `--verbose' (`-v') option on the command line, `tar' 1099will list the files it is acting on as it is working. In verbose mode, 1100the `create' example above would appear as: 1101 1102 $ `tar --create --verbose --file=collection.tar blues folk jazz' 1103 blues 1104 folk 1105 jazz 1106 1107 This example is just like the example we showed which did not use 1108`--verbose', except that `tar' generated the remaining lines . 1109 1110 In the rest of the examples in this chapter, we will frequently use 1111`verbose' mode so we can show actions or `tar' responses that you would 1112otherwise not see, and which are important for you to understand. 1113 1114 1115File: tar.info, Node: short create, Next: create dir, Prev: create verbose, Up: create 1116 11172.6.4 Short Forms with `create' 1118------------------------------- 1119 1120As we said before, the `--create' (`-c') operation is one of the most 1121basic uses of `tar', and you will use it countless times. Eventually, 1122you will probably want to use abbreviated (or "short") forms of options. 1123A full discussion of the three different forms that options can take 1124appears in *note Styles::; for now, here is what the previous example 1125(including the `--verbose' (`-v') option) looks like using short option 1126forms: 1127 1128 $ `tar -cvf collection.tar blues folk jazz' 1129 blues 1130 folk 1131 jazz 1132 1133As you can see, the system responds the same no matter whether you use 1134long or short option forms. 1135 1136 One difference between using short and long option forms is that, 1137although the exact placement of arguments following options is no more 1138specific when using short forms, it is easier to become confused and 1139make a mistake when using short forms. For example, suppose you 1140attempted the above example in the following way: 1141 1142 $ `tar -cfv collection.tar blues folk jazz' 1143 1144In this case, `tar' will make an archive file called `v', containing the 1145files `blues', `folk', and `jazz', because the `v' is the closest "file 1146name" to the `-f' option, and is thus taken to be the chosen archive 1147file name. `tar' will try to add a file called `collection.tar' to the 1148`v' archive file; if the file `collection.tar' did not already exist, 1149`tar' will report an error indicating that this file does not exist. If 1150the file `collection.tar' does already exist (e.g., from a previous 1151command you may have run), then `tar' will add this file to the archive. 1152Because the `-v' option did not get registered, `tar' will not run under 1153`verbose' mode, and will not report its progress. 1154 1155 The end result is that you may be quite confused about what happened, 1156and possibly overwrite a file. To illustrate this further, we will show 1157you how an example we showed previously would look using short forms. 1158 1159 This example, 1160 1161 $ `tar blues --create folk --file=collection.tar jazz' 1162 1163is confusing as it is. When shown using short forms, however, it 1164becomes much more so: 1165 1166 $ `tar blues -c folk -f collection.tar jazz' 1167 1168It would be very easy to put the wrong string of characters immediately 1169following the `-f', but doing that could sacrifice valuable data. 1170 1171 For this reason, we recommend that you pay very careful attention to 1172the order of options and placement of file and archive names, especially 1173when using short option forms. Not having the option name written out 1174mnemonically can affect how well you remember which option does what, 1175and therefore where different names have to be placed. 1176 1177 1178File: tar.info, Node: create dir, Prev: short create, Up: create 1179 11802.6.5 Archiving Directories 1181--------------------------- 1182 1183You can archive a directory by specifying its directory name as a file 1184name argument to `tar'. The files in the directory will be archived 1185relative to the working directory, and the directory will be re-created 1186along with its contents when the archive is extracted. 1187 1188 To archive a directory, first move to its superior directory. If you 1189have followed the previous instructions in this tutorial, you should 1190type: 1191 1192 $ `cd ..' 1193 $ 1194 1195This will put you into the directory which contains `practice', i.e., 1196your home directory. Once in the superior directory, you can specify 1197the subdirectory, `practice', as a file name argument. To store 1198`practice' in the new archive file `music.tar', type: 1199 1200 $ `tar --create --verbose --file=music.tar practice' 1201 1202`tar' should output: 1203 1204 practice/ 1205 practice/blues 1206 practice/folk 1207 practice/jazz 1208 practice/collection.tar 1209 1210 Note that the archive thus created is not in the subdirectory 1211`practice', but rather in the current working directory--the directory 1212from which `tar' was invoked. Before trying to archive a directory from 1213its superior directory, you should make sure you have write access to 1214the superior directory itself, not only the directory you are trying 1215archive with `tar'. For example, you will probably not be able to store 1216your home directory in an archive by invoking `tar' from the root 1217directory; *Note absolute::. (Note also that `collection.tar', the 1218original archive file, has itself been archived. `tar' will accept any 1219file as a file to be archived, regardless of its content. When 1220`music.tar' is extracted, the archive file `collection.tar' will be 1221re-written into the file system). 1222 1223 If you give `tar' a command such as 1224 1225 $ `tar --create --file=foo.tar .' 1226 1227`tar' will report `tar: ./foo.tar is the archive; not dumped'. This 1228happens because `tar' creates the archive `foo.tar' in the current 1229directory before putting any files into it. Then, when `tar' attempts 1230to add all the files in the directory `.' to the archive, it notices 1231that the file `./foo.tar' is the same as the archive `foo.tar', and 1232skips it. (It makes no sense to put an archive into itself.) GNU `tar' 1233will continue in this case, and create the archive normally, except for 1234the exclusion of that one file. (_Please note:_ Other implementations 1235of `tar' may not be so clever; they will enter an infinite loop when 1236this happens, so you should not depend on this behavior unless you are 1237certain you are running GNU `tar'. In general, it is wise to always 1238place the archive outside of the directory being dumped. 1239 1240 1241File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial 1242 12432.7 How to List Archives 1244======================== 1245 1246Frequently, you will find yourself wanting to determine exactly what a 1247particular archive contains. You can use the `--list' (`-t') operation 1248to get the member names as they currently appear in the archive, as well 1249as various attributes of the files at the time they were archived. For 1250example, you can examine the archive `collection.tar' that you created 1251in the last section with the command, 1252 1253 $ `tar --list --file=collection.tar' 1254 1255The output of `tar' would then be: 1256 1257 blues 1258 folk 1259 jazz 1260 1261The archive `bfiles.tar' would list as follows: 1262 1263 ./birds 1264 baboon 1265 ./box 1266 1267Be sure to use a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option just 1268as with `--create' (`-c') to specify the name of the archive. 1269 1270 If you use the `--verbose' (`-v') option with `--list', then `tar' 1271will print out a listing reminiscent of `ls -l', showing owner, file 1272size, and so forth. This output is described in detail in *note verbose 1273member listing::. 1274 1275 If you had used `--verbose' (`-v') mode, the example above would look 1276like: 1277 1278 $ `tar --list --verbose --file=collection.tar folk' 1279 -rw-r--r-- myself user 62 1990-05-23 10:55 folk 1280 1281 It is important to notice that the output of `tar --list --verbose' 1282does not necessarily match that produced by `tar --create --verbose' 1283while creating the archive. It is because GNU `tar', unless told 1284explicitly not to do so, removes some directory prefixes from file names 1285before storing them in the archive (*Note absolute::, for more 1286information). In other words, in verbose mode GNU `tar' shows "file 1287names" when creating an archive and "member names" when listing it. 1288Consider this example: 1289 1290 $ `tar cfv archive /etc/mail' 1291 tar: Removing leading `/' from member names 1292 /etc/mail/ 1293 /etc/mail/sendmail.cf 1294 /etc/mail/aliases 1295 $ `tar tf archive' 1296 etc/mail/ 1297 etc/mail/sendmail.cf 1298 etc/mail/aliases 1299 1300 This default behavior can sometimes be inconvenient. You can force 1301GNU `tar' show member names when creating archive by supplying 1302`--show-stored-names' option. 1303 1304`--show-stored-names' 1305 Print member (as opposed to _file_) names when creating the 1306 archive. 1307 1308 You can specify one or more individual member names as arguments when 1309using `list'. In this case, `tar' will only list the names of members 1310you identify. For example, `tar --list --file=afiles.tar apple' would 1311only print `apple'. 1312 1313 Because `tar' preserves paths, file names must be specified as they 1314appear in the archive (i.e., relative to the directory from which the 1315archive was created). Therefore, it is essential when specifying member 1316names to `tar' that you give the exact member names. For example, 1317`tar --list --file=bfiles.tar birds' would produce an error message 1318something like `tar: birds: Not found in archive', because there is no 1319member named `birds', only one named `./birds'. While the names `birds' 1320and `./birds' name the same file, _member_ names by default are compared 1321verbatim. 1322 1323 However, `tar --list --file=bfiles.tar baboon' would respond with 1324`baboon', because this exact member name is in the archive file 1325`bfiles.tar'. If you are not sure of the exact file name, use "globbing 1326patterns", for example: 1327 1328 $ `tar --list --file=bfiles.tar --wildcards '*b*'' 1329 1330will list all members whose name contains `b'. *Note wildcards::, for a 1331detailed discussion of globbing patterns and related `tar' command line 1332options. 1333 1334* Menu: 1335 1336* list dir:: 1337 1338 1339File: tar.info, Node: list dir, Up: list 1340 1341Listing the Contents of a Stored Directory 1342------------------------------------------ 1343 1344To get information about the contents of an archived directory, use the 1345directory name as a file name argument in conjunction with `--list' 1346(`-t'). To find out file attributes, include the `--verbose' (`-v') 1347option. 1348 1349 For example, to find out about files in the directory `practice', in 1350the archive file `music.tar', type: 1351 1352 $ `tar --list --verbose --file=music.tar practice' 1353 1354 `tar' responds: 1355 1356 drwxrwxrwx myself user 0 1990-05-31 21:49 practice/ 1357 -rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues 1358 -rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk 1359 -rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz 1360 -rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar 1361 1362 When you use a directory name as a file name argument, `tar' acts on 1363all the files (including sub-directories) in that directory. 1364 1365 1366File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial 1367 13682.8 How to Extract Members from an Archive 1369========================================== 1370 1371 _(This message will disappear, once this node revised.)_ 1372 1373 Creating an archive is only half the job--there is no point in 1374storing files in an archive if you can't retrieve them. The act of 1375retrieving members from an archive so they can be used and manipulated 1376as unarchived files again is called "extraction". To extract files from 1377an archive, use the `--extract' (`--get' or `-x') operation. As with 1378`--create', specify the name of the archive with `--file' (`-f') option. 1379Extracting an archive does not modify the archive in any way; you can 1380extract it multiple times if you want or need to. 1381 1382 Using `--extract', you can extract an entire archive, or specific 1383files. The files can be directories containing other files, or not. As 1384with `--create' (`-c') and `--list' (`-t'), you may use the short or the 1385long form of the operation without affecting the performance. 1386 1387* Menu: 1388 1389* extracting archives:: 1390* extracting files:: 1391* extract dir:: 1392* extracting untrusted archives:: 1393* failing commands:: 1394 1395 1396File: tar.info, Node: extracting archives, Next: extracting files, Up: extract 1397 13982.8.1 Extracting an Entire Archive 1399---------------------------------- 1400 1401To extract an entire archive, specify the archive file name only, with 1402no individual file names as arguments. For example, 1403 1404 $ `tar -xvf collection.tar' 1405 1406produces this: 1407 1408 -rw-r--r-- me user 28 1996-10-18 16:31 jazz 1409 -rw-r--r-- me user 21 1996-09-23 16:44 blues 1410 -rw-r--r-- me user 20 1996-09-23 16:44 folk 1411 1412 1413File: tar.info, Node: extracting files, Next: extract dir, Prev: extracting archives, Up: extract 1414 14152.8.2 Extracting Specific Files 1416------------------------------- 1417 1418To extract specific archive members, give their exact member names as 1419arguments, as printed by `--list' (`-t'). If you had mistakenly deleted 1420one of the files you had placed in the archive `collection.tar' earlier 1421(say, `blues'), you can extract it from the archive without changing the 1422archive's structure. Its contents will be identical to the original 1423file `blues' that you deleted. 1424 1425 First, make sure you are in the `practice' directory, and list the 1426files in the directory. Now, delete the file, `blues', and list the 1427files in the directory again. 1428 1429 You can now extract the member `blues' from the archive file 1430`collection.tar' like this: 1431 1432 $ `tar --extract --file=collection.tar blues' 1433 1434If you list the files in the directory again, you will see that the file 1435`blues' has been restored, with its original permissions, data 1436modification times, and owner.(1) (These parameters will be identical 1437to those which the file had when you originally placed it in the 1438archive; any changes you may have made before deleting the file from the 1439file system, however, will _not_ have been made to the archive member.) 1440The archive file, `collection.tar', is the same as it was before you 1441extracted `blues'. You can confirm this by running `tar' with `--list' 1442(`-t'). 1443 1444 Remember that as with other operations, specifying the exact member 1445name is important. `tar --extract --file=bfiles.tar birds' will fail, 1446because there is no member named `birds'. To extract the member named 1447`./birds', you must specify `tar --extract --file=bfiles.tar ./birds'. 1448If you don't remember the exact member names, use `--list' (`-t') option 1449(*note list::). You can also extract those members that match a 1450specific "globbing pattern". For example, to extract from `bfiles.tar' 1451all files that begin with `b', no matter their directory prefix, you 1452could type: 1453 1454 $ `tar -x -f bfiles.tar --wildcards --no-anchored 'b*'' 1455 1456Here, `--wildcards' instructs `tar' to treat command line arguments as 1457globbing patterns and `--no-anchored' informs it that the patterns apply 1458to member names after any `/' delimiter. The use of globbing patterns 1459is discussed in detail in *Note wildcards::. 1460 1461 You can extract a file to standard output by combining the above 1462options with the `--to-stdout' (`-O') option (*note Writing to Standard 1463Output::). 1464 1465 If you give the `--verbose' option, then `--extract' will print the 1466names of the archive members as it extracts them. 1467 1468 ---------- Footnotes ---------- 1469 1470 (1) This is only accidentally true, but not in general. Whereas 1471modification times are always restored, in most cases, one has to be 1472root for restoring the owner, and use a special option for restoring 1473permissions. Here, it just happens that the restoring user is also the 1474owner of the archived members, and that the current `umask' is 1475compatible with original permissions. 1476 1477 1478File: tar.info, Node: extract dir, Next: extracting untrusted archives, Prev: extracting files, Up: extract 1479 14802.8.3 Extracting Files that are Directories 1481------------------------------------------- 1482 1483Extracting directories which are members of an archive is similar to 1484extracting other files. The main difference to be aware of is that if 1485the extracted directory has the same name as any directory already in 1486the working directory, then files in the extracted directory will be 1487placed into the directory of the same name. Likewise, if there are 1488files in the pre-existing directory with the same names as the members 1489which you extract, the files from the extracted archive will replace the 1490files already in the working directory (and possible subdirectories). 1491This will happen regardless of whether or not the files in the working 1492directory were more recent than those extracted (there exist, however, 1493special options that alter this behavior *note Writing::). 1494 1495 However, if a file was stored with a directory name as part of its 1496file name, and that directory does not exist under the working directory 1497when the file is extracted, `tar' will create the directory. 1498 1499 We can demonstrate how to use `--extract' to extract a directory file 1500with an example. Change to the `practice' directory if you weren't 1501there, and remove the files `folk' and `jazz'. Then, go back to the 1502parent directory and extract the archive `music.tar'. You may either 1503extract the entire archive, or you may extract only the files you just 1504deleted. To extract the entire archive, don't give any file names as 1505arguments after the archive name `music.tar'. To extract only the files 1506you deleted, use the following command: 1507 1508 $ `tar -xvf music.tar practice/folk practice/jazz' 1509 practice/folk 1510 practice/jazz 1511 1512If you were to specify two `--verbose' (`-v') options, `tar' would have 1513displayed more detail about the extracted files, as shown in the example 1514below: 1515 1516 $ `tar -xvvf music.tar practice/folk practice/jazz' 1517 -rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz 1518 -rw-r--r-- me user 20 1996-09-23 16:44 practice/folk 1519 1520Because you created the directory with `practice' as part of the file 1521names of each of the files by archiving the `practice' directory as 1522`practice', you must give `practice' as part of the file names when you 1523extract those files from the archive. 1524 1525 1526File: tar.info, Node: extracting untrusted archives, Next: failing commands, Prev: extract dir, Up: extract 1527 15282.8.4 Extracting Archives from Untrusted Sources 1529------------------------------------------------ 1530 1531Extracting files from archives can overwrite files that already exist. 1532If you receive an archive from an untrusted source, you should make a 1533new directory and extract into that directory, so that you don't have to 1534worry about the extraction overwriting one of your existing files. For 1535example, if `untrusted.tar' came from somewhere else on the Internet, 1536and you don't necessarily trust its contents, you can extract it as 1537follows: 1538 1539 $ `mkdir newdir' 1540 $ `cd newdir' 1541 $ `tar -xvf ../untrusted.tar' 1542 1543 It is also a good practice to examine contents of the archive before 1544extracting it, using `--list' (`-t') option, possibly combined with 1545`--verbose' (`-v'). 1546 1547 1548File: tar.info, Node: failing commands, Prev: extracting untrusted archives, Up: extract 1549 15502.8.5 Commands That Will Fail 1551----------------------------- 1552 1553Here are some sample commands you might try which will not work, and why 1554they won't work. 1555 1556 If you try to use this command, 1557 1558 $ `tar -xvf music.tar folk jazz' 1559 1560you will get the following response: 1561 1562 tar: folk: Not found in archive 1563 tar: jazz: Not found in archive 1564 $ 1565 1566This is because these files were not originally _in_ the parent 1567directory `..', where the archive is located; they were in the 1568`practice' directory, and their file names reflect this: 1569 1570 $ `tar -tvf music.tar' 1571 practice/folk 1572 practice/jazz 1573 practice/rock 1574 1575Likewise, if you try to use this command, 1576 1577 $ `tar -tvf music.tar folk jazz' 1578 1579you would get a similar response. Members with those names are not in 1580the archive. You must use the correct member names, or wildcards, in 1581order to extract the files from the archive. 1582 1583 If you have forgotten the correct names of the files in the archive, 1584use `tar --list --verbose' to list them correctly. 1585 1586 1587File: tar.info, Node: going further, Prev: extract, Up: Tutorial 1588 15892.9 Going Further Ahead in this Manual 1590====================================== 1591 1592 1593File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top 1594 15953 Invoking GNU `tar' 1596******************** 1597 1598 _(This message will disappear, once this node revised.)_ 1599 1600 This chapter is about how one invokes the GNU `tar' command, from the 1601command synopsis (*note Synopsis::). There are numerous options, and 1602many styles for writing them. One mandatory option specifies the 1603operation `tar' should perform (*note Operation Summary::), other 1604options are meant to detail how this operation should be performed 1605(*note Option Summary::). Non-option arguments are not always 1606interpreted the same way, depending on what the operation is. 1607 1608 You will find in this chapter everything about option styles and 1609rules for writing them (*note Styles::). On the other hand, operations 1610and options are fully described elsewhere, in other chapters. Here, you 1611will find only synthetic descriptions for operations and options, 1612together with pointers to other parts of the `tar' manual. 1613 1614 Some options are so special they are fully described right in this 1615chapter. They have the effect of inhibiting the normal operation of 1616`tar' or else, they globally alter the amount of feedback the user 1617receives about what is going on. These are the `--help' and `--version' 1618(*note help::), `--verbose' (*note verbose::) and `--interactive' 1619options (*note interactive::). 1620 1621* Menu: 1622 1623* Synopsis:: 1624* using tar options:: 1625* Styles:: 1626* All Options:: 1627* help:: 1628* defaults:: 1629* verbose:: 1630* interactive:: 1631 1632 1633File: tar.info, Node: Synopsis, Next: using tar options, Up: tar invocation 1634 16353.1 General Synopsis of `tar' 1636============================= 1637 1638The GNU `tar' program is invoked as either one of: 1639 1640 `tar OPTION... [NAME]...' 1641 `tar LETTER... [ARGUMENT]... [OPTION]... [NAME]...' 1642 1643 The second form is for when old options are being used. 1644 1645 You can use `tar' to store files in an archive, to extract them from 1646an archive, and to do other types of archive manipulation. The primary 1647argument to `tar', which is called the "operation", specifies which 1648action to take. The other arguments to `tar' are either "options", 1649which change the way `tar' performs an operation, or file names or 1650archive members, which specify the files or members `tar' is to act on. 1651 1652 You can actually type in arguments in any order, even if in this 1653manual the options always precede the other arguments, to make examples 1654easier to understand. Further, the option stating the main operation 1655mode (the `tar' main command) is usually given first. 1656 1657 Each NAME in the synopsis above is interpreted as an archive member 1658name when the main command is one of `--compare' (`--diff', `-d'), 1659`--delete', `--extract' (`--get', `-x'), `--list' (`-t') or `--update' 1660(`-u'). When naming archive members, you must give the exact name of 1661the member in the archive, as it is printed by `--list'. For `--append' 1662(`-r') and `--create' (`-c'), these NAME arguments specify the names of 1663either files or directory hierarchies to place in the archive. These 1664files or hierarchies should already exist in the file system, prior to 1665the execution of the `tar' command. 1666 1667 `tar' interprets relative file names as being relative to the working 1668directory. `tar' will make all file names relative (by removing leading 1669slashes when archiving or restoring files), unless you specify otherwise 1670(using the `--absolute-names' option). *Note absolute::, for more 1671information about `--absolute-names'. 1672 1673 If you give the name of a directory as either a file name or a member 1674name, then `tar' acts recursively on all the files and directories 1675beneath that directory. For example, the name `/' identifies all the 1676files in the file system to `tar'. 1677 1678 The distinction between file names and archive member names is 1679especially important when shell globbing is used, and sometimes a source 1680of confusion for newcomers. *Note wildcards::, for more information 1681about globbing. The problem is that shells may only glob using existing 1682files in the file system. Only `tar' itself may glob on archive 1683members, so when needed, you must ensure that wildcard characters reach 1684`tar' without being interpreted by the shell first. Using a backslash 1685before `*' or `?', or putting the whole argument between quotes, is 1686usually sufficient for this. 1687 1688 Even if NAMEs are often specified on the command line, they can also 1689be read from a text file in the file system, using the 1690`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option. 1691 1692 If you don't use any file name arguments, `--append' (`-r'), 1693`--delete' and `--concatenate' (`--catenate', `-A') will do nothing, 1694while `--create' (`-c') will usually yield a diagnostic and inhibit 1695`tar' execution. The other operations of `tar' (`--list', `--extract', 1696`--compare', and `--update') will act on the entire contents of the 1697archive. 1698 1699 Besides successful exits, GNU `tar' may fail for many reasons. Some 1700reasons correspond to bad usage, that is, when the `tar' command is 1701improperly written. Errors may be encountered later, while encountering 1702an error processing the archive or the files. Some errors are 1703recoverable, in which case the failure is delayed until `tar' has 1704completed all its work. Some errors are such that it would not 1705meaningful, or at least risky, to continue processing: `tar' then aborts 1706processing immediately. All abnormal exits, whether immediate or 1707delayed, should always be clearly diagnosed on `stderr', after a line 1708stating the nature of the error. 1709 1710 GNU `tar' returns only a few exit statuses. I'm really aiming 1711simplicity in that area, for now. If you are not using the `--compare' 1712`--diff', `-d') option, zero means that everything went well, besides 1713maybe innocuous warnings. Nonzero means that something went wrong. 1714Right now, as of today, "nonzero" is almost always 2, except for remote 1715operations, where it may be 128. 1716 1717 1718File: tar.info, Node: using tar options, Next: Styles, Prev: Synopsis, Up: tar invocation 1719 17203.2 Using `tar' Options 1721======================= 1722 1723GNU `tar' has a total of eight operating modes which allow you to 1724perform a variety of tasks. You are required to choose one operating 1725mode each time you employ the `tar' program by specifying one, and only 1726one operation as an argument to the `tar' command (two lists of four 1727operations each may be found at *note frequent operations:: and *note 1728Operations::). Depending on circumstances, you may also wish to 1729customize how the chosen operating mode behaves. For example, you may 1730wish to change the way the output looks, or the format of the files that 1731you wish to archive may require you to do something special in order to 1732make the archive look right. 1733 1734 You can customize and control `tar''s performance by running `tar' 1735with one or more options (such as `--verbose' (`-v'), which we used in 1736the tutorial). As we said in the tutorial, "options" are arguments to 1737`tar' which are (as their name suggests) optional. Depending on the 1738operating mode, you may specify one or more options. Different options 1739will have different effects, but in general they all change details of 1740the operation, such as archive format, archive name, or level of user 1741interaction. Some options make sense with all operating modes, while 1742others are meaningful only with particular modes. You will likely use 1743some options frequently, while you will only use others infrequently, or 1744not at all. (A full list of options is available in *note All 1745Options::.) 1746 1747 The `TAR_OPTIONS' environment variable specifies default options to 1748be placed in front of any explicit options. For example, if 1749`TAR_OPTIONS' is `-v --unlink-first', `tar' behaves as if the two 1750options `-v' and `--unlink-first' had been specified before any explicit 1751options. Option specifications are separated by whitespace. A 1752backslash escapes the next character, so it can be used to specify an 1753option containing whitespace or a backslash. 1754 1755 Note that `tar' options are case sensitive. For example, the options 1756`-T' and `-t' are different; the first requires an argument for stating 1757the name of a file providing a list of NAMEs, while the second does not 1758require an argument and is another way to write `--list' (`-t'). 1759 1760 In addition to the eight operations, there are many options to `tar', 1761and three different styles for writing both: long (mnemonic) form, short 1762form, and old style. These styles are discussed below. Both the 1763options and the operations can be written in any of these three styles. 1764 1765 1766File: tar.info, Node: Styles, Next: All Options, Prev: using tar options, Up: tar invocation 1767 17683.3 The Three Option Styles 1769=========================== 1770 1771There are three styles for writing operations and options to the command 1772line invoking `tar'. The different styles were developed at different 1773times during the history of `tar'. These styles will be presented 1774below, from the most recent to the oldest. 1775 1776 Some options must take an argument. (For example, `--file' (`-f')) 1777takes the name of an archive file as an argument. If you do not supply 1778an archive file name, `tar' will use a default, but this can be 1779confusing; thus, we recommend that you always supply a specific archive 1780file name.) Where you _place_ the arguments generally depends on which 1781style of options you choose. We will detail specific information 1782relevant to each option style in the sections on the different option 1783styles, below. The differences are subtle, yet can often be very 1784important; incorrect option placement can cause you to overwrite a 1785number of important files. We urge you to note these differences, and 1786only use the option style(s) which makes the most sense to you until you 1787feel comfortable with the others. 1788 1789 Some options _may_ take an argument. Such options may have at most 1790long and short forms, they do not have old style equivalent. The rules 1791for specifying an argument for such options are stricter than those for 1792specifying mandatory arguments. Please, pay special attention to them. 1793 1794* Menu: 1795 1796* Long Options:: Long Option Style 1797* Short Options:: Short Option Style 1798* Old Options:: Old Option Style 1799* Mixing:: Mixing Option Styles 1800 1801 1802File: tar.info, Node: Long Options, Next: Short Options, Up: Styles 1803 18043.3.1 Long Option Style 1805----------------------- 1806 1807Each option has at least one "long" (or "mnemonic") name starting with 1808two dashes in a row, e.g., `--list'. The long names are more clear than 1809their corresponding short or old names. It sometimes happens that a 1810single long option has many different different names which are 1811synonymous, such as `--compare' and `--diff'. In addition, long option 1812names can be given unique abbreviations. For example, `--cre' can be 1813used in place of `--create' because there is no other long option which 1814begins with `cre'. (One way to find this out is by trying it and seeing 1815what happens; if a particular abbreviation could represent more than one 1816option, `tar' will tell you that that abbreviation is ambiguous and 1817you'll know that that abbreviation won't work. You may also choose to 1818run `tar --help' to see a list of options. Be aware that if you run 1819`tar' with a unique abbreviation for the long name of an option you 1820didn't want to use, you are stuck; `tar' will perform the command as 1821ordered.) 1822 1823 Long options are meant to be obvious and easy to remember, and their 1824meanings are generally easier to discern than those of their 1825corresponding short options (see below). For example: 1826 1827 $ `tar --create --verbose --blocking-factor=20 --file=/dev/rmt0' 1828 1829gives a fairly good set of hints about what the command does, even for 1830those not fully acquainted with `tar'. 1831 1832 Long options which require arguments take those arguments immediately 1833following the option name. There are two ways of specifying a mandatory 1834argument. It can be separated from the option name either by an equal 1835sign, or by any amount of white space characters. For example, the 1836`--file' option (which tells the name of the `tar' archive) is given a 1837file such as `archive.tar' as argument by using any of the following 1838notations: `--file=archive.tar' or `--file archive.tar'. 1839 1840 In contrast, optional arguments must always be introduced using an 1841equal sign. For example, the `--backup' option takes an optional 1842argument specifying backup type. It must be used as 1843`--backup=BACKUP-TYPE'. 1844 1845 1846File: tar.info, Node: Short Options, Next: Old Options, Prev: Long Options, Up: Styles 1847 18483.3.2 Short Option Style 1849------------------------ 1850 1851Most options also have a "short option" name. Short options start with 1852a single dash, and are followed by a single character, e.g., `-t' (which 1853is equivalent to `--list'). The forms are absolutely identical in 1854function; they are interchangeable. 1855 1856 The short option names are faster to type than long option names. 1857 1858 Short options which require arguments take their arguments 1859immediately following the option, usually separated by white space. It 1860is also possible to stick the argument right after the short option 1861name, using no intervening space. For example, you might write 1862`-f archive.tar' or `-farchive.tar' instead of using 1863`--file=archive.tar'. Both `--file=ARCHIVE-NAME' and `-f ARCHIVE-NAME' 1864denote the option which indicates a specific archive, here named 1865`archive.tar'. 1866 1867 Short options which take optional arguments take their arguments 1868immediately following the option letter, _without any intervening white 1869space characters_. 1870 1871 Short options' letters may be clumped together, but you are not 1872required to do this (as compared to old options; see below). When short 1873options are clumped as a set, use one (single) dash for them all, e.g., 1874``tar' -cvf'. Only the last option in such a set is allowed to have an 1875argument(1). 1876 1877 When the options are separated, the argument for each option which 1878requires an argument directly follows that option, as is usual for Unix 1879programs. For example: 1880 1881 $ `tar -c -v -b 20 -f /dev/rmt0' 1882 1883 If you reorder short options' locations, be sure to move any 1884arguments that belong to them. If you do not move the arguments 1885properly, you may end up overwriting files. 1886 1887 ---------- Footnotes ---------- 1888 1889 (1) Clustering many options, the last of which has an argument, is a 1890rather opaque way to write options. Some wonder if GNU `getopt' should 1891not even be made helpful enough for considering such usages as invalid. 1892 1893 1894File: tar.info, Node: Old Options, Next: Mixing, Prev: Short Options, Up: Styles 1895 18963.3.3 Old Option Style 1897---------------------- 1898 1899 _(This message will disappear, once this node revised.)_ 1900 1901 Like short options, "old options" are single letters. However, old 1902options must be written together as a single clumped set, without spaces 1903separating them or dashes preceding them(1). This set of letters must 1904be the first to appear on the command line, after the `tar' program name 1905and some white space; old options cannot appear anywhere else. The 1906letter of an old option is exactly the same letter as the corresponding 1907short option. For example, the old option `t' is the same as the short 1908option `-t', and consequently, the same as the long option `--list'. So 1909for example, the command `tar cv' specifies the option `-v' in addition 1910to the operation `-c'. 1911 1912 When options that need arguments are given together with the command, 1913all the associated arguments follow, in the same order as the options. 1914Thus, the example given previously could also be written in the old 1915style as follows: 1916 1917 $ `tar cvbf 20 /dev/rmt0' 1918 1919Here, `20' is the argument of `-b' and `/dev/rmt0' is the argument of 1920`-f'. 1921 1922 On the other hand, this old style syntax makes it difficult to match 1923option letters with their corresponding arguments, and is often 1924confusing. In the command `tar cvbf 20 /dev/rmt0', for example, `20' is 1925the argument for `-b', `/dev/rmt0' is the argument for `-f', and `-v' 1926does not have a corresponding argument. Even using short options like 1927in `tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all arguments next 1928to the option they pertain to. 1929 1930 If you want to reorder the letters in the old option argument, be 1931sure to reorder any corresponding argument appropriately. 1932 1933 This old way of writing `tar' options can surprise even experienced 1934users. For example, the two commands: 1935 1936 `tar cfz archive.tar.gz file' 1937 `tar -cfz archive.tar.gz file' 1938 1939are quite different. The first example uses `archive.tar.gz' as the 1940value for option `f' and recognizes the option `z'. The second example, 1941however, uses `z' as the value for option `f' -- probably not what was 1942intended. 1943 1944 Old options are kept for compatibility with old versions of `tar'. 1945 1946 This second example could be corrected in many ways, among which the 1947following are equivalent: 1948 1949 `tar -czf archive.tar.gz file' 1950 `tar -cf archive.tar.gz -z file' 1951 `tar cf archive.tar.gz -z file' 1952 1953 As far as we know, all `tar' programs, GNU and non-GNU, support old 1954options. GNU `tar' supports them not only for historical reasons, but 1955also because many people are used to them. For compatibility with Unix 1956`tar', the first argument is always treated as containing command and 1957option letters even if it doesn't start with `-'. Thus, `tar c' is 1958equivalent to `tar -c': both of them specify the `--create' (`-c') 1959command to create an archive. 1960 1961 ---------- Footnotes ---------- 1962 1963 (1) Beware that if you precede options with a dash, you are announcing 1964the short option style instead of the old option style; short options 1965are decoded differently. 1966 1967 1968File: tar.info, Node: Mixing, Prev: Old Options, Up: Styles 1969 19703.3.4 Mixing Option Styles 1971-------------------------- 1972 1973All three styles may be intermixed in a single `tar' command, so long as 1974the rules for each style are fully respected(1). Old style options and 1975either of the modern styles of options may be mixed within a single 1976`tar' command. However, old style options must be introduced as the 1977first arguments only, following the rule for old options (old options 1978must appear directly after the `tar' command and some white space). 1979Modern options may be given only after all arguments to the old options 1980have been collected. If this rule is not respected, a modern option 1981might be falsely interpreted as the value of the argument to one of the 1982old style options. 1983 1984 For example, all the following commands are wholly equivalent, and 1985illustrate the many combinations and orderings of option styles. 1986 1987 `tar --create --file=archive.tar' 1988 `tar --create -f archive.tar' 1989 `tar --create -farchive.tar' 1990 `tar --file=archive.tar --create' 1991 `tar --file=archive.tar -c' 1992 `tar -c --file=archive.tar' 1993 `tar -c -f archive.tar' 1994 `tar -c -farchive.tar' 1995 `tar -cf archive.tar' 1996 `tar -cfarchive.tar' 1997 `tar -f archive.tar --create' 1998 `tar -f archive.tar -c' 1999 `tar -farchive.tar --create' 2000 `tar -farchive.tar -c' 2001 `tar c --file=archive.tar' 2002 `tar c -f archive.tar' 2003 `tar c -farchive.tar' 2004 `tar cf archive.tar' 2005 `tar f archive.tar --create' 2006 `tar f archive.tar -c' 2007 `tar fc archive.tar' 2008 2009 On the other hand, the following commands are _not_ equivalent to the 2010previous set: 2011 2012 `tar -f -c archive.tar' 2013 `tar -fc archive.tar' 2014 `tar -fcarchive.tar' 2015 `tar -farchive.tarc' 2016 `tar cfarchive.tar' 2017 2018These last examples mean something completely different from what the 2019user intended (judging based on the example in the previous set which 2020uses long options, whose intent is therefore very clear). The first 2021four specify that the `tar' archive would be a file named `-c', `c', 2022`carchive.tar' or `archive.tarc', respectively. The first two examples 2023also specify a single non-option, NAME argument having the value 2024`archive.tar'. The last example contains only old style option letters 2025(repeating option `c' twice), not all of which are meaningful (eg., `.', 2026`h', or `i'), with no argument value. 2027 2028 ---------- Footnotes ---------- 2029 2030 (1) Before GNU `tar' version 1.11.6, a bug prevented intermixing old 2031style options with long options in some cases. 2032 2033 2034File: tar.info, Node: All Options, Next: help, Prev: Styles, Up: tar invocation 2035 20363.4 All `tar' Options 2037===================== 2038 2039The coming manual sections contain an alphabetical listing of all `tar' 2040operations and options, with brief descriptions and cross references to 2041more in-depth explanations in the body of the manual. They also contain 2042an alphabetically arranged table of the short option forms with their 2043corresponding long option. You can use this table as a reference for 2044deciphering `tar' commands in scripts. 2045 2046* Menu: 2047 2048* Operation Summary:: 2049* Option Summary:: 2050* Short Option Summary:: 2051 2052 2053File: tar.info, Node: Operation Summary, Next: Option Summary, Up: All Options 2054 20553.4.1 Operations 2056---------------- 2057 2058`--append' 2059`-r' 2060 Appends files to the end of the archive. *Note append::. 2061 2062`--catenate' 2063`-A' 2064 Same as `--concatenate'. *Note concatenate::. 2065 2066`--compare' 2067`-d' 2068 Compares archive members with their counterparts in the file 2069 system, and reports differences in file size, mode, owner, 2070 modification date and contents. *Note compare::. 2071 2072`--concatenate' 2073`-A' 2074 Appends other `tar' archives to the end of the archive. *Note 2075 concatenate::. 2076 2077`--create' 2078`-c' 2079 Creates a new `tar' archive. *Note create::. 2080 2081`--delete' 2082 Deletes members from the archive. Don't try this on a archive on a 2083 tape! *Note delete::. 2084 2085`--diff' 2086`-d' 2087 Same `--compare'. *Note compare::. 2088 2089`--extract' 2090`-x' 2091 Extracts members from the archive into the file system. *Note 2092 extract::. 2093 2094`--get' 2095`-x' 2096 Same as `--extract'. *Note extract::. 2097 2098`--list' 2099`-t' 2100 Lists the members in an archive. *Note list::. 2101 2102`--update' 2103`-u' 2104 Adds files to the end of the archive, but only if they are newer 2105 than their counterparts already in the archive, or if they do not 2106 already exist in the archive. *Note update::. 2107 2108 2109File: tar.info, Node: Option Summary, Next: Short Option Summary, Prev: Operation Summary, Up: All Options 2110 21113.4.2 `tar' Options 2112------------------- 2113 2114`--absolute-names' 2115`-P' 2116 Normally when creating an archive, `tar' strips an initial `/' from 2117 member names. This option disables that behavior. *Note 2118 absolute::. 2119 2120`--after-date' 2121 (See `--newer', *note after::) 2122 2123`--anchored' 2124 A pattern must match an initial subsequence of the name's 2125 components. *Note controlling pattern-matching::. 2126 2127`--atime-preserve' 2128`--atime-preserve=replace' 2129`--atime-preserve=system' 2130 Attempt to preserve the access time of files when reading them. 2131 This option currently is effective only on files that you own, 2132 unless you have superuser privileges. 2133 2134 `--atime-preserve=replace' remembers the access time of a file 2135 before reading it, and then restores the access time afterwards. 2136 This may cause problems if other programs are reading the file at 2137 the same time, as the times of their accesses will be lost. On 2138 most platforms restoring the access time also requires `tar' to 2139 restore the data modification time too, so this option may also 2140 cause problems if other programs are writing the file at the same 2141 time. (Tar attempts to detect this situation, but cannot do so 2142 reliably due to race conditions.) Worse, on most platforms 2143 restoring the access time also updates the status change time, 2144 which means that this option is incompatible with incremental 2145 backups. 2146 2147 `--atime-preserve=system' avoids changing time stamps on files, 2148 without interfering with time stamp updates caused by other 2149 programs, so it works better with incremental backups. However, it 2150 requires a special `O_NOATIME' option from the underlying operating 2151 and file system implementation, and it also requires that searching 2152 directories does not update their access times. As of this writing 2153 (November 2005) this works only with Linux, and only with Linux 2154 kernels 2.6.8 and later. Worse, there is currently no reliable way 2155 to know whether this feature actually works. Sometimes `tar' knows 2156 that it does not work, and if you use `--atime-preserve=system' 2157 then `tar' complains and exits right away. But other times `tar' 2158 might think that the option works when it actually does not. 2159 2160 Currently `--atime-preserve' with no operand defaults to 2161 `--atime-preserve=replace', but this may change in the future as 2162 support for `--atime-preserve=system' improves. 2163 2164 If your operating system does not support 2165 `--atime-preserve=system', you might be able to preserve access 2166 times reliably by by using the `mount' command. For example, you 2167 can mount the file system read-only, or access the file system via 2168 a read-only loopback mount, or use the `noatime' mount option 2169 available on some systems. However, mounting typically requires 2170 superuser privileges and can be a pain to manage. 2171 2172`--backup=BACKUP-TYPE' 2173 Rather than deleting files from the file system, `tar' will back 2174 them up using simple or numbered backups, depending upon 2175 BACKUP-TYPE. *Note backup::. 2176 2177`--block-number' 2178`-R' 2179 With this option present, `tar' prints error messages for read 2180 errors with the block number in the archive file. *Note 2181 block-number::. 2182 2183`--blocking-factor=BLOCKING' 2184`-b BLOCKING' 2185 Sets the blocking factor `tar' uses to BLOCKING x 512 bytes per 2186 record. *Note Blocking Factor::. 2187 2188`--bzip2' 2189`-j' 2190 This option tells `tar' to read or write archives through `bzip2'. 2191 *Note gzip::. 2192 2193`--checkpoint[=NUMBER]' 2194 This option directs `tar' to print periodic checkpoint messages as 2195 it reads through the archive. It is intended for when you want a 2196 visual indication that `tar' is still running, but don't want to 2197 see `--verbose' output. For a detailed description, see *note 2198 Progress information::. 2199 2200`--check-links' 2201`-l' 2202 If this option was given, `tar' will check the number of links 2203 dumped for each processed file. If this number does not match the 2204 total number of hard links for the file, a warning message will be 2205 output (1). 2206 2207`--compress' 2208`--uncompress' 2209`-Z' 2210 `tar' will use the `compress' program when reading or writing the 2211 archive. This allows you to directly act on archives while saving 2212 space. *Note gzip::. 2213 2214`--confirmation' 2215 (See `--interactive'.) *Note interactive::. 2216 2217`--delay-directory-restore' 2218 Delay setting modification times and permissions of extracted 2219 directories until the end of extraction. *Note Directory 2220 Modification Times and Permissions::. 2221 2222`--dereference' 2223`-h' 2224 When creating a `tar' archive, `tar' will archive the file that a 2225 symbolic link points to, rather than archiving the symlink. *Note 2226 dereference::. 2227 2228`--directory=DIR' 2229`-C DIR' 2230 When this option is specified, `tar' will change its current 2231 directory to DIR before performing any operations. When this 2232 option is used during archive creation, it is order sensitive. 2233 *Note directory::. 2234 2235`--exclude=PATTERN' 2236 When performing operations, `tar' will skip files that match 2237 PATTERN. *Note exclude::. 2238 2239`--exclude-from=FILE' 2240`-X FILE' 2241 Similar to `--exclude', except `tar' will use the list of patterns 2242 in the file FILE. *Note exclude::. 2243 2244`--exclude-caches' 2245 Automatically excludes all directories containing a cache directory 2246 tag. *Note exclude::. 2247 2248`--file=ARCHIVE' 2249`-f ARCHIVE' 2250 `tar' will use the file ARCHIVE as the `tar' archive it performs 2251 operations on, rather than `tar''s compilation dependent default. 2252 *Note file tutorial::. 2253 2254`--files-from=FILE' 2255`-T FILE' 2256 `tar' will use the contents of FILE as a list of archive members or 2257 files to operate on, in addition to those specified on the 2258 command-line. *Note files::. 2259 2260`--force-local' 2261 Forces `tar' to interpret the filename given to `--file' as a local 2262 file, even if it looks like a remote tape drive name. *Note local 2263 and remote archives::. 2264 2265`--format=FORMAT' 2266`-H FORMAT' 2267 Selects output archive format. FORMAT may be one of the following: 2268 2269 `v7' 2270 Creates an archive that is compatible with Unix V7 `tar'. 2271 2272 `oldgnu' 2273 Creates an archive that is compatible with GNU `tar' version 2274 1.12 or earlier. 2275 2276 `gnu' 2277 Creates archive in GNU tar 1.13 format. Basically it is the 2278 same as `oldgnu' with the only difference in the way it 2279 handles long numeric fields. 2280 2281 `ustar' 2282 Creates a POSIX.1-1988 compatible archive. 2283 2284 `posix' 2285 Creates a POSIX.1-2001 archive. 2286 2287 *Note Formats::, for a detailed discussion of these formats. 2288 2289`--group=GROUP' 2290 Files added to the `tar' archive will have a group id of GROUP, 2291 rather than the group from the source file. GROUP is first decoded 2292 as a group symbolic name, but if this interpretation fails, it has 2293 to be a decimal numeric group ID. *Note override::. 2294 2295 Also see the comments for the `--owner=USER' option. 2296 2297`--gzip' 2298`--gunzip' 2299`--ungzip' 2300`-z' 2301 This option tells `tar' to read or write archives through `gzip', 2302 allowing `tar' to directly operate on several kinds of compressed 2303 archives transparently. *Note gzip::. 2304 2305`--help' 2306`-?' 2307 `tar' will print out a short message summarizing the operations and 2308 options to `tar' and exit. *Note help::. 2309 2310`--ignore-case' 2311 Ignore case when matching member or file names with patterns. *Note 2312 controlling pattern-matching::. 2313 2314`--ignore-command-error' 2315 Ignore exit codes of subprocesses. *Note Writing to an External 2316 Program::. 2317 2318`--ignore-failed-read' 2319 Do not exit unsuccessfully merely because an unreadable file was 2320 encountered. *Note Reading::. 2321 2322`--ignore-zeros' 2323`-i' 2324 With this option, `tar' will ignore zeroed blocks in the archive, 2325 which normally signals EOF. *Note Reading::. 2326 2327`--incremental' 2328`-G' 2329 Used to inform `tar' that it is working with an old GNU-format 2330 incremental backup archive. It is intended primarily for backwards 2331 compatibility only. *Note Incremental Dumps::, for a detailed 2332 discussion of incremental archives. 2333 2334`--index-file=FILE' 2335 Send verbose output to FILE instead of to standard output. 2336 2337`--info-script=SCRIPT-FILE' 2338`--new-volume-script=SCRIPT-FILE' 2339`-F SCRIPT-FILE' 2340 When `tar' is performing multi-tape backups, SCRIPT-FILE is run at 2341 the end of each tape. If SCRIPT-FILE exits with nonzero status, 2342 `tar' fails immediately. *Note info-script::, for a detailed 2343 discussion of SCRIPT-FILE. 2344 2345`--interactive' 2346`--confirmation' 2347`-w' 2348 Specifies that `tar' should ask the user for confirmation before 2349 performing potentially destructive options, such as overwriting 2350 files. *Note interactive::. 2351 2352`--keep-newer-files' 2353 Do not replace existing files that are newer than their archive 2354 copies when extracting files from an archive. 2355 2356`--keep-old-files' 2357`-k' 2358 Do not overwrite existing files when extracting files from an 2359 archive. *Note Keep Old Files::. 2360 2361`--label=NAME' 2362`-V NAME' 2363 When creating an archive, instructs `tar' to write NAME as a name 2364 record in the archive. When extracting or listing archives, `tar' 2365 will only operate on archives that have a label matching the 2366 pattern specified in NAME. *Note Tape Files::. 2367 2368`--listed-incremental=SNAPSHOT-FILE' 2369`-g SNAPSHOT-FILE' 2370 During a `--create' operation, specifies that the archive that 2371 `tar' creates is a new GNU-format incremental backup, using 2372 SNAPSHOT-FILE to determine which files to backup. With other 2373 operations, informs `tar' that the archive is in incremental 2374 format. *Note Incremental Dumps::. 2375 2376`--mode=PERMISSIONS' 2377 When adding files to an archive, `tar' will use PERMISSIONS for the 2378 archive members, rather than the permissions from the files. 2379 PERMISSIONS can be specified either as an octal number or as 2380 symbolic permissions, like with `chmod'. *Note override::. 2381 2382`--mtime=DATE' 2383 When adding files to an archive, `tar' will use DATE as the 2384 modification time of members when creating archives, instead of 2385 their actual modification times. The value of DATE can be either a 2386 textual date representation (*note Date input formats::) or a name 2387 of the existing file, starting with `/' or `.'. In the latter 2388 case, the modification time of that file is used. *Note override::. 2389 2390`--multi-volume' 2391`-M' 2392 Informs `tar' that it should create or otherwise operate on a 2393 multi-volume `tar' archive. *Note Using Multiple Tapes::. 2394 2395`--new-volume-script' 2396 (see -info-script) 2397 2398`--seek' 2399`-n' 2400 Assume that the archive media supports seeks to arbitrary 2401 locations. Usually `tar' determines automatically whether the 2402 archive can be seeked or not. This option is intended for use in 2403 cases when such recognition fails. 2404 2405`--newer=DATE' 2406`--after-date=DATE' 2407`-N' 2408 When creating an archive, `tar' will only add files that have 2409 changed since DATE. If DATE begins with `/' or `.', it is taken to 2410 be the name of a file whose data modification time specifies the 2411 date. *Note after::. 2412 2413`--newer-mtime=DATE' 2414 Like `--newer', but add only files whose contents have changed (as 2415 opposed to just `--newer', which will also back up files for which 2416 any status information has changed). *Note after::. 2417 2418`--no-anchored' 2419 An exclude pattern can match any subsequence of the name's 2420 components. *Note controlling pattern-matching::. 2421 2422`--no-delay-directory-restore' 2423 Setting modification times and permissions of extracted directories 2424 when all files from this directory has been extracted. This is the 2425 default. *Note Directory Modification Times and Permissions::. 2426 2427`--no-ignore-case' 2428 Use case-sensitive matching. *Note controlling pattern-matching::. 2429 2430`--no-ignore-command-error' 2431 Print warnings about subprocesses terminated with a non-zero exit 2432 code. *Note Writing to an External Program::. 2433 2434`--no-overwrite-dir' 2435 Preserve metadata of existing directories when extracting files 2436 from an archive. *Note Overwrite Old Files::. 2437 2438`--no-quote-chars=STRING' 2439 Remove characters listed in STRING from the list of quoted 2440 characters set by the previous `--quote-chars' option (*note 2441 quoting styles::). 2442 2443`--no-recursion' 2444 With this option, `tar' will not recurse into directories. *Note 2445 recurse::. 2446 2447`--no-same-owner' 2448`-o' 2449 When extracting an archive, do not attempt to preserve the owner 2450 specified in the `tar' archive. This the default behavior for 2451 ordinary users. 2452 2453`--no-same-permissions' 2454 When extracting an archive, subtract the user's umask from files 2455 from the permissions specified in the archive. This is the default 2456 behavior for ordinary users. 2457 2458`--no-unquote' 2459 Treat all input file or member names literally, do not interpret 2460 escape sequences. *Note input name quoting::. 2461 2462`--no-wildcards' 2463 Do not use wildcards. *Note controlling pattern-matching::. 2464 2465`--no-wildcards-match-slash' 2466 Wildcards do not match `/'. *Note controlling pattern-matching::. 2467 2468`--null' 2469 When `tar' is using the `--files-from' option, this option 2470 instructs `tar' to expect filenames terminated with `NUL', so `tar' 2471 can correctly work with file names that contain newlines. *Note 2472 nul::. 2473 2474`--numeric-owner' 2475 This option will notify `tar' that it should use numeric user and 2476 group IDs when creating a `tar' file, rather than names. *Note 2477 Attributes::. 2478 2479`-o' 2480 The function of this option depends on the action `tar' is 2481 performing. When extracting files, `-o' is a synonym for 2482 `--no-same-owner', i.e. it prevents `tar' from restoring ownership 2483 of files being extracted. 2484 2485 When creating an archive, it is a synonym for `--old-archive'. 2486 This behavior is for compatibility with previous versions of GNU 2487 `tar', and will be removed in the future releases. 2488 2489 *Note Changes::, for more information. 2490 2491`--occurrence[=NUMBER]' 2492 This option can be used in conjunction with one of the subcommands 2493 `--delete', `--diff', `--extract' or `--list' when a list of files 2494 is given either on the command line or via `-T' option. 2495 2496 This option instructs `tar' to process only the NUMBERth occurrence 2497 of each named file. NUMBER defaults to 1, so 2498 2499 tar -x -f archive.tar --occurrence filename 2500 2501 will extract the first occurrence of the member `filename' from 2502 `archive.tar' and will terminate without scanning to the end of the 2503 archive. 2504 2505`--old-archive' 2506 Synonym for `--format=v7'. 2507 2508`--one-file-system' 2509 Used when creating an archive. Prevents `tar' from recursing into 2510 directories that are on different file systems from the current 2511 directory (2). 2512 2513`--overwrite' 2514 Overwrite existing files and directory metadata when extracting 2515 files from an archive. *Note Overwrite Old Files::. 2516 2517`--overwrite-dir' 2518 Overwrite the metadata of existing directories when extracting 2519 files from an archive. *Note Overwrite Old Files::. 2520 2521`--owner=USER' 2522 Specifies that `tar' should use USER as the owner of members when 2523 creating archives, instead of the user associated with the source 2524 file. USER is first decoded as a user symbolic name, but if this 2525 interpretation fails, it has to be a decimal numeric user ID. 2526 *Note override::. 2527 2528 This option does not affect extraction from archives. 2529 2530`--transform=SED-EXPR' 2531 Transform file or member names using `sed' replacement expression 2532 SED-EXPR. For example, 2533 2534 $ `tar cf archive.tar --transform 's,^\./,usr/,' .' 2535 2536 will add to `archive' files from the current working directory, 2537 replacing initial `./' prefix with `usr/'. For the detailed 2538 discussion, *Note transform::. 2539 2540 To see transformed member names in verbose listings, use 2541 `--show-transformed-names' option (*note show-transformed-names::). 2542 2543`--quote-chars=STRING' 2544 Always quote characters from STRING, even if the selected quoting 2545 style would not quote them (*note quoting styles::). 2546 2547`--quoting-style=STYLE' 2548 Set quoting style to use when printing member and file names (*note 2549 quoting styles::). Valid STYLE values are: `literal', `shell', 2550 `shell-always', `c', `escape', `locale', and `clocale'. Default 2551 quoting style is `escape', unless overridden while configuring the 2552 package. 2553 2554`--pax-option=KEYWORD-LIST' 2555 This option is meaningful only with POSIX.1-2001 archives (*note 2556 posix::). It modifies the way `tar' handles the extended header 2557 keywords. KEYWORD-LIST is a comma-separated list of keyword 2558 options. *Note PAX keywords::, for a detailed discussion. 2559 2560`--portability' 2561`--old-archive' 2562 Synonym for `--format=v7'. 2563 2564`--posix' 2565 Same as `--format=posix'. 2566 2567`--preserve' 2568 Synonymous with specifying both `--preserve-permissions' and 2569 `--same-order'. *Note Setting Access Permissions::. 2570 2571`--preserve-order' 2572 (See `--same-order'; *note Reading::.) 2573 2574`--preserve-permissions' 2575`--same-permissions' 2576`-p' 2577 When `tar' is extracting an archive, it normally subtracts the 2578 users' umask from the permissions specified in the archive and uses 2579 that number as the permissions to create the destination file. 2580 Specifying this option instructs `tar' that it should use the 2581 permissions directly from the archive. *Note Setting Access 2582 Permissions::. 2583 2584`--read-full-records' 2585`-B' 2586 Specifies that `tar' should reblock its input, for reading from 2587 pipes on systems with buggy implementations. *Note Reading::. 2588 2589`--record-size=SIZE' 2590 Instructs `tar' to use SIZE bytes per record when accessing the 2591 archive. *Note Blocking Factor::. 2592 2593`--recursion' 2594 With this option, `tar' recurses into directories. *Note 2595 recurse::. 2596 2597`--recursive-unlink' 2598 Remove existing directory hierarchies before extracting directories 2599 of the same name from the archive. *Note Recursive Unlink::. 2600 2601`--remove-files' 2602 Directs `tar' to remove the source file from the file system after 2603 appending it to an archive. *Note remove files::. 2604 2605`--restrict' 2606 Disable use of some potentially harmful `tar' options. Currently 2607 this option disables shell invocaton from multi-volume menu (*note 2608 Using Multiple Tapes::). 2609 2610`--rmt-command=CMD' 2611 Notifies `tar' that it should use CMD instead of the default 2612 `/usr/libexec/rmt' (*note Remote Tape Server::). 2613 2614`--rsh-command=CMD' 2615 Notifies `tar' that is should use CMD to communicate with remote 2616 devices. *Note Device::. 2617 2618`--same-order' 2619`--preserve-order' 2620`-s' 2621 This option is an optimization for `tar' when running on machines 2622 with small amounts of memory. It informs `tar' that the list of 2623 file arguments has already been sorted to match the order of files 2624 in the archive. *Note Reading::. 2625 2626`--same-owner' 2627 When extracting an archive, `tar' will attempt to preserve the 2628 owner specified in the `tar' archive with this option present. 2629 This is the default behavior for the superuser; this option has an 2630 effect only for ordinary users. *Note Attributes::. 2631 2632`--same-permissions' 2633 (See `--preserve-permissions'; *note Setting Access Permissions::.) 2634 2635`--show-defaults' 2636 Displays the default options used by `tar' and exits successfully. 2637 This option is intended for use in shell scripts. Here is an 2638 example of what you can see using this option: 2639 2640 $ tar --show-defaults 2641 --format=gnu -f- -b20 --quoting-style=escape \ 2642 --rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh 2643 2644`--show-omitted-dirs' 2645 Instructs `tar' to mention directories its skipping over when 2646 operating on a `tar' archive. *Note show-omitted-dirs::. 2647 2648`--show-transformed-names' 2649`--show-stored-names' 2650 Display file or member names after applying any transformations 2651 (*note transform::). In particular, when used in conjunction with 2652 one of archive creation operations it instructs tar to list the 2653 member names stored in the archive, as opposed to the actual file 2654 names. *Note listing member and file names::. 2655 2656`--sparse' 2657`-S' 2658 Invokes a GNU extension when adding files to an archive that 2659 handles sparse files efficiently. *Note sparse::. 2660 2661`--sparse-version=VERSION' 2662 Specified the "format version" to use when archiving sparse files. 2663 Implies `--sparse'. *Note sparse::. For the description of the 2664 supported sparse formats, *Note Sparse Formats::. 2665 2666`--starting-file=NAME' 2667`-K NAME' 2668 This option affects extraction only; `tar' will skip extracting 2669 files in the archive until it finds one that matches NAME. *Note 2670 Scarce::. 2671 2672`--strip-components=NUMBER' 2673 Strip given NUMBER of leading components from file names before 2674 extraction.(3) For example, if archive `archive.tar' contained 2675 `/some/file/name', then running 2676 2677 tar --extract --file archive.tar --strip-components=2 2678 2679 would extract this file to file `name'. 2680 2681`--suffix=SUFFIX' 2682 Alters the suffix `tar' uses when backing up files from the default 2683 `~'. *Note backup::. 2684 2685`--tape-length=NUM' 2686`-L NUM' 2687 Specifies the length of tapes that `tar' is writing as being 2688 NUM x 1024 bytes long. *Note Using Multiple Tapes::. 2689 2690`--test-label' 2691 Reads the volume label. If an argument is specified, test whether 2692 it matches the volume label. *Note --test-label option::. 2693 2694`--to-command=COMMAND' 2695 During extraction `tar' will pipe extracted files to the standard 2696 input of COMMAND. *Note Writing to an External Program::. 2697 2698`--to-stdout' 2699`-O' 2700 During extraction, `tar' will extract files to stdout rather than 2701 to the file system. *Note Writing to Standard Output::. 2702 2703`--totals[=SIGNO]' 2704 Displays the total number of bytes transferred when processing an 2705 archive. If an argument is given, these data are displayed on 2706 request, when signal SIGNO is delivered to `tar'. *Note totals::. 2707 2708`--touch' 2709`-m' 2710 Sets the data modification time of extracted files to the 2711 extraction time, rather than the data modification time stored in 2712 the archive. *Note Data Modification Times::. 2713 2714`--uncompress' 2715 (See `--compress'. *note gzip::) 2716 2717`--ungzip' 2718 (See `--gzip'. *note gzip::) 2719 2720`--unlink-first' 2721`-U' 2722 Directs `tar' to remove the corresponding file from the file system 2723 before extracting it from the archive. *Note Unlink First::. 2724 2725`--unquote' 2726 Enable unquoting input file or member names (default). *Note input 2727 name quoting::. 2728 2729`--use-compress-program=PROG' 2730 Instructs `tar' to access the archive through PROG, which is 2731 presumed to be a compression program of some sort. *Note gzip::. 2732 2733`--utc' 2734 Display file modification dates in UTC. This option implies 2735 `--verbose'. 2736 2737`--verbose' 2738`-v' 2739 Specifies that `tar' should be more verbose about the operations 2740 its performing. This option can be specified multiple times for 2741 some operations to increase the amount of information displayed. 2742 *Note verbose::. 2743 2744`--verify' 2745`-W' 2746 Verifies that the archive was correctly written when creating an 2747 archive. *Note verify::. 2748 2749`--version' 2750 Print information about the program's name, version, origin and 2751 legal status, all on standard output, and then exit successfully. 2752 *Note help::. 2753 2754`--volno-file=FILE' 2755 Used in conjunction with `--multi-volume'. `tar' will keep track 2756 of which volume of a multi-volume archive its working in FILE. 2757 *Note volno-file::. 2758 2759`--wildcards' 2760 Use wildcards when matching member names with patterns. *Note 2761 controlling pattern-matching::. 2762 2763`--wildcards-match-slash' 2764 Wildcards match `/'. *Note controlling pattern-matching::. 2765 2766 ---------- Footnotes ---------- 2767 2768 (1) Earlier versions of GNU `tar' understood `-l' as a synonym for 2769`--one-file-system'. The current semantics, which complies to UNIX98, 2770was introduced with version 1.15.91. *Note Changes::, for more 2771information. 2772 2773 (2) Earlier versions of GNU `tar' understood `-l' as a synonym for 2774`--one-file-system'. This has changed in version 1.15.91. *Note 2775Changes::, for more information. 2776 2777 (3) This option was called `--strip-path' in version 1.14. 2778 2779 2780File: tar.info, Node: Short Option Summary, Prev: Option Summary, Up: All Options 2781 27823.4.3 Short Options Cross Reference 2783----------------------------------- 2784 2785Here is an alphabetized list of all of the short option forms, matching 2786them with the equivalent long option. 2787 2788Short Option Reference 2789 2790-------------------------------------------------------------------------- 2791-A *note --concatenate::. 2792 2793-B *note --read-full-records::. 2794 2795-C *note --directory::. 2796 2797-F *note --info-script::. 2798 2799-G *note --incremental::. 2800 2801-K *note --starting-file::. 2802 2803-L *note --tape-length::. 2804 2805-M *note --multi-volume::. 2806 2807-N *note --newer::. 2808 2809-O *note --to-stdout::. 2810 2811-P *note --absolute-names::. 2812 2813-R *note --block-number::. 2814 2815-S *note --sparse::. 2816 2817-T *note --files-from::. 2818 2819-U *note --unlink-first::. 2820 2821-V *note --label::. 2822 2823-W *note --verify::. 2824 2825-X *note --exclude-from::. 2826 2827-Z *note --compress::. 2828 2829-b *note --blocking-factor::. 2830 2831-c *note --create::. 2832 2833-d *note --compare::. 2834 2835-f *note --file::. 2836 2837-g *note --listed-incremental::. 2838 2839-h *note --dereference::. 2840 2841-i *note --ignore-zeros::. 2842 2843-j *note --bzip2::. 2844 2845-k *note --keep-old-files::. 2846 2847-l *note --check-links::. 2848 2849-m *note --touch::. 2850 2851-o When creating, *note --no-same-owner::, when extracting 2852 -- *note --portability::. 2853 2854 The later usage is deprecated. It is retained for 2855 compatibility with the earlier versions of GNU `tar'. 2856 In the future releases `-o' will be equivalent to 2857 `--no-same-owner' only. 2858 2859-p *note --preserve-permissions::. 2860 2861-r *note --append::. 2862 2863-s *note --same-order::. 2864 2865-t *note --list::. 2866 2867-u *note --update::. 2868 2869-v *note --verbose::. 2870 2871-w *note --interactive::. 2872 2873-x *note --extract::. 2874 2875-z *note --gzip::. 2876 2877 2878File: tar.info, Node: help, Next: defaults, Prev: All Options, Up: tar invocation 2879 28803.5 GNU `tar' documentation 2881=========================== 2882 2883Being careful, the first thing is really checking that you are using GNU 2884`tar', indeed. The `--version' option causes `tar' to print information 2885about its name, version, origin and legal status, all on standard 2886output, and then exit successfully. For example, `tar --version' might 2887print: 2888 2889 tar (GNU tar) 1.15.92 2890 Copyright (C) 2006 Free Software Foundation, Inc. 2891 This is free software. You may redistribute copies of it under the terms 2892 of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. 2893 There is NO WARRANTY, to the extent permitted by law. 2894 2895 Written by John Gilmore and Jay Fenlason. 2896 2897The first occurrence of `tar' in the result above is the program name in 2898the package (for example, `rmt' is another program), while the second 2899occurrence of `tar' is the name of the package itself, containing 2900possibly many programs. The package is currently named `tar', after the 2901name of the main program it contains(1). 2902 2903 Another thing you might want to do is checking the spelling or 2904meaning of some particular `tar' option, without resorting to this 2905manual, for once you have carefully read it. GNU `tar' has a short help 2906feature, triggerable through the `--help' option. By using this option, 2907`tar' will print a usage message listing all available options on 2908standard output, then exit successfully, without doing anything else and 2909ignoring all other options. Even if this is only a brief summary, it 2910may be several screens long. So, if you are not using some kind of 2911scrollable window, you might prefer to use something like: 2912 2913 $ `tar --help | less' 2914 2915presuming, here, that you like using `less' for a pager. Other popular 2916pagers are `more' and `pg'. If you know about some KEYWORD which 2917interests you and do not want to read all the `--help' output, another 2918common idiom is doing: 2919 2920 tar --help | grep KEYWORD 2921 2922for getting only the pertinent lines. Notice, however, that some `tar' 2923options have long description lines and the above command will list only 2924the first of them. 2925 2926 The exact look of the option summary displayed by `tar --help' is 2927configurable. *Note Configuring Help Summary::, for a detailed 2928description. 2929 2930 If you only wish to check the spelling of an option, running `tar 2931--usage' may be a better choice. This will display a terse list of 2932`tar' option without accompanying explanations. 2933 2934 The short help output is quite succinct, and you might have to get 2935back to the full documentation for precise points. If you are reading 2936this paragraph, you already have the `tar' manual in some form. This 2937manual is available in a variety of forms from 2938`http://www.gnu.org/software/tar/manual'. It may be printed out of the 2939GNU `tar' distribution, provided you have TeX already installed 2940somewhere, and a laser printer around. Just configure the distribution, 2941execute the command `make dvi', then print `doc/tar.dvi' the usual way 2942(contact your local guru to know how). If GNU `tar' has been 2943conveniently installed at your place, this manual is also available in 2944interactive, hypertextual form as an Info file. Just call `info tar' 2945or, if you do not have the `info' program handy, use the Info reader 2946provided within GNU Emacs, calling `tar' from the main Info menu. 2947 2948 There is currently no `man' page for GNU `tar'. If you observe such 2949a `man' page on the system you are running, either it does not belong to 2950GNU `tar', or it has not been produced by GNU. Some package maintainers 2951convert `tar --help' output to a man page, using `help2man'. In any 2952case, please bear in mind that the authoritative source of information 2953about GNU `tar' is this Texinfo documentation. 2954 2955 ---------- Footnotes ---------- 2956 2957 (1) There are plans to merge the `cpio' and `tar' packages into a single 2958one which would be called `paxutils'. So, who knows if, one of this 2959days, the `--version' would not output `tar (GNU paxutils) 3.2' 2960 2961 2962File: tar.info, Node: defaults, Next: verbose, Prev: help, Up: tar invocation 2963 29643.6 Obtaining GNU `tar' default values 2965====================================== 2966 2967GNU `tar' has some predefined defaults that are used when you do not 2968explicitely specify another values. To obtain a list of such defaults, 2969use `--show-defaults' option. This will output the values in the form 2970of `tar' command line options: 2971 2972 `tar --show-defaults' 2973 --format=gnu -f- -b20 --quoting-style=escape 2974 --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh 2975 2976Notice, that this option outputs only one line. The example output 2977above has been split to fit page boundaries. 2978 2979The above output shows that this version of GNU `tar' defaults to using 2980`gnu' archive format (*note Formats::), it uses standard output as the 2981archive, if no `--file' option has been given (*note file tutorial::), 2982the default blocking factor is 20 (*note Blocking Factor::). It also 2983shows the default locations where `tar' will look for `rmt' and `rsh' 2984binaries. 2985 2986 2987File: tar.info, Node: verbose, Next: interactive, Prev: defaults, Up: tar invocation 2988 29893.7 Checking `tar' progress 2990=========================== 2991 2992Typically, `tar' performs most operations without reporting any 2993information to the user except error messages. When using `tar' with 2994many options, particularly ones with complicated or difficult-to-predict 2995behavior, it is possible to make serious mistakes. `tar' provides 2996several options that make observing `tar' easier. These options cause 2997`tar' to print information as it progresses in its job, and you might 2998want to use them just for being more careful about what is going on, or 2999merely for entertaining yourself. If you have encountered a problem 3000when operating on an archive, however, you may need more information 3001than just an error message in order to solve the problem. The following 3002options can be helpful diagnostic tools. 3003 3004 Normally, the `--list' (`-t') command to list an archive prints just 3005the file names (one per line) and the other commands are silent. When 3006used with most operations, the `--verbose' (`-v') option causes `tar' to 3007print the name of each file or archive member as it is processed. This 3008and the other options which make `tar' print status information can be 3009useful in monitoring `tar'. 3010 3011 With `--create' or `--extract', `--verbose' used once just prints the 3012names of the files or members as they are processed. Using it twice 3013causes `tar' to print a longer listing (*Note verbose member listing::, 3014for the description) for each member. Since `--list' already prints 3015the names of the members, `--verbose' used once with `--list' causes 3016`tar' to print an `ls -l' type listing of the files in the archive. The 3017following examples both extract members with long list output: 3018 3019 $ `tar --extract --file=archive.tar --verbose --verbose' 3020 $ `tar xvvf archive.tar' 3021 3022 Verbose output appears on the standard output except when an archive 3023is being written to the standard output, as with `tar --create --file=- 3024--verbose' (`tar cfv -', or even `tar cv'--if the installer let standard 3025output be the default archive). In that case `tar' writes verbose 3026output to the standard error stream. 3027 3028 If `--index-file=FILE' is specified, `tar' sends verbose output to 3029FILE rather than to standard output or standard error. 3030 3031 The `--totals' option causes `tar' to print on the standard error the 3032total amount of bytes transferred when processing an archive. When 3033creating or appending to an archive, this option prints the number of 3034bytes written to the archive and the average speed at which they have 3035been written, e.g.: 3036 3037 $ `tar -c -f archive.tar --totals /home' 3038 Total bytes written: 7924664320 (7.4GiB, 85MiB/s) 3039 3040 When reading an archive, this option displays the number of bytes 3041read: 3042 3043 $ `tar -x -f archive.tar --totals' 3044 Total bytes read: 7924664320 (7.4GiB, 95MiB/s) 3045 3046 Finally, when deleting from an archive, the `--totals' option 3047displays both numbers plus number of bytes removed from the archive: 3048 3049 $ `tar --delete -f foo.tar --totals --wildcards '*~'' 3050 Total bytes read: 9543680 (9.2MiB, 201MiB/s) 3051 Total bytes written: 3829760 (3.7MiB, 81MiB/s) 3052 Total bytes deleted: 1474048 3053 3054 You can also obtain this information on request. When `--totals' is 3055used with an argument, this argument is interpreted as a symbolic name 3056of a signal, upon delivery of which the statistics is to be printed: 3057 3058`--totals=SIGNO' 3059 Print statistics upon delivery of signal SIGNO. Valid arguments 3060 are: `SIGHUP', `SIGQUIT', `SIGINT', `SIGUSR1' and `SIGUSR2'. 3061 Shortened names without `SIG' prefix are also accepted. 3062 3063 Both forms of `--totals' option can be used simultaneously. Thus, 3064`tar -x --totals --totals=USR1' instructs `tar' to extract all members 3065from its default archive and print statistics after finishing the 3066extraction, as well as when receiving signal `SIGUSR1'. 3067 3068 The `--checkpoint' option prints an occasional message as `tar' reads 3069or writes the archive. It is designed for those who don't need the more 3070detailed (and voluminous) output of `--block-number' (`-R'), but do want 3071visual confirmation that `tar' is actually making forward progress. By 3072default it prints a message each 10 records read or written. This can 3073be changed by giving it a numeric argument after an equal sign: 3074 3075 $ `tar -c --checkpoint=1000' /var 3076 tar: Write checkpoint 1000 3077 tar: Write checkpoint 2000 3078 tar: Write checkpoint 3000 3079 3080 This example shows the default checkpoint message used by `tar'. If 3081you place a dot immediately after the equal sign, it will print a `.' at 3082each checkpoint. For example: 3083 3084 $ `tar -c --checkpoint=.1000' /var 3085 ... 3086 3087 The `--show-omitted-dirs' option, when reading an archive--with 3088`--list' or `--extract', for example--causes a message to be printed for 3089each directory in the archive which is skipped. This happens regardless 3090of the reason for skipping: the directory might not have been named on 3091the command line (implicitly or explicitly), it might be excluded by the 3092use of the `--exclude=PATTERN' option, or some other reason. 3093 3094 If `--block-number' (`-R') is used, `tar' prints, along with every 3095message it would normally produce, the block number within the archive 3096where the message was triggered. Also, supplementary messages are 3097triggered when reading blocks full of NULs, or when hitting end of file 3098on the archive. As of now, if the archive if properly terminated with a 3099NUL block, the reading of the file may stop before end of file is met, 3100so the position of end of file will not usually show when 3101`--block-number' (`-R') is used. Note that GNU `tar' drains the archive 3102before exiting when reading the archive from a pipe. 3103 3104 This option is especially useful when reading damaged archives, since 3105it helps pinpoint the damaged sections. It can also be used with 3106`--list' (`-t') when listing a file-system backup tape, allowing you to 3107choose among several backup tapes when retrieving a file later, in favor 3108of the tape where the file appears earliest (closest to the front of the 3109tape). *Note backup::. 3110 3111 3112File: tar.info, Node: interactive, Prev: verbose, Up: tar invocation 3113 31143.8 Asking for Confirmation During Operations 3115============================================= 3116 3117Typically, `tar' carries out a command without stopping for further 3118instructions. In some situations however, you may want to exclude some 3119files and archive members from the operation (for instance if disk or 3120storage space is tight). You can do this by excluding certain files 3121automatically (*note Choosing::), or by performing an operation 3122interactively, using the `--interactive' (`-w') option. `tar' also 3123accepts `--confirmation' for this option. 3124 3125 When the `--interactive' (`-w') option is specified, before reading, 3126writing, or deleting files, `tar' first prints a message for each such 3127file, telling what operation it intends to take, then asks for 3128confirmation on the terminal. The actions which require confirmation 3129include adding a file to the archive, extracting a file from the 3130archive, deleting a file from the archive, and deleting a file from 3131disk. To confirm the action, you must type a line of input beginning 3132with `y'. If your input line begins with anything other than `y', `tar' 3133skips that file. 3134 3135 If `tar' is reading the archive from the standard input, `tar' opens 3136the file `/dev/tty' to support the interactive communications. 3137 3138 Verbose output is normally sent to standard output, separate from 3139other error messages. However, if the archive is produced directly on 3140standard output, then verbose output is mixed with errors on `stderr'. 3141Producing the archive on standard output may be used as a way to avoid 3142using disk space, when the archive is soon to be consumed by another 3143process reading it, say. Some people felt the need of producing an 3144archive on stdout, still willing to segregate between verbose output and 3145error output. A possible approach would be using a named pipe to 3146receive the archive, and having the consumer process to read from that 3147named pipe. This has the advantage of letting standard output free to 3148receive verbose output, all separate from errors. 3149 3150 3151File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top 3152 31534 GNU `tar' Operations 3154********************** 3155 3156* Menu: 3157 3158* Basic tar:: 3159* Advanced tar:: 3160* create options:: 3161* extract options:: 3162* backup:: 3163* Applications:: 3164* looking ahead:: 3165 3166 3167File: tar.info, Node: Basic tar, Next: Advanced tar, Up: operations 3168 31694.1 Basic GNU `tar' Operations 3170============================== 3171 3172The basic `tar' operations, `--create' (`-c'), `--list' (`-t') and 3173`--extract' (`--get', `-x'), are currently presented and described in 3174the tutorial chapter of this manual. This section provides some 3175complementary notes for these operations. 3176 3177`--create' 3178`-c' 3179 Creating an empty archive would have some kind of elegance. One 3180 can initialize an empty archive and later use `--append' (`-r') for 3181 adding all members. Some applications would not welcome making an 3182 exception in the way of adding the first archive member. On the 3183 other hand, many people reported that it is dangerously too easy 3184 for `tar' to destroy a magnetic tape with an empty archive(1). The 3185 two most common errors are: 3186 3187 1. Mistakingly using `create' instead of `extract', when the 3188 intent was to extract the full contents of an archive. This 3189 error is likely: keys `c' and `x' are right next to each other 3190 on the QWERTY keyboard. Instead of being unpacked, the 3191 archive then gets wholly destroyed. When users speak about 3192 "exploding" an archive, they usually mean something else :-). 3193 3194 2. Forgetting the argument to `file', when the intent was to 3195 create an archive with a single file in it. This error is 3196 likely because a tired user can easily add the `f' key to the 3197 cluster of option letters, by the mere force of habit, without 3198 realizing the full consequence of doing so. The usual 3199 consequence is that the single file, which was meant to be 3200 saved, is rather destroyed. 3201 3202 So, recognizing the likelihood and the catastrophical nature of 3203 these errors, GNU `tar' now takes some distance from elegance, and 3204 cowardly refuses to create an archive when `--create' option is 3205 given, there are no arguments besides options, and `--files-from' 3206 (`-T') option is _not_ used. To get around the cautiousness of GNU 3207 `tar' and nevertheless create an archive with nothing in it, one 3208 may still use, as the value for the `--files-from' option, a file 3209 with no names in it, as shown in the following commands: 3210 3211 `tar --create --file=empty-archive.tar --files-from=/dev/null' 3212 `tar cfT empty-archive.tar /dev/null' 3213 3214`--extract' 3215`--get' 3216`-x' 3217 A socket is stored, within a GNU `tar' archive, as a pipe. 3218 3219``--list' (`-t')' 3220 GNU `tar' now shows dates as `1996-08-30', while it used to show 3221 them as `Aug 30 1996'. Preferably, people should get used to ISO 3222 8601 dates. Local American dates should be made available again 3223 with full date localization support, once ready. In the meantime, 3224 programs not being localizable for dates should prefer 3225 international dates, that's really the way to go. 3226 3227 Look up `http://www.cl.cam.ac.uk/~mgk25/iso-time.html' if you are 3228 curious, it contains a detailed explanation of the ISO 8601 3229 standard. 3230 3231 ---------- Footnotes ---------- 3232 3233 (1) This is well described in `Unix-haters Handbook', by Simson 3234Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN 32351-56884-203-1. 3236 3237 3238File: tar.info, Node: Advanced tar, Next: create options, Prev: Basic tar, Up: operations 3239 32404.2 Advanced GNU `tar' Operations 3241================================= 3242 3243Now that you have learned the basics of using GNU `tar', you may want to 3244learn about further ways in which `tar' can help you. 3245 3246 This chapter presents five, more advanced operations which you 3247probably won't use on a daily basis, but which serve more specialized 3248functions. We also explain the different styles of options and why you 3249might want to use one or another, or a combination of them in your `tar' 3250commands. Additionally, this chapter includes options which allow you 3251to define the output from `tar' more carefully, and provide help and 3252error correction in special circumstances. 3253 3254* Menu: 3255 3256* Operations:: 3257* append:: 3258* update:: 3259* concatenate:: 3260* delete:: 3261* compare:: 3262 3263 3264File: tar.info, Node: Operations, Next: append, Up: Advanced tar 3265 32664.2.1 The Five Advanced `tar' Operations 3267---------------------------------------- 3268 3269 _(This message will disappear, once this node revised.)_ 3270 3271 In the last chapter, you learned about the first three operations to 3272`tar'. This chapter presents the remaining five operations to `tar': 3273`--append', `--update', `--concatenate', `--delete', and `--compare'. 3274 3275 You are not likely to use these operations as frequently as those 3276covered in the last chapter; however, since they perform specialized 3277functions, they are quite useful when you do need to use them. We will 3278give examples using the same directory and files that you created in the 3279last chapter. As you may recall, the directory is called `practice', 3280the files are `jazz', `blues', `folk', `rock', and the two archive files 3281you created are `collection.tar' and `music.tar'. 3282 3283 We will also use the archive files `afiles.tar' and `bfiles.tar'. 3284The archive `afiles.tar' contains the members `apple', `angst', and 3285`aspic'; `bfiles.tar' contains the members `./birds', `baboon', and 3286`./box'. 3287 3288 Unless we state otherwise, all practicing you do and examples you 3289follow in this chapter will take place in the `practice' directory that 3290you created in the previous chapter; see *note prepare for examples::. 3291(Below in this section, we will remind you of the state of the examples 3292where the last chapter left them.) 3293 3294 The five operations that we will cover in this chapter are: 3295 3296`--append' 3297`-r' 3298 Add new entries to an archive that already exists. 3299 3300`--update' 3301`-r' 3302 Add more recent copies of archive members to the end of an archive, 3303 if they exist. 3304 3305`--concatenate' 3306`--catenate' 3307`-A' 3308 Add one or more pre-existing archives to the end of another 3309 archive. 3310 3311`--delete' 3312 Delete items from an archive (does not work on tapes). 3313 3314`--compare' 3315`--diff' 3316`-d' 3317 Compare archive members to their counterparts in the file system. 3318 3319 3320File: tar.info, Node: append, Next: update, Prev: Operations, Up: Advanced tar 3321 33224.2.2 How to Add Files to Existing Archives: `--append' 3323------------------------------------------------------- 3324 3325 _(This message will disappear, once this node revised.)_ 3326 3327 If you want to add files to an existing archive, you don't need to 3328create a new archive; you can use `--append' (`-r'). The archive must 3329already exist in order to use `--append'. (A related operation is the 3330`--update' operation; you can use this to add newer versions of archive 3331members to an existing archive. To learn how to do this with 3332`--update', *note update::.) 3333 3334 If you use `--append' to add a file that has the same name as an 3335archive member to an archive containing that archive member, then the 3336old member is not deleted. What does happen, however, is somewhat 3337complex. `tar' _allows_ you to have infinite number of files with the 3338same name. Some operations treat these same-named members no 3339differently than any other set of archive members: for example, if you 3340view an archive with `--list' (`-t'), you will see all of those members 3341listed, with their data modification times, owners, etc. 3342 3343 Other operations don't deal with these members as perfectly as you 3344might prefer; if you were to use `--extract' to extract the archive, 3345only the most recently added copy of a member with the same name as four 3346other members would end up in the working directory. This is because 3347`--extract' extracts an archive in the order the members appeared in the 3348archive; the most recently archived members will be extracted last. 3349Additionally, an extracted member will _replace_ a file of the same name 3350which existed in the directory already, and `tar' will not prompt you 3351about this(1). Thus, only the most recently archived member will end up 3352being extracted, as it will replace the one extracted before it, and so 3353on. 3354 3355 There exists a special option that allows you to get around this 3356behavior and extract (or list) only a particular copy of the file. This 3357is `--occurrence' option. If you run `tar' with this option, it will 3358extract only the first copy of the file. You may also give this option 3359an argument specifying the number of copy to be extracted. Thus, for 3360example if the archive `archive.tar' contained three copies of file 3361`myfile', then the command 3362 3363 tar --extract --file archive.tar --occurrence=2 myfile 3364 3365would extract only the second copy. *Note --occurrence: Option Summary, 3366for the description of `--occurrence' option. 3367 3368 If you want to replace an archive member, use `--delete' to delete 3369the member you want to remove from the archive, , and then use 3370`--append' to add the member you want to be in the archive. Note that 3371you can not change the order of the archive; the most recently added 3372member will still appear last. In this sense, you cannot truly 3373"replace" one member with another. (Replacing one member with another 3374will not work on certain types of media, such as tapes; see *note 3375delete:: and *note Media::, for more information.) 3376 3377* Menu: 3378 3379* appending files:: Appending Files to an Archive 3380* multiple:: 3381 3382 ---------- Footnotes ---------- 3383 3384 (1) Unless you give it `--keep-old-files' option, or the disk copy is 3385newer than the the one in the archive and you invoke `tar' with 3386`--keep-newer-files' option 3387 3388 3389File: tar.info, Node: appending files, Next: multiple, Up: append 3390 33914.2.2.1 Appending Files to an Archive 3392..................................... 3393 3394 _(This message will disappear, once this node revised.)_ 3395 3396 The simplest way to add a file to an already existing archive is the 3397`--append' (`-r') operation, which writes specified files into the 3398archive whether or not they are already among the archived files. 3399 3400 When you use `--append', you _must_ specify file name arguments, as 3401there is no default. If you specify a file that already exists in the 3402archive, another copy of the file will be added to the end of the 3403archive. As with other operations, the member names of the newly added 3404files will be exactly the same as their names given on the command line. 3405The `--verbose' (`-v') option will print out the names of the files as 3406they are written into the archive. 3407 3408 `--append' cannot be performed on some tape drives, unfortunately, 3409due to deficiencies in the formats those tape drives use. The archive 3410must be a valid `tar' archive, or else the results of using this 3411operation will be unpredictable. *Note Media::. 3412 3413 To demonstrate using `--append' to add a file to an archive, create a 3414file called `rock' in the `practice' directory. Make sure you are in 3415the `practice' directory. Then, run the following `tar' command to add 3416`rock' to `collection.tar': 3417 3418 $ `tar --append --file=collection.tar rock' 3419 3420If you now use the `--list' (`-t') operation, you will see that `rock' 3421has been added to the archive: 3422 3423 $ `tar --list --file=collection.tar' 3424 -rw-r--r-- me user 28 1996-10-18 16:31 jazz 3425 -rw-r--r-- me user 21 1996-09-23 16:44 blues 3426 -rw-r--r-- me user 20 1996-09-23 16:44 folk 3427 -rw-r--r-- me user 20 1996-09-23 16:44 rock 3428 3429 3430File: tar.info, Node: multiple, Prev: appending files, Up: append 3431 34324.2.2.2 Multiple Members with the Same Name 3433........................................... 3434 3435You can use `--append' (`-r') to add copies of files which have been 3436updated since the archive was created. (However, we do not recommend 3437doing this since there is another `tar' option called `--update'; *Note 3438update::, for more information. We describe this use of `--append' here 3439for the sake of completeness.) When you extract the archive, the older 3440version will be effectively lost. This works because files are 3441extracted from an archive in the order in which they were archived. 3442Thus, when the archive is extracted, a file archived later in time will 3443replace a file of the same name which was archived earlier, even though 3444the older version of the file will remain in the archive unless you 3445delete all versions of the file. 3446 3447 Supposing you change the file `blues' and then append the changed 3448version to `collection.tar'. As you saw above, the original `blues' is 3449in the archive `collection.tar'. If you change the file and append the 3450new version of the file to the archive, there will be two copies in the 3451archive. When you extract the archive, the older version of the file 3452will be extracted first, and then replaced by the newer version when it 3453is extracted. 3454 3455 You can append the new, changed copy of the file `blues' to the 3456archive in this way: 3457 3458 $ `tar --append --verbose --file=collection.tar blues' 3459 blues 3460 3461Because you specified the `--verbose' option, `tar' has printed the name 3462of the file being appended as it was acted on. Now list the contents of 3463the archive: 3464 3465 $ `tar --list --verbose --file=collection.tar' 3466 -rw-r--r-- me user 28 1996-10-18 16:31 jazz 3467 -rw-r--r-- me user 21 1996-09-23 16:44 blues 3468 -rw-r--r-- me user 20 1996-09-23 16:44 folk 3469 -rw-r--r-- me user 20 1996-09-23 16:44 rock 3470 -rw-r--r-- me user 58 1996-10-24 18:30 blues 3471 3472The newest version of `blues' is now at the end of the archive (note the 3473different creation dates and file sizes). If you extract the archive, 3474the older version of the file `blues' will be replaced by the newer 3475version. You can confirm this by extracting the archive and running 3476`ls' on the directory. 3477 3478 If you wish to extract the first occurrence of the file `blues' from 3479the archive, use `--occurrence' option, as shown in the following 3480example: 3481 3482 $ `tar --extract -vv --occurrence --file=collection.tar blues' 3483 -rw-r--r-- me user 21 1996-09-23 16:44 blues 3484 3485 *Note Writing::, for more information on `--extract' and *Note 3486-occurrence: Option Summary, for the description of `--occurrence' 3487option. 3488 3489 3490File: tar.info, Node: update, Next: concatenate, Prev: append, Up: Advanced tar 3491 34924.2.3 Updating an Archive 3493------------------------- 3494 3495 _(This message will disappear, once this node revised.)_ 3496 3497 In the previous section, you learned how to use `--append' to add a 3498file to an existing archive. A related operation is `--update' (`-u'). 3499The `--update' operation updates a `tar' archive by comparing the date 3500of the specified archive members against the date of the file with the 3501same name. If the file has been modified more recently than the archive 3502member, then the newer version of the file is added to the archive (as 3503with `--append'). 3504 3505 Unfortunately, you cannot use `--update' with magnetic tape drives. 3506The operation will fail. 3507 3508 Both `--update' and `--append' work by adding to the end of the 3509archive. When you extract a file from the archive, only the version 3510stored last will wind up in the file system, unless you use the 3511`--backup' option. *Note multiple::, for a detailed discussion. 3512 3513* Menu: 3514 3515* how to update:: 3516 3517 3518File: tar.info, Node: how to update, Up: update 3519 35204.2.3.1 How to Update an Archive Using `--update' 3521................................................. 3522 3523You must use file name arguments with the `--update' (`-u') operation. 3524If you don't specify any files, `tar' won't act on any files and won't 3525tell you that it didn't do anything (which may end up confusing you). 3526 3527 To see the `--update' option at work, create a new file, `classical', 3528in your practice directory, and some extra text to the file `blues', 3529using any text editor. Then invoke `tar' with the `update' operation 3530and the `--verbose' (`-v') option specified, using the names of all the 3531files in the practice directory as file name arguments: 3532 3533 $ `tar --update -v -f collection.tar blues folk rock classical' 3534 blues 3535 classical 3536 $ 3537 3538Because we have specified verbose mode, `tar' prints out the names of 3539the files it is working on, which in this case are the names of the 3540files that needed to be updated. If you run `tar --list' and look at 3541the archive, you will see `blues' and `classical' at its end. There 3542will be a total of two versions of the member `blues'; the one at the 3543end will be newer and larger, since you added text before updating it. 3544 3545 (The reason `tar' does not overwrite the older file when updating it 3546is because writing to the middle of a section of tape is a difficult 3547process. Tapes are not designed to go backward. *Note Media::, for 3548more information about tapes. 3549 3550 `--update' (`-u') is not suitable for performing backups for two 3551reasons: it does not change directory content entries, and it lengthens 3552the archive every time it is used. The GNU `tar' options intended 3553specifically for backups are more efficient. If you need to run 3554backups, please consult *note Backups::. 3555 3556 3557File: tar.info, Node: concatenate, Next: delete, Prev: update, Up: Advanced tar 3558 35594.2.4 Combining Archives with `--concatenate' 3560--------------------------------------------- 3561 3562Sometimes it may be convenient to add a second archive onto the end of 3563an archive rather than adding individual files to the archive. To add 3564one or more archives to the end of another archive, you should use the 3565`--concatenate' (`--catenate', `-A') operation. 3566 3567 To use `--concatenate', give the first archive with `--file' option 3568and name the rest of archives to be concatenated on the command line. 3569The members, and their member names, will be copied verbatim from those 3570archives to the first one. (1) The new, concatenated archive will be 3571called by the same name as the one given with the `--file' option. As 3572usual, if you omit `--file', `tar' will use the value of the environment 3573variable `TAPE', or, if this has not been set, the default archive name. 3574 3575 To demonstrate how `--concatenate' works, create two small archives 3576called `bluesrock.tar' and `folkjazz.tar', using the relevant files from 3577`practice': 3578 3579 $ `tar -cvf bluesrock.tar blues rock' 3580 blues 3581 rock 3582 $ `tar -cvf folkjazz.tar folk jazz' 3583 folk 3584 jazz 3585 3586If you like, You can run `tar --list' to make sure the archives contain 3587what they are supposed to: 3588 3589 $ `tar -tvf bluesrock.tar' 3590 -rw-r--r-- melissa user 105 1997-01-21 19:42 blues 3591 -rw-r--r-- melissa user 33 1997-01-20 15:34 rock 3592 $ `tar -tvf jazzfolk.tar' 3593 -rw-r--r-- melissa user 20 1996-09-23 16:44 folk 3594 -rw-r--r-- melissa user 65 1997-01-30 14:15 jazz 3595 3596 We can concatenate these two archives with `tar': 3597 3598 $ `cd ..' 3599 $ `tar --concatenate --file=bluesrock.tar jazzfolk.tar' 3600 3601 If you now list the contents of the `bluesrock.tar', you will see 3602that now it also contains the archive members of `jazzfolk.tar': 3603 3604 $ `tar --list --file=bluesrock.tar' 3605 blues 3606 rock 3607 folk 3608 jazz 3609 3610 When you use `--concatenate', the source and target archives must 3611already exist and must have been created using compatible format 3612parameters. Notice, that `tar' does not check whether the archives it 3613concatenates have compatible formats, it does not even check if the 3614files are really tar archives. 3615 3616 Like `--append' (`-r'), this operation cannot be performed on some 3617tape drives, due to deficiencies in the formats those tape drives use. 3618 3619 It may seem more intuitive to you to want or try to use `cat' to 3620concatenate two archives instead of using the `--concatenate' operation; 3621after all, `cat' is the utility for combining files. 3622 3623 However, `tar' archives incorporate an end-of-file marker which must 3624be removed if the concatenated archives are to be read properly as one 3625archive. `--concatenate' removes the end-of-archive marker from the 3626target archive before each new archive is appended. If you use `cat' to 3627combine the archives, the result will not be a valid `tar' format 3628archive. If you need to retrieve files from an archive that was added 3629to using the `cat' utility, use the `--ignore-zeros' (`-i') option. 3630*Note Ignore Zeros::, for further information on dealing with archives 3631improperly combined using the `cat' shell utility. 3632 3633 ---------- Footnotes ---------- 3634 3635 (1) This can cause multiple members to have the same name, for 3636information on how this affects reading the archive, *note multiple::. 3637 3638 3639File: tar.info, Node: delete, Next: compare, Prev: concatenate, Up: Advanced tar 3640 36414.2.5 Removing Archive Members Using `--delete' 3642----------------------------------------------- 3643 3644 _(This message will disappear, once this node revised.)_ 3645 3646 You can remove members from an archive by using the `--delete' 3647option. Specify the name of the archive with `--file' (`-f') and then 3648specify the names of the members to be deleted; if you list no member 3649names, nothing will be deleted. The `--verbose' option will cause `tar' 3650to print the names of the members as they are deleted. As with 3651`--extract', you must give the exact member names when using `tar 3652--delete'. `--delete' will remove all versions of the named file from 3653the archive. The `--delete' operation can run very slowly. 3654 3655 Unlike other operations, `--delete' has no short form. 3656 3657 This operation will rewrite the archive. You can only use `--delete' 3658on an archive if the archive device allows you to write to any point on 3659the media, such as a disk; because of this, it does not work on magnetic 3660tapes. Do not try to delete an archive member from a magnetic tape; the 3661action will not succeed, and you will be likely to scramble the archive 3662and damage your tape. There is no safe way (except by completely 3663re-writing the archive) to delete files from most kinds of magnetic 3664tape. *Note Media::. 3665 3666 To delete all versions of the file `blues' from the archive 3667`collection.tar' in the `practice' directory, make sure you are in that 3668directory, and then, 3669 3670 $ `tar --list --file=collection.tar' 3671 blues 3672 folk 3673 jazz 3674 rock 3675 $ `tar --delete --file=collection.tar blues' 3676 $ `tar --list --file=collection.tar' 3677 folk 3678 jazz 3679 rock 3680 $ 3681 3682 The `--delete' option has been reported to work properly when `tar' 3683acts as a filter from `stdin' to `stdout'. 3684 3685 3686File: tar.info, Node: compare, Prev: delete, Up: Advanced tar 3687 36884.2.6 Comparing Archive Members with the File System 3689---------------------------------------------------- 3690 3691 _(This message will disappear, once this node revised.)_ 3692 3693 The `--compare' (`-d'), or `--diff' operation compares specified 3694archive members against files with the same names, and then reports 3695differences in file size, mode, owner, modification date and contents. 3696You should _only_ specify archive member names, not file names. If you 3697do not name any members, then `tar' will compare the entire archive. If 3698a file is represented in the archive but does not exist in the file 3699system, `tar' reports a difference. 3700 3701 You have to specify the record size of the archive when modifying an 3702archive with a non-default record size. 3703 3704 `tar' ignores files in the file system that do not have corresponding 3705members in the archive. 3706 3707 The following example compares the archive members `rock', `blues' 3708and `funk' in the archive `bluesrock.tar' with files of the same name in 3709the file system. (Note that there is no file, `funk'; `tar' will report 3710an error message.) 3711 3712 $ `tar --compare --file=bluesrock.tar rock blues funk' 3713 rock 3714 blues 3715 tar: funk not found in archive 3716 3717 The spirit behind the `--compare' (`--diff', `-d') option is to check 3718whether the archive represents the current state of files on disk, more 3719than validating the integrity of the archive media. For this later 3720goal, *Note verify::. 3721 3722 3723File: tar.info, Node: create options, Next: extract options, Prev: Advanced tar, Up: operations 3724 37254.3 Options Used by `--create' 3726============================== 3727 3728The previous chapter described the basics of how to use `--create' 3729(`-c') to create an archive from a set of files. *Note create::. This 3730section described advanced options to be used with `--create'. 3731 3732* Menu: 3733 3734* override:: Overriding File Metadata. 3735* Ignore Failed Read:: 3736 3737 3738File: tar.info, Node: override, Next: Ignore Failed Read, Up: create options 3739 37404.3.1 Overriding File Metadata 3741------------------------------ 3742 3743As described above, a `tar' archive keeps, for each member it contains, 3744its "metadata", such as modification time, mode and ownership of the 3745file. GNU `tar' allows to replace these data with other values when 3746adding files to the archive. The options described in this section 3747affect creation of archives of any type. For POSIX archives, see also 3748*note PAX keywords::, for additional ways of controlling metadata, 3749stored in the archive. 3750 3751`--mode=PERMISSIONS' 3752 When adding files to an archive, `tar' will use PERMISSIONS for the 3753 archive members, rather than the permissions from the files. 3754 PERMISSIONS can be specified either as an octal number or as 3755 symbolic permissions, like with `chmod' (*Note Permissions: 3756 (fileutils)File permissions. This reference also has useful 3757 information for those not being overly familiar with the UNIX 3758 permission system). Using latter syntax allows for more 3759 flexibility. For example, the value `a+rw' adds read and write 3760 permissions for everybody, while retaining executable bits on 3761 directories or on any other file already marked as executable: 3762 3763 $ `tar -c -f archive.tar --mode='a+rw' .' 3764 3765`--mtime=DATE' 3766 When adding files to an archive, `tar' will use DATE as the 3767 modification time of members when creating archives, instead of 3768 their actual modification times. The argument DATE can be either a 3769 textual date representation in almost arbitrary format (*note Date 3770 input formats::) or a name of the existing file, starting with `/' 3771 or `.'. In the latter case, the modification time of that file 3772 will be used. 3773 3774 The following example will set the modification date to 00:00:00 3775 UTC, January 1, 1970: 3776 3777 $ `tar -c -f archive.tar --mtime='1970-01-01' .' 3778 3779 When used with `--verbose' (*note verbose tutorial::) GNU `tar' 3780 will try to convert the specified date back to its textual 3781 representation and compare it with the one given with `--mtime' 3782 options. If the two dates differ, `tar' will print a warning 3783 saying what date it will use. This is to help user ensure he is 3784 using the right date. 3785 3786 For example: 3787 3788 $ `tar -c -f archive.tar -v --mtime=yesterday .' 3789 tar: Option --mtime: Treating date `yesterday' as 2006-06-20 3790 13:06:29.152478 3791 ... 3792 3793`--owner=USER' 3794 Specifies that `tar' should use USER as the owner of members when 3795 creating archives, instead of the user associated with the source 3796 file. The argument USER can be either an existing user symbolic 3797 name, or a decimal numeric user ID. 3798 3799 There is no value indicating a missing number, and `0' usually 3800 means `root'. Some people like to force `0' as the value to offer 3801 in their distributions for the owner of files, because the `root' 3802 user is anonymous anyway, so that might as well be the owner of 3803 anonymous archives. For example: 3804 3805 $ `tar -c -f archive.tar --owner=0 .' 3806 # Or: 3807 $ `tar -c -f archive.tar --owner=root .' 3808 3809`--group=GROUP' 3810 Files added to the `tar' archive will have a group id of GROUP, 3811 rather than the group from the source file. The argument GROUP can 3812 be either an existing group symbolic name, or a decimal numeric 3813 group ID. 3814 3815 3816File: tar.info, Node: Ignore Failed Read, Prev: override, Up: create options 3817 38184.3.2 Ignore Fail Read 3819---------------------- 3820 3821`--ignore-failed-read' 3822 Do not exit with nonzero on unreadable files or directories. 3823 3824 3825File: tar.info, Node: extract options, Next: backup, Prev: create options, Up: operations 3826 38274.4 Options Used by `--extract' 3828=============================== 3829 3830 _(This message will disappear, once this node revised.)_ 3831 3832 The previous chapter showed how to use `--extract' to extract an 3833archive into the file system. Various options cause `tar' to extract 3834more information than just file contents, such as the owner, the 3835permissions, the modification date, and so forth. This section presents 3836options to be used with `--extract' when certain special considerations 3837arise. You may review the information presented in *note extract:: for 3838more basic information about the `--extract' operation. 3839 3840* Menu: 3841 3842* Reading:: Options to Help Read Archives 3843* Writing:: Changing How `tar' Writes Files 3844* Scarce:: Coping with Scarce Resources 3845 3846 3847File: tar.info, Node: Reading, Next: Writing, Up: extract options 3848 38494.4.1 Options to Help Read Archives 3850----------------------------------- 3851 3852 _(This message will disappear, once this node revised.)_ 3853 3854 Normally, `tar' will request data in full record increments from an 3855archive storage device. If the device cannot return a full record, 3856`tar' will report an error. However, some devices do not always return 3857full records, or do not require the last record of an archive to be 3858padded out to the next record boundary. To keep reading until you 3859obtain a full record, or to accept an incomplete record if it contains 3860an end-of-archive marker, specify the `--read-full-records' (`-B') 3861option in conjunction with the `--extract' or `--list' operations. 3862*Note Blocking::. 3863 3864 The `--read-full-records' (`-B') option is turned on by default when 3865`tar' reads an archive from standard input, or from a remote machine. 3866This is because on BSD Unix systems, attempting to read a pipe returns 3867however much happens to be in the pipe, even if it is less than was 3868requested. If this option were not enabled, `tar' would fail as soon as 3869it read an incomplete record from the pipe. 3870 3871 If you're not sure of the blocking factor of an archive, you can read 3872the archive by specifying `--read-full-records' (`-B') and 3873`--blocking-factor=512-SIZE' (`-b 512-SIZE'), using a blocking factor 3874larger than what the archive uses. This lets you avoid having to 3875determine the blocking factor of an archive. *Note Blocking Factor::. 3876 3877* Menu: 3878 3879* read full records:: 3880* Ignore Zeros:: 3881 3882 3883File: tar.info, Node: read full records, Next: Ignore Zeros, Up: Reading 3884 3885Reading Full Records 3886.................... 3887 3888`--read-full-records' 3889 3890`-B' 3891 Use in conjunction with `--extract' (`--get', `-x') to read an 3892 archive which contains incomplete records, or one which has a 3893 blocking factor less than the one specified. 3894 3895 3896File: tar.info, Node: Ignore Zeros, Prev: read full records, Up: Reading 3897 3898Ignoring Blocks of Zeros 3899........................ 3900 3901Normally, `tar' stops reading when it encounters a block of zeros 3902between file entries (which usually indicates the end of the archive). 3903`--ignore-zeros' (`-i') allows `tar' to completely read an archive which 3904contains a block of zeros before the end (i.e., a damaged archive, or 3905one that was created by concatenating several archives together). 3906 3907 The `--ignore-zeros' (`-i') option is turned off by default because 3908many versions of `tar' write garbage after the end-of-archive entry, 3909since that part of the media is never supposed to be read. GNU `tar' 3910does not write after the end of an archive, but seeks to maintain 3911compatiblity among archiving utilities. 3912 3913`--ignore-zeros' 3914`-i' 3915 To ignore blocks of zeros (i.e., end-of-archive entries) which may 3916 be encountered while reading an archive. Use in conjunction with 3917 `--extract' or `--list'. 3918 3919 3920File: tar.info, Node: Writing, Next: Scarce, Prev: Reading, Up: extract options 3921 39224.4.2 Changing How `tar' Writes Files 3923------------------------------------- 3924 3925 _(This message will disappear, once this node revised.)_ 3926 3927* Menu: 3928 3929* Dealing with Old Files:: 3930* Overwrite Old Files:: 3931* Keep Old Files:: 3932* Keep Newer Files:: 3933* Unlink First:: 3934* Recursive Unlink:: 3935* Data Modification Times:: 3936* Setting Access Permissions:: 3937* Directory Modification Times and Permissions:: 3938* Writing to Standard Output:: 3939* Writing to an External Program:: 3940* remove files:: 3941 3942 3943File: tar.info, Node: Dealing with Old Files, Next: Overwrite Old Files, Up: Writing 3944 3945Options Controlling the Overwriting of Existing Files 3946..................................................... 3947 3948When extracting files, if `tar' discovers that the extracted file 3949already exists, it normally replaces the file by removing it before 3950extracting it, to prevent confusion in the presence of hard or symbolic 3951links. (If the existing file is a symbolic link, it is removed, not 3952followed.) However, if a directory cannot be removed because it is 3953nonempty, `tar' normally overwrites its metadata (ownership, permission, 3954etc.). The `--overwrite-dir' option enables this default behavior. To 3955be more cautious and preserve the metadata of such a directory, use the 3956`--no-overwrite-dir' option. 3957 3958 To be even more cautious and prevent existing files from being 3959replaced, use the `--keep-old-files' (`-k') option. It causes `tar' to 3960refuse to replace or update a file that already exists, i.e., a file 3961with the same name as an archive member prevents extraction of that 3962archive member. Instead, it reports an error. 3963 3964 To be more aggressive about altering existing files, use the 3965`--overwrite' option. It causes `tar' to overwrite existing files and 3966to follow existing symbolic links when extracting. 3967 3968 Some people argue that GNU `tar' should not hesitate to overwrite 3969files with other files when extracting. When extracting a `tar' 3970archive, they expect to see a faithful copy of the state of the file 3971system when the archive was created. It is debatable that this would 3972always be a proper behavior. For example, suppose one has an archive in 3973which `usr/local' is a link to `usr/local2'. Since then, maybe the site 3974removed the link and renamed the whole hierarchy from `/usr/local2' to 3975`/usr/local'. Such things happen all the time. I guess it would not be 3976welcome at all that GNU `tar' removes the whole hierarchy just to make 3977room for the link to be reinstated (unless it _also_ simultaneously 3978restores the full `/usr/local2', of course!) GNU `tar' is indeed able 3979to remove a whole hierarchy to reestablish a symbolic link, for example, 3980but _only if_ `--recursive-unlink' is specified to allow this behavior. 3981In any case, single files are silently removed. 3982 3983 Finally, the `--unlink-first' (`-U') option can improve performance 3984in some cases by causing `tar' to remove files unconditionally before 3985extracting them. 3986 3987 3988File: tar.info, Node: Overwrite Old Files, Next: Keep Old Files, Prev: Dealing with Old Files, Up: Writing 3989 3990Overwrite Old Files 3991................... 3992 3993`--overwrite' 3994 Overwrite existing files and directory metadata when extracting 3995 files from an archive. 3996 3997 This causes `tar' to write extracted files into the file system 3998 without regard to the files already on the system; i.e., files with 3999 the same names as archive members are overwritten when the archive 4000 is extracted. It also causes `tar' to extract the ownership, 4001 permissions, and time stamps onto any preexisting files or 4002 directories. If the name of a corresponding file name is a 4003 symbolic link, the file pointed to by the symbolic link will be 4004 overwritten instead of the symbolic link itself (if this is 4005 possible). Moreover, special devices, empty directories and even 4006 symbolic links are automatically removed if they are in the way of 4007 extraction. 4008 4009 Be careful when using the `--overwrite' option, particularly when 4010 combined with the `--absolute-names' (`-P') option, as this 4011 combination can change the contents, ownership or permissions of 4012 any file on your system. Also, many systems do not take kindly to 4013 overwriting files that are currently being executed. 4014 4015`--overwrite-dir' 4016 Overwrite the metadata of directories when extracting files from an 4017 archive, but remove other files before extracting. 4018 4019 4020File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing 4021 4022Keep Old Files 4023.............. 4024 4025`--keep-old-files' 4026`-k' 4027 Do not replace existing files from archive. The `--keep-old-files' 4028 (`-k') option prevents `tar' from replacing existing files with 4029 files with the same name from the archive. The `--keep-old-files' 4030 option is meaningless with `--list' (`-t'). Prevents `tar' from 4031 replacing files in the file system during extraction. 4032 4033 4034File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing 4035 4036Keep Newer Files 4037................ 4038 4039`--keep-newer-files' 4040 Do not replace existing files that are newer than their archive 4041 copies. This option is meaningless with `--list' (`-t'). 4042 4043 4044File: tar.info, Node: Unlink First, Next: Recursive Unlink, Prev: Keep Newer Files, Up: Writing 4045 4046Unlink First 4047............ 4048 4049`--unlink-first' 4050`-U' 4051 Remove files before extracting over them. This can make `tar' run 4052 a bit faster if you know in advance that the extracted files all 4053 need to be removed. Normally this option slows `tar' down 4054 slightly, so it is disabled by default. 4055 4056 4057File: tar.info, Node: Recursive Unlink, Next: Data Modification Times, Prev: Unlink First, Up: Writing 4058 4059Recursive Unlink 4060................ 4061 4062`--recursive-unlink' 4063 When this option is specified, try removing files and directory 4064 hierarchies before extracting over them. _This is a dangerous 4065 option!_ 4066 4067 If you specify the `--recursive-unlink' option, `tar' removes 4068_anything_ that keeps you from extracting a file as far as current 4069permissions will allow it. This could include removal of the contents 4070of a full directory hierarchy. 4071 4072 4073File: tar.info, Node: Data Modification Times, Next: Setting Access Permissions, Prev: Recursive Unlink, Up: Writing 4074 4075Setting Data Modification Times 4076............................... 4077 4078Normally, `tar' sets the data modification times of extracted files to 4079the corresponding times recorded for the files in the archive, but 4080limits the permissions of extracted files by the current `umask' 4081setting. 4082 4083 To set the data modification times of extracted files to the time 4084when the files were extracted, use the `--touch' (`-m') option in 4085conjunction with `--extract' (`--get', `-x'). 4086 4087`--touch' 4088`-m' 4089 Sets the data modification time of extracted archive members to the 4090 time they were extracted, not the time recorded for them in the 4091 archive. Use in conjunction with `--extract' (`--get', `-x'). 4092 4093 4094File: tar.info, Node: Setting Access Permissions, Next: Directory Modification Times and Permissions, Prev: Data Modification Times, Up: Writing 4095 4096Setting Access Permissions 4097.......................... 4098 4099To set the modes (access permissions) of extracted files to those 4100recorded for those files in the archive, use `--same-permissions' in 4101conjunction with the `--extract' (`--get', `-x') operation. 4102 4103`--preserve-permissions' 4104`--same-permissions' 4105`-p' 4106 Set modes of extracted archive members to those recorded in the 4107 archive, instead of current umask settings. Use in conjunction 4108 with `--extract' (`--get', `-x'). 4109 4110 4111File: tar.info, Node: Directory Modification Times and Permissions, Next: Writing to Standard Output, Prev: Setting Access Permissions, Up: Writing 4112 4113Directory Modification Times and Permissions 4114............................................ 4115 4116After sucessfully extracting a file member, GNU `tar' normally restores 4117its permissions and modification times, as described in the previous 4118sections. This cannot be done for directories, because after extracting 4119a directory `tar' will almost certainly extract files into that 4120directory and this will cause the directory modification time to be 4121updated. Moreover, restoring that directory permissions may not permit 4122file creation within it. Thus, restoring directory permissions and 4123modification times must be delayed at least until all files have been 4124extracted into that directory. GNU `tar' restores directories using the 4125following approach. 4126 4127 The extracted directories are created with the mode specified in the 4128archive, as modified by the umask of the user, which gives sufficient 4129permissions to allow file creation. The meta-information about the 4130directory is recorded in the temporary list of directories. When 4131preparing to extract next archive member, GNU `tar' checks if the 4132directory prefix of this file contains the remembered directory. If it 4133does not, the program assumes that all files have been extracted into 4134that directory, restores its modification time and permissions and 4135removes its entry from the internal list. This approach allows to 4136correctly restore directory meta-information in the majority of cases, 4137while keeping memory requirements sufficiently small. It is based on 4138the fact, that most `tar' archives use the predefined order of members: 4139first the directory, then all the files and subdirectories in that 4140directory. 4141 4142 However, this is not always true. The most important exception are 4143incremental archives (*note Incremental Dumps::). The member order in 4144an incremental archive is reversed: first all directory members are 4145stored, followed by other (non-directory) members. So, when extracting 4146from incremental archives, GNU `tar' alters the above procedure. It 4147remebers all restored directories, and restores their meta-data only 4148after the entire archive has been processed. Notice, that you do not 4149need to specity any special options for that, as GNU `tar' automatically 4150detects archives in incremental format. 4151 4152 There may be cases, when such processing is required for normal 4153archives too. Consider the following example: 4154 4155 $ `tar --no-recursion -cvf archive \ 4156 foo foo/file1 bar bar/file foo/file2' 4157 foo/ 4158 foo/file1 4159 bar/ 4160 bar/file 4161 foo/file2 4162 4163 During the normal operation, after encountering `bar' GNU `tar' will 4164assume that all files from the directory `foo' were already extracted 4165and will therefore restore its timestamp and permission bits. However, 4166after extracting `foo/file2' the directory timestamp will be offset 4167again. 4168 4169 To correctly restore directory meta-information in such cases, use 4170`delay-directory-restore' command line option: 4171 4172`--delay-directory-restore' 4173 Delays restoring of the modification times and permissions of 4174 extracted directories until the end of extraction. This way, 4175 correct meta-information is restored even if the archive has 4176 unusual member ordering. 4177 4178`--no-delay-directory-restore' 4179 Cancel the effect of the previous `--delay-directory-restore'. Use 4180 this option if you have used `--delay-directory-restore' in 4181 `TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to 4182 temporarily disable it. 4183 4184 4185File: tar.info, Node: Writing to Standard Output, Next: Writing to an External Program, Prev: Directory Modification Times and Permissions, Up: Writing 4186 4187Writing to Standard Output 4188.......................... 4189 4190To write the extracted files to the standard output, instead of creating 4191the files on the file system, use `--to-stdout' (`-O') in conjunction 4192with `--extract' (`--get', `-x'). This option is useful if you are 4193extracting files to send them through a pipe, and do not need to 4194preserve them in the file system. If you extract multiple members, they 4195appear on standard output concatenated, in the order they are found in 4196the archive. 4197 4198`--to-stdout' 4199`-O' 4200 Writes files to the standard output. Use only in conjunction with 4201 `--extract' (`--get', `-x'). When this option is used, instead of 4202 creating the files specified, `tar' writes the contents of the 4203 files extracted to its standard output. This may be useful if you 4204 are only extracting the files in order to send them through a pipe. 4205 This option is meaningless with `--list' (`-t'). 4206 4207 This can be useful, for example, if you have a tar archive containing 4208a big file and don't want to store the file on disk before processing 4209it. You can use a command like this: 4210 4211 tar -xOzf foo.tgz bigfile | process 4212 4213 or even like this if you want to process the concatenation of the 4214files: 4215 4216 tar -xOzf foo.tgz bigfile1 bigfile2 | process 4217 4218 Hovewer, `--to-command' may be more convenient for use with multiple 4219files. See the next section. 4220 4221 4222File: tar.info, Node: Writing to an External Program, Next: remove files, Prev: Writing to Standard Output, Up: Writing 4223 4224Writing to an External Program 4225.............................. 4226 4227You can instruct `tar' to send the contents of each extracted file to 4228the standard input of an external program: 4229 4230`--to-command=COMMAND' 4231 Extract files and pipe their contents to the standard input of 4232 COMMAND. When this option is used, instead of creating the files 4233 specified, `tar' invokes COMMAND and pipes the contents of the 4234 files to its standard output. COMMAND may contain command line 4235 arguments. The program is executed via `sh -c'. Notice, that 4236 COMMAND is executed once for each regular file extracted. 4237 Non-regular files (directories, etc.) are ignored when this option 4238 is used. 4239 4240 The command can obtain the information about the file it processes 4241from the following environment variables: 4242 4243TAR_FILETYPE 4244 Type of the file. It is a single letter with the following meaning: 4245 4246 f Regular file 4247 d Directory 4248 l Symbolic link 4249 h Hard link 4250 b Block device 4251 c Character device 4252 4253 Currently only regular files are supported. 4254 4255TAR_MODE 4256 File mode, an octal number. 4257 4258TAR_FILENAME 4259 The name of the file. 4260 4261TAR_REALNAME 4262 Name of the file as stored in the archive. 4263 4264TAR_UNAME 4265 Name of the file owner. 4266 4267TAR_GNAME 4268 Name of the file owner group. 4269 4270TAR_ATIME 4271 Time of last access. It is a decimal number, representing seconds 4272 since the epoch. If the archive provides times with nanosecond 4273 precision, the nanoseconds are appended to the timestamp after a 4274 decimal point. 4275 4276TAR_MTIME 4277 Time of last modification. 4278 4279TAR_CTIME 4280 Time of last status change. 4281 4282TAR_SIZE 4283 Size of the file. 4284 4285TAR_UID 4286 UID of the file owner. 4287 4288TAR_GID 4289 GID of the file owner. 4290 4291 In addition to these variables, `TAR_VERSION' contains the GNU `tar' 4292version number. 4293 4294 If COMMAND exits with a non-0 status, `tar' will print an error 4295message similar to the following: 4296 4297 tar: 2345: Child returned status 1 4298 4299 Here, `2345' is the PID of the finished process. 4300 4301 If this behavior is not wanted, use `--ignore-command-error': 4302 4303`--ignore-command-error' 4304 Ignore exit codes of subprocesses. Notice that if the program 4305 exits on signal or otherwise terminates abnormally, the error 4306 message will be printed even if this option is used. 4307 4308`--no-ignore-command-error' 4309 Cancel the effect of any previous `--ignore-command-error' option. 4310 This option is useful if you have set `--ignore-command-error' in 4311 `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to temporarily cancel 4312 it. 4313 4314 4315File: tar.info, Node: remove files, Prev: Writing to an External Program, Up: Writing 4316 4317Removing Files 4318.............. 4319 4320`--remove-files' 4321 Remove files after adding them to the archive. 4322 4323 4324File: tar.info, Node: Scarce, Prev: Writing, Up: extract options 4325 43264.4.3 Coping with Scarce Resources 4327---------------------------------- 4328 4329 _(This message will disappear, once this node revised.)_ 4330 4331* Menu: 4332 4333* Starting File:: 4334* Same Order:: 4335 4336 4337File: tar.info, Node: Starting File, Next: Same Order, Up: Scarce 4338 4339Starting File 4340............. 4341 4342`--starting-file=NAME' 4343`-K NAME' 4344 Starts an operation in the middle of an archive. Use in 4345 conjunction with `--extract' (`--get', `-x') or `--list' (`-t'). 4346 4347 If a previous attempt to extract files failed due to lack of disk 4348space, you can use `--starting-file=NAME' (`-K NAME') to start 4349extracting only after member NAME of the archive. This assumes, of 4350course, that there is now free space, or that you are now extracting 4351into a different file system. (You could also choose to suspend `tar', 4352remove unnecessary files from the file system, and then restart the same 4353`tar' operation. In this case, `--starting-file' is not necessary. 4354*Note Incremental Dumps::, *Note interactive::, and *note exclude::.) 4355 4356 4357File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce 4358 4359Same Order 4360.......... 4361 4362`--same-order' 4363`--preserve-order' 4364`-s' 4365 To process large lists of file names on machines with small amounts 4366 of memory. Use in conjunction with `--compare' (`--diff', `-d'), 4367 `--list' (`-t') or `--extract' (`--get', `-x'). 4368 4369 The `--same-order' (`--preserve-order', `-s') option tells `tar' that 4370the list of file names to be listed or extracted is sorted in the same 4371order as the files in the archive. This allows a large list of names to 4372be used, even on a small machine that would not otherwise be able to 4373hold all the names in memory at the same time. Such a sorted list can 4374easily be created by running `tar -t' on the archive and editing its 4375output. 4376 4377 This option is probably never needed on modern computer systems. 4378 4379 4380File: tar.info, Node: backup, Next: Applications, Prev: extract options, Up: operations 4381 43824.5 Backup options 4383================== 4384 4385GNU `tar' offers options for making backups of files before writing new 4386versions. These options control the details of these backups. They may 4387apply to the archive itself before it is created or rewritten, as well 4388as individual extracted members. Other GNU programs (`cp', `install', 4389`ln', and `mv', for example) offer similar options. 4390 4391 Backup options may prove unexpectedly useful when extracting archives 4392containing many members having identical name, or when extracting 4393archives on systems having file name limitations, making different 4394members appear has having similar names through the side-effect of name 4395truncation. (This is true only if we have a good scheme for truncated 4396backup names, which I'm not sure at all: I suspect work is needed in 4397this area.) When any existing file is backed up before being 4398overwritten by extraction, then clashing files are automatically be 4399renamed to be unique, and the true name is kept for only the last file 4400of a series of clashing files. By using verbose mode, users may track 4401exactly what happens. 4402 4403 At the detail level, some decisions are still experimental, and may 4404change in the future, we are waiting comments from our users. So, 4405please do not learn to depend blindly on the details of the backup 4406features. For example, currently, directories themselves are never 4407renamed through using these options, so, extracting a file over a 4408directory still has good chances to fail. Also, backup options apply to 4409created archives, not only to extracted members. For created archives, 4410backups will not be attempted when the archive is a block or character 4411device, or when it refers to a remote file. 4412 4413 For the sake of simplicity and efficiency, backups are made by 4414renaming old files prior to creation or extraction, and not by copying. 4415The original name is restored if the file creation fails. If a failure 4416occurs after a partial extraction of a file, both the backup and the 4417partially extracted file are kept. 4418 4419`--backup[=METHOD]' 4420 Back up files that are about to be overwritten or removed. Without 4421 this option, the original versions are destroyed. 4422 4423 Use METHOD to determine the type of backups made. If METHOD is not 4424 specified, use the value of the `VERSION_CONTROL' environment 4425 variable. And if `VERSION_CONTROL' is not set, use the `existing' 4426 method. 4427 4428 This option corresponds to the Emacs variable `version-control'; 4429 the same values for METHOD are accepted as in Emacs. This option 4430 also allows more descriptive names. The valid METHODs are: 4431 4432 `t' 4433 `numbered' 4434 Always make numbered backups. 4435 4436 `nil' 4437 `existing' 4438 Make numbered backups of files that already have them, simple 4439 backups of the others. 4440 4441 `never' 4442 `simple' 4443 Always make simple backups. 4444 4445`--suffix=SUFFIX' 4446 Append SUFFIX to each backup file made with `--backup'. If this 4447 option is not specified, the value of the `SIMPLE_BACKUP_SUFFIX' 4448 environment variable is used. And if `SIMPLE_BACKUP_SUFFIX' is not 4449 set, the default is `~', just as in Emacs. 4450 4451 4452File: tar.info, Node: Applications, Next: looking ahead, Prev: backup, Up: operations 4453 44544.6 Notable `tar' Usages 4455======================== 4456 4457 _(This message will disappear, once this node revised.)_ 4458 4459 You can easily use archive files to transport a group of files from 4460one system to another: put all relevant files into an archive on one 4461computer system, transfer the archive to another system, and extract the 4462contents there. The basic transfer medium might be magnetic tape, 4463Internet FTP, or even electronic mail (though you must encode the 4464archive with `uuencode' in order to transport it properly by mail). 4465Both machines do not have to use the same operating system, as long as 4466they both support the `tar' program. 4467 4468 For example, here is how you might copy a directory's contents from 4469one disk to another, while preserving the dates, modes, owners and 4470link-structure of all the files therein. In this case, the transfer 4471medium is a "pipe", which is one a Unix redirection mechanism: 4472 4473 $ `(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)' 4474 4475You can avoid subshells by using `-C' option: 4476 4477 $ `tar -C sourcedir -cf - . | tar -C targetdir -xf -' 4478 4479The command also works using short option forms: 4480 4481 $ `(cd sourcedir; tar --create --file=- . ) \ 4482 | (cd targetdir; tar --extract --file=-)' 4483 # Or: 4484 $ `tar --directory sourcedir --create --file=- . ) \ 4485 | tar --directory targetdir --extract --file=-' 4486 4487This is one of the easiest methods to transfer a `tar' archive. 4488 4489 4490File: tar.info, Node: looking ahead, Prev: Applications, Up: operations 4491 44924.7 Looking Ahead: The Rest of this Manual 4493========================================== 4494 4495You have now seen how to use all eight of the operations available to 4496`tar', and a number of the possible options. The next chapter explains 4497how to choose and change file and archive names, how to use files to 4498store names of other files which you can then call as arguments to `tar' 4499(this can help you save time if you expect to archive the same list of 4500files a number of times), and so forth. 4501 4502 If there are too many files to conveniently list on the command line, 4503you can list the names in a file, and `tar' will read that file. *Note 4504files::. 4505 4506 There are various ways of causing `tar' to skip over some files, and 4507not archive them. *Note Choosing::. 4508 4509 4510File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top 4511 45125 Performing Backups and Restoring Files 4513**************************************** 4514 4515 _(This message will disappear, once this node revised.)_ 4516 4517 GNU `tar' is distributed along with the scripts which the Free 4518Software Foundation uses for performing backups. There is no 4519corresponding scripts available yet for doing restoration of files. 4520Even if there is a good chance those scripts may be satisfying to you, 4521they are not the only scripts or methods available for doing backups and 4522restore. You may well create your own, or use more sophisticated 4523packages dedicated to that purpose. 4524 4525 Some users are enthusiastic about `Amanda' (The Advanced Maryland 4526Automatic Network Disk Archiver), a backup system developed by James da 4527Silva `jds@cs.umd.edu' and available on many Unix systems. This is free 4528software, and it is available at these places: 4529 4530 http://www.cs.umd.edu/projects/amanda/amanda.html 4531 ftp://ftp.cs.umd.edu/pub/amanda 4532 4533 This chapter documents both the provided shell scripts and `tar' 4534options which are more specific to usage as a backup tool. 4535 4536 To "back up" a file system means to create archives that contain all 4537the files in that file system. Those archives can then be used to 4538restore any or all of those files (for instance if a disk crashes or a 4539file is accidentally deleted). File system "backups" are also called 4540"dumps". 4541 4542* Menu: 4543 4544* Full Dumps:: Using `tar' to Perform Full Dumps 4545* Incremental Dumps:: Using `tar' to Perform Incremental Dumps 4546* Backup Levels:: Levels of Backups 4547* Backup Parameters:: Setting Parameters for Backups and Restoration 4548* Scripted Backups:: Using the Backup Scripts 4549* Scripted Restoration:: Using the Restore Script 4550 4551 4552File: tar.info, Node: Full Dumps, Next: Incremental Dumps, Up: Backups 4553 45545.1 Using `tar' to Perform Full Dumps 4555===================================== 4556 4557 _(This message will disappear, once this node revised.)_ 4558 4559 Full dumps should only be made when no other people or programs are 4560modifying files in the file system. If files are modified while `tar' 4561is making the backup, they may not be stored properly in the archive, in 4562which case you won't be able to restore them if you have to. (Files not 4563being modified are written with no trouble, and do not corrupt the 4564entire archive.) 4565 4566 You will want to use the `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') 4567option to give the archive a volume label, so you can tell what this 4568archive is even if the label falls off the tape, or anything like that. 4569 4570 Unless the file system you are dumping is guaranteed to fit on one 4571volume, you will need to use the `--multi-volume' (`-M') option. Make 4572sure you have enough tapes on hand to complete the backup. 4573 4574 If you want to dump each file system separately you will need to use 4575the `--one-file-system' option to prevent `tar' from crossing file 4576system boundaries when storing (sub)directories. 4577 4578 The `--incremental' (`-G') (*note Incremental Dumps::) option is not 4579needed, since this is a complete copy of everything in the file system, 4580and a full restore from this backup would only be done onto a completely 4581empty disk. 4582 4583 Unless you are in a hurry, and trust the `tar' program (and your 4584tapes), it is a good idea to use the `--verify' (`-W') option, to make 4585sure your files really made it onto the dump properly. This will also 4586detect cases where the file was modified while (or just after) it was 4587being archived. Not all media (notably cartridge tapes) are capable of 4588being verified, unfortunately. 4589 4590 4591File: tar.info, Node: Incremental Dumps, Next: Backup Levels, Prev: Full Dumps, Up: Backups 4592 45935.2 Using `tar' to Perform Incremental Dumps 4594============================================ 4595 4596"Incremental backup" is a special form of GNU `tar' archive that stores 4597additional metadata so that exact state of the file system can be 4598restored when extracting the archive. 4599 4600 GNU `tar' currently offers two options for handling incremental 4601backups: `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') and 4602`--incremental' (`-G'). 4603 4604 The option `--listed-incremental' instructs tar to operate on an 4605incremental archive with additional metadata stored in a standalone 4606file, called a "snapshot file". The purpose of this file is to help 4607determine which files have been changed, added or deleted since the last 4608backup, so that the next incremental backup will contain only modified 4609files. The name of the snapshot file is given as an argument to the 4610option: 4611 4612`--listed-incremental=FILE' 4613`-g FILE' 4614 Handle incremental backups with snapshot data in FILE. 4615 4616 To create an incremental backup, you would use `--listed-incremental' 4617together with `--create' (*note create::). For example: 4618 4619 $ `tar --create \ 4620 --file=archive.1.tar \ 4621 --listed-incremental=/var/log/usr.snar \ 4622 /usr' 4623 4624 This will create in `archive.1.tar' an incremental backup of the 4625`/usr' file system, storing additional metadata in the file 4626`/var/log/usr.snar'. If this file does not exist, it will be created. 4627The created archive will then be a "level 0 backup"; please see the next 4628section for more on backup levels. 4629 4630 Otherwise, if the file `/var/log/usr.snar' exists, it determines 4631which files are modified. In this case only these files will be stored 4632in the archive. Suppose, for example, that after running the above 4633command, you delete file `/usr/doc/old' and create directory 4634`/usr/local/db' with the following contents: 4635 4636 $ `ls /usr/local/db' 4637 /usr/local/db/data 4638 /usr/local/db/index 4639 4640 Some time later you create another incremental backup. You will then 4641see: 4642 4643 $ `tar --create \ 4644 --file=archive.2.tar \ 4645 --listed-incremental=/var/log/usr.snar \ 4646 /usr' 4647 tar: usr/local/db: Directory is new 4648 usr/local/db/ 4649 usr/local/db/data 4650 usr/local/db/index 4651 4652The created archive `archive.2.tar' will contain only these three 4653members. This archive is called a "level 1 backup". Notice that 4654`/var/log/usr.snar' will be updated with the new data, so if you plan to 4655create more `level 1' backups, it is necessary to create a working copy 4656of the snapshot file before running `tar'. The above example will then 4657be modified as follows: 4658 4659 $ `cp /var/log/usr.snar /var/log/usr.snar-1' 4660 $ `tar --create \ 4661 --file=archive.2.tar \ 4662 --listed-incremental=/var/log/usr.snar-1 \ 4663 /usr' 4664 4665 Incremental dumps depend crucially on time stamps, so the results are 4666unreliable if you modify a file's time stamps during dumping (e.g., with 4667the `--atime-preserve=replace' option), or if you set the clock 4668backwards. 4669 4670 Metadata stored in snapshot files include device numbers, which, 4671obviously is supposed to be a non-volatile value. However, it turns out 4672that NFS devices have undependable values when an automounter gets in 4673the picture. This can lead to a great deal of spurious redumping in 4674incremental dumps, so it is somewhat useless to compare two NFS devices 4675numbers over time. The solution implemented currently is to considers 4676all NFS devices as being equal when it comes to comparing directories; 4677this is fairly gross, but there does not seem to be a better way to go. 4678 4679 Note that incremental archives use `tar' extensions and may not be 4680readable by non-GNU versions of the `tar' program. 4681 4682 To extract from the incremental dumps, use `--listed-incremental' 4683together with `--extract' option (*note extracting files::). In this 4684case, `tar' does not need to access snapshot file, since all the data 4685necessary for extraction are stored in the archive itself. So, when 4686extracting, you can give whatever argument to `--listed-incremental', 4687the usual practice is to use `--listed-incremental=/dev/null'. 4688Alternatively, you can use `--incremental', which needs no arguments. 4689In general, `--incremental' (`-G') can be used as a shortcut for 4690`--listed-incremental' when listing or extracting incremental backups 4691(for more information, regarding this option, *note incremental-op::). 4692 4693 When extracting from the incremental backup GNU `tar' attempts to 4694restore the exact state the file system had when the archive was 4695created. In particular, it will _delete_ those files in the file system 4696that did not exist in their directories when the archive was created. 4697If you have created several levels of incremental files, then in order 4698to restore the exact contents the file system had when the last level 4699was created, you will need to restore from all backups in turn. 4700Continuing our example, to restore the state of `/usr' file system, one 4701would do(1): 4702 4703 $ `tar --extract \ 4704 --listed-incremental=/dev/null \ 4705 --file archive.1.tar' 4706 $ `tar --extract \ 4707 --listed-incremental=/dev/null \ 4708 --file archive.2.tar' 4709 4710 To list the contents of an incremental archive, use `--list' (*note 4711list::), as usual. To obtain more information about the archive, use 4712`--listed-incremental' or `--incremental' combined with two `--verbose' 4713options(2): 4714 4715 `tar --list --incremental --verbose --verbose archive.tar' 4716 4717 This command will print, for each directory in the archive, the list 4718of files in that directory at the time the archive was created. This 4719information is put out in a format which is both human-readable and 4720unambiguous for a program: each file name is printed as 4721 4722 X FILE 4723 4724where X is a letter describing the status of the file: `Y' if the file 4725is present in the archive, `N' if the file is not included in the 4726archive, or a `D' if the file is a directory (and is included in the 4727archive). *Note Dumpdir::, for the detailed description of dumpdirs and 4728status codes. Each such line is terminated by a newline character. The 4729last line is followed by an additional newline to indicate the end of 4730the data. 4731 4732 The option `--incremental' (`-G') gives the same behavior as 4733`--listed-incremental' when used with `--list' and `--extract' options. 4734When used with `--create' option, it creates an incremental archive 4735without creating snapshot file. Thus, it is impossible to create 4736several levels of incremental backups with `--incremental' option. 4737 4738 ---------- Footnotes ---------- 4739 4740 (1) Notice, that since both archives were created withouth `-P' option 4741(*note absolute::), these commands should be run from the root file 4742system. 4743 4744 (2) Two `--verbose' options were selected to avoid breaking usual 4745verbose listing output (`--list --verbose') when using in scripts. 4746 4747 Versions of GNU `tar' up to 1.15.1 used to dump verbatim binary 4748contents of the DUMPDIR header (with terminating nulls) when 4749`--incremental' or `--listed-incremental' option was given, no matter 4750what the verbosity level. This behavior, and, especially, the binary 4751output it produced were considered incovenient and were changed in 4752version 1.16 4753 4754 4755File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups 4756 47575.3 Levels of Backups 4758===================== 4759 4760An archive containing all the files in the file system is called a "full 4761backup" or "full dump". You could insure your data by creating a full 4762dump every day. This strategy, however, would waste a substantial 4763amount of archive media and user time, as unchanged files are daily 4764re-archived. 4765 4766 It is more efficient to do a full dump only occasionally. To back up 4767files between full dumps, you can use "incremental dumps". A "level 4768one" dump archives all the files that have changed since the last full 4769dump. 4770 4771 A typical dump strategy would be to perform a full dump once a week, 4772and a level one dump once a day. This means some versions of files will 4773in fact be archived more than once, but this dump strategy makes it 4774possible to restore a file system to within one day of accuracy by only 4775extracting two archives--the last weekly (full) dump and the last daily 4776(level one) dump. The only information lost would be in files changed 4777or created since the last daily backup. (Doing dumps more than once a 4778day is usually not worth the trouble). 4779 4780 GNU `tar' comes with scripts you can use to do full and level-one 4781(actually, even level-two and so on) dumps. Using scripts (shell 4782programs) to perform backups and restoration is a convenient and 4783reliable alternative to typing out file name lists and `tar' commands by 4784hand. 4785 4786 Before you use these scripts, you need to edit the file 4787`backup-specs', which specifies parameters used by the backup scripts 4788and by the restore script. This file is usually located in 4789`/etc/backup' directory. *Note Backup Parameters::, for its detailed 4790description. Once the backup parameters are set, you can perform 4791backups or restoration by running the appropriate script. 4792 4793 The name of the backup script is `backup'. The name of the restore 4794script is `restore'. The following sections describe their use in 4795detail. 4796 4797 _Please Note:_ The backup and restoration scripts are designed to be 4798used together. While it is possible to restore files by hand from an 4799archive which was created using a backup script, and to create an 4800archive by hand which could then be extracted using the restore script, 4801it is easier to use the scripts. *Note Incremental Dumps::, before 4802making such an attempt. 4803 4804 4805File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups 4806 48075.4 Setting Parameters for Backups and Restoration 4808================================================== 4809 4810The file `backup-specs' specifies backup parameters for the backup and 4811restoration scripts provided with `tar'. You must edit `backup-specs' 4812to fit your system configuration and schedule before using these 4813scripts. 4814 4815 Syntactically, `backup-specs' is a shell script, containing mainly 4816variable assignments. However, any valid shell construct is allowed in 4817this file. Particularly, you may wish to define functions within that 4818script (e.g., see `RESTORE_BEGIN' below). For more information about 4819shell script syntax, please refer to the definition of the Shell Command 4820Language 4821(http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta 4822g_02). See also *note Bash Features: (bashref)Top. 4823 4824 The shell variables controlling behavior of `backup' and `restore' 4825are described in the following subsections. 4826 4827* Menu: 4828 4829* General-Purpose Variables:: 4830* Magnetic Tape Control:: 4831* User Hooks:: 4832* backup-specs example:: An Example Text of `Backup-specs' 4833 4834 4835File: tar.info, Node: General-Purpose Variables, Next: Magnetic Tape Control, Up: Backup Parameters 4836 48375.4.1 General-Purpose Variables 4838------------------------------- 4839 4840 -- Backup variable: ADMINISTRATOR 4841 The user name of the backup administrator. `Backup' scripts sends 4842 a backup report to this address. 4843 4844 -- Backup variable: BACKUP_HOUR 4845 The hour at which the backups are done. This can be a number from 4846 0 to 23, or the time specification in form HOURS:MINUTES, or the 4847 string `now'. 4848 4849 This variable is used by `backup'. Its value may be overridden 4850 using `--time' option (*note Scripted Backups::). 4851 4852 -- Backup variable: TAPE_FILE 4853 The device `tar' writes the archive to. If TAPE_FILE is a remote 4854 archive (*note remote-dev::), backup script will suppose that your 4855 `mt' is able to access remote devices. If RSH (*note RSH::) is 4856 set, `--rsh-command' option will be added to invocations of `mt'. 4857 4858 -- Backup variable: BLOCKING 4859 The blocking factor `tar' will use when writing the dump archive. 4860 *Note Blocking Factor::. 4861 4862 -- Backup variable: BACKUP_DIRS 4863 A list of file systems to be dumped (for `backup'), or restored 4864 (for `restore'). You can include any directory name in the list -- 4865 subdirectories on that file system will be included, regardless of 4866 how they may look to other networked machines. Subdirectories on 4867 other file systems will be ignored. 4868 4869 The host name specifies which host to run `tar' on, and should 4870 normally be the host that actually contains the file system. 4871 However, the host machine must have GNU `tar' installed, and must 4872 be able to access the directory containing the backup scripts and 4873 their support files using the same file name that is used on the 4874 machine where the scripts are run (i.e. what `pwd' will print when 4875 in that directory on that machine). If the host that contains the 4876 file system does not have this capability, you can specify another 4877 host as long as it can access the file system through NFS. 4878 4879 If the list of file systems is very long you may wish to put it in 4880 a separate file. This file is usually named `/etc/backup/dirs', 4881 but this name may be overridden in `backup-specs' using `DIRLIST' 4882 variable. 4883 4884 -- Backup variable: DIRLIST 4885 A path to the file containing the list of the file systems to 4886 backup or restore. By default it is `/etc/backup/dirs'. 4887 4888 -- Backup variable: BACKUP_FILES 4889 A list of individual files to be dumped (for `backup'), or restored 4890 (for `restore'). These should be accessible from the machine on 4891 which the backup script is run. 4892 4893 If the list of file systems is very long you may wish to store it 4894 in a separate file. This file is usually named 4895 `/etc/backup/files', but this name may be overridden in 4896 `backup-specs' using `FILELIST' variable. 4897 4898 -- Backup variable: FILELIST 4899 A path to the file containing the list of the individual files to 4900 backup or restore. By default it is `/etc/backup/files'. 4901 4902 -- Backup variable: MT 4903 Full file name of `mt' binary. 4904 4905 -- Backup variable: RSH 4906 Full file name of `rsh' binary or its equivalent. You may wish to 4907 set it to `ssh', to improve security. In this case you will have 4908 to use public key authentication. 4909 4910 -- Backup variable: RSH_COMMAND 4911 Full file name of `rsh' binary on remote mashines. This will be 4912 passed via `--rsh-command' option to the remote invocation of GNU 4913 `tar'. 4914 4915 -- Backup variable: VOLNO_FILE 4916 Name of temporary file to hold volume numbers. This needs to be 4917 accessible by all the machines which have file systems to be 4918 dumped. 4919 4920 -- Backup variable: XLIST 4921 Name of "exclude file list". An "exclude file list" is a file 4922 located on the remote machine and containing the list of files to 4923 be excluded from the backup. Exclude file lists are searched in 4924 /etc/tar-backup directory. A common use for exclude file lists is 4925 to exclude files containing security-sensitive information (e.g., 4926 `/etc/shadow' from backups). 4927 4928 This variable affects only `backup'. 4929 4930 -- Backup variable: SLEEP_TIME 4931 Time to sleep between dumps of any two successive file systems 4932 4933 This variable affects only `backup'. 4934 4935 -- Backup variable: DUMP_REMIND_SCRIPT 4936 Script to be run when it's time to insert a new tape in for the 4937 next volume. Administrators may want to tailor this script for 4938 their site. If this variable isn't set, GNU `tar' will display its 4939 built-in prompt, and will expect confirmation from the console. 4940 For the description of the default prompt, see *note change volume 4941 prompt::. 4942 4943 -- Backup variable: SLEEP_MESSAGE 4944 Message to display on the terminal while waiting for dump time. 4945 Usually this will just be some literal text. 4946 4947 -- Backup variable: TAR 4948 Full file name of the GNU `tar' executable. If this is not set, 4949 backup scripts will search `tar' in the current shell path. 4950 4951 4952File: tar.info, Node: Magnetic Tape Control, Next: User Hooks, Prev: General-Purpose Variables, Up: Backup Parameters 4953 49545.4.2 Magnetic Tape Control 4955--------------------------- 4956 4957Backup scripts access tape device using special "hook functions". These 4958functions take a single argument - the name of the tape device. Their 4959names are kept in the following variables: 4960 4961 -- Backup variable: MT_BEGIN 4962 The name of "begin" function. This function is called before 4963 accessing the drive. By default it retensions the tape: 4964 4965 MT_BEGIN=mt_begin 4966 4967 mt_begin() { 4968 mt -f "$1" retension 4969 } 4970 4971 -- Backup variable: MT_REWIND 4972 The name of "rewind" function. The default definition is as 4973 follows: 4974 4975 MT_REWIND=mt_rewind 4976 4977 mt_rewind() { 4978 mt -f "$1" rewind 4979 } 4980 4981 -- Backup variable: MT_OFFLINE 4982 The name of the function switching the tape off line. By default 4983 it is defined as follows: 4984 4985 MT_OFFLINE=mt_offline 4986 4987 mt_offline() { 4988 mt -f "$1" offl 4989 } 4990 4991 -- Backup variable: MT_STATUS 4992 The name of the function used to obtain the status of the archive 4993 device, including error count. Default definition: 4994 4995 MT_STATUS=mt_status 4996 4997 mt_status() { 4998 mt -f "$1" status 4999 } 5000 5001 5002File: tar.info, Node: User Hooks, Next: backup-specs example, Prev: Magnetic Tape Control, Up: Backup Parameters 5003 50045.4.3 User Hooks 5005---------------- 5006 5007"User hooks" are shell functions executed before and after each `tar' 5008invocation. Thus, there are "backup hooks", which are executed before 5009and after dumping each file system, and "restore hooks", executed before 5010and after restoring a file system. Each user hook is a shell function 5011taking four arguments: 5012 5013 -- User Hook Function: hook LEVEL HOST FS FSNAME 5014 Its arguments are: 5015 5016 LEVEL 5017 Current backup or restore level. 5018 5019 HOST 5020 Name or IP address of the host machine being dumped or 5021 restored. 5022 5023 FS 5024 Full path name to the file system being dumped or restored. 5025 5026 FSNAME 5027 File system name with directory separators replaced with 5028 colons. This is useful, e.g., for creating unique files. 5029 5030 Following variables keep the names of user hook functions 5031 5032 -- Backup variable: DUMP_BEGIN 5033 Dump begin function. It is executed before dumping the file 5034 system. 5035 5036 -- Backup variable: DUMP_END 5037 Executed after dumping the file system. 5038 5039 -- Backup variable: RESTORE_BEGIN 5040 Executed before restoring the file system. 5041 5042 -- Backup variable: RESTORE_END 5043 Executed after restoring the file system. 5044 5045 5046File: tar.info, Node: backup-specs example, Prev: User Hooks, Up: Backup Parameters 5047 50485.4.4 An Example Text of `Backup-specs' 5049--------------------------------------- 5050 5051The following is an example of `backup-specs': 5052 5053 # site-specific parameters for file system backup. 5054 5055 ADMINISTRATOR=friedman 5056 BACKUP_HOUR=1 5057 TAPE_FILE=/dev/nrsmt0 5058 5059 # Use `ssh' instead of the less secure `rsh' 5060 RSH=/usr/bin/ssh 5061 RSH_COMMAND=/usr/bin/ssh 5062 5063 # Override MT_STATUS function: 5064 my_status() { 5065 mts -t $TAPE_FILE 5066 } 5067 MT_STATUS=my_status 5068 5069 # Disable MT_OFFLINE function 5070 MT_OFFLINE=: 5071 5072 BLOCKING=124 5073 BACKUP_DIRS=" 5074 albert:/fs/fsf 5075 apple-gunkies:/gd 5076 albert:/fs/gd2 5077 albert:/fs/gp 5078 geech:/usr/jla 5079 churchy:/usr/roland 5080 albert:/ 5081 albert:/usr 5082 apple-gunkies:/ 5083 apple-gunkies:/usr 5084 gnu:/hack 5085 gnu:/u 5086 apple-gunkies:/com/mailer/gnu 5087 apple-gunkies:/com/archive/gnu" 5088 5089 BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]" 5090 5091 5092File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups 5093 50945.5 Using the Backup Scripts 5095============================ 5096 5097The syntax for running a backup script is: 5098 5099 backup --level=LEVEL --time=TIME 5100 5101 The `level' option requests the dump level. Thus, to produce a full 5102dump, specify `--level=0' (this is the default, so `--level' may be 5103omitted if its value is `0'). (1) 5104 5105 The `--time' option determines when should the backup be run. TIME 5106may take three forms: 5107 5108HH:MM 5109 The dump must be run at HH hours MM minutes. 5110 5111HH 5112 The dump must be run at HH hours 5113 5114now 5115 The dump must be run immediately. 5116 5117 You should start a script with a tape or disk mounted. Once you 5118start a script, it prompts you for new tapes or disks as it needs them. 5119Media volumes don't have to correspond to archive files -- a 5120multi-volume archive can be started in the middle of a tape that already 5121contains the end of another multi-volume archive. The `restore' script 5122prompts for media by its archive volume, so to avoid an error message 5123you should keep track of which tape (or disk) contains which volume of 5124the archive (*note Scripted Restoration::). 5125 5126 The backup scripts write two files on the file system. The first is 5127a record file in `/etc/tar-backup/', which is used by the scripts to 5128store and retrieve information about which files were dumped. This file 5129is not meant to be read by humans, and should not be deleted by them. 5130*Note Snapshot Files::, for a more detailed explanation of this file. 5131 5132 The second file is a log file containing the names of the file 5133systems and files dumped, what time the backup was made, and any error 5134messages that were generated, as well as how much space was left in the 5135media volume after the last volume of the archive was written. You 5136should check this log file after every backup. The file name is 5137`log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and 5138N represents current dump level number. 5139 5140 The script also prints the name of each system being dumped to the 5141standard output. 5142 5143 Following is the full list of options accepted by `backup' script: 5144 5145`-l LEVEL' 5146`--level=LEVEL' 5147 Do backup level LEVEL (default 0). 5148 5149`-f' 5150`--force' 5151 Force backup even if today's log file already exists. 5152 5153`-v[LEVEL]' 5154`--verbose[=LEVEL]' 5155 Set verbosity level. The higher the level is, the more debugging 5156 information will be output during execution. Devault LEVEL is 100, 5157 which means the highest debugging level. 5158 5159`-t START-TIME' 5160`--time=START-TIME' 5161 Wait till TIME, then do backup. 5162 5163`-h' 5164`--help' 5165 Display short help message and exit. 5166 5167`-V' 5168`--version' 5169 Display information about the program's name, version, origin and 5170 legal status, all on standard output, and then exit successfully. 5171 5172 ---------- Footnotes ---------- 5173 5174 (1) For backward compatibility, the `backup' will also try to deduce the 5175requested dump level from the name of the script itself. If the name 5176consists of a string `level-' followed by a single decimal digit, that 5177digit is taken as the dump level number. Thus, you may create a link 5178from `backup' to `level-1' and then run `level-1' whenever you need to 5179create a level one dump. 5180 5181 5182File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups 5183 51845.6 Using the Restore Script 5185============================ 5186 5187To restore files that were archived using a scripted backup, use the 5188`restore' script. Its usage is quite straightforward. In the simplest 5189form, invoke `restore --all', it will then restore all the file systems 5190and files specified in `backup-specs' (*note BACKUP_DIRS: 5191General-Purpose Variables.). 5192 5193 You may select the file systems (and/or files) to restore by giving 5194`restore' list of "patterns" in its command line. For example, running 5195 5196 restore 'albert:*' 5197 5198will restore all file systems on the machine `albert'. A more 5199complicated example: 5200 5201 restore 'albert:*' '*:/var' 5202 5203This command will restore all file systems on the machine `albert' as 5204well as `/var' file system on all machines. 5205 5206 By default `restore' will start restoring files from the lowest 5207available dump level (usually zero) and will continue through all 5208available dump levels. There may be situations where such a thorough 5209restore is not necessary. For example, you may wish to restore only 5210files from the recent level one backup. To do so, use `--level' option, 5211as shown in the example below: 5212 5213 restore --level=1 5214 5215 The full list of options accepted by `restore' follows: 5216 5217`-a' 5218`--all' 5219 Restore all file systems and files specified in `backup-specs' 5220 5221`-l LEVEL' 5222`--level=LEVEL' 5223 Start restoring from the given backup level, instead of the default 5224 0. 5225 5226`-v[LEVEL]' 5227`--verbose[=LEVEL]' 5228 Set verbosity level. The higher the level is, the more debugging 5229 information will be output during execution. Devault LEVEL is 100, 5230 which means the highest debugging level. 5231 5232`-h' 5233`--help' 5234 Display short help message and exit. 5235 5236`-V' 5237`--version' 5238 Display information about the program's name, version, origin and 5239 legal status, all on standard output, and then exit successfully. 5240 5241 You should start the restore script with the media containing the 5242first volume of the archive mounted. The script will prompt for other 5243volumes as they are needed. If the archive is on tape, you don't need 5244to rewind the tape to to its beginning--if the tape head is positioned 5245past the beginning of the archive, the script will rewind the tape as 5246needed. *Note Tape Positioning::, for a discussion of tape positioning. 5247 5248 *Warning:* The script will delete files from the active file system 5249 if they were not in the file system when the archive was made. 5250 5251 *Note Incremental Dumps::, for an explanation of how the script makes 5252that determination. 5253 5254 5255File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top 5256 52576 Choosing Files and Names for `tar' 5258************************************ 5259 5260 _(This message will disappear, once this node revised.)_ 5261 5262 Certain options to `tar' enable you to specify a name for your 5263archive. Other options let you decide which files to include or exclude 5264from the archive, based on when or whether files were modified, whether 5265the file names do or don't match specified patterns, or whether files 5266are in specified directories. 5267 5268 This chapter discusses these options in detail. 5269 5270* Menu: 5271 5272* file:: Choosing the Archive's Name 5273* Selecting Archive Members:: 5274* files:: Reading Names from a File 5275* exclude:: Excluding Some Files 5276* wildcards:: Wildcards Patterns and Matching 5277* quoting styles:: Ways of Quoting Special Characters in Names 5278* transform:: Modifying File and Member Names 5279* after:: Operating Only on New Files 5280* recurse:: Descending into Directories 5281* one:: Crossing File System Boundaries 5282 5283 5284File: tar.info, Node: file, Next: Selecting Archive Members, Up: Choosing 5285 52866.1 Choosing and Naming Archive Files 5287===================================== 5288 5289 _(This message will disappear, once this node revised.)_ 5290 5291 By default, `tar' uses an archive file name that was compiled when it 5292was built on the system; usually this name refers to some physical tape 5293drive on the machine. However, the person who installed `tar' on the 5294system may not have set the default to a meaningful value as far as most 5295users are concerned. As a result, you will usually want to tell `tar' 5296where to find (or create) the archive. The `--file=ARCHIVE-NAME' (`-f 5297ARCHIVE-NAME') option allows you to either specify or name a file to use 5298as the archive instead of the default archive file location. 5299 5300`--file=ARCHIVE-NAME' 5301`-f ARCHIVE-NAME' 5302 Name the archive to create or operate on. Use in conjunction with 5303 any operation. 5304 5305 For example, in this `tar' command, 5306 5307 $ `tar -cvf collection.tar blues folk jazz' 5308 5309`collection.tar' is the name of the archive. It must directly follow 5310the `-f' option, since whatever directly follows `-f' _will_ end up 5311naming the archive. If you neglect to specify an archive name, you may 5312end up overwriting a file in the working directory with the archive you 5313create since `tar' will use this file's name for the archive name. 5314 5315 An archive can be saved as a file in the file system, sent through a 5316pipe or over a network, or written to an I/O device such as a tape, 5317floppy disk, or CD write drive. 5318 5319 If you do not name the archive, `tar' uses the value of the 5320environment variable `TAPE' as the file name for the archive. If that 5321is not available, `tar' uses a default, compiled-in archive name, 5322usually that for tape unit zero (i.e. `/dev/tu00'). 5323 5324 If you use `-' as an ARCHIVE-NAME, `tar' reads the archive from 5325standard input (when listing or extracting files), or writes it to 5326standard output (when creating an archive). If you use `-' as an 5327ARCHIVE-NAME when modifying an archive, `tar' reads the original archive 5328from its standard input and writes the entire new archive to its 5329standard output. 5330 5331 The following example is a convenient way of copying directory 5332hierarchy from `sourcedir' to `targetdir'. 5333 5334 $ `(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)' 5335 5336 The `-C' option allows to avoid using subshells: 5337 5338 $ `tar -C sourcedir -cf - . | tar -C targetdir -xpf -' 5339 5340 In both examples above, the leftmost `tar' invocation archives the 5341contents of `sourcedir' to the standard output, while the rightmost one 5342reads this archive from its standard input and extracts it. The `-p' 5343option tells it to restore permissions of the extracted files. 5344 5345 To specify an archive file on a device attached to a remote machine, 5346use the following: 5347 5348 `--file=HOSTNAME:/DEV/FILE-NAME' 5349 5350`tar' will complete the remote connection, if possible, and prompt you 5351for a username and password. If you use 5352`--file=@HOSTNAME:/DEV/FILE-NAME', `tar' will complete the remote 5353connection, if possible, using your username as the username on the 5354remote machine. 5355 5356 If the archive file name includes a colon (`:'), then it is assumed 5357to be a file on another machine. If the archive file is 5358`USER@HOST:FILE', then FILE is used on the host HOST. The remote host 5359is accessed using the `rsh' program, with a username of USER. If the 5360username is omitted (along with the `@' sign), then your user name will 5361be used. (This is the normal `rsh' behavior.) It is necessary for the 5362remote machine, in addition to permitting your `rsh' access, to have the 5363`rmt' program installed (This command is included in the GNU `tar' 5364distribution and by default is installed under `PREFIX/libexec/rmt', 5365were PREFIX means your installation prefix). If you need to use a file 5366whose name includes a colon, then the remote tape drive behavior can be 5367inhibited by using the `--force-local' option. 5368 5369 When the archive is being created to `/dev/null', GNU `tar' tries to 5370minimize input and output operations. The Amanda backup system, when 5371used with GNU `tar', has an initial sizing pass which uses this feature. 5372 5373 5374File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing 5375 53766.2 Selecting Archive Members 5377============================= 5378 5379"File Name arguments" specify which files in the file system `tar' 5380operates on, when creating or adding to an archive, or which archive 5381members `tar' operates on, when reading or deleting from an archive. 5382*Note Operations::. 5383 5384 To specify file names, you can include them as the last arguments on 5385the command line, as follows: 5386 `tar' OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...] 5387 5388 If a file name begins with dash (`-'), precede it with `--add-file' 5389option to prevent it from being treated as an option. 5390 5391 By default GNU `tar' attempts to "unquote" each file or member name, 5392replacing "escape sequences" according to the following table: 5393 5394Escape Replaced with 5395----------------------------------------------------------- 5396\a Audible bell (ASCII 7) 5397\b Backspace (ASCII 8) 5398\f Form feed (ASCII 12) 5399\n New line (ASCII 10) 5400\r Carriage return (ASCII 13) 5401\t Horizontal tabulation (ASCII 9) 5402\v Vertical tabulation (ASCII 11) 5403\? ASCII 127 5404\N ASCII N (N should be an octal number 5405 of up to 3 digits) 5406 5407 A backslash followed by any other symbol is retained. 5408 5409 This default behavior is controlled by the following command line 5410option: 5411 5412`--unquote' 5413 Enable unquoting input file or member names (default). 5414 5415`--no-unquote' 5416 Disable unquoting input file or member names. 5417 5418 If you specify a directory name as a file name argument, all the 5419files in that directory are operated on by `tar'. 5420 5421 If you do not specify files, `tar' behavior differs depending on the 5422operation mode as described below: 5423 5424 When `tar' is invoked with `--create' (`-c'), `tar' will stop 5425immediately, reporting the following: 5426 5427 $ `tar cf a.tar' 5428 tar: Cowardly refusing to create an empty archive 5429 Try `tar --help' or `tar --usage' for more information. 5430 5431 If you specify either `--list' (`-t') or `--extract' (`--get', `-x'), 5432`tar' operates on all the archive members in the archive. 5433 5434 If run with `--diff' option, tar will compare the archive with the 5435contents of the current working directory. 5436 5437 If you specify any other operation, `tar' does nothing. 5438 5439 By default, `tar' takes file names from the command line. However, 5440there are other ways to specify file or member names, or to modify the 5441manner in which `tar' selects the files or members upon which to 5442operate. In general, these methods work both for specifying the names 5443of files and archive members. 5444 5445 5446File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing 5447 54486.3 Reading Names from a File 5449============================= 5450 5451Instead of giving the names of files or archive members on the command 5452line, you can put the names into a file, and then use the 5453`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'. Give 5454the name of the file which contains the list of files to include as the 5455argument to `--files-from'. In the list, the file names should be 5456separated by newlines. You will frequently use this option when you 5457have generated the list of files to archive with the `find' utility. 5458 5459`--files-from=FILE-NAME' 5460`-T FILE-NAME' 5461 Get names to extract or create from file FILE-NAME. 5462 5463 If you give a single dash as a file name for `--files-from', (i.e., 5464you specify either `--files-from=-' or `-T -'), then the file names are 5465read from standard input. 5466 5467 Unless you are running `tar' with `--create', you can not use both 5468`--files-from=-' and `--file=-' (`-f -') in the same command. 5469 5470 Any number of `-T' options can be given in the command line. 5471 5472 The following example shows how to use `find' to generate a list of 5473files smaller than 400K in length and put that list into a file called 5474`small-files'. You can then use the `-T' option to `tar' to specify the 5475files from that file, `small-files', to create the archive `little.tgz'. 5476(The `-z' option to `tar' compresses the archive with `gzip'; *note 5477gzip:: for more information.) 5478 5479 $ `find . -size -400 -print > small-files' 5480 $ `tar -c -v -z -T small-files -f little.tgz' 5481 5482In the file list given by `-T' option, any file name beginning with `-' 5483character is considered a `tar' option and is processed accordingly.(1) 5484For example, the common use of this feature is to change to another 5485directory by specifying `-C' option: 5486 5487 $ `cat list' 5488 -C/etc 5489 passwd 5490 hosts 5491 -C/lib 5492 libc.a 5493 $ `tar -c -f foo.tar --files-from list' 5494 5495In this example, `tar' will first switch to `/etc' directory and add 5496files `passwd' and `hosts' to the archive. Then it will change to 5497`/lib' directory and will archive the file `libc.a'. Thus, the 5498resulting archive `foo.tar' will contain: 5499 5500 $ `tar tf foo.tar' 5501 passwd 5502 hosts 5503 libc.a 5504 5505Notice that the option parsing algorithm used with `-T' is stricter than 5506the one used by shell. Namely, when specifying option arguments, you 5507should observe the following rules: 5508 5509 * When using short (single-letter) option form, its argument must 5510 immediately follow the option letter, without any intervening 5511 whitespace. For example: `-Cdir'. 5512 5513 * When using long option form, the option argument must be separated 5514 from the option by a single equal sign. No whitespace is allowed 5515 on any side of the equal sign. For example: `--directory=dir'. 5516 5517 * For both short and long option forms, the option argument can be 5518 given on the next line after the option name, e.g.: 5519 5520 --directory 5521 dir 5522 5523 and 5524 5525 -C 5526 dir 5527 5528 If you happen to have a file whose name starts with `-', precede it 5529with `--add-file' option to prevent it from being recognized as an 5530option. For example: `--add-file=--my-file'. 5531 5532* Menu: 5533 5534* nul:: 5535 5536 ---------- Footnotes ---------- 5537 5538 (1) Versions of GNU `tar' up to 1.15.1 recognized only `-C' option in 5539file lists, and only if the option and its argument occupied two 5540consecutive lines. 5541 5542 5543File: tar.info, Node: nul, Up: files 5544 55456.3.1 `NUL' Terminated File Names 5546--------------------------------- 5547 5548The `--null' option causes `--files-from=FILE-OF-NAMES' (`-T 5549FILE-OF-NAMES') to read file names terminated by a `NUL' instead of a 5550newline, so files whose names contain newlines can be archived using 5551`--files-from'. 5552 5553`--null' 5554 Only consider `NUL' terminated file names, instead of files that 5555 terminate in a newline. 5556 5557 The `--null' option is just like the one in GNU `xargs' and `cpio', 5558and is useful with the `-print0' predicate of GNU `find'. In `tar', 5559`--null' also disables special handling for file names that begin with 5560dash. 5561 5562 This example shows how to use `find' to generate a list of files 5563larger than 800K in length and put that list into a file called 5564`long-files'. The `-print0' option to `find' is just like `-print', 5565except that it separates files with a `NUL' rather than with a newline. 5566You can then run `tar' with both the `--null' and `-T' options to 5567specify that `tar' get the files from that file, `long-files', to create 5568the archive `big.tgz'. The `--null' option to `tar' will cause `tar' to 5569recognize the `NUL' separator between files. 5570 5571 $ `find . -size +800 -print0 > long-files' 5572 $ `tar -c -v --null --files-from=long-files --file=big.tar' 5573 5574 5575File: tar.info, Node: exclude, Next: wildcards, Prev: files, Up: Choosing 5576 55776.4 Excluding Some Files 5578======================== 5579 5580 _(This message will disappear, once this node revised.)_ 5581 5582 To avoid operating on files whose names match a particular pattern, 5583use the `--exclude' or `--exclude-from' options. 5584 5585`--exclude=PATTERN' 5586 Causes `tar' to ignore files that match the PATTERN. 5587 5588 The `--exclude=PATTERN' option prevents any file or member whose name 5589matches the shell wildcard (PATTERN) from being operated on. For 5590example, to create an archive with all the contents of the directory 5591`src' except for files whose names end in `.o', use the command `tar -cf 5592src.tar --exclude='*.o' src'. 5593 5594 You may give multiple `--exclude' options. 5595 5596`--exclude-from=FILE' 5597`-X FILE' 5598 Causes `tar' to ignore files that match the patterns listed in 5599 FILE. 5600 5601 Use the `--exclude-from' option to read a list of patterns, one per 5602line, from FILE; `tar' will ignore files matching those patterns. Thus 5603if `tar' is called as `tar -c -X foo .' and the file `foo' contains a 5604single line `*.o', no files whose names end in `.o' will be added to the 5605archive. 5606 5607`--exclude-caches' 5608 Causes `tar' to ignore directories containing a cache directory 5609 tag. 5610 5611 When creating an archive, the `--exclude-caches' option causes `tar' 5612to exclude all directories that contain a "cache directory tag". A cache 5613directory tag is a short file with the well-known name `CACHEDIR.TAG' 5614and having a standard header specified in 5615`http://www.brynosaurus.com/cachedir/spec.html'. Various applications 5616write cache directory tags into directories they use to hold 5617regenerable, non-precious data, so that such data can be more easily 5618excluded from backups. 5619 5620* Menu: 5621 5622* problems with exclude:: 5623 5624 5625File: tar.info, Node: problems with exclude, Up: exclude 5626 5627Problems with Using the `exclude' Options 5628----------------------------------------- 5629 5630Some users find `exclude' options confusing. Here are some common 5631pitfalls: 5632 5633 * The main operating mode of `tar' does not act on a path name 5634 explicitly listed on the command line if one of its file name 5635 components is excluded. In the example above, if you create an 5636 archive and exclude files that end with `*.o', but explicitly name 5637 the file `dir.o/foo' after all the options have been listed, 5638 `dir.o/foo' will be excluded from the archive. 5639 5640 * You can sometimes confuse the meanings of `--exclude' and 5641 `--exclude-from'. Be careful: use `--exclude' when files to be 5642 excluded are given as a pattern on the command line. Use 5643 `--exclude-from' to introduce the name of a file which contains a 5644 list of patterns, one per line; each of these patterns can exclude 5645 zero, one, or many files. 5646 5647 * When you use `--exclude=PATTERN', be sure to quote the PATTERN 5648 parameter, so GNU `tar' sees wildcard characters like `*'. If you 5649 do not do this, the shell might expand the `*' itself using files 5650 at hand, so `tar' might receive a list of files instead of one 5651 pattern, or none at all, making the command somewhat illegal. This 5652 might not correspond to what you want. 5653 5654 For example, write: 5655 5656 $ `tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY' 5657 5658 rather than: 5659 5660 # _Wrong!_ 5661 $ `tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY' 5662 5663 * You must use use shell syntax, or globbing, rather than `regexp' 5664 syntax, when using exclude options in `tar'. If you try to use 5665 `regexp' syntax to describe files to be excluded, your command 5666 might fail. 5667 5668 * In earlier versions of `tar', what is now the `--exclude-from' 5669 option was called `--exclude' instead. Now, `--exclude' applies to 5670 patterns listed on the command line and `--exclude-from' applies to 5671 patterns listed in a file. 5672 5673 5674File: tar.info, Node: wildcards, Next: quoting styles, Prev: exclude, Up: Choosing 5675 56766.5 Wildcards Patterns and Matching 5677=================================== 5678 5679"Globbing" is the operation by which "wildcard" characters, `*' or `?' 5680for example, are replaced and expanded into all existing files matching 5681the given pattern. GNU `tar' can use wildcard patterns for matching (or 5682globbing) archive members when extracting from or listing an archive. 5683Wildcard patterns are also used for verifying volume labels of `tar' 5684archives. This section has the purpose of explaining wildcard syntax 5685for `tar'. 5686 5687 A PATTERN should be written according to shell syntax, using wildcard 5688characters to effect globbing. Most characters in the pattern stand for 5689themselves in the matched string, and case is significant: `a' will 5690match only `a', and not `A'. The character `?' in the pattern matches 5691any single character in the matched string. The character `*' in the 5692pattern matches zero, one, or more single characters in the matched 5693string. The character `\' says to take the following character of the 5694pattern _literally_; it is useful when one needs to match the `?', `*', 5695`[' or `\' characters, themselves. 5696 5697 The character `[', up to the matching `]', introduces a character 5698class. A "character class" is a list of acceptable characters for the 5699next single character of the matched string. For example, `[abcde]' 5700would match any of the first five letters of the alphabet. Note that 5701within a character class, all of the "special characters" listed above 5702other than `\' lose their special meaning; for example, `[-\\[*?]]' 5703would match any of the characters, `-', `\', `[', `*', `?', or `]'. 5704(Due to parsing constraints, the characters `-' and `]' must either come 5705_first_ or _last_ in a character class.) 5706 5707 If the first character of the class after the opening `[' is `!' or 5708`^', then the meaning of the class is reversed. Rather than listing 5709character to match, it lists those characters which are _forbidden_ as 5710the next single character of the matched string. 5711 5712 Other characters of the class stand for themselves. The special 5713construction `[A-E]', using an hyphen between two letters, is meant to 5714represent all characters between A and E, inclusive. 5715 5716 Periods (`.') or forward slashes (`/') are not considered special for 5717wildcard matches. However, if a pattern completely matches a directory 5718prefix of a matched string, then it matches the full matched string: 5719thus, excluding a directory also excludes all the files beneath it. 5720 5721* Menu: 5722 5723* controlling pattern-matching:: 5724 5725 5726File: tar.info, Node: controlling pattern-matching, Up: wildcards 5727 5728Controlling Pattern-Matching 5729---------------------------- 5730 5731For the purposes of this section, we call "exclusion members" all member 5732names obtained while processing `--exclude' and `--exclude-from' 5733options, and "inclusion members" those member names that were given in 5734the command line or read from the file specified with `--files-from' 5735option. 5736 5737 These two pairs of member lists are used in the following operations: 5738`--diff', `--extract', `--list', `--update'. 5739 5740 There are no inclusion members in create mode (`--create' and 5741`--append'), since in this mode the names obtained from the command line 5742refer to _files_, not archive members. 5743 5744 By default, inclusion members are compared with archive members 5745literally (1) and exclusion members are treated as globbing patterns. 5746For example: 5747 5748 $ `tar tf foo.tar' 5749 a.c 5750 b.c 5751 a.txt 5752 [remarks] 5753 # Member names are used verbatim: 5754 $ `tar -xf foo.tar -v '[remarks]'' 5755 [remarks] 5756 # Exclude member names are globbed: 5757 $ `tar -xf foo.tar -v --exclude '*.c'' 5758 a.txt 5759 [remarks] 5760 5761 This behavior can be altered by using the following options: 5762 5763`--wildcards' 5764 Treat all member names as wildcards. 5765 5766`--no-wildcards' 5767 Treat all member names as literal strings. 5768 5769 Thus, to extract files whose names end in `.c', you can use: 5770 5771 $ `tar -xf foo.tar -v --wildcards '*.c'' 5772 a.c 5773 b.c 5774 5775Notice quoting of the pattern to prevent the shell from interpreting it. 5776 5777 The effect of `--wildcards' option is cancelled by `--no-wildcards'. 5778This can be used to pass part of the command line arguments verbatim and 5779other part as globbing patterns. For example, the following invocation: 5780 5781 $ `tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'' 5782 5783instructs `tar' to extract from `foo.tar' all files whose names end in 5784`.txt' and the file named `[remarks]'. 5785 5786 Normally, a pattern matches a name if an initial subsequence of the 5787name's components matches the pattern, where `*', `?', and `[...]' are 5788the usual shell wildcards, `\' escapes wildcards, and wildcards can 5789match `/'. 5790 5791 Other than optionally stripping leading `/' from names (*note 5792absolute::), patterns and names are used as-is. For example, trailing 5793`/' is not trimmed from a user-specified name before deciding whether to 5794exclude it. 5795 5796 However, this matching procedure can be altered by the options listed 5797below. These options accumulate. For example: 5798 5799 --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme' 5800 5801ignores case when excluding `makefile', but not when excluding `readme'. 5802 5803`--anchored' 5804`--no-anchored' 5805 If anchored, a pattern must match an initial subsequence of the 5806 name's components. Otherwise, the pattern can match any 5807 subsequence. Default is `--no-anchored' for exclusion members and 5808 `--anchored' inclusion members. 5809 5810`--ignore-case' 5811`--no-ignore-case' 5812 When ignoring case, upper-case patterns match lower-case names and 5813 vice versa. When not ignoring case (the default), matching is 5814 case-sensitive. 5815 5816`--wildcards-match-slash' 5817`--no-wildcards-match-slash' 5818 When wildcards match slash (the default for exclusion members), a 5819 wildcard like `*' in the pattern can match a `/' in the name. 5820 Otherwise, `/' is matched only by `/'. 5821 5822 The `--recursion' and `--no-recursion' options (*note recurse::) also 5823affect how member patterns are interpreted. If recursion is in effect, 5824a pattern matches a name if it matches any of the name's parent 5825directories. 5826 5827 The following table summarizes pattern-matching default values: 5828 5829Members Default settings 5830-------------------------------------------------------------------------- 5831Inclusion `--no-wildcards --anchored 5832 --no-wildcards-match-slash' 5833Exclusion `--wildcards --no-anchored 5834 --wildcards-match-slash' 5835 5836 ---------- Footnotes ---------- 5837 5838 (1) Notice that earlier GNU `tar' versions used globbing for inclusion 5839members, which contradicted to UNIX98 specification and was not 5840documented. *Note Changes::, for more information on this and other 5841changes. 5842 5843 5844File: tar.info, Node: quoting styles, Next: transform, Prev: wildcards, Up: Choosing 5845 58466.6 Quoting Member Names 5847======================== 5848 5849When displaying member names, `tar' takes care to avoid ambiguities 5850caused by certain characters. This is called "name quoting". The 5851characters in question are: 5852 5853 * Non-printable control characters: 5854 5855 Character ASCII Character name 5856 ------------------------------------------------------------------- 5857 \a 7 Audible bell 5858 \b 8 Backspace 5859 \f 12 Form feed 5860 \n 10 New line 5861 \r 13 Carriage return 5862 \t 9 Horizontal tabulation 5863 \v 11 Vertical tabulation 5864 5865 * Space (ASCII 32) 5866 5867 * Single and double quotes (`'' and `"') 5868 5869 * Backslash (`\') 5870 5871 The exact way `tar' uses to quote these characters depends on the 5872"quoting style". The default quoting style, called "escape" (see 5873below), uses backslash notation to represent control characters, space 5874and backslash. Using this quoting style, control characters are 5875represented as listed in column `Character' in the above table, a space 5876is printed as `\ ' and a backslash as `\\'. 5877 5878 GNU `tar' offers seven distinct quoting styles, which can be selected 5879using `--quoting-style' option: 5880 5881`--quoting-style=STYLE' 5882 Sets quoting style. Valid values for STYLE argument are: literal, 5883 shell, shell-always, c, escape, locale, clocale. 5884 5885 These styles are described in detail below. To illustrate their 5886effect, we will use an imaginary tar archive `arch.tar' containing the 5887following members: 5888 5889 # 1. Contains horizontal tabulation character. 5890 a tab 5891 # 2. Contains newline character 5892 a 5893 newline 5894 # 3. Contains a space 5895 a space 5896 # 4. Contains double quotes 5897 a"double"quote 5898 # 5. Contains single quotes 5899 a'single'quote 5900 # 6. Contains a backslash character: 5901 a\backslash 5902 5903 Here is how usual `ls' command would have listed them, if they had 5904existed in the current working directory: 5905 5906 $ `ls' 5907 a\ttab 5908 a\nnewline 5909 a\ space 5910 a"double"quote 5911 a'single'quote 5912 a\\backslash 5913 5914 Quoting styles: 5915 5916`literal' 5917 No quoting, display each character as is: 5918 5919 $ `tar tf arch.tar --quoting-style=literal' 5920 ./ 5921 ./a space 5922 ./a'single'quote 5923 ./a"double"quote 5924 ./a\backslash 5925 ./a tab 5926 ./a 5927 newline 5928 5929`shell' 5930 Display characters the same way Bourne shell does: control 5931 characters, except `\t' and `\n', are printed using backslash 5932 escapes, `\t' and `\n' are printed as is, and a single quote is 5933 printed as `\''. If a name contains any quoted characters, it is 5934 enclosed in single quotes. In particular, if a name contains 5935 single quotes, it is printed as several single-quoted strings: 5936 5937 $ `tar tf arch.tar --quoting-style=shell' 5938 ./ 5939 './a space' 5940 './a'\''single'\''quote' 5941 './a"double"quote' 5942 './a\backslash' 5943 './a tab' 5944 './a 5945 newline' 5946 5947`shell-always' 5948 Same as `shell', but the names are always enclosed in single 5949 quotes: 5950 5951 $ `tar tf arch.tar --quoting-style=shell-always' 5952 './' 5953 './a space' 5954 './a'\''single'\''quote' 5955 './a"double"quote' 5956 './a\backslash' 5957 './a tab' 5958 './a 5959 newline' 5960 5961`c' 5962 Use the notation of the C programming language. All names are 5963 enclosed in double quotes. Control characters are quoted using 5964 backslash notations, double quotes are represented as `\"', 5965 backslash characters are represented as `\\'. Single quotes and 5966 spaces are not quoted: 5967 5968 $ `tar tf arch.tar --quoting-style=c' 5969 "./" 5970 "./a space" 5971 "./a'single'quote" 5972 "./a\"double\"quote" 5973 "./a\\backslash" 5974 "./a\ttab" 5975 "./a\nnewline" 5976 5977`escape' 5978 Control characters are printed using backslash notation, a space is 5979 printed as `\ ' and a backslash as `\\'. This is the default 5980 quoting style, unless it was changed when configured the package. 5981 5982 $ `tar tf arch.tar --quoting-style=escape' 5983 ./ 5984 ./a space 5985 ./a'single'quote 5986 ./a"double"quote 5987 ./a\\backslash 5988 ./a\ttab 5989 ./a\nnewline 5990 5991`locale' 5992 Control characters, single quote and backslash are printed using 5993 backslash notation. All names are quoted using left and right 5994 quotation marks, appropriate to the current locale. If it does not 5995 define quotation marks, use ``' as left and `'' as right quotation 5996 marks. Any occurrences of the right quotation mark in a name are 5997 escaped with `\', for example: 5998 5999 For example: 6000 6001 $ `tar tf arch.tar --quoting-style=locale' 6002 `./' 6003 `./a space' 6004 `./a\'single\'quote' 6005 `./a"double"quote' 6006 `./a\\backslash' 6007 `./a\ttab' 6008 `./a\nnewline' 6009 6010`clocale' 6011 Same as `locale', but `"' is used for both left and right quotation 6012 marks, if not provided by the currently selected locale: 6013 6014 $ `tar tf arch.tar --quoting-style=clocale' 6015 "./" 6016 "./a space" 6017 "./a'single'quote" 6018 "./a\"double\"quote" 6019 "./a\\backslash" 6020 "./a\ttab" 6021 "./a\nnewline" 6022 6023 You can specify which characters should be quoted in addition to 6024those implied by the current quoting style: 6025 6026`--quote-chars=STRING' 6027 Always quote characters from STRING, even if the selected quoting 6028 style would not quote them. 6029 6030 For example, using `escape' quoting (compare with the usual escape 6031listing above): 6032 6033 $ `tar tf arch.tar --quoting-style=escape --quote-chars=' "'' 6034 ./ 6035 ./a\ space 6036 ./a'single'quote 6037 ./a\"double\"quote 6038 ./a\\backslash 6039 ./a\ttab 6040 ./a\nnewline 6041 6042 To disable quoting of such additional characters, use the following 6043option: 6044 6045`--no-quote-chars=STRING' 6046 Remove characters listed in STRING from the list of quoted 6047 characters set by the previous `--quote-chars' option. 6048 6049 This option is particularly useful if you have added `--quote-chars' 6050to your `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for 6051the current invocation. 6052 6053 Note, that `--no-quote-chars' does _not_ disable those characters 6054that are quoted by default in the selected quoting style. 6055 6056 6057File: tar.info, Node: transform, Next: after, Prev: quoting styles, Up: Choosing 6058 60596.7 Modifying File and Member Names 6060=================================== 6061 6062`Tar' archives contain detailed information about files stored in them 6063and full file names are part of that information. When storing file to 6064an archive, its file name is recorded in the archive along with the 6065actual file contents. When restoring from an archive, a file is created 6066on disk with exactly the same name as that stored in the archive. In 6067the majority of cases this is the desired behavior of a file archiver. 6068However, there are some cases when it is not. 6069 6070 First of all, it is often unsafe to extract archive members with 6071absolute file names or those that begin with a `../'. GNU `tar' takes 6072special precautions when extracting such names and provides a special 6073option for handling them, which is described in *note absolute::. 6074 6075 Secondly, you may wish to extract file names without some leading 6076directory components, or with otherwise modified names. In other cases 6077it is desirable to store files under differing names in the archive. 6078 6079 GNU `tar' provides two options for these needs. 6080 6081`--strip-components=NUMBER' 6082 Strip given NUMBER of leading components from file names before 6083 extraction. 6084 6085 For example, suppose you have archived whole `/usr' hierarchy to a 6086tar archive named `usr.tar'. Among other files, this archive contains 6087`usr/include/stdlib.h', which you wish to extract to the current working 6088directory. To do so, you type: 6089 6090 $ `tar -xf usr.tar --strip=2 usr/include/stdlib.h' 6091 6092 The option `--strip=2' instructs `tar' to strip the two leading 6093components (`usr/' and `include/') off the file name. 6094 6095 If you add to the above invocation `--verbose' (`-v') option, you 6096will note that the verbose listing still contains the full file name, 6097with the two removed components still in place. This can be 6098inconvenient, so `tar' provides a special option for altering this 6099behavior: 6100 6101`--show-transformed-names' 6102 Display file or member names with all requested transformations 6103 applied. 6104 6105For example: 6106 6107 $ `tar -xf usr.tar -v --strip=2 usr/include/stdlib.h' 6108 usr/include/stdlib.h 6109 $ `tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h' 6110 stdlib.h 6111 6112 Notice that in both cases the file is `stdlib.h' extracted to the 6113current working directory, `--show-transformed-names' affects only the 6114way its name is displayed. 6115 6116 This option is especially useful for verifying whether the invocation 6117will have the desired effect. Thus, before running 6118 6119 $ `tar -x --strip=N' 6120 6121it is often advisable to run 6122 6123 $ `tar -t -v --show-transformed --strip=N' 6124 6125to make sure the command will produce the intended results. 6126 6127 In case you need to apply more complex modifications to the file 6128name, GNU `tar' provides a general-purpose transformation option: 6129 6130`--transform=EXPRESSION' 6131 Modify file names using supplied EXPRESSION. 6132 6133The EXPRESSION is a `sed'-like replace expression of the form: 6134 6135 s/REGEXP/REPLACE/[FLAGS] 6136 6137where REGEXP is a "regular expression", REPLACE is a replacement for 6138each file name part that matches REGEXP. Both REGEXP and REPLACE are 6139described in detail in *note The "s" Command: (sed)The "s" Command. 6140 6141 Supported FLAGS are: 6142 6143`g' 6144 Apply the replacement to _all_ matches to the REGEXP, not just the 6145 first. 6146 6147`i' 6148 Use case-insensitive matching 6149 6150`x' 6151 REGEXP is an "extended regular expression" (*note Extended regular 6152 expressions: (sed)Extended regexps.). 6153 6154`NUMBER' 6155 Only replace the NUMBERth match of the REGEXP. 6156 6157 Note: the POSIX standard does not specify what should happen when 6158 you mix the `g' and NUMBER modifiers. GNU `tar' follows the GNU 6159 `sed' implementation in this regard, so the the interaction is 6160 defined to be: ignore matches before the NUMBERth, and then match 6161 and replace all matches from the NUMBERth on. 6162 6163 Any delimiter can be used in lieue of `/', the only requirement being 6164that it be used consistently throughout the expression. For example, the 6165following two expressions are equivalent: 6166 6167 s/one/two/ 6168 s,one,two, 6169 6170 Changing delimiters is often useful when the REGEX contains slashes. 6171For example, it is more convenient to write `s,/,-,' than `s/\//-/'. 6172 6173 Here are several examples of `--transform' usage: 6174 6175 1. Extract `usr/' hierarchy into `usr/local/': 6176 6177 $ `tar --transform='s,usr/,usr/local/,' -x -f arch.tar' 6178 6179 2. Strip two leading directory components (equivalent to 6180 `--strip-components=2'): 6181 6182 $ `tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar' 6183 6184 3. Prepend `/prefix/' to each file name: 6185 6186 $ `tar --transform 's,^,/prefix/,' -x -f arch.tar' 6187 6188 4. Convert each file name to lower case: 6189 6190 $ `tar --transform 's/.*/\L&/' -x -f arch.tar' 6191 6192 Unlike `--strip-components', `--transform' can be used in any GNU 6193`tar' operation mode. For example, the following command adds files to 6194the archive while replacing the leading `usr/' component with `var/': 6195 6196 $ `tar -cf arch.tar --transform='s,^usr/,var/,' /' 6197 6198 To test `--transform' effect we suggest using 6199`--show-transformed-names' option: 6200 6201 $ `tar -cf arch.tar --transform='s,^usr/,var/,' \ 6202 --verbose --show-transformed-names /' 6203 6204 If both `--strip-components' and `--transform' are used together, 6205then `--transform' is applied first, and the required number of 6206components is then stripped from its result. 6207 6208 6209File: tar.info, Node: after, Next: recurse, Prev: transform, Up: Choosing 6210 62116.8 Operating Only on New Files 6212=============================== 6213 6214 _(This message will disappear, once this node revised.)_ 6215 6216 The `--after-date=DATE' (`--newer=DATE', `-N DATE') option causes 6217`tar' to only work on files whose data modification or status change 6218times are newer than the DATE given. If DATE starts with `/' or `.', it 6219is taken to be a file name; the data modification time of that file is 6220used as the date. If you use this option when creating or appending to 6221an archive, the archive will only include new files. If you use 6222`--after-date' when extracting an archive, `tar' will only extract files 6223newer than the DATE you specify. 6224 6225 If you only want `tar' to make the date comparison based on 6226modification of the file's data (rather than status changes), then use 6227the `--newer-mtime=DATE' option. 6228 6229 You may use these options with any operation. Note that these 6230options differ from the `--update' (`-u') operation in that they allow 6231you to specify a particular date against which `tar' can compare when 6232deciding whether or not to archive the files. 6233 6234`--after-date=DATE' 6235`--newer=DATE' 6236`-N DATE' 6237 Only store files newer than DATE. 6238 6239 Acts on files only if their data modification or status change 6240 times are later than DATE. Use in conjunction with any operation. 6241 6242 If DATE starts with `/' or `.', it is taken to be a file name; the 6243 data modification time of that file is used as the date. 6244 6245`--newer-mtime=DATE' 6246 Acts like `--after-date', but only looks at data modification 6247 times. 6248 6249 These options limit `tar' to operate only on files which have been 6250modified after the date specified. A file's status is considered to 6251have changed if its contents have been modified, or if its owner, 6252permissions, and so forth, have been changed. (For more information on 6253how to specify a date, see *note Date input formats::; remember that the 6254entire date argument must be quoted if it contains any spaces.) 6255 6256 Gurus would say that `--after-date' tests both the data modification 6257time (`mtime', the time the contents of the file were last modified) and 6258the status change time (`ctime', the time the file's status was last 6259changed: owner, permissions, etc.) fields, while `--newer-mtime' tests 6260only the `mtime' field. 6261 6262 To be precise, `--after-date' checks _both_ `mtime' and `ctime' and 6263processes the file if either one is more recent than DATE, while 6264`--newer-mtime' only checks `mtime' and disregards `ctime'. Neither 6265does it use `atime' (the last time the contents of the file were looked 6266at). 6267 6268 Date specifiers can have embedded spaces. Because of this, you may 6269need to quote date arguments to keep the shell from parsing them as 6270separate arguments. For example, the following command will add to the 6271archive all the files modified less than two days ago: 6272 6273 $ `tar -cf foo.tar --newer-mtime '2 days ago'' 6274 6275 When any of these options is used with the option `--verbose' (*note 6276verbose tutorial::) GNU `tar' will try to convert the specified date 6277back to its textual representation and compare that with the one given 6278with the option. If the two dates differ, `tar' will print a warning 6279saying what date it will use. This is to help user ensure he is using 6280the right date. For example: 6281 6282 $ `tar -c -f archive.tar --after-date='10 days ago' .' 6283 tar: Option --after-date: Treating date `10 days ago' as 2006-06-11 6284 13:19:37.232434 6285 6286 *Please Note:* `--after-date' and `--newer-mtime' should not be 6287 used for incremental backups. *Note Incremental Dumps::, for 6288 proper way of creating incremental backups. 6289 6290 6291File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing 6292 62936.9 Descending into Directories 6294=============================== 6295 6296 _(This message will disappear, once this node revised.)_ 6297 6298 Usually, `tar' will recursively explore all directories (either those 6299given on the command line or through the `--files-from' option) for the 6300various files they contain. However, you may not always want `tar' to 6301act this way. 6302 6303 The `--no-recursion' option inhibits `tar''s recursive descent into 6304specified directories. If you specify `--no-recursion', you can use the 6305`find' utility for hunting through levels of directories to construct a 6306list of file names which you could then pass to `tar'. `find' allows 6307you to be more selective when choosing which files to archive; see *note 6308files::, for more information on using `find' with `tar', or look. 6309 6310`--no-recursion' 6311 Prevents `tar' from recursively descending directories. 6312 6313`--recursion' 6314 Requires `tar' to recursively descend directories. This is the 6315 default. 6316 6317 When you use `--no-recursion', GNU `tar' grabs directory entries 6318themselves, but does not descend on them recursively. Many people use 6319`find' for locating files they want to back up, and since `tar' 6320_usually_ recursively descends on directories, they have to use the 6321`-not -type d' test in their `find' invocation (*note Type: 6322(find)Type.), as they usually do not want all the files in a directory. 6323They then use the `--files-from' option to archive the files located via 6324`find'. 6325 6326 The problem when restoring files archived in this manner is that the 6327directories themselves are not in the archive; so the 6328`--same-permissions' (`--preserve-permissions', `-p') option does not 6329affect them--while users might really like it to. Specifying 6330`--no-recursion' is a way to tell `tar' to grab only the directory 6331entries given to it, adding no new files on its own. To summarize, if 6332you use `find' to create a list of files to be stored in an archive, use 6333it as follows: 6334 6335 $ `find DIR TESTS | \ 6336 tar -cf ARCHIVE -T - --no-recursion' 6337 6338 The `--no-recursion' option also applies when extracting: it causes 6339`tar' to extract only the matched directory entries, not the files under 6340those directories. 6341 6342 The `--no-recursion' option also affects how globbing patterns are 6343interpreted (*note controlling pattern-matching::). 6344 6345 The `--no-recursion' and `--recursion' options apply to later options 6346and operands, and can be overridden by later occurrences of 6347`--no-recursion' and `--recursion'. For example: 6348 6349 $ `tar -cf jams.tar --no-recursion grape --recursion grape/concord' 6350 6351creates an archive with one entry for `grape', and the recursive 6352contents of `grape/concord', but no entries under `grape' other than 6353`grape/concord'. 6354 6355 6356File: tar.info, Node: one, Prev: recurse, Up: Choosing 6357 63586.10 Crossing File System Boundaries 6359==================================== 6360 6361 _(This message will disappear, once this node revised.)_ 6362 6363 `tar' will normally automatically cross file system boundaries in 6364order to archive files which are part of a directory tree. You can 6365change this behavior by running `tar' and specifying 6366`--one-file-system'. This option only affects files that are archived 6367because they are in a directory that is being archived; `tar' will still 6368archive files explicitly named on the command line or through 6369`--files-from', regardless of where they reside. 6370 6371`--one-file-system' 6372 Prevents `tar' from crossing file system boundaries when archiving. 6373 Use in conjunction with any write operation. 6374 6375 The `--one-file-system' option causes `tar' to modify its normal 6376behavior in archiving the contents of directories. If a file in a 6377directory is not on the same file system as the directory itself, then 6378`tar' will not archive that file. If the file is a directory itself, 6379`tar' will not archive anything beneath it; in other words, `tar' will 6380not cross mount points. 6381 6382 This option is useful for making full or incremental archival backups 6383of a file system. If this option is used in conjunction with 6384`--verbose' (`-v'), files that are excluded are mentioned by name on the 6385standard error. 6386 6387* Menu: 6388 6389* directory:: Changing Directory 6390* absolute:: Absolute File Names 6391 6392 6393File: tar.info, Node: directory, Next: absolute, Up: one 6394 63956.10.1 Changing the Working Directory 6396------------------------------------- 6397 6398 _(This message will disappear, once this node revised.)_ 6399 6400 To change the working directory in the middle of a list of file 6401names, either on the command line or in a file specified using 6402`--files-from' (`-T'), use `--directory' (`-C'). This will change the 6403working directory to the specified directory after that point in the 6404list. 6405 6406`--directory=DIRECTORY' 6407`-C DIRECTORY' 6408 Changes the working directory in the middle of a command line. 6409 6410 For example, 6411 6412 $ `tar -c -f jams.tar grape prune -C food cherry' 6413 6414will place the files `grape' and `prune' from the current directory into 6415the archive `jams.tar', followed by the file `cherry' from the directory 6416`food'. This option is especially useful when you have several widely 6417separated files that you want to store in the same archive. 6418 6419 Note that the file `cherry' is recorded in the archive under the 6420precise name `cherry', _not_ `food/cherry'. Thus, the archive will 6421contain three files that all appear to have come from the same 6422directory; if the archive is extracted with plain `tar --extract', all 6423three files will be written in the current directory. 6424 6425 Contrast this with the command, 6426 6427 $ `tar -c -f jams.tar grape prune -C food red/cherry' 6428 6429which records the third file in the archive under the name `red/cherry' 6430so that, if the archive is extracted using `tar --extract', the third 6431file will be written in a subdirectory named `orange-colored'. 6432 6433 You can use the `--directory' option to make the archive independent 6434of the original name of the directory holding the files. The following 6435command places the files `/etc/passwd', `/etc/hosts', and `/lib/libc.a' 6436into the archive `foo.tar': 6437 6438 $ `tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a' 6439 6440However, the names of the archive members will be exactly what they were 6441on the command line: `passwd', `hosts', and `libc.a'. They will not 6442appear to be related by file name to the original directories where 6443those files were located. 6444 6445 Note that `--directory' options are interpreted consecutively. If 6446`--directory' specifies a relative file name, it is interpreted relative 6447to the then current directory, which might not be the same as the 6448original current working directory of `tar', due to a previous 6449`--directory' option. 6450 6451 When using `--files-from' (*note files::), you can put various `tar' 6452options (including `-C') in the file list. Notice, however, that in 6453this case the option and its argument may not be separated by 6454whitespace. If you use short option, its argument must either follow 6455the option letter immediately, without any intervening whitespace, or 6456occupy the next line. Otherwise, if you use long option, separate its 6457argument by an equal sign. 6458 6459 For instance, the file list for the above example will be: 6460 6461 -C 6462 /etc 6463 passwd 6464 hosts 6465 -C 6466 /lib 6467 libc.a 6468 6469To use it, you would invoke `tar' as follows: 6470 6471 $ `tar -c -f foo.tar --files-from list' 6472 6473 Notice also that you can only use the short option variant in the 6474file list, i.e., always use `-C', not `--directory'. 6475 6476 The interpretation of `--directory' is disabled by `--null' option. 6477 6478 6479File: tar.info, Node: absolute, Prev: directory, Up: one 6480 64816.10.2 Absolute File Names 6482-------------------------- 6483 6484 _(This message will disappear, once this node revised.)_ 6485 6486`--absolute-names' 6487`-P' 6488 Do not strip leading slashes from file names, and permit file names 6489 containing a `..' file name component. 6490 6491 By default, GNU `tar' drops a leading `/' on input or output, and 6492complains about file names containing a `..' component. This option 6493turns off this behavior. 6494 6495 When `tar' extracts archive members from an archive, it strips any 6496leading slashes (`/') from the member name. This causes absolute member 6497names in the archive to be treated as relative file names. This allows 6498you to have such members extracted wherever you want, instead of being 6499restricted to extracting the member in the exact directory named in the 6500archive. For example, if the archive member has the name `/etc/passwd', 6501`tar' will extract it as if the name were really `etc/passwd'. 6502 6503 File names containing `..' can cause problems when extracting, so 6504`tar' normally warns you about such files when creating an archive, and 6505rejects attempts to extracts such files. 6506 6507 Other `tar' programs do not do this. As a result, if you create an 6508archive whose member names start with a slash, they will be difficult 6509for other people with a non-GNU `tar' program to use. Therefore, GNU 6510`tar' also strips leading slashes from member names when putting members 6511into the archive. For example, if you ask `tar' to add the file 6512`/bin/ls' to an archive, it will do so, but the member name will be 6513`bin/ls'.(1) 6514 6515 If you use the `--absolute-names' (`-P') option, `tar' will do none 6516of these transformations. 6517 6518 To archive or extract files relative to the root directory, specify 6519the `--absolute-names' (`-P') option. 6520 6521 Normally, `tar' acts on files relative to the working 6522directory--ignoring superior directory names when archiving, and 6523ignoring leading slashes when extracting. 6524 6525 When you specify `--absolute-names' (`-P'), `tar' stores file names 6526including all superior directory names, and preserves leading slashes. 6527If you only invoked `tar' from the root directory you would never need 6528the `--absolute-names' option, but using this option may be more 6529convenient than switching to root. 6530 6531`--absolute-names' 6532 Preserves full file names (including superior directory names) when 6533 archiving files. Preserves leading slash when extracting files. 6534 6535 `tar' prints out a message about removing the `/' from file names. 6536This message appears once per GNU `tar' invocation. It represents 6537something which ought to be told; ignoring what it means can cause very 6538serious surprises, later. 6539 6540 Some people, nevertheless, do not want to see this message. Wanting 6541to play really dangerously, one may of course redirect `tar' standard 6542error to the sink. For example, under `sh': 6543 6544 $ `tar -c -f archive.tar /home 2> /dev/null' 6545 6546Another solution, both nicer and simpler, would be to change to the `/' 6547directory first, and then avoid absolute notation. For example: 6548 6549 $ `(cd / && tar -c -f archive.tar home)' 6550 # or: 6551 $ `tar -c -f archive.tar -C / home' 6552 6553 ---------- Footnotes ---------- 6554 6555 (1) A side effect of this is that when `--create' is used with 6556`--verbose' the resulting output is not, generally speaking, the same as 6557the one you'd get running `tar --list' command. This may be important 6558if you use some scripts for comparing both outputs. *Note listing 6559member and file names::, for the information on how to handle this case. 6560 6561 6562File: tar.info, Node: Date input formats, Next: Formats, Prev: Choosing, Up: Top 6563 65647 Date input formats 6565******************** 6566 6567First, a quote: 6568 6569 Our units of temporal measurement, from seconds on up to months, 6570 are so complicated, asymmetrical and disjunctive so as to make 6571 coherent mental reckoning in time all but impossible. Indeed, had 6572 some tyrannical god contrived to enslave our minds to time, to make 6573 it all but impossible for us to escape subjection to sodden 6574 routines and unpleasant surprises, he could hardly have done better 6575 than handing down our present system. It is like a set of 6576 trapezoidal building blocks, with no vertical or horizontal 6577 surfaces, like a language in which the simplest thought demands 6578 ornate constructions, useless particles and lengthy 6579 circumlocutions. Unlike the more successful patterns of language 6580 and science, which enable us to face experience boldly or at least 6581 level-headedly, our system of temporal calculation silently and 6582 persistently encourages our terror of time. 6583 6584 ... It is as though architects had to measure length in feet, 6585 width in meters and height in ells; as though basic instruction 6586 manuals demanded a knowledge of five different languages. It is no 6587 wonder then that we often look into our own immediate past or 6588 future, last Tuesday or a week from Sunday, with feelings of 6589 helpless confusion. ... 6590 6591 -- Robert Grudin, `Time and the Art of Living'. 6592 6593 This section describes the textual date representations that GNU 6594programs accept. These are the strings you, as a user, can supply as 6595arguments to the various programs. The C interface (via the `get_date' 6596function) is not described here. 6597 6598* Menu: 6599 6600* General date syntax:: Common rules. 6601* Calendar date items:: 19 Dec 1994. 6602* Time of day items:: 9:20pm. 6603* Time zone items:: EST, PDT, GMT. 6604* Day of week items:: Monday and others. 6605* Relative items in date strings:: next tuesday, 2 years ago. 6606* Pure numbers in date strings:: 19931219, 1440. 6607* Seconds since the Epoch:: @1078100502. 6608* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". 6609* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al. 6610 6611 6612File: tar.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats 6613 66147.1 General date syntax 6615======================= 6616 6617A "date" is a string, possibly empty, containing many items separated by 6618whitespace. The whitespace may be omitted when no ambiguity arises. 6619The empty string means the beginning of today (i.e., midnight). Order 6620of the items is immaterial. A date string may contain many flavors of 6621items: 6622 6623 * calendar date items 6624 6625 * time of day items 6626 6627 * time zone items 6628 6629 * day of the week items 6630 6631 * relative items 6632 6633 * pure numbers. 6634 6635We describe each of these item types in turn, below. 6636 6637 A few ordinal numbers may be written out in words in some contexts. 6638This is most useful for specifying day of the week items or relative 6639items (see below). Among the most commonly used ordinal numbers, the 6640word `last' stands for -1, `this' stands for 0, and `first' and `next' 6641both stand for 1. Because the word `second' stands for the unit of time 6642there is no way to write the ordinal number 2, but for convenience 6643`third' stands for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6, 6644`seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10, 6645`eleventh' for 11 and `twelfth' for 12. 6646 6647 When a month is written this way, it is still considered to be 6648written numerically, instead of being "spelled in full"; this changes 6649the allowed strings. 6650 6651 In the current implementation, only English is supported for words 6652and abbreviations like `AM', `DST', `EST', `first', `January', `Sunday', 6653`tomorrow', and `year'. 6654 6655 The output of the `date' command is not always acceptable as a date 6656string, not only because of the language problem, but also because there 6657is no standard meaning for time zone items like `IST'. When using 6658`date' to generate a date string intended to be parsed later, specify a 6659date format that is independent of language and that does not use time 6660zone items other than `UTC' and `Z'. Here are some ways to do this: 6661 6662 $ LC_ALL=C TZ=UTC0 date 6663 Mon Mar 1 00:21:42 UTC 2004 6664 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' 6665 2004-03-01 00:21:42Z 6666 $ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. 6667 2004-02-29 16:21:42,692722128-0800 6668 $ date --rfc-2822 # a GNU extension 6669 Sun, 29 Feb 2004 16:21:42 -0800 6670 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. 6671 2004-02-29 16:21:42 -0800 6672 $ date +'@%s.%N' # %s and %N are GNU extensions. 6673 @1078100502.692722128 6674 6675 Alphabetic case is completely ignored in dates. Comments may be 6676introduced between round parentheses, as long as included parentheses 6677are properly nested. Hyphens not followed by a digit are currently 6678ignored. Leading zeros on numbers are ignored. 6679 6680 Invalid dates like `2005-02-29' or times like `24:00' are rejected. 6681In the typical case of a host that does not support leap seconds, a time 6682like `23:59:60' is rejected even if it corresponds to a valid leap 6683second. 6684 6685 6686File: tar.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats 6687 66887.2 Calendar date items 6689======================= 6690 6691A "calendar date item" specifies a day of the year. It is specified 6692differently, depending on whether the month is specified numerically or 6693literally. All these strings specify the same calendar date: 6694 6695 1972-09-24 # ISO 8601. 6696 72-9-24 # Assume 19xx for 69 through 99, 6697 # 20xx for 00 through 68. 6698 72-09-24 # Leading zeros are ignored. 6699 9/24/72 # Common U.S. writing. 6700 24 September 1972 6701 24 Sept 72 # September has a special abbreviation. 6702 24 Sep 72 # Three-letter abbreviations always allowed. 6703 Sep 24, 1972 6704 24-sep-72 6705 24sep72 6706 6707 The year can also be omitted. In this case, the last specified year 6708is used, or the current year if none. For example: 6709 6710 9/24 6711 sep 24 6712 6713 Here are the rules. 6714 6715 For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed, 6716where YEAR is any positive number, MONTH is a number between 01 and 12, 6717and DAY is a number between 01 and 31. A leading zero must be present 6718if a number is less than ten. If YEAR is 68 or smaller, then 2000 is 6719added to it; otherwise, if YEAR is less than 100, then 1900 is added to 6720it. The construct `MONTH/DAY/YEAR', popular in the United States, is 6721accepted. Also `MONTH/DAY', omitting the year. 6722 6723 Literal months may be spelled out in full: `January', `February', 6724`March', `April', `May', `June', `July', `August', `September', 6725`October', `November' or `December'. Literal months may be abbreviated 6726to their first three letters, possibly followed by an abbreviating dot. 6727It is also permitted to write `Sept' instead of `September'. 6728 6729 When months are written literally, the calendar date may be given as 6730any of the following: 6731 6732 DAY MONTH YEAR 6733 DAY MONTH 6734 MONTH DAY YEAR 6735 DAY-MONTH-YEAR 6736 6737 Or, omitting the year: 6738 6739 MONTH DAY 6740 6741 6742File: tar.info, Node: Time of day items, Next: Time zone items, Prev: Calendar date items, Up: Date input formats 6743 67447.3 Time of day items 6745===================== 6746 6747A "time of day item" in date strings specifies the time on a given day. 6748Here are some examples, all of which represent the same time: 6749 6750 20:02:00.000000 6751 20:02 6752 8:02pm 6753 20:02-0500 # In EST (U.S. Eastern Standard Time). 6754 6755 More generally, the time of day may be given as `HOUR:MINUTE:SECOND', 6756where HOUR is a number between 0 and 23, MINUTE is a number between 0 6757and 59, and SECOND is a number between 0 and 59 possibly followed by `.' 6758or `,' and a fraction containing one or more digits. Alternatively, 6759`:SECOND' can be omitted, in which case it is taken to be zero. On the 6760rare hosts that support leap seconds, SECOND may be 60. 6761 6762 If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR 6763is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken 6764to be zero). `am' indicates the first half of the day, `pm' indicates 6765the second half of the day. In this notation, 12 is the predecessor of 67661: midnight is `12am' while noon is `12pm'. (This is the zero-oriented 6767interpretation of `12am' and `12pm', as opposed to the old tradition 6768derived from Latin which uses `12m' for noon and `12pm' for midnight.) 6769 6770 The time may alternatively be followed by a time zone correction, 6771expressed as `SHHMM', where S is `+' or `-', HH is a number of zone 6772hours and MM is a number of zone minutes. You can also separate HH from 6773MM with a colon. When a time zone correction is given this way, it 6774forces interpretation of the time relative to Coordinated Universal Time 6775(UTC), overriding any previous specification for the time zone or the 6776local time zone. For example, `+0530' and `+05:30' both stand for the 6777time zone 5.5 hours ahead of UTC (e.g., India). The MINUTE part of the 6778time of day may not be elided when a time zone correction is used. This 6779is the best way to specify a time zone correction by fractional parts of 6780an hour. 6781 6782 Either `am'/`pm' or a time zone correction may be specified, but not 6783both. 6784 6785 6786File: tar.info, Node: Time zone items, Next: Day of week items, Prev: Time of day items, Up: Date input formats 6787 67887.4 Time zone items 6789=================== 6790 6791A "time zone item" specifies an international time zone, indicated by a 6792small set of letters, e.g., `UTC' or `Z' for Coordinated Universal Time. 6793Any included periods are ignored. By following a non-daylight-saving 6794time zone by the string `DST' in a separate word (that is, separated by 6795some white space), the corresponding daylight saving time zone may be 6796specified. Alternatively, a non-daylight-saving time zone can be 6797followed by a time zone correction, to add the two values. This is 6798normally done only for `UTC'; for example, `UTC+05:30' is equivalent to 6799`+05:30'. 6800 6801 Time zone items other than `UTC' and `Z' are obsolescent and are not 6802recommended, because they are ambiguous; for example, `EST' has a 6803different meaning in Australia than in the United States. Instead, it's 6804better to use unambiguous numeric time zone corrections like `-0500', as 6805described in the previous section. 6806 6807 If neither a time zone item nor a time zone correction is supplied, 6808time stamps are interpreted using the rules of the default time zone 6809(*note Specifying time zone rules::). 6810 6811 6812File: tar.info, Node: Day of week items, Next: Relative items in date strings, Prev: Time zone items, Up: Date input formats 6813 68147.5 Day of week items 6815===================== 6816 6817The explicit mention of a day of the week will forward the date (only if 6818necessary) to reach that day of the week in the future. 6819 6820 Days of the week may be spelled out in full: `Sunday', `Monday', 6821`Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may be 6822abbreviated to their first three letters, optionally followed by a 6823period. The special abbreviations `Tues' for `Tuesday', `Wednes' for 6824`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed. 6825 6826 A number may precede a day of the week item to move forward 6827supplementary weeks. It is best used in expression like `third monday'. 6828In this context, `last DAY' or `next DAY' is also acceptable; they move 6829one week before or after the day that DAY by itself would represent. 6830 6831 A comma following a day of the week item is ignored. 6832 6833 6834File: tar.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats 6835 68367.6 Relative items in date strings 6837================================== 6838 6839"Relative items" adjust a date (or the current date if none) forward or 6840backward. The effects of relative items accumulate. Here are some 6841examples: 6842 6843 1 year 6844 1 year ago 6845 3 years 6846 2 days 6847 6848 The unit of time displacement may be selected by the string `year' or 6849`month' for moving by whole years or months. These are fuzzy units, as 6850years and months are not all of equal duration. More precise units are 6851`fortnight' which is worth 14 days, `week' worth 7 days, `day' worth 24 6852hours, `hour' worth 60 minutes, `minute' or `min' worth 60 seconds, and 6853`second' or `sec' worth one second. An `s' suffix on these units is 6854accepted and ignored. 6855 6856 The unit of time may be preceded by a multiplier, given as an 6857optionally signed number. Unsigned numbers are taken as positively 6858signed. No number at all implies 1 for a multiplier. Following a 6859relative item by the string `ago' is equivalent to preceding the unit by 6860a multiplier with value -1. 6861 6862 The string `tomorrow' is worth one day in the future (equivalent to 6863`day'), the string `yesterday' is worth one day in the past (equivalent 6864to `day ago'). 6865 6866 The strings `now' or `today' are relative items corresponding to 6867zero-valued time displacement, these strings come from the fact a 6868zero-valued time displacement represents the current time when not 6869otherwise changed by previous items. They may be used to stress other 6870items, like in `12:00 today'. The string `this' also has the meaning of 6871a zero-valued time displacement, but is preferred in date strings like 6872`this thursday'. 6873 6874 When a relative item causes the resulting date to cross a boundary 6875where the clocks were adjusted, typically for daylight saving time, the 6876resulting date and time are adjusted accordingly. 6877 6878 The fuzz in units can cause problems with relative items. For 6879example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because 68802003-06-31 is an invalid date. To determine the previous month more 6881reliably, you can ask for the month before the 15th of the current 6882month. For example: 6883 6884 $ date -R 6885 Thu, 31 Jul 2003 13:02:39 -0700 6886 $ date --date='-1 month' +'Last month was %B?' 6887 Last month was July? 6888 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' 6889 Last month was June! 6890 6891 Also, take care when manipulating dates around clock changes such as 6892daylight saving leaps. In a few cases these have added or subtracted as 6893much as 24 hours from the clock, so it is often wise to adopt universal 6894time by setting the `TZ' environment variable to `UTC0' before embarking 6895on calendrical calculations. 6896 6897 6898File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats 6899 69007.7 Pure numbers in date strings 6901================================ 6902 6903The precise interpretation of a pure decimal number depends on the 6904context in the date string. 6905 6906 If the decimal number is of the form YYYYMMDD and no other calendar 6907date item (*note Calendar date items::) appears before it in the date 6908string, then YYYY is read as the year, MM as the month number and DD as 6909the day of the month, for the specified calendar date. 6910 6911 If the decimal number is of the form HHMM and no other time of day 6912item appears before it in the date string, then HH is read as the hour 6913of the day and MM as the minute of the hour, for the specified time of 6914day. MM can also be omitted. 6915 6916 If both a calendar date and a time of day appear to the left of a 6917number in the date string, but no relative item, then the number 6918overrides the year. 6919 6920 6921File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats 6922 69237.8 Seconds since the Epoch 6924=========================== 6925 6926If you precede a number with `@', it represents an internal time stamp 6927as a count of seconds. The number can contain an internal decimal point 6928(either `.' or `,'); any excess precision not supported by the internal 6929representation is truncated toward minus infinity. Such a number cannot 6930be combined with any other date item, as it specifies a complete time 6931stamp. 6932 6933 Internally, computer times are represented as a count of seconds 6934since an epoch--a well-defined point of time. On GNU and POSIX systems, 6935the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this time, `@1' 6936represents 1970-01-01 00:00:01 UTC, and so forth. GNU and most other 6937POSIX-compliant systems support such times as an extension to POSIX, 6938using negative counts, so that `@-1' represents 1969-12-31 23:59:59 UTC. 6939 6940 Traditional Unix systems count seconds with 32-bit two's-complement 6941integers and can represent times from 1901-12-13 20:45:52 through 69422038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of 6943seconds with nanosecond subcounts, and can represent all the times in 6944the known lifetime of the universe to a resolution of 1 nanosecond. 6945 6946 On most hosts, these counts ignore the presence of leap seconds. For 6947example, on most hosts `@915148799' represents 1998-12-31 23:59:59 UTC, 6948`@915148800' represents 1999-01-01 00:00:00 UTC, and there is no way to 6949represent the intervening leap second 1998-12-31 23:59:60 UTC. 6950 6951 6952File: tar.info, Node: Specifying time zone rules, Next: Authors of get_date, Prev: Seconds since the Epoch, Up: Date input formats 6953 69547.9 Specifying time zone rules 6955============================== 6956 6957Normally, dates are interpreted using the rules of the current time 6958zone, which in turn are specified by the `TZ' environment variable, or 6959by a system default if `TZ' is not set. To specify a different set of 6960default time zone rules that apply just to one date, start the date with 6961a string of the form `TZ="RULE"'. The two quote characters (`"') must 6962be present in the date, and any quotes or backslashes within RULE must 6963be escaped by a backslash. 6964 6965 For example, with the GNU `date' command you can answer the question 6966"What time is it in New York when a Paris clock shows 6:30am on October 696731, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown 6968in the following shell transcript: 6969 6970 $ export TZ="America/New_York" 6971 $ date --date='TZ="Europe/Paris" 2004-10-31 06:30' 6972 Sun Oct 31 01:30:00 EDT 2004 6973 6974 In this example, the `--date' operand begins with its own `TZ' 6975setting, so the rest of that operand is processed according to 6976`Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it 6977were in Paris. However, since the output of the `date' command is 6978processed according to the overall time zone rules, it uses New York 6979time. (Paris was normally six hours ahead of New York in 2004, but this 6980example refers to a brief Halloween period when the gap was five hours.) 6981 6982 A `TZ' value is a rule that typically names a location in the `tz' 6983database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of 6984location names appears in the TWiki Date and Time Gateway 6985(http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a 6986colon before a location name in a `TZ' setting, e.g., 6987`TZ=":America/New_York"'. 6988 6989 The `tz' database includes a wide variety of locations ranging from 6990`Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea 6991and have your own private time zone, or if you are using a non-GNU host 6992that does not support the `tz' database, you may need to use a POSIX 6993rule instead. Simple POSIX rules like `UTC0' specify a time zone 6994without daylight saving time; other rules can specify simple daylight 6995saving regimes. *Note Specifying the Time Zone with `TZ': (libc)TZ 6996Variable. 6997 6998 6999File: tar.info, Node: Authors of get_date, Prev: Specifying time zone rules, Up: Date input formats 7000 70017.10 Authors of `get_date' 7002========================== 7003 7004`get_date' was originally implemented by Steven M. Bellovin 7005(<smb@research.att.com>) while at the University of North Carolina at 7006Chapel Hill. The code was later tweaked by a couple of people on 7007Usenet, then completely overhauled by Rich $alz (<rsalz@bbn.com>) and 7008Jim Berets (<jberets@bbn.com>) in August, 1990. Various revisions for 7009the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert 7010and others. 7011 7012 This chapter was originally produced by Franc,ois Pinard 7013(<pinard@iro.umontreal.ca>) from the `getdate.y' source code, and then 7014edited by K. Berry (<kb@cs.umb.edu>). 7015 7016 7017File: tar.info, Node: Formats, Next: Media, Prev: Date input formats, Up: Top 7018 70198 Controlling the Archive Format 7020******************************** 7021 7022Due to historical reasons, there are several formats of tar archives. 7023All of them are based on the same principles, but have some subtle 7024differences that often make them incompatible with each other. 7025 7026 GNU tar is able to create and handle archives in a variety of 7027formats. The most frequently used formats are (in alphabetical order): 7028 7029gnu 7030 Format used by GNU `tar' versions up to 1.13.25. This format 7031 derived from an early POSIX standard, adding some improvements such 7032 as sparse file handling and incremental archives. Unfortunately 7033 these features were implemented in a way incompatible with other 7034 archive formats. 7035 7036 Archives in `gnu' format are able to hold pathnames of unlimited 7037 length. 7038 7039oldgnu 7040 Format used by GNU `tar' of versions prior to 1.12. 7041 7042v7 7043 Archive format, compatible with the V7 implementation of tar. This 7044 format imposes a number of limitations. The most important of them 7045 are: 7046 7047 1. The maximum length of a file name is limited to 99 characters. 7048 7049 2. The maximum length of a symbolic link is limited to 99 7050 characters. 7051 7052 3. It is impossible to store special files (block and character 7053 devices, fifos etc.) 7054 7055 4. Maximum value of user or group ID is limited to 2097151 7056 (7777777 octal) 7057 7058 5. V7 archives do not contain symbolic ownership information 7059 (user and group name of the file owner). 7060 7061 This format has traditionally been used by Automake when producing 7062 Makefiles. This practice will change in the future, in the 7063 meantime, however this means that projects containing filenames 7064 more than 99 characters long will not be able to use GNU `tar' 7065 1.15.92 and Automake prior to 1.9. 7066 7067ustar 7068 Archive format defined by POSIX.1-1988 specification. It stores 7069 symbolic ownership information. It is also able to store special 7070 files. However, it imposes several restrictions as well: 7071 7072 1. The maximum length of a file name is limited to 256 7073 characters, provided that the filename can be split at 7074 directory separator in two parts, first of them being at most 7075 155 bytes long. So, in most cases the maximum file name 7076 length will be shorter than 256 characters. 7077 7078 2. The maximum length of a symbolic link name is limited to 100 7079 characters. 7080 7081 3. Maximum size of a file the archive is able to accomodate is 7082 8GB 7083 7084 4. Maximum value of UID/GID is 2097151. 7085 7086 5. Maximum number of bits in device major and minor numbers is 7087 21. 7088 7089star 7090 Format used by Jo"rg Schilling `star' implementation. GNU `tar' is 7091 able to read `star' archives but currently does not produce them. 7092 7093posix 7094 Archive format defined by POSIX.1-2001 specification. This is the 7095 most flexible and feature-rich format. It does not impose any 7096 restrictions on file sizes or filename lengths. This format is 7097 quite recent, so not all tar implementations are able to handle it 7098 properly. However, this format is designed in such a way that any 7099 tar implementation able to read `ustar' archives will be able to 7100 read most `posix' archives as well, with the only exception that 7101 any additional information (such as long file names etc.) will in 7102 such case be extracted as plain text files along with the files it 7103 refers to. 7104 7105 This archive format will be the default format for future versions 7106 of GNU `tar'. 7107 7108 The following table summarizes the limitations of each of these 7109formats: 7110 7111Format UID File Size Path Name Devn 7112-------------------------------------------------------------------- 7113gnu 1.8e19 Unlimited Unlimited 63 7114oldgnu 1.8e19 Unlimited Unlimited 63 7115v7 2097151 8GB 99 n/a 7116ustar 2097151 8GB 256 21 7117posix Unlimited Unlimited Unlimited Unlimited 7118 7119 The default format for GNU `tar' is defined at compilation time. You 7120may check it by running `tar --help', and examining the last lines of 7121its output. Usually, GNU `tar' is configured to create archives in 7122`gnu' format, however, future version will switch to `posix'. 7123 7124* Menu: 7125 7126* Compression:: Using Less Space through Compression 7127* Attributes:: Handling File Attributes 7128* Portability:: Making `tar' Archives More Portable 7129* cpio:: Comparison of `tar' and `cpio' 7130 7131 7132File: tar.info, Node: Compression, Next: Attributes, Up: Formats 7133 71348.1 Using Less Space through Compression 7135======================================== 7136 7137* Menu: 7138 7139* gzip:: Creating and Reading Compressed Archives 7140* sparse:: Archiving Sparse Files 7141 7142 7143File: tar.info, Node: gzip, Next: sparse, Up: Compression 7144 71458.1.1 Creating and Reading Compressed Archives 7146---------------------------------------------- 7147 7148GNU `tar' is able to create and read compressed archives. It supports 7149`gzip' and `bzip2' compression programs. For backward compatibilty, it 7150also supports `compress' command, although we strongly recommend against 7151using it, since there is a patent covering the algorithm it uses and you 7152could be sued for patent infringement merely by running `compress'! 7153Besides, it is less effective than `gzip' and `bzip2'. 7154 7155 Creating a compressed archive is simple: you just specify a 7156"compression option" along with the usual archive creation commands. 7157The compression option is `-z' (`--gzip') to create a `gzip' compressed 7158archive, `-j' (`--bzip2') to create a `bzip2' compressed archive, and 7159`-Z' (`--compress') to use `compress' program. For example: 7160 7161 $ `tar cfz archive.tar.gz .' 7162 7163 Reading compressed archive is even simpler: you don't need to specify 7164any additional options as GNU `tar' recognizes its format automatically. 7165Thus, the following commands will list and extract the archive created 7166in previous example: 7167 7168 # List the compressed archive 7169 $ `tar tf archive.tar.gz' 7170 # Extract the compressed archive 7171 $ `tar xf archive.tar.gz' 7172 7173 The only case when you have to specify a decompression option while 7174reading the archive is when reading from a pipe or from a tape drive 7175that does not support random access. However, in this case GNU `tar' 7176will indicate which option you should use. For example: 7177 7178 $ `cat archive.tar.gz | tar tf -' 7179 tar: Archive is compressed. Use -z option 7180 tar: Error is not recoverable: exiting now 7181 7182 If you see such diagnostics, just add the suggested option to the 7183invocation of GNU `tar': 7184 7185 $ `cat archive.tar.gz | tar tfz -' 7186 7187 Notice also, that there are several restrictions on operations on 7188compressed archives. First of all, compressed archives cannot be 7189modified, i.e., you cannot update (`--update' (`-u')) them or delete 7190(`--delete') members from them. Likewise, you cannot append another 7191`tar' archive to a compressed archive using `--append' (`-r')). 7192Secondly, multi-volume archives cannot be compressed. 7193 7194 The following table summarizes compression options used by GNU `tar'. 7195 7196`-z' 7197`--gzip' 7198`--ungzip' 7199 Filter the archive through `gzip'. 7200 7201 You can use `--gzip' and `--gunzip' on physical devices (tape 7202 drives, etc.) and remote files as well as on normal files; data to 7203 or from such devices or remote files is reblocked by another copy 7204 of the `tar' program to enforce the specified (or default) record 7205 size. The default compression parameters are used; if you need to 7206 override them, set `GZIP' environment variable, e.g.: 7207 7208 $ `GZIP=--best tar cfz archive.tar.gz subdir' 7209 7210 Another way would be to avoid the `--gzip' (`--gunzip', `--ungzip', 7211 `-z') option and run `gzip' explicitly: 7212 7213 $ `tar cf - subdir | gzip --best -c - > archive.tar.gz' 7214 7215 About corrupted compressed archives: `gzip''ed files have no 7216 redundancy, for maximum compression. The adaptive nature of the 7217 compression scheme means that the compression tables are implicitly 7218 spread all over the archive. If you lose a few blocks, the dynamic 7219 construction of the compression tables becomes unsynchronized, and 7220 there is little chance that you could recover later in the archive. 7221 7222 There are pending suggestions for having a per-volume or per-file 7223 compression in GNU `tar'. This would allow for viewing the 7224 contents without decompression, and for resynchronizing 7225 decompression at every volume or file, in case of corrupted 7226 archives. Doing so, we might lose some compressibility. But this 7227 would have make recovering easier. So, there are pros and cons. 7228 We'll see! 7229 7230`-j' 7231`--bzip2' 7232 Filter the archive through `bzip2'. Otherwise like `--gzip'. 7233 7234`-Z' 7235`--compress' 7236`--uncompress' 7237 Filter the archive through `compress'. Otherwise like `--gzip'. 7238 7239 The GNU Project recommends you not use `compress', because there is 7240 a patent covering the algorithm it uses. You could be sued for 7241 patent infringement merely by running `compress'. 7242 7243`--use-compress-program=PROG' 7244 Use external compression program PROG. Use this option if you have 7245 a compression program that GNU `tar' does not support. There are 7246 two requirements to which PROG should comply: 7247 7248 First, when called without options, it should read data from 7249 standard input, compress it and output it on standard output. 7250 7251 Secondly, if called with `-d' argument, it should do exactly the 7252 opposite, i.e., read the compressed data from the standard input 7253 and produce uncompressed data on the standard output. 7254 7255 The `--use-compress-program' option, in particular, lets you 7256implement your own filters, not necessarily dealing with 7257compression/decomression. For example, suppose you wish to implement 7258PGP encryption on top of compression, using `gpg' (*note gpg: 7259(gpg)Top.). The following script does that: 7260 7261 #! /bin/sh 7262 case $1 in 7263 -d) gpg --decrypt - | gzip -d -c;; 7264 '') gzip -c | gpg -s ;; 7265 *) echo "Unknown option $1">&2; exit 1;; 7266 esac 7267 7268 Suppose you name it `gpgz' and save it somewhere in your `PATH'. 7269Then the following command will create a commpressed archive signed with 7270your private key: 7271 7272 $ `tar -cf foo.tar.gpgz --use-compress=gpgz .' 7273 7274Likewise, the following command will list its contents: 7275 7276 $ `tar -tf foo.tar.gpgz --use-compress=gpgz .' 7277 7278 7279File: tar.info, Node: sparse, Prev: gzip, Up: Compression 7280 72818.1.2 Archiving Sparse Files 7282---------------------------- 7283 7284Files in the file system occasionally have "holes". A "hole" in a file 7285is a section of the file's contents which was never written. The 7286contents of a hole reads as all zeros. On many operating systems, 7287actual disk storage is not allocated for holes, but they are counted in 7288the length of the file. If you archive such a file, `tar' could create 7289an archive longer than the original. To have `tar' attempt to recognize 7290the holes in a file, use `--sparse' (`-S'). When you use this option, 7291then, for any file using less disk space than would be expected from its 7292length, `tar' searches the file for consecutive stretches of zeros. It 7293then records in the archive for the file where the consecutive stretches 7294of zeros are, and only archives the "real contents" of the file. On 7295extraction (using `--sparse' is not needed on extraction) any such files 7296have holes created wherever the continuous stretches of zeros were 7297found. Thus, if you use `--sparse', `tar' archives won't take more 7298space than the original. 7299 7300`-S' 7301`--sparse' 7302 This option istructs `tar' to test each file for sparseness before 7303 attempting to archive it. If the file is found to be sparse it is 7304 treated specially, thus allowing to decrease the amount of space 7305 used by its image in the archive. 7306 7307 This option is meaningful only when creating or updating archives. 7308 It has no effect on extraction. 7309 7310 Consider using `--sparse' when performing file system backups, to 7311avoid archiving the expanded forms of files stored sparsely in the 7312system. 7313 7314 Even if your system has no sparse files currently, some may be 7315created in the future. If you use `--sparse' while making file system 7316backups as a matter of course, you can be assured the archive will never 7317take more space on the media than the files take on disk (otherwise, 7318archiving a disk filled with sparse files might take hundreds of tapes). 7319*Note Incremental Dumps::. 7320 7321 However, be aware that `--sparse' option presents a serious drawback. 7322Namely, in order to determine if the file is sparse `tar' has to read it 7323before trying to archive it, so in total the file is read *twice*. So, 7324always bear in mind that the time needed to process all files with this 7325option is roughly twice the time needed to archive them without it. 7326 7327 When using `POSIX' archive format, GNU `tar' is able to store sparse 7328files using in three distinct ways, called "sparse formats". A sparse 7329format is identified by its "number", consisting, as usual of two 7330decimal numbers, delimited by a dot. By default, format `1.0' is used. 7331If, for some reason, you wish to use an earlier format, you can select 7332it using `--sparse-version' option. 7333 7334`--sparse-version=VERSION' 7335 Select the format to store sparse files in. Valid VERSION values 7336 are: `0.0', `0.1' and `1.0'. *Note Sparse Formats::, for a 7337 detailed description of each format. 7338 7339 Using `--sparse-format' option implies `--sparse'. 7340 7341 7342File: tar.info, Node: Attributes, Next: Portability, Prev: Compression, Up: Formats 7343 73448.2 Handling File Attributes 7345============================ 7346 7347 _(This message will disappear, once this node revised.)_ 7348 7349 When `tar' reads files, it updates their access times. To avoid 7350this, use the `--atime-preserve[=METHOD]' option, which can either reset 7351the access time retroactively or avoid changing it in the first place. 7352 7353 Handling of file attributes 7354 7355`--atime-preserve' 7356`--atime-preserve=replace' 7357`--atime-preserve=system' 7358 Preserve the access times of files that are read. This works only 7359 for files that you own, unless you have superuser privileges. 7360 7361 `--atime-preserve=replace' works on most systems, but it also 7362 restores the data modification time and updates the status change 7363 time. Hence it doesn't interact with incremental dumps nicely 7364 (*note Incremental Dumps::), and it can set access or data 7365 modification times incorrectly if other programs access the file 7366 while `tar' is running. 7367 7368 `--atime-preserve=system' avoids changing the access time in the 7369 first place, if the operating system supports this. Unfortunately, 7370 this may or may not work on any given operating system or file 7371 system. If `tar' knows for sure it won't work, it complains right 7372 away. 7373 7374 Currently `--atime-preserve' with no operand defaults to 7375 `--atime-preserve=replace', but this is intended to change to 7376 `--atime-preserve=system' when the latter is better-supported. 7377 7378`-m' 7379`--touch' 7380 Do not extract data modification time. 7381 7382 When this option is used, `tar' leaves the data modification times 7383 of the files it extracts as the times when the files were 7384 extracted, instead of setting it to the times recorded in the 7385 archive. 7386 7387 This option is meaningless with `--list' (`-t'). 7388 7389`--same-owner' 7390 Create extracted files with the same ownership they have in the 7391 archive. 7392 7393 This is the default behavior for the superuser, so this option is 7394 meaningful only for non-root users, when `tar' is executed on those 7395 systems able to give files away. This is considered as a security 7396 flaw by many people, at least because it makes quite difficult to 7397 correctly account users for the disk space they occupy. Also, the 7398 `suid' or `sgid' attributes of files are easily and silently lost 7399 when files are given away. 7400 7401 When writing an archive, `tar' writes the user id and user name 7402 separately. If it can't find a user name (because the user id is 7403 not in `/etc/passwd'), then it does not write one. When restoring, 7404 it tries to look the name (if one was written) up in `/etc/passwd'. 7405 If it fails, then it uses the user id stored in the archive 7406 instead. 7407 7408`--no-same-owner' 7409`-o' 7410 Do not attempt to restore ownership when extracting. This is the 7411 default behavior for ordinary users, so this option has an effect 7412 only for the superuser. 7413 7414`--numeric-owner' 7415 The `--numeric-owner' option allows (ANSI) archives to be written 7416 without user/group name information or such information to be 7417 ignored when extracting. It effectively disables the generation 7418 and/or use of user/group name information. This option forces 7419 extraction using the numeric ids from the archive, ignoring the 7420 names. 7421 7422 This is useful in certain circumstances, when restoring a backup 7423 from an emergency floppy with different passwd/group files for 7424 example. It is otherwise impossible to extract files with the 7425 right ownerships if the password file in use during the extraction 7426 does not match the one belonging to the file system(s) being 7427 extracted. This occurs, for example, if you are restoring your 7428 files after a major crash and had booted from an emergency floppy 7429 with no password file or put your disk into another machine to do 7430 the restore. 7431 7432 The numeric ids are _always_ saved into `tar' archives. The 7433 identifying names are added at create time when provided by the 7434 system, unless `--old-archive' (`-o') is used. Numeric ids could 7435 be used when moving archives between a collection of machines using 7436 a centralized management for attribution of numeric ids to users 7437 and groups. This is often made through using the NIS capabilities. 7438 7439 When making a `tar' file for distribution to other sites, it is 7440 sometimes cleaner to use a single owner for all files in the 7441 distribution, and nicer to specify the write permission bits of the 7442 files as stored in the archive independently of their actual value 7443 on the file system. The way to prepare a clean distribution is 7444 usually to have some Makefile rule creating a directory, copying 7445 all needed files in that directory, then setting ownership and 7446 permissions as wanted (there are a lot of possible schemes), and 7447 only then making a `tar' archive out of this directory, before 7448 cleaning everything out. Of course, we could add a lot of options 7449 to GNU `tar' for fine tuning permissions and ownership. This is 7450 not the good way, I think. GNU `tar' is already crowded with 7451 options and moreover, the approach just explained gives you a great 7452 deal of control already. 7453 7454`-p' 7455`--same-permissions' 7456`--preserve-permissions' 7457 Extract all protection information. 7458 7459 This option causes `tar' to set the modes (access permissions) of 7460 extracted files exactly as recorded in the archive. If this option 7461 is not used, the current `umask' setting limits the permissions on 7462 extracted files. This option is by default enabled when `tar' is 7463 executed by a superuser. 7464 7465 This option is meaningless with `--list' (`-t'). 7466 7467`--preserve' 7468 Same as both `--same-permissions' and `--same-order'. 7469 7470 The `--preserve' option has no equivalent short option name. It is 7471 equivalent to `--same-permissions' plus `--same-order'. 7472 7473 7474File: tar.info, Node: Portability, Next: cpio, Prev: Attributes, Up: Formats 7475 74768.3 Making `tar' Archives More Portable 7477======================================= 7478 7479Creating a `tar' archive on a particular system that is meant to be 7480useful later on many other machines and with other versions of `tar' is 7481more challenging than you might think. `tar' archive formats have been 7482evolving since the first versions of Unix. Many such formats are 7483around, and are not always compatible with each other. This section 7484discusses a few problems, and gives some advice about making `tar' 7485archives more portable. 7486 7487 One golden rule is simplicity. For example, limit your `tar' 7488archives to contain only regular files and directories, avoiding other 7489kind of special files. Do not attempt to save sparse files or 7490contiguous files as such. Let's discuss a few more problems, in turn. 7491 7492* Menu: 7493 7494* Portable Names:: Portable Names 7495* dereference:: Symbolic Links 7496* old:: Old V7 Archives 7497* ustar:: Ustar Archives 7498* gnu:: GNU and old GNU format archives. 7499* posix:: POSIX archives 7500* Checksumming:: Checksumming Problems 7501* Large or Negative Values:: Large files, negative time stamps, etc. 7502* Other Tars:: How to Extract GNU-Specific Data Using 7503 Other `tar' Implementations 7504 7505