1\input texinfo @c -*-texinfo-*- 2@comment %**start of header 3@setfilename tar.info 4@include version.texi 5@settitle GNU tar @value{VERSION} 6@setchapternewpage odd 7 8@finalout 9 10@smallbook 11@c %**end of header 12 13@c Maintenance notes: 14@c 1. Pay attention to @FIXME{}s and @UNREVISED{}s 15@c 2. Before creating final variant: 16@c 2.1. Run `make check-options' to make sure all options are properly 17@c documented; 18@c 2.2. Run `make master-menu' (see comment before the master menu). 19 20@include rendition.texi 21@include value.texi 22 23@defcodeindex op 24 25@c Put everything in one index (arbitrarily chosen to be the concept index). 26@syncodeindex fn cp 27@syncodeindex ky cp 28@syncodeindex pg cp 29@syncodeindex vr cp 30 31@copying 32 33This manual is for @acronym{GNU} @command{tar} (version 34@value{VERSION}, @value{UPDATED}), which creates and extracts files 35from archives. 36 37Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 382003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 39 40@quotation 41Permission is granted to copy, distribute and/or modify this document 42under the terms of the GNU Free Documentation License, Version 1.1 or 43any later version published by the Free Software Foundation; with no 44Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' 45and with the Back-Cover Texts as in (a) below. A copy of the license 46is included in the section entitled "GNU Free Documentation License". 47 48(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 49this GNU Manual. Buying copies from GNU Press supports the FSF in 50developing GNU and promoting software freedom.'' 51@end quotation 52@end copying 53 54@dircategory Archiving 55@direntry 56* Tar: (tar). Making tape (or disk) archives. 57@end direntry 58 59@dircategory Individual utilities 60@direntry 61* tar: (tar)tar invocation. Invoking @GNUTAR{}. 62@end direntry 63 64@shorttitlepage @acronym{GNU} @command{tar} 65 66@titlepage 67@title @acronym{GNU} tar: an archiver tool 68@subtitle @value{RENDITION} @value{VERSION}, @value{UPDATED} 69@author John Gilmore, Jay Fenlason et al. 70 71@page 72@vskip 0pt plus 1filll 73@insertcopying 74@end titlepage 75 76@ifnottex 77@node Top 78@top @acronym{GNU} tar: an archiver tool 79 80@insertcopying 81 82@cindex file archival 83@cindex archiving files 84 85The first part of this master menu lists the major nodes in this Info 86document. The rest of the menu lists all the lower level nodes. 87@end ifnottex 88 89@c The master menu goes here. 90@c 91@c NOTE: To update it from within Emacs, make sure mastermenu.el is 92@c loaded and run texinfo-master-menu. 93@c To update it from the command line, run 94@c 95@c make master-menu 96 97@menu 98* Introduction:: 99* Tutorial:: 100* tar invocation:: 101* operations:: 102* Backups:: 103* Choosing:: 104* Date input formats:: 105* Formats:: 106* Media:: 107 108Appendices 109 110* Changes:: 111* Configuring Help Summary:: 112* Tar Internals:: 113* Genfile:: 114* Free Software Needs Free Documentation:: 115* Copying This Manual:: 116* Index of Command Line Options:: 117* Index:: 118 119@detailmenu 120 --- The Detailed Node Listing --- 121 122Introduction 123 124* Book Contents:: What this Book Contains 125* Definitions:: Some Definitions 126* What tar Does:: What @command{tar} Does 127* Naming tar Archives:: How @command{tar} Archives are Named 128* Authors:: @GNUTAR{} Authors 129* Reports:: Reporting bugs or suggestions 130 131Tutorial Introduction to @command{tar} 132 133* assumptions:: 134* stylistic conventions:: 135* basic tar options:: Basic @command{tar} Operations and Options 136* frequent operations:: 137* Two Frequent Options:: 138* create:: How to Create Archives 139* list:: How to List Archives 140* extract:: How to Extract Members from an Archive 141* going further:: 142 143Two Frequently Used Options 144 145* file tutorial:: 146* verbose tutorial:: 147* help tutorial:: 148 149How to Create Archives 150 151* prepare for examples:: 152* Creating the archive:: 153* create verbose:: 154* short create:: 155* create dir:: 156 157How to List Archives 158 159* list dir:: 160 161How to Extract Members from an Archive 162 163* extracting archives:: 164* extracting files:: 165* extract dir:: 166* extracting untrusted archives:: 167* failing commands:: 168 169Invoking @GNUTAR{} 170 171* Synopsis:: 172* using tar options:: 173* Styles:: 174* All Options:: 175* help:: 176* defaults:: 177* verbose:: 178* interactive:: 179 180The Three Option Styles 181 182* Long Options:: Long Option Style 183* Short Options:: Short Option Style 184* Old Options:: Old Option Style 185* Mixing:: Mixing Option Styles 186 187All @command{tar} Options 188 189* Operation Summary:: 190* Option Summary:: 191* Short Option Summary:: 192 193@GNUTAR{} Operations 194 195* Basic tar:: 196* Advanced tar:: 197* create options:: 198* extract options:: 199* backup:: 200* Applications:: 201* looking ahead:: 202 203Advanced @GNUTAR{} Operations 204 205* Operations:: 206* append:: 207* update:: 208* concatenate:: 209* delete:: 210* compare:: 211 212How to Add Files to Existing Archives: @option{--append} 213 214* appending files:: Appending Files to an Archive 215* multiple:: 216 217Updating an Archive 218 219* how to update:: 220 221Options Used by @option{--create} 222 223* override:: Overriding File Metadata. 224* Ignore Failed Read:: 225 226Options Used by @option{--extract} 227 228* Reading:: Options to Help Read Archives 229* Writing:: Changing How @command{tar} Writes Files 230* Scarce:: Coping with Scarce Resources 231 232Options to Help Read Archives 233 234* read full records:: 235* Ignore Zeros:: 236 237Changing How @command{tar} Writes Files 238 239* Dealing with Old Files:: 240* Overwrite Old Files:: 241* Keep Old Files:: 242* Keep Newer Files:: 243* Unlink First:: 244* Recursive Unlink:: 245* Data Modification Times:: 246* Setting Access Permissions:: 247* Directory Modification Times and Permissions:: 248* Writing to Standard Output:: 249* Writing to an External Program:: 250* remove files:: 251 252Coping with Scarce Resources 253 254* Starting File:: 255* Same Order:: 256 257Performing Backups and Restoring Files 258 259* Full Dumps:: Using @command{tar} to Perform Full Dumps 260* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps 261* Backup Levels:: Levels of Backups 262* Backup Parameters:: Setting Parameters for Backups and Restoration 263* Scripted Backups:: Using the Backup Scripts 264* Scripted Restoration:: Using the Restore Script 265 266Setting Parameters for Backups and Restoration 267 268* General-Purpose Variables:: 269* Magnetic Tape Control:: 270* User Hooks:: 271* backup-specs example:: An Example Text of @file{Backup-specs} 272 273Choosing Files and Names for @command{tar} 274 275* file:: Choosing the Archive's Name 276* Selecting Archive Members:: 277* files:: Reading Names from a File 278* exclude:: Excluding Some Files 279* wildcards:: Wildcards Patterns and Matching 280* quoting styles:: Ways of Quoting Special Characters in Names 281* transform:: Modifying File and Member Names 282* after:: Operating Only on New Files 283* recurse:: Descending into Directories 284* one:: Crossing File System Boundaries 285 286Reading Names from a File 287 288* nul:: 289 290Excluding Some Files 291 292* problems with exclude:: 293 294Wildcards Patterns and Matching 295 296* controlling pattern-matching:: 297 298Crossing File System Boundaries 299 300* directory:: Changing Directory 301* absolute:: Absolute File Names 302 303Date input formats 304 305* General date syntax:: Common rules. 306* Calendar date items:: 19 Dec 1994. 307* Time of day items:: 9:20pm. 308* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}. 309* Day of week items:: Monday and others. 310* Relative items in date strings:: next tuesday, 2 years ago. 311* Pure numbers in date strings:: 19931219, 1440. 312* Seconds since the Epoch:: @@1078100502. 313* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". 314* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al. 315 316Controlling the Archive Format 317 318* Portability:: Making @command{tar} Archives More Portable 319* Compression:: Using Less Space through Compression 320* Attributes:: Handling File Attributes 321* cpio:: Comparison of @command{tar} and @command{cpio} 322 323Making @command{tar} Archives More Portable 324 325* Portable Names:: Portable Names 326* dereference:: Symbolic Links 327* old:: Old V7 Archives 328* ustar:: Ustar Archives 329* gnu:: GNU and old GNU format archives. 330* posix:: @acronym{POSIX} archives 331* Checksumming:: Checksumming Problems 332* Large or Negative Values:: Large files, negative time stamps, etc. 333* Other Tars:: How to Extract GNU-Specific Data Using 334 Other @command{tar} Implementations 335 336@GNUTAR{} and @acronym{POSIX} @command{tar} 337 338* PAX keywords:: Controlling Extended Header Keywords. 339 340How to Extract GNU-Specific Data Using Other @command{tar} Implementations 341 342* Split Recovery:: Members Split Between Volumes 343* Sparse Recovery:: Sparse Members 344 345Using Less Space through Compression 346 347* gzip:: Creating and Reading Compressed Archives 348* sparse:: Archiving Sparse Files 349 350Tapes and Other Archive Media 351 352* Device:: Device selection and switching 353* Remote Tape Server:: 354* Common Problems and Solutions:: 355* Blocking:: Blocking 356* Many:: Many archives on one tape 357* Using Multiple Tapes:: Using Multiple Tapes 358* label:: Including a Label in the Archive 359* verify:: 360* Write Protection:: 361 362Blocking 363 364* Format Variations:: Format Variations 365* Blocking Factor:: The Blocking Factor of an Archive 366 367Many Archives on One Tape 368 369* Tape Positioning:: Tape Positions and Tape Marks 370* mt:: The @command{mt} Utility 371 372Using Multiple Tapes 373 374* Multi-Volume Archives:: Archives Longer than One Tape or Disk 375* Tape Files:: Tape Files 376* Tarcat:: Concatenate Volumes into a Single Archive 377 378 379Tar Internals 380 381* Standard:: Basic Tar Format 382* Extensions:: @acronym{GNU} Extensions to the Archive Format 383* Sparse Formats:: Storing Sparse Files 384* Snapshot Files:: 385* Dumpdir:: 386 387Storing Sparse Files 388 389* Old GNU Format:: 390* PAX 0:: PAX Format, Versions 0.0 and 0.1 391* PAX 1:: PAX Format, Version 1.0 392 393Genfile 394 395* Generate Mode:: File Generation Mode. 396* Status Mode:: File Status Mode. 397* Exec Mode:: Synchronous Execution mode. 398 399Copying This Manual 400 401* GNU Free Documentation License:: License for copying this manual 402 403@end detailmenu 404@end menu 405 406@node Introduction 407@chapter Introduction 408 409@GNUTAR{} creates 410and manipulates @dfn{archives} which are actually collections of 411many other files; the program provides users with an organized and 412systematic method for controlling a large amount of data. 413The name ``tar'' originally came from the phrase ``Tape ARchive'', but 414archives need not (and these days, typically do not) reside on tapes. 415 416@menu 417* Book Contents:: What this Book Contains 418* Definitions:: Some Definitions 419* What tar Does:: What @command{tar} Does 420* Naming tar Archives:: How @command{tar} Archives are Named 421* Authors:: @GNUTAR{} Authors 422* Reports:: Reporting bugs or suggestions 423@end menu 424 425@node Book Contents 426@section What this Book Contains 427 428The first part of this chapter introduces you to various terms that will 429recur throughout the book. It also tells you who has worked on @GNUTAR{} 430and its documentation, and where you should send bug reports 431or comments. 432 433The second chapter is a tutorial (@pxref{Tutorial}) which provides a 434gentle introduction for people who are new to using @command{tar}. It is 435meant to be self contained, not requiring any reading from subsequent 436chapters to make sense. It moves from topic to topic in a logical, 437progressive order, building on information already explained. 438 439Although the tutorial is paced and structured to allow beginners to 440learn how to use @command{tar}, it is not intended solely for beginners. 441The tutorial explains how to use the three most frequently used 442operations (@samp{create}, @samp{list}, and @samp{extract}) as well as 443two frequently used options (@samp{file} and @samp{verbose}). The other 444chapters do not refer to the tutorial frequently; however, if a section 445discusses something which is a complex variant of a basic concept, there 446may be a cross reference to that basic concept. (The entire book, 447including the tutorial, assumes that the reader understands some basic 448concepts of using a Unix-type operating system; @pxref{Tutorial}.) 449 450The third chapter presents the remaining five operations, and 451information about using @command{tar} options and option syntax. 452 453@FIXME{this sounds more like a @acronym{GNU} Project Manuals Concept [tm] more 454than the reality. should think about whether this makes sense to say 455here, or not.} The other chapters are meant to be used as a 456reference. Each chapter presents everything that needs to be said 457about a specific topic. 458 459One of the chapters (@pxref{Date input formats}) exists in its 460entirety in other @acronym{GNU} manuals, and is mostly self-contained. 461In addition, one section of this manual (@pxref{Standard}) contains a 462big quote which is taken directly from @command{tar} sources. 463 464In general, we give both long and short (abbreviated) option names 465at least once in each section where the relevant option is covered, so 466that novice readers will become familiar with both styles. (A few 467options have no short versions, and the relevant sections will 468indicate this.) 469 470@node Definitions 471@section Some Definitions 472 473@cindex archive 474@cindex tar archive 475The @command{tar} program is used to create and manipulate @command{tar} 476archives. An @dfn{archive} is a single file which contains the contents 477of many files, while still identifying the names of the files, their 478owner(s), and so forth. (In addition, archives record access 479permissions, user and group, size in bytes, and data modification time. 480Some archives also record the file names in each archived directory, as 481well as other file and directory information.) You can use @command{tar} 482to @dfn{create} a new archive in a specified directory. 483 484@cindex member 485@cindex archive member 486@cindex file name 487@cindex member name 488The files inside an archive are called @dfn{members}. Within this 489manual, we use the term @dfn{file} to refer only to files accessible in 490the normal ways (by @command{ls}, @command{cat}, and so forth), and the term 491@dfn{member} to refer only to the members of an archive. Similarly, a 492@dfn{file name} is the name of a file, as it resides in the file system, 493and a @dfn{member name} is the name of an archive member within the 494archive. 495 496@cindex extraction 497@cindex unpacking 498The term @dfn{extraction} refers to the process of copying an archive 499member (or multiple members) into a file in the file system. Extracting 500all the members of an archive is often called @dfn{extracting the 501archive}. The term @dfn{unpack} can also be used to refer to the 502extraction of many or all the members of an archive. Extracting an 503archive does not destroy the archive's structure, just as creating an 504archive does not destroy the copies of the files that exist outside of 505the archive. You may also @dfn{list} the members in a given archive 506(this is often thought of as ``printing'' them to the standard output, 507or the command line), or @dfn{append} members to a pre-existing archive. 508All of these operations can be performed using @command{tar}. 509 510@node What tar Does 511@section What @command{tar} Does 512 513@cindex tar 514The @command{tar} program provides the ability to create @command{tar} 515archives, as well as various other kinds of manipulation. For example, 516you can use @command{tar} on previously created archives to extract files, 517to store additional files, or to update or list files which were already 518stored. 519 520Initially, @command{tar} archives were used to store files conveniently on 521magnetic tape. The name @command{tar} comes from this use; it stands for 522@code{t}ape @code{ar}chiver. Despite the utility's name, @command{tar} can 523direct its output to available devices, files, or other programs (using 524pipes). @command{tar} may even access remote devices or files (as archives). 525 526You can use @command{tar} archives in many ways. We want to stress a few 527of them: storage, backup, and transportation. 528 529@FIXME{the following table entries need a bit of work.} 530@table @asis 531@item Storage 532Often, @command{tar} archives are used to store related files for 533convenient file transfer over a network. For example, the 534@acronym{GNU} Project distributes its software bundled into 535@command{tar} archives, so that all the files relating to a particular 536program (or set of related programs) can be transferred as a single 537unit. 538 539A magnetic tape can store several files in sequence. However, the tape 540has no names for these files; it only knows their relative position on 541the tape. One way to store several files on one tape and retain their 542names is by creating a @command{tar} archive. Even when the basic transfer 543mechanism can keep track of names, as FTP can, the nuisance of handling 544multiple files, directories, and multiple links makes @command{tar} 545archives useful. 546 547Archive files are also used for long-term storage. You can think of 548this as transportation from the present into the future. (It is a 549science-fiction idiom that you can move through time as well as in 550space; the idea here is that @command{tar} can be used to move archives in 551all dimensions, even time!) 552 553@item Backup 554Because the archive created by @command{tar} is capable of preserving 555file information and directory structure, @command{tar} is commonly 556used for performing full and incremental backups of disks. A backup 557puts a collection of files (possibly pertaining to many users and 558projects) together on a disk or a tape. This guards against 559accidental destruction of the information in those files. 560@GNUTAR{} has special features that allow it to be 561used to make incremental and full dumps of all the files in a 562file system. 563 564@item Transportation 565You can create an archive on one system, transfer it to another system, 566and extract the contents there. This allows you to transport a group of 567files from one system to another. 568@end table 569 570@node Naming tar Archives 571@section How @command{tar} Archives are Named 572 573Conventionally, @command{tar} archives are given names ending with 574@samp{.tar}. This is not necessary for @command{tar} to operate properly, 575but this manual follows that convention in order to accustom readers to 576it and to make examples more clear. 577 578@cindex tar file 579@cindex entry 580@cindex tar entry 581Often, people refer to @command{tar} archives as ``@command{tar} files,'' and 582archive members as ``files'' or ``entries''. For people familiar with 583the operation of @command{tar}, this causes no difficulty. However, in 584this manual, we consistently refer to ``archives'' and ``archive 585members'' to make learning to use @command{tar} easier for novice users. 586 587@node Authors 588@section @GNUTAR{} Authors 589 590@GNUTAR{} was originally written by John Gilmore, 591and modified by many people. The @acronym{GNU} enhancements were 592written by Jay Fenlason, then Joy Kendall, and the whole package has 593been further maintained by Thomas Bushnell, n/BSG, Fran@,{c}ois 594Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of 595numerous and kind users. 596 597We wish to stress that @command{tar} is a collective work, and owes much to 598all those people who reported problems, offered solutions and other 599insights, or shared their thoughts and suggestions. An impressive, yet 600partial list of those contributors can be found in the @file{THANKS} 601file from the @GNUTAR{} distribution. 602 603@FIXME{i want all of these names mentioned, Absolutely. BUT, i'm not 604sure i want to spell out the history in this detail, at least not for 605the printed book. i'm just not sure it needs to be said this way. 606i'll think about it.} 607 608@FIXME{History is more important, and surely more interesting, than 609actual names. Quoting names without history would be meaningless. FP} 610 611Jay Fenlason put together a draft of a @GNUTAR{} 612manual, borrowing notes from the original man page from John Gilmore. 613This was withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy 614Gorin worked on a tutorial and manual for @GNUTAR{}. 615Fran@,{c}ois Pinard put version 1.11.8 of the manual together by 616taking information from all these sources and merging them. Melissa 617Weisshaus finally edited and redesigned the book to create version 6181.12. The book for versions from 1.14 up to @value{VERSION} were edited 619by the current maintainer, Sergey Poznyakoff. 620 621For version 1.12, Daniel Hagerty contributed a great deal of technical 622consulting. In particular, he is the primary author of @ref{Backups}. 623 624In July, 2003 @GNUTAR{} was put on CVS at savannah.gnu.org 625(see @url{http://savannah.gnu.org/projects/tar}), and 626active development and maintenance work has started 627again. Currently @GNUTAR{} is being maintained by Paul Eggert, Sergey 628Poznyakoff and Jeff Bailey. 629 630Support for @acronym{POSIX} archives was added by Sergey Poznyakoff. 631 632@node Reports 633@section Reporting bugs or suggestions 634 635@cindex bug reports 636@cindex reporting bugs 637If you find problems or have suggestions about this program or manual, 638please report them to @file{bug-tar@@gnu.org}. 639 640When reporting a bug, please be sure to include as much detail as 641possible, in order to reproduce it. @FIXME{Be more specific, I'd 642like to make this node as detailed as 'Bug reporting' node in Emacs 643manual}. 644 645@node Tutorial 646@chapter Tutorial Introduction to @command{tar} 647 648This chapter guides you through some basic examples of three @command{tar} 649operations: @option{--create}, @option{--list}, and @option{--extract}. If 650you already know how to use some other version of @command{tar}, then you 651may not need to read this chapter. This chapter omits most complicated 652details about how @command{tar} works. 653 654@menu 655* assumptions:: 656* stylistic conventions:: 657* basic tar options:: Basic @command{tar} Operations and Options 658* frequent operations:: 659* Two Frequent Options:: 660* create:: How to Create Archives 661* list:: How to List Archives 662* extract:: How to Extract Members from an Archive 663* going further:: 664@end menu 665 666@node assumptions 667@section Assumptions this Tutorial Makes 668 669This chapter is paced to allow beginners to learn about @command{tar} 670slowly. At the same time, we will try to cover all the basic aspects of 671these three operations. In order to accomplish both of these tasks, we 672have made certain assumptions about your knowledge before reading this 673manual, and the hardware you will be using: 674 675@itemize @bullet 676@item 677Before you start to work through this tutorial, you should understand 678what the terms ``archive'' and ``archive member'' mean 679(@pxref{Definitions}). In addition, you should understand something 680about how Unix-type operating systems work, and you should know how to 681use some basic utilities. For example, you should know how to create, 682list, copy, rename, edit, and delete files and directories; how to 683change between directories; and how to figure out where you are in the 684file system. You should have some basic understanding of directory 685structure and how files are named according to which directory they are 686in. You should understand concepts such as standard output and standard 687input, what various definitions of the term ``argument'' mean, and the 688differences between relative and absolute file names. @FIXME{and what 689else?} 690 691@item 692This manual assumes that you are working from your own home directory 693(unless we state otherwise). In this tutorial, you will create a 694directory to practice @command{tar} commands in. When we show file names, 695we will assume that those names are relative to your home directory. 696For example, my home directory is @file{/home/fsf/melissa}. All of 697my examples are in a subdirectory of the directory named by that file 698name; the subdirectory is called @file{practice}. 699 700@item 701In general, we show examples of archives which exist on (or can be 702written to, or worked with from) a directory on a hard disk. In most 703cases, you could write those archives to, or work with them on any other 704device, such as a tape drive. However, some of the later examples in 705the tutorial and next chapter will not work on tape drives. 706Additionally, working with tapes is much more complicated than working 707with hard disks. For these reasons, the tutorial does not cover working 708with tape drives. @xref{Media}, for complete information on using 709@command{tar} archives with tape drives. 710 711@FIXME{this is a cop out. need to add some simple tape drive info.} 712@end itemize 713 714@node stylistic conventions 715@section Stylistic Conventions 716 717In the examples, @samp{$} represents a typical shell prompt. It 718precedes lines you should type; to make this more clear, those lines are 719shown in @kbd{this font}, as opposed to lines which represent the 720computer's response; those lines are shown in @code{this font}, or 721sometimes @samp{like this}. 722 723@c When we have lines which are too long to be 724@c displayed in any other way, we will show them like this: 725 726@node basic tar options 727@section Basic @command{tar} Operations and Options 728 729@command{tar} can take a wide variety of arguments which specify and define 730the actions it will have on the particular set of files or the archive. 731The main types of arguments to @command{tar} fall into one of two classes: 732operations, and options. 733 734Some arguments fall into a class called @dfn{operations}; exactly one of 735these is both allowed and required for any instance of using @command{tar}; 736you may @emph{not} specify more than one. People sometimes speak of 737@dfn{operating modes}. You are in a particular operating mode when you 738have specified the operation which specifies it; there are eight 739operations in total, and thus there are eight operating modes. 740 741The other arguments fall into the class known as @dfn{options}. You are 742not required to specify any options, and you are allowed to specify more 743than one at a time (depending on the way you are using @command{tar} at 744that time). Some options are used so frequently, and are so useful for 745helping you type commands more carefully that they are effectively 746``required''. We will discuss them in this chapter. 747 748You can write most of the @command{tar} operations and options in any 749of three forms: long (mnemonic) form, short form, and old style. Some 750of the operations and options have no short or ``old'' forms; however, 751the operations and options which we will cover in this tutorial have 752corresponding abbreviations. @FIXME{make sure this is still the case, 753at the end}We will indicate those abbreviations appropriately to get 754you used to seeing them. (Note that the ``old style'' option forms 755exist in @GNUTAR{} for compatibility with Unix 756@command{tar}. In this book we present a full discussion of this way 757of writing options and operations (@pxref{Old Options}), and we discuss 758the other two styles of writing options (@xref{Long Options}, and 759@pxref{Short Options}). 760 761In the examples and in the text of this tutorial, we usually use the 762long forms of operations and options; but the ``short'' forms produce 763the same result and can make typing long @command{tar} commands easier. 764For example, instead of typing 765 766@smallexample 767@kbd{tar --create --verbose --file=afiles.tar apple angst aspic} 768@end smallexample 769 770@noindent 771you can type 772@smallexample 773@kbd{tar -c -v -f afiles.tar apple angst aspic} 774@end smallexample 775 776@noindent 777or even 778@smallexample 779@kbd{tar -cvf afiles.tar apple angst aspic} 780@end smallexample 781 782@noindent 783For more information on option syntax, see @ref{Advanced tar}. In 784discussions in the text, when we name an option by its long form, we 785also give the corresponding short option in parentheses. 786 787The term, ``option'', can be confusing at times, since ``operations'' 788are often lumped in with the actual, @emph{optional} ``options'' in certain 789general class statements. For example, we just talked about ``short and 790long forms of options and operations''. However, experienced @command{tar} 791users often refer to these by shorthand terms such as, ``short and long 792options''. This term assumes that the ``operations'' are included, also. 793Context will help you determine which definition of ``options'' to use. 794 795Similarly, the term ``command'' can be confusing, as it is often used in 796two different ways. People sometimes refer to @command{tar} ``commands''. 797A @command{tar} @dfn{command} is the entire command line of user input 798which tells @command{tar} what to do --- including the operation, options, 799and any arguments (file names, pipes, other commands, etc.). However, 800you will also sometimes hear the term ``the @command{tar} command''. When 801the word ``command'' is used specifically like this, a person is usually 802referring to the @command{tar} @emph{operation}, not the whole line. 803Again, use context to figure out which of the meanings the speaker 804intends. 805 806@node frequent operations 807@section The Three Most Frequently Used Operations 808 809Here are the three most frequently used operations (both short and long 810forms), as well as a brief description of their meanings. The rest of 811this chapter will cover how to use these operations in detail. We will 812present the rest of the operations in the next chapter. 813 814@table @option 815@item --create 816@itemx -c 817Create a new @command{tar} archive. 818@item --list 819@itemx -t 820List the contents of an archive. 821@item --extract 822@itemx -x 823Extract one or more members from an archive. 824@end table 825 826@node Two Frequent Options 827@section Two Frequently Used Options 828 829To understand how to run @command{tar} in the three operating modes listed 830previously, you also need to understand how to use two of the options to 831@command{tar}: @option{--file} (which takes an archive file as an argument) 832and @option{--verbose}. (You are usually not @emph{required} to specify 833either of these options when you run @command{tar}, but they can be very 834useful in making things more clear and helping you avoid errors.) 835 836@menu 837* file tutorial:: 838* verbose tutorial:: 839* help tutorial:: 840@end menu 841 842@node file tutorial 843@unnumberedsubsec The @option{--file} Option 844 845@table @option 846@xopindex{file, tutorial} 847@item --file=@var{archive-name} 848@itemx -f @var{archive-name} 849Specify the name of an archive file. 850@end table 851 852You can specify an argument for the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option whenever you 853use @command{tar}; this option determines the name of the archive file 854that @command{tar} will work on. 855 856@vrindex TAPE 857If you don't specify this argument, then @command{tar} will examine 858the environment variable @env{TAPE}. If it is set, its value will be 859used as the archive name. Otherwise, @command{tar} will use the 860default archive, determined at the compile time. Usually it is 861standard output or some physical tape drive attached to your machine 862(you can verify what the default is by running @kbd{tar 863--show-defaults}, @pxref{defaults}). If there is no tape drive 864attached, or the default is not meaningful, then @command{tar} will 865print an error message. The error message might look roughly like one 866of the following: 867 868@smallexample 869tar: can't open /dev/rmt8 : No such device or address 870tar: can't open /dev/rsmt0 : I/O error 871@end smallexample 872 873@noindent 874To avoid confusion, we recommend that you always specify an archive file 875name by using @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) when writing your @command{tar} commands. 876For more information on using the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option, see 877@ref{file}. 878 879@node verbose tutorial 880@unnumberedsubsec The @option{--verbose} Option 881 882@table @option 883@xopindex{verbose, introduced} 884@item --verbose 885@itemx -v 886Show the files being worked on as @command{tar} is running. 887@end table 888 889@option{--verbose} (@option{-v}) shows details about the results of running 890@command{tar}. This can be especially useful when the results might not be 891obvious. For example, if you want to see the progress of @command{tar} as 892it writes files into the archive, you can use the @option{--verbose} 893option. In the beginning, you may find it useful to use 894@option{--verbose} at all times; when you are more accustomed to 895@command{tar}, you will likely want to use it at certain times but not at 896others. We will use @option{--verbose} at times to help make something 897clear, and we will give many examples both using and not using 898@option{--verbose} to show the differences. 899 900Each instance of @option{--verbose} on the command line increases the 901verbosity level by one, so if you need more details on the output, 902specify it twice. 903 904When reading archives (@option{--list}, @option{--extract}, 905@option{--diff}), @command{tar} by default prints only the names of 906the members being extracted. Using @option{--verbose} will show a full, 907@command{ls} style member listing. 908 909In contrast, when writing archives (@option{--create}, @option{--append}, 910@option{--update}), @command{tar} does not print file names by 911default. So, a single @option{--verbose} option shows the file names 912being added to the archive, while two @option{--verbose} options 913enable the full listing. 914 915For example, to create an archive in verbose mode: 916 917@smallexample 918$ @kbd{tar -cvf afiles.tar apple angst aspic} 919apple 920angst 921aspic 922@end smallexample 923 924@noindent 925Creating the same archive with the verbosity level 2 could give: 926 927@smallexample 928$ @kbd{tar -cvvf afiles.tar apple angst aspic} 929-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple 930-rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst 931-rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic 932@end smallexample 933 934@noindent 935This works equally well using short or long forms of options. Using 936long forms, you would simply write out the mnemonic form of the option 937twice, like this: 938 939@smallexample 940$ @kbd{tar --create --verbose --verbose @dots{}} 941@end smallexample 942 943@noindent 944Note that you must double the hyphens properly each time. 945 946Later in the tutorial, we will give examples using @w{@option{--verbose 947--verbose}}. 948 949@anchor{verbose member listing} 950The full output consists of six fields: 951 952@itemize @bullet 953@item File type and permissions in symbolic form. 954These are displayed in the same format as the first column of 955@command{ls -l} output (@pxref{What information is listed, 956format=verbose, Verbose listing, fileutils, GNU file utilities}). 957 958@item Owner name and group separated by a slash character. 959If these data are not available (for example, when listing a @samp{v7} format 960archive), numeric @acronym{ID} values are printed instead. 961 962@item Size of the file, in bytes. 963 964@item File modification date in ISO 8601 format. 965 966@item File modification time. 967 968@item File name. 969If the name contains any special characters (white space, newlines, 970etc.) these are displayed in an unambiguous form using so called 971@dfn{quoting style}. For the detailed discussion of available styles 972and on how to use them, see @ref{quoting styles}. 973 974Depending on the file type, the name can be followed by some 975additional information, described in the following table: 976 977@table @samp 978@item -> @var{link-name} 979The file or archive member is a @dfn{symbolic link} and 980@var{link-name} is the name of file it links to. 981 982@item link to @var{link-name} 983The file or archive member is a @dfn{hard link} and @var{link-name} is 984the name of file it links to. 985 986@item --Long Link-- 987The archive member is an old GNU format long link. You will normally 988not encounter this. 989 990@item --Long Name-- 991The archive member is an old GNU format long name. You will normally 992not encounter this. 993 994@item --Volume Header-- 995The archive member is a GNU @dfn{volume header} (@pxref{Tape Files}). 996 997@item --Continued at byte @var{n}-- 998Encountered only at the beginning of a multi-volume archive 999(@pxref{Using Multiple Tapes}). This archive member is a continuation 1000from the previous volume. The number @var{n} gives the offset where 1001the original file was split. 1002 1003@item unknown file type @var{c} 1004An archive member of unknown type. @var{c} is the type character from 1005the archive header. If you encounter such a message, it means that 1006either your archive contains proprietary member types @GNUTAR{} is not 1007able to handle, or the archive is corrupted. 1008@end table 1009 1010@end itemize 1011 1012For example, here is an archive listing containing most of the special 1013suffixes explained above: 1014 1015@smallexample 1016@group 1017V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header-- 1018-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at 1019byte 32456-- 1020-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple 1021lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple 1022-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues 1023hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues 1024@end group 1025@end smallexample 1026 1027@smallexample 1028@end smallexample 1029 1030@node help tutorial 1031@unnumberedsubsec Getting Help: Using the @option{--help} Option 1032 1033@table @option 1034@opindex help 1035@item --help 1036 1037The @option{--help} option to @command{tar} prints out a very brief list of 1038all operations and option available for the current version of 1039@command{tar} available on your system. 1040@end table 1041 1042@node create 1043@section How to Create Archives 1044@UNREVISED 1045 1046@cindex Creation of the archive 1047@cindex Archive, creation of 1048One of the basic operations of @command{tar} is @option{--create} (@option{-c}), which 1049you use to create a @command{tar} archive. We will explain 1050@option{--create} first because, in order to learn about the other 1051operations, you will find it useful to have an archive available to 1052practice on. 1053 1054To make this easier, in this section you will first create a directory 1055containing three files. Then, we will show you how to create an 1056@emph{archive} (inside the new directory). Both the directory, and 1057the archive are specifically for you to practice on. The rest of this 1058chapter and the next chapter will show many examples using this 1059directory and the files you will create: some of those files may be 1060other directories and other archives. 1061 1062The three files you will archive in this example are called 1063@file{blues}, @file{folk}, and @file{jazz}. The archive is called 1064@file{collection.tar}. 1065 1066This section will proceed slowly, detailing how to use @option{--create} 1067in @code{verbose} mode, and showing examples using both short and long 1068forms. In the rest of the tutorial, and in the examples in the next 1069chapter, we will proceed at a slightly quicker pace. This section 1070moves more slowly to allow beginning users to understand how 1071@command{tar} works. 1072 1073@menu 1074* prepare for examples:: 1075* Creating the archive:: 1076* create verbose:: 1077* short create:: 1078* create dir:: 1079@end menu 1080 1081@node prepare for examples 1082@subsection Preparing a Practice Directory for Examples 1083 1084To follow along with this and future examples, create a new directory 1085called @file{practice} containing files called @file{blues}, @file{folk} 1086and @file{jazz}. The files can contain any information you like: 1087ideally, they should contain information which relates to their names, 1088and be of different lengths. Our examples assume that @file{practice} 1089is a subdirectory of your home directory. 1090 1091Now @command{cd} to the directory named @file{practice}; @file{practice} 1092is now your @dfn{working directory}. (@emph{Please note}: Although 1093the full file name of this directory is 1094@file{/@var{homedir}/practice}, in our examples we will refer to 1095this directory as @file{practice}; the @var{homedir} is presumed. 1096 1097In general, you should check that the files to be archived exist where 1098you think they do (in the working directory) by running @command{ls}. 1099Because you just created the directory and the files and have changed to 1100that directory, you probably don't need to do that this time. 1101 1102It is very important to make sure there isn't already a file in the 1103working directory with the archive name you intend to use (in this case, 1104@samp{collection.tar}), or that you don't care about its contents. 1105Whenever you use @samp{create}, @command{tar} will erase the current 1106contents of the file named by @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) if it exists. @command{tar} 1107will not tell you if you are about to overwrite an archive unless you 1108specify an option which does this (@pxref{backup}, for the 1109information on how to do so). To add files to an existing archive, 1110you need to use a different option, such as @option{--append} (@option{-r}); see 1111@ref{append} for information on how to do this. 1112 1113@node Creating the archive 1114@subsection Creating the Archive 1115 1116@xopindex{create, introduced} 1117To place the files @file{blues}, @file{folk}, and @file{jazz} into an 1118archive named @file{collection.tar}, use the following command: 1119 1120@smallexample 1121$ @kbd{tar --create --file=collection.tar blues folk jazz} 1122@end smallexample 1123 1124The order of the arguments is not very important, @emph{when using long 1125option forms}. You could also say: 1126 1127@smallexample 1128$ @kbd{tar blues --create folk --file=collection.tar jazz} 1129@end smallexample 1130 1131@noindent 1132However, you can see that this order is harder to understand; this is 1133why we will list the arguments in the order that makes the commands 1134easiest to understand (and we encourage you to do the same when you use 1135@command{tar}, to avoid errors). 1136 1137Note that the sequence 1138@option{--file=@-collection.tar} is considered to be @emph{one} argument. 1139If you substituted any other string of characters for 1140@kbd{collection.tar}, then that string would become the name of the 1141archive file you create. 1142 1143The order of the options becomes more important when you begin to use 1144short forms. With short forms, if you type commands in the wrong order 1145(even if you type them correctly in all other ways), you may end up with 1146results you don't expect. For this reason, it is a good idea to get 1147into the habit of typing options in the order that makes inherent sense. 1148@xref{short create}, for more information on this. 1149 1150In this example, you type the command as shown above: @option{--create} 1151is the operation which creates the new archive 1152(@file{collection.tar}), and @option{--file} is the option which lets 1153you give it the name you chose. The files, @file{blues}, @file{folk}, 1154and @file{jazz}, are now members of the archive, @file{collection.tar} 1155(they are @dfn{file name arguments} to the @option{--create} operation. 1156@xref{Choosing}, for the detailed discussion on these.) Now that they are 1157in the archive, they are called @emph{archive members}, not files. 1158(@pxref{Definitions,members}). 1159 1160When you create an archive, you @emph{must} specify which files you 1161want placed in the archive. If you do not specify any archive 1162members, @GNUTAR{} will complain. 1163 1164If you now list the contents of the working directory (@command{ls}), you will 1165find the archive file listed as well as the files you saw previously: 1166 1167@smallexample 1168blues folk jazz collection.tar 1169@end smallexample 1170 1171@noindent 1172Creating the archive @samp{collection.tar} did not destroy the copies of 1173the files in the directory. 1174 1175Keep in mind that if you don't indicate an operation, @command{tar} will not 1176run and will prompt you for one. If you don't name any files, @command{tar} 1177will complain. You must have write access to the working directory, 1178or else you will not be able to create an archive in that directory. 1179 1180@emph{Caution}: Do not attempt to use @option{--create} (@option{-c}) to add files to 1181an existing archive; it will delete the archive and write a new one. 1182Use @option{--append} (@option{-r}) instead. @xref{append}. 1183 1184@node create verbose 1185@subsection Running @option{--create} with @option{--verbose} 1186 1187@xopindex{create, using with @option{--verbose}} 1188@xopindex{verbose, using with @option{--create}} 1189If you include the @option{--verbose} (@option{-v}) option on the command line, 1190@command{tar} will list the files it is acting on as it is working. In 1191verbose mode, the @code{create} example above would appear as: 1192 1193@smallexample 1194$ @kbd{tar --create --verbose --file=collection.tar blues folk jazz} 1195blues 1196folk 1197jazz 1198@end smallexample 1199 1200This example is just like the example we showed which did not use 1201@option{--verbose}, except that @command{tar} generated the remaining lines 1202@iftex 1203(note the different font styles). 1204@end iftex 1205@ifinfo 1206. 1207@end ifinfo 1208 1209In the rest of the examples in this chapter, we will frequently use 1210@code{verbose} mode so we can show actions or @command{tar} responses that 1211you would otherwise not see, and which are important for you to 1212understand. 1213 1214@node short create 1215@subsection Short Forms with @samp{create} 1216 1217As we said before, the @option{--create} (@option{-c}) operation is one of the most 1218basic uses of @command{tar}, and you will use it countless times. 1219Eventually, you will probably want to use abbreviated (or ``short'') 1220forms of options. A full discussion of the three different forms that 1221options can take appears in @ref{Styles}; for now, here is what the 1222previous example (including the @option{--verbose} (@option{-v}) option) looks like 1223using short option forms: 1224 1225@smallexample 1226$ @kbd{tar -cvf collection.tar blues folk jazz} 1227blues 1228folk 1229jazz 1230@end smallexample 1231 1232@noindent 1233As you can see, the system responds the same no matter whether you use 1234long or short option forms. 1235 1236@FIXME{i don't like how this is worded:} One difference between using 1237short and long option forms is that, although the exact placement of 1238arguments following options is no more specific when using short forms, 1239it is easier to become confused and make a mistake when using short 1240forms. For example, suppose you attempted the above example in the 1241following way: 1242 1243@smallexample 1244$ @kbd{tar -cfv collection.tar blues folk jazz} 1245@end smallexample 1246 1247@noindent 1248In this case, @command{tar} will make an archive file called @file{v}, 1249containing the files @file{blues}, @file{folk}, and @file{jazz}, because 1250the @samp{v} is the closest ``file name'' to the @option{-f} option, and 1251is thus taken to be the chosen archive file name. @command{tar} will try 1252to add a file called @file{collection.tar} to the @file{v} archive file; 1253if the file @file{collection.tar} did not already exist, @command{tar} will 1254report an error indicating that this file does not exist. If the file 1255@file{collection.tar} does already exist (e.g., from a previous command 1256you may have run), then @command{tar} will add this file to the archive. 1257Because the @option{-v} option did not get registered, @command{tar} will not 1258run under @samp{verbose} mode, and will not report its progress. 1259 1260The end result is that you may be quite confused about what happened, 1261and possibly overwrite a file. To illustrate this further, we will show 1262you how an example we showed previously would look using short forms. 1263 1264This example, 1265 1266@smallexample 1267$ @kbd{tar blues --create folk --file=collection.tar jazz} 1268@end smallexample 1269 1270@noindent 1271is confusing as it is. When shown using short forms, however, it 1272becomes much more so: 1273 1274@smallexample 1275$ @kbd{tar blues -c folk -f collection.tar jazz} 1276@end smallexample 1277 1278@noindent 1279It would be very easy to put the wrong string of characters 1280immediately following the @option{-f}, but doing that could sacrifice 1281valuable data. 1282 1283For this reason, we recommend that you pay very careful attention to 1284the order of options and placement of file and archive names, 1285especially when using short option forms. Not having the option name 1286written out mnemonically can affect how well you remember which option 1287does what, and therefore where different names have to be placed. 1288 1289@node create dir 1290@subsection Archiving Directories 1291 1292@cindex Archiving Directories 1293@cindex Directories, Archiving 1294You can archive a directory by specifying its directory name as a 1295file name argument to @command{tar}. The files in the directory will be 1296archived relative to the working directory, and the directory will be 1297re-created along with its contents when the archive is extracted. 1298 1299To archive a directory, first move to its superior directory. If you 1300have followed the previous instructions in this tutorial, you should 1301type: 1302 1303@smallexample 1304$ @kbd{cd ..} 1305$ 1306@end smallexample 1307 1308@noindent 1309This will put you into the directory which contains @file{practice}, 1310i.e., your home directory. Once in the superior directory, you can 1311specify the subdirectory, @file{practice}, as a file name argument. To 1312store @file{practice} in the new archive file @file{music.tar}, type: 1313 1314@smallexample 1315$ @kbd{tar --create --verbose --file=music.tar practice} 1316@end smallexample 1317 1318@noindent 1319@command{tar} should output: 1320 1321@smallexample 1322practice/ 1323practice/blues 1324practice/folk 1325practice/jazz 1326practice/collection.tar 1327@end smallexample 1328 1329Note that the archive thus created is not in the subdirectory 1330@file{practice}, but rather in the current working directory---the 1331directory from which @command{tar} was invoked. Before trying to archive a 1332directory from its superior directory, you should make sure you have 1333write access to the superior directory itself, not only the directory 1334you are trying archive with @command{tar}. For example, you will probably 1335not be able to store your home directory in an archive by invoking 1336@command{tar} from the root directory; @xref{absolute}. (Note 1337also that @file{collection.tar}, the original archive file, has itself 1338been archived. @command{tar} will accept any file as a file to be 1339archived, regardless of its content. When @file{music.tar} is 1340extracted, the archive file @file{collection.tar} will be re-written 1341into the file system). 1342 1343If you give @command{tar} a command such as 1344 1345@smallexample 1346$ @kbd{tar --create --file=foo.tar .} 1347@end smallexample 1348 1349@noindent 1350@command{tar} will report @samp{tar: ./foo.tar is the archive; not 1351dumped}. This happens because @command{tar} creates the archive 1352@file{foo.tar} in the current directory before putting any files into 1353it. Then, when @command{tar} attempts to add all the files in the 1354directory @file{.} to the archive, it notices that the file 1355@file{./foo.tar} is the same as the archive @file{foo.tar}, and skips 1356it. (It makes no sense to put an archive into itself.) @GNUTAR{} 1357will continue in this case, and create the archive 1358normally, except for the exclusion of that one file. (@emph{Please 1359note:} Other implementations of @command{tar} may not be so clever; 1360they will enter an infinite loop when this happens, so you should not 1361depend on this behavior unless you are certain you are running 1362@GNUTAR{}. In general, it is wise to always place the archive outside 1363of the directory being dumped. 1364 1365@node list 1366@section How to List Archives 1367 1368@opindex list 1369Frequently, you will find yourself wanting to determine exactly what a 1370particular archive contains. You can use the @option{--list} 1371(@option{-t}) operation to get the member names as they currently 1372appear in the archive, as well as various attributes of the files at 1373the time they were archived. For example, you can examine the archive 1374@file{collection.tar} that you created in the last section with the 1375command, 1376 1377@smallexample 1378$ @kbd{tar --list --file=collection.tar} 1379@end smallexample 1380 1381@noindent 1382The output of @command{tar} would then be: 1383 1384@smallexample 1385blues 1386folk 1387jazz 1388@end smallexample 1389 1390@noindent 1391The archive @file{bfiles.tar} would list as follows: 1392 1393@smallexample 1394./birds 1395baboon 1396./box 1397@end smallexample 1398 1399@noindent 1400Be sure to use a @option{--file=@var{archive-name}} (@option{-f 1401@var{archive-name}}) option just as with @option{--create} 1402(@option{-c}) to specify the name of the archive. 1403 1404@xopindex{list, using with @option{--verbose}} 1405@xopindex{verbose, using with @option{--list}} 1406If you use the @option{--verbose} (@option{-v}) option with 1407@option{--list}, then @command{tar} will print out a listing 1408reminiscent of @w{@samp{ls -l}}, showing owner, file size, and so 1409forth. This output is described in detail in @ref{verbose member listing}. 1410 1411If you had used @option{--verbose} (@option{-v}) mode, the example 1412above would look like: 1413 1414@smallexample 1415$ @kbd{tar --list --verbose --file=collection.tar folk} 1416-rw-r--r-- myself user 62 1990-05-23 10:55 folk 1417@end smallexample 1418 1419@cindex listing member and file names 1420@anchor{listing member and file names} 1421It is important to notice that the output of @kbd{tar --list 1422--verbose} does not necessarily match that produced by @kbd{tar 1423--create --verbose} while creating the archive. It is because 1424@GNUTAR{}, unless told explicitly not to do so, removes some directory 1425prefixes from file names before storing them in the archive 1426(@xref{absolute}, for more information). In other 1427words, in verbose mode @GNUTAR{} shows @dfn{file names} when creating 1428an archive and @dfn{member names} when listing it. Consider this 1429example: 1430 1431@smallexample 1432@group 1433$ @kbd{tar cfv archive /etc/mail} 1434tar: Removing leading `/' from member names 1435/etc/mail/ 1436/etc/mail/sendmail.cf 1437/etc/mail/aliases 1438$ @kbd{tar tf archive} 1439etc/mail/ 1440etc/mail/sendmail.cf 1441etc/mail/aliases 1442@end group 1443@end smallexample 1444 1445@opindex show-stored-names 1446 This default behavior can sometimes be inconvenient. You can force 1447@GNUTAR{} show member names when creating archive by supplying 1448@option{--show-stored-names} option. 1449 1450@table @option 1451@item --show-stored-names 1452Print member (as opposed to @emph{file}) names when creating the archive. 1453@end table 1454 1455@cindex File name arguments, using @option{--list} with 1456@xopindex{list, using with file name arguments} 1457You can specify one or more individual member names as arguments when 1458using @samp{list}. In this case, @command{tar} will only list the 1459names of members you identify. For example, @w{@kbd{tar --list 1460--file=afiles.tar apple}} would only print @file{apple}. 1461 1462Because @command{tar} preserves file names, these must be specified as 1463they appear in the archive (i.e., relative to the directory from which 1464the archive was created). Therefore, it is essential when specifying 1465member names to @command{tar} that you give the exact member names. 1466For example, @w{@kbd{tar --list --file=bfiles.tar birds}} would produce an 1467error message something like @samp{tar: birds: Not found in archive}, 1468because there is no member named @file{birds}, only one named 1469@file{./birds}. While the names @file{birds} and @file{./birds} name 1470the same file, @emph{member} names by default are compared verbatim. 1471 1472However, @w{@kbd{tar --list --file=bfiles.tar baboon}} would respond 1473with @file{baboon}, because this exact member name is in the archive file 1474@file{bfiles.tar}. If you are not sure of the exact file name, 1475use @dfn{globbing patterns}, for example: 1476 1477@smallexample 1478$ @kbd{tar --list --file=bfiles.tar --wildcards '*b*'} 1479@end smallexample 1480 1481@noindent 1482will list all members whose name contains @samp{b}. @xref{wildcards}, 1483for a detailed discussion of globbing patterns and related 1484@command{tar} command line options. 1485 1486@menu 1487* list dir:: 1488@end menu 1489 1490@node list dir 1491@unnumberedsubsec Listing the Contents of a Stored Directory 1492 1493To get information about the contents of an archived directory, 1494use the directory name as a file name argument in conjunction with 1495@option{--list} (@option{-t}). To find out file attributes, include the 1496@option{--verbose} (@option{-v}) option. 1497 1498For example, to find out about files in the directory @file{practice}, in 1499the archive file @file{music.tar}, type: 1500 1501@smallexample 1502$ @kbd{tar --list --verbose --file=music.tar practice} 1503@end smallexample 1504 1505@command{tar} responds: 1506 1507@smallexample 1508drwxrwxrwx myself user 0 1990-05-31 21:49 practice/ 1509-rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues 1510-rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk 1511-rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz 1512-rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar 1513@end smallexample 1514 1515When you use a directory name as a file name argument, @command{tar} acts on 1516all the files (including sub-directories) in that directory. 1517 1518@node extract 1519@section How to Extract Members from an Archive 1520@UNREVISED 1521@cindex Extraction 1522@cindex Retrieving files from an archive 1523@cindex Resurrecting files from an archive 1524 1525@opindex extract 1526Creating an archive is only half the job---there is no point in storing 1527files in an archive if you can't retrieve them. The act of retrieving 1528members from an archive so they can be used and manipulated as 1529unarchived files again is called @dfn{extraction}. To extract files 1530from an archive, use the @option{--extract} (@option{--get} or 1531@option{-x}) operation. As with @option{--create}, specify the name 1532of the archive with @option{--file} (@option{-f}) option. Extracting 1533an archive does not modify the archive in any way; you can extract it 1534multiple times if you want or need to. 1535 1536Using @option{--extract}, you can extract an entire archive, or specific 1537files. The files can be directories containing other files, or not. As 1538with @option{--create} (@option{-c}) and @option{--list} (@option{-t}), you may use the short or the 1539long form of the operation without affecting the performance. 1540 1541@menu 1542* extracting archives:: 1543* extracting files:: 1544* extract dir:: 1545* extracting untrusted archives:: 1546* failing commands:: 1547@end menu 1548 1549@node extracting archives 1550@subsection Extracting an Entire Archive 1551 1552To extract an entire archive, specify the archive file name only, with 1553no individual file names as arguments. For example, 1554 1555@smallexample 1556$ @kbd{tar -xvf collection.tar} 1557@end smallexample 1558 1559@noindent 1560produces this: 1561 1562@smallexample 1563-rw-r--r-- me user 28 1996-10-18 16:31 jazz 1564-rw-r--r-- me user 21 1996-09-23 16:44 blues 1565-rw-r--r-- me user 20 1996-09-23 16:44 folk 1566@end smallexample 1567 1568@node extracting files 1569@subsection Extracting Specific Files 1570 1571To extract specific archive members, give their exact member names as 1572arguments, as printed by @option{--list} (@option{-t}). If you had 1573mistakenly deleted one of the files you had placed in the archive 1574@file{collection.tar} earlier (say, @file{blues}), you can extract it 1575from the archive without changing the archive's structure. Its 1576contents will be identical to the original file @file{blues} that you 1577deleted. 1578 1579First, make sure you are in the @file{practice} directory, and list the 1580files in the directory. Now, delete the file, @samp{blues}, and list 1581the files in the directory again. 1582 1583You can now extract the member @file{blues} from the archive file 1584@file{collection.tar} like this: 1585 1586@smallexample 1587$ @kbd{tar --extract --file=collection.tar blues} 1588@end smallexample 1589 1590@noindent 1591If you list the files in the directory again, you will see that the file 1592@file{blues} has been restored, with its original permissions, data 1593modification times, and owner.@footnote{This is only accidentally 1594true, but not in general. Whereas modification times are always 1595restored, in most cases, one has to be root for restoring the owner, 1596and use a special option for restoring permissions. Here, it just 1597happens that the restoring user is also the owner of the archived 1598members, and that the current @code{umask} is compatible with original 1599permissions.} (These parameters will be identical to those which 1600the file had when you originally placed it in the archive; any changes 1601you may have made before deleting the file from the file system, 1602however, will @emph{not} have been made to the archive member.) The 1603archive file, @samp{collection.tar}, is the same as it was before you 1604extracted @samp{blues}. You can confirm this by running @command{tar} with 1605@option{--list} (@option{-t}). 1606 1607Remember that as with other operations, specifying the exact member 1608name is important. @w{@kbd{tar --extract --file=bfiles.tar birds}} 1609will fail, because there is no member named @file{birds}. To extract 1610the member named @file{./birds}, you must specify @w{@kbd{tar 1611--extract --file=bfiles.tar ./birds}}. If you don't remember the 1612exact member names, use @option{--list} (@option{-t}) option 1613(@pxref{list}). You can also extract those members that match a 1614specific @dfn{globbing pattern}. For example, to extract from 1615@file{bfiles.tar} all files that begin with @samp{b}, no matter their 1616directory prefix, you could type: 1617 1618@smallexample 1619$ @kbd{tar -x -f bfiles.tar --wildcards --no-anchored 'b*'} 1620@end smallexample 1621 1622@noindent 1623Here, @option{--wildcards} instructs @command{tar} to treat 1624command line arguments as globbing patterns and @option{--no-anchored} 1625informs it that the patterns apply to member names after any @samp{/} 1626delimiter. The use of globbing patterns is discussed in detail in 1627@xref{wildcards}. 1628 1629You can extract a file to standard output by combining the above options 1630with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard 1631Output}). 1632 1633If you give the @option{--verbose} option, then @option{--extract} 1634will print the names of the archive members as it extracts them. 1635 1636@node extract dir 1637@subsection Extracting Files that are Directories 1638 1639Extracting directories which are members of an archive is similar to 1640extracting other files. The main difference to be aware of is that if 1641the extracted directory has the same name as any directory already in 1642the working directory, then files in the extracted directory will be 1643placed into the directory of the same name. Likewise, if there are 1644files in the pre-existing directory with the same names as the members 1645which you extract, the files from the extracted archive will replace 1646the files already in the working directory (and possible 1647subdirectories). This will happen regardless of whether or not the 1648files in the working directory were more recent than those extracted 1649(there exist, however, special options that alter this behavior 1650@pxref{Writing}). 1651 1652However, if a file was stored with a directory name as part of its file 1653name, and that directory does not exist under the working directory when 1654the file is extracted, @command{tar} will create the directory. 1655 1656We can demonstrate how to use @option{--extract} to extract a directory 1657file with an example. Change to the @file{practice} directory if you 1658weren't there, and remove the files @file{folk} and @file{jazz}. Then, 1659go back to the parent directory and extract the archive 1660@file{music.tar}. You may either extract the entire archive, or you may 1661extract only the files you just deleted. To extract the entire archive, 1662don't give any file names as arguments after the archive name 1663@file{music.tar}. To extract only the files you deleted, use the 1664following command: 1665 1666@smallexample 1667$ @kbd{tar -xvf music.tar practice/folk practice/jazz} 1668practice/folk 1669practice/jazz 1670@end smallexample 1671 1672@noindent 1673If you were to specify two @option{--verbose} (@option{-v}) options, @command{tar} 1674would have displayed more detail about the extracted files, as shown 1675in the example below: 1676 1677@smallexample 1678$ @kbd{tar -xvvf music.tar practice/folk practice/jazz} 1679-rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz 1680-rw-r--r-- me user 20 1996-09-23 16:44 practice/folk 1681@end smallexample 1682 1683@noindent 1684Because you created the directory with @file{practice} as part of the 1685file names of each of the files by archiving the @file{practice} 1686directory as @file{practice}, you must give @file{practice} as part 1687of the file names when you extract those files from the archive. 1688 1689@node extracting untrusted archives 1690@subsection Extracting Archives from Untrusted Sources 1691 1692Extracting files from archives can overwrite files that already exist. 1693If you receive an archive from an untrusted source, you should make a 1694new directory and extract into that directory, so that you don't have 1695to worry about the extraction overwriting one of your existing files. 1696For example, if @file{untrusted.tar} came from somewhere else on the 1697Internet, and you don't necessarily trust its contents, you can 1698extract it as follows: 1699 1700@smallexample 1701$ @kbd{mkdir newdir} 1702$ @kbd{cd newdir} 1703$ @kbd{tar -xvf ../untrusted.tar} 1704@end smallexample 1705 1706It is also a good practice to examine contents of the archive 1707before extracting it, using @option{--list} (@option{-t}) option, possibly combined 1708with @option{--verbose} (@option{-v}). 1709 1710@node failing commands 1711@subsection Commands That Will Fail 1712 1713Here are some sample commands you might try which will not work, and why 1714they won't work. 1715 1716If you try to use this command, 1717 1718@smallexample 1719$ @kbd{tar -xvf music.tar folk jazz} 1720@end smallexample 1721 1722@noindent 1723you will get the following response: 1724 1725@smallexample 1726tar: folk: Not found in archive 1727tar: jazz: Not found in archive 1728$ 1729@end smallexample 1730 1731@noindent 1732This is because these files were not originally @emph{in} the parent 1733directory @file{..}, where the archive is located; they were in the 1734@file{practice} directory, and their file names reflect this: 1735 1736@smallexample 1737$ @kbd{tar -tvf music.tar} 1738practice/folk 1739practice/jazz 1740practice/rock 1741@end smallexample 1742 1743@FIXME{make sure the above works when going through the examples in 1744order...} 1745 1746@noindent 1747Likewise, if you try to use this command, 1748 1749@smallexample 1750$ @kbd{tar -tvf music.tar folk jazz} 1751@end smallexample 1752 1753@noindent 1754you would get a similar response. Members with those names are not in the 1755archive. You must use the correct member names, or wildcards, in order 1756to extract the files from the archive. 1757 1758If you have forgotten the correct names of the files in the archive, 1759use @w{@kbd{tar --list --verbose}} to list them correctly. 1760 1761@FIXME{more examples, here? hag thinks it's a good idea.} 1762 1763@node going further 1764@section Going Further Ahead in this Manual 1765 1766@FIXME{need to write up a node here about the things that are going to 1767be in the rest of the manual.} 1768 1769@node tar invocation 1770@chapter Invoking @GNUTAR{} 1771@UNREVISED 1772 1773This chapter is about how one invokes the @GNUTAR{} 1774command, from the command synopsis (@pxref{Synopsis}). There are 1775numerous options, and many styles for writing them. One mandatory 1776option specifies the operation @command{tar} should perform 1777(@pxref{Operation Summary}), other options are meant to detail how 1778this operation should be performed (@pxref{Option Summary}). 1779Non-option arguments are not always interpreted the same way, 1780depending on what the operation is. 1781 1782You will find in this chapter everything about option styles and rules for 1783writing them (@pxref{Styles}). On the other hand, operations and options 1784are fully described elsewhere, in other chapters. Here, you will find 1785only synthetic descriptions for operations and options, together with 1786pointers to other parts of the @command{tar} manual. 1787 1788Some options are so special they are fully described right in this 1789chapter. They have the effect of inhibiting the normal operation of 1790@command{tar} or else, they globally alter the amount of feedback the user 1791receives about what is going on. These are the @option{--help} and 1792@option{--version} (@pxref{help}), @option{--verbose} (@pxref{verbose}) 1793and @option{--interactive} options (@pxref{interactive}). 1794 1795@menu 1796* Synopsis:: 1797* using tar options:: 1798* Styles:: 1799* All Options:: 1800* help:: 1801* defaults:: 1802* verbose:: 1803* interactive:: 1804@end menu 1805 1806@node Synopsis 1807@section General Synopsis of @command{tar} 1808 1809The @GNUTAR{} program is invoked as either one of: 1810 1811@smallexample 1812@kbd{tar @var{option}@dots{} [@var{name}]@dots{}} 1813@kbd{tar @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}} 1814@end smallexample 1815 1816The second form is for when old options are being used. 1817 1818You can use @command{tar} to store files in an archive, to extract them from 1819an archive, and to do other types of archive manipulation. The primary 1820argument to @command{tar}, which is called the @dfn{operation}, specifies 1821which action to take. The other arguments to @command{tar} are either 1822@dfn{options}, which change the way @command{tar} performs an operation, 1823or file names or archive members, which specify the files or members 1824@command{tar} is to act on. 1825 1826You can actually type in arguments in any order, even if in this manual 1827the options always precede the other arguments, to make examples easier 1828to understand. Further, the option stating the main operation mode 1829(the @command{tar} main command) is usually given first. 1830 1831Each @var{name} in the synopsis above is interpreted as an archive member 1832name when the main command is one of @option{--compare} 1833(@option{--diff}, @option{-d}), @option{--delete}, @option{--extract} 1834(@option{--get}, @option{-x}), @option{--list} (@option{-t}) or 1835@option{--update} (@option{-u}). When naming archive members, you 1836must give the exact name of the member in the archive, as it is 1837printed by @option{--list}. For @option{--append} (@option{-r}) and 1838@option{--create} (@option{-c}), these @var{name} arguments specify 1839the names of either files or directory hierarchies to place in the archive. 1840These files or hierarchies should already exist in the file system, 1841prior to the execution of the @command{tar} command. 1842 1843@command{tar} interprets relative file names as being relative to the 1844working directory. @command{tar} will make all file names relative 1845(by removing leading slashes when archiving or restoring files), 1846unless you specify otherwise (using the @option{--absolute-names} 1847option). @xref{absolute}, for more information about 1848@option{--absolute-names}. 1849 1850If you give the name of a directory as either a file name or a member 1851name, then @command{tar} acts recursively on all the files and directories 1852beneath that directory. For example, the name @file{/} identifies all 1853the files in the file system to @command{tar}. 1854 1855The distinction between file names and archive member names is especially 1856important when shell globbing is used, and sometimes a source of confusion 1857for newcomers. @xref{wildcards}, for more information about globbing. 1858The problem is that shells may only glob using existing files in the 1859file system. Only @command{tar} itself may glob on archive members, so when 1860needed, you must ensure that wildcard characters reach @command{tar} without 1861being interpreted by the shell first. Using a backslash before @samp{*} 1862or @samp{?}, or putting the whole argument between quotes, is usually 1863sufficient for this. 1864 1865Even if @var{name}s are often specified on the command line, they 1866can also be read from a text file in the file system, using the 1867@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) option. 1868 1869If you don't use any file name arguments, @option{--append} (@option{-r}), 1870@option{--delete} and @option{--concatenate} (@option{--catenate}, 1871@option{-A}) will do nothing, while @option{--create} (@option{-c}) 1872will usually yield a diagnostic and inhibit @command{tar} execution. 1873The other operations of @command{tar} (@option{--list}, 1874@option{--extract}, @option{--compare}, and @option{--update}) 1875will act on the entire contents of the archive. 1876 1877@cindex exit status 1878@cindex return status 1879Besides successful exits, @GNUTAR{} may fail for 1880many reasons. Some reasons correspond to bad usage, that is, when the 1881@command{tar} command is improperly written. Errors may be 1882encountered later, while encountering an error processing the archive 1883or the files. Some errors are recoverable, in which case the failure 1884is delayed until @command{tar} has completed all its work. Some 1885errors are such that it would not meaningful, or at least risky, to 1886continue processing: @command{tar} then aborts processing immediately. 1887All abnormal exits, whether immediate or delayed, should always be 1888clearly diagnosed on @code{stderr}, after a line stating the nature of 1889the error. 1890 1891Possible exit codes of @GNUTAR{} are summarized in the following 1892table: 1893 1894@table @asis 1895@item 0 1896@samp{Successful termination}. 1897 1898@item 1 1899@samp{Some files differ}. If tar was invoked with @option{--compare} 1900(@option{--diff}, @option{-d}) command line option, this means that 1901some files in the archive differ from their disk counterparts 1902(@pxref{compare}). If tar was given @option{--create}, 1903@option{--append} or @option{--update} option, this exit code means 1904that some files were changed while being archived and so the resulting 1905archive does not contain the exact copy of the file set. 1906 1907@item 2 1908@samp{Fatal error}. This means that some fatal, unrecoverable error 1909occurred. 1910@end table 1911 1912If @command{tar} has invoked a subprocess and that subprocess exited with a 1913nonzero exit code, @command{tar} exits with that code as well. 1914This can happen, for example, if @command{tar} was given some 1915compression option (@pxref{gzip}) and the external compressor program 1916failed. Another example is @command{rmt} failure during backup to the 1917remote device (@pxref{Remote Tape Server}). 1918 1919@node using tar options 1920@section Using @command{tar} Options 1921 1922@GNUTAR{} has a total of eight operating modes which 1923allow you to perform a variety of tasks. You are required to choose 1924one operating mode each time you employ the @command{tar} program by 1925specifying one, and only one operation as an argument to the 1926@command{tar} command (two lists of four operations each may be found 1927at @ref{frequent operations} and @ref{Operations}). Depending on 1928circumstances, you may also wish to customize how the chosen operating 1929mode behaves. For example, you may wish to change the way the output 1930looks, or the format of the files that you wish to archive may require 1931you to do something special in order to make the archive look right. 1932 1933You can customize and control @command{tar}'s performance by running 1934@command{tar} with one or more options (such as @option{--verbose} 1935(@option{-v}), which we used in the tutorial). As we said in the 1936tutorial, @dfn{options} are arguments to @command{tar} which are (as 1937their name suggests) optional. Depending on the operating mode, you 1938may specify one or more options. Different options will have different 1939effects, but in general they all change details of the operation, such 1940as archive format, archive name, or level of user interaction. Some 1941options make sense with all operating modes, while others are 1942meaningful only with particular modes. You will likely use some 1943options frequently, while you will only use others infrequently, or 1944not at all. (A full list of options is available in @pxref{All Options}.) 1945 1946@vrindex TAR_OPTIONS, environment variable 1947@anchor{TAR_OPTIONS} 1948The @env{TAR_OPTIONS} environment variable specifies default options to 1949be placed in front of any explicit options. For example, if 1950@code{TAR_OPTIONS} is @samp{-v --unlink-first}, @command{tar} behaves as 1951if the two options @option{-v} and @option{--unlink-first} had been 1952specified before any explicit options. Option specifications are 1953separated by whitespace. A backslash escapes the next character, so it 1954can be used to specify an option containing whitespace or a backslash. 1955 1956Note that @command{tar} options are case sensitive. For example, the 1957options @option{-T} and @option{-t} are different; the first requires an 1958argument for stating the name of a file providing a list of @var{name}s, 1959while the second does not require an argument and is another way to 1960write @option{--list} (@option{-t}). 1961 1962In addition to the eight operations, there are many options to 1963@command{tar}, and three different styles for writing both: long (mnemonic) 1964form, short form, and old style. These styles are discussed below. 1965Both the options and the operations can be written in any of these three 1966styles. 1967 1968@FIXME{menu at end of this node. need to think of an actual outline 1969for this chapter; probably do that after stuff from chapter 4 is 1970incorporated.} 1971 1972@node Styles 1973@section The Three Option Styles 1974 1975There are three styles for writing operations and options to the command 1976line invoking @command{tar}. The different styles were developed at 1977different times during the history of @command{tar}. These styles will be 1978presented below, from the most recent to the oldest. 1979 1980Some options must take an argument. (For example, @option{--file} 1981(@option{-f})) takes the name of an archive file as an argument. If 1982you do not supply an archive file name, @command{tar} will use a 1983default, but this can be confusing; thus, we recommend that you always 1984supply a specific archive file name.) Where you @emph{place} the 1985arguments generally depends on which style of options you choose. We 1986will detail specific information relevant to each option style in the 1987sections on the different option styles, below. The differences are 1988subtle, yet can often be very important; incorrect option placement 1989can cause you to overwrite a number of important files. We urge you 1990to note these differences, and only use the option style(s) which 1991makes the most sense to you until you feel comfortable with the others. 1992 1993Some options @emph{may} take an argument. Such options may have at 1994most long and short forms, they do not have old style equivalent. The 1995rules for specifying an argument for such options are stricter than 1996those for specifying mandatory arguments. Please, pay special 1997attention to them. 1998 1999@menu 2000* Long Options:: Long Option Style 2001* Short Options:: Short Option Style 2002* Old Options:: Old Option Style 2003* Mixing:: Mixing Option Styles 2004@end menu 2005 2006@node Long Options 2007@subsection Long Option Style 2008 2009Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with two 2010dashes in a row, e.g., @option{--list}. The long names are more clear than 2011their corresponding short or old names. It sometimes happens that a 2012single long option has many different names which are 2013synonymous, such as @option{--compare} and @option{--diff}. In addition, 2014long option names can be given unique abbreviations. For example, 2015@option{--cre} can be used in place of @option{--create} because there is no 2016other long option which begins with @samp{cre}. (One way to find 2017this out is by trying it and seeing what happens; if a particular 2018abbreviation could represent more than one option, @command{tar} will tell 2019you that that abbreviation is ambiguous and you'll know that that 2020abbreviation won't work. You may also choose to run @samp{tar --help} 2021to see a list of options. Be aware that if you run @command{tar} with a 2022unique abbreviation for the long name of an option you didn't want to 2023use, you are stuck; @command{tar} will perform the command as ordered.) 2024 2025Long options are meant to be obvious and easy to remember, and their 2026meanings are generally easier to discern than those of their 2027corresponding short options (see below). For example: 2028 2029@smallexample 2030$ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0} 2031@end smallexample 2032 2033@noindent 2034gives a fairly good set of hints about what the command does, even 2035for those not fully acquainted with @command{tar}. 2036 2037Long options which require arguments take those arguments 2038immediately following the option name. There are two ways of 2039specifying a mandatory argument. It can be separated from the 2040option name either by an equal sign, or by any amount of 2041white space characters. For example, the @option{--file} option (which 2042tells the name of the @command{tar} archive) is given a file such as 2043@file{archive.tar} as argument by using any of the following notations: 2044@option{--file=archive.tar} or @option{--file archive.tar}. 2045 2046In contrast, optional arguments must always be introduced using 2047an equal sign. For example, the @option{--backup} option takes 2048an optional argument specifying backup type. It must be used 2049as @option{--backup=@var{backup-type}}. 2050 2051@node Short Options 2052@subsection Short Option Style 2053 2054Most options also have a @dfn{short option} name. Short options start with 2055a single dash, and are followed by a single character, e.g., @option{-t} 2056(which is equivalent to @option{--list}). The forms are absolutely 2057identical in function; they are interchangeable. 2058 2059The short option names are faster to type than long option names. 2060 2061Short options which require arguments take their arguments immediately 2062following the option, usually separated by white space. It is also 2063possible to stick the argument right after the short option name, using 2064no intervening space. For example, you might write @w{@option{-f 2065archive.tar}} or @option{-farchive.tar} instead of using 2066@option{--file=archive.tar}. Both @option{--file=@var{archive-name}} and 2067@w{@option{-f @var{archive-name}}} denote the option which indicates a 2068specific archive, here named @file{archive.tar}. 2069 2070Short options which take optional arguments take their arguments 2071immediately following the option letter, @emph{without any intervening 2072white space characters}. 2073 2074Short options' letters may be clumped together, but you are not 2075required to do this (as compared to old options; see below). When 2076short options are clumped as a set, use one (single) dash for them 2077all, e.g., @w{@samp{@command{tar} -cvf}}. Only the last option in 2078such a set is allowed to have an argument@footnote{Clustering many 2079options, the last of which has an argument, is a rather opaque way to 2080write options. Some wonder if @acronym{GNU} @code{getopt} should not 2081even be made helpful enough for considering such usages as invalid.}. 2082 2083When the options are separated, the argument for each option which requires 2084an argument directly follows that option, as is usual for Unix programs. 2085For example: 2086 2087@smallexample 2088$ @kbd{tar -c -v -b 20 -f /dev/rmt0} 2089@end smallexample 2090 2091If you reorder short options' locations, be sure to move any arguments 2092that belong to them. If you do not move the arguments properly, you may 2093end up overwriting files. 2094 2095@node Old Options 2096@subsection Old Option Style 2097@UNREVISED 2098 2099Like short options, @dfn{old options} are single letters. However, old options 2100must be written together as a single clumped set, without spaces separating 2101them or dashes preceding them@footnote{Beware that if you precede options 2102with a dash, you are announcing the short option style instead of the 2103old option style; short options are decoded differently.}. This set 2104of letters must be the first to appear on the command line, after the 2105@command{tar} program name and some white space; old options cannot appear 2106anywhere else. The letter of an old option is exactly the same letter as 2107the corresponding short option. For example, the old option @samp{t} is 2108the same as the short option @option{-t}, and consequently, the same as the 2109long option @option{--list}. So for example, the command @w{@samp{tar 2110cv}} specifies the option @option{-v} in addition to the operation @option{-c}. 2111 2112When options that need arguments are given together with the command, 2113all the associated arguments follow, in the same order as the options. 2114Thus, the example given previously could also be written in the old 2115style as follows: 2116 2117@smallexample 2118$ @kbd{tar cvbf 20 /dev/rmt0} 2119@end smallexample 2120 2121@noindent 2122Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is 2123the argument of @option{-f}. 2124 2125On the other hand, this old style syntax makes it difficult to match 2126option letters with their corresponding arguments, and is often 2127confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example, 2128@samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the 2129argument for @option{-f}, and @option{-v} does not have a corresponding 2130argument. Even using short options like in @w{@samp{tar -c -v -b 20 -f 2131/dev/rmt0}} is clearer, putting all arguments next to the option they 2132pertain to. 2133 2134If you want to reorder the letters in the old option argument, be 2135sure to reorder any corresponding argument appropriately. 2136 2137This old way of writing @command{tar} options can surprise even experienced 2138users. For example, the two commands: 2139 2140@smallexample 2141@kbd{tar cfz archive.tar.gz file} 2142@kbd{tar -cfz archive.tar.gz file} 2143@end smallexample 2144 2145@noindent 2146are quite different. The first example uses @file{archive.tar.gz} as 2147the value for option @samp{f} and recognizes the option @samp{z}. The 2148second example, however, uses @file{z} as the value for option 2149@samp{f} --- probably not what was intended. 2150 2151Old options are kept for compatibility with old versions of @command{tar}. 2152 2153This second example could be corrected in many ways, among which the 2154following are equivalent: 2155 2156@smallexample 2157@kbd{tar -czf archive.tar.gz file} 2158@kbd{tar -cf archive.tar.gz -z file} 2159@kbd{tar cf archive.tar.gz -z file} 2160@end smallexample 2161 2162@cindex option syntax, traditional 2163As far as we know, all @command{tar} programs, @acronym{GNU} and 2164non-@acronym{GNU}, support old options. @GNUTAR{} 2165supports them not only for historical reasons, but also because many 2166people are used to them. For compatibility with Unix @command{tar}, 2167the first argument is always treated as containing command and option 2168letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is 2169equivalent to @w{@samp{tar -c}:} both of them specify the 2170@option{--create} (@option{-c}) command to create an archive. 2171 2172@node Mixing 2173@subsection Mixing Option Styles 2174 2175All three styles may be intermixed in a single @command{tar} command, 2176so long as the rules for each style are fully 2177respected@footnote{Before @GNUTAR{} version 1.11.6, 2178a bug prevented intermixing old style options with long options in 2179some cases.}. Old style options and either of the modern styles of 2180options may be mixed within a single @command{tar} command. However, 2181old style options must be introduced as the first arguments only, 2182following the rule for old options (old options must appear directly 2183after the @command{tar} command and some white space). Modern options 2184may be given only after all arguments to the old options have been 2185collected. If this rule is not respected, a modern option might be 2186falsely interpreted as the value of the argument to one of the old 2187style options. 2188 2189For example, all the following commands are wholly equivalent, and 2190illustrate the many combinations and orderings of option styles. 2191 2192@smallexample 2193@kbd{tar --create --file=archive.tar} 2194@kbd{tar --create -f archive.tar} 2195@kbd{tar --create -farchive.tar} 2196@kbd{tar --file=archive.tar --create} 2197@kbd{tar --file=archive.tar -c} 2198@kbd{tar -c --file=archive.tar} 2199@kbd{tar -c -f archive.tar} 2200@kbd{tar -c -farchive.tar} 2201@kbd{tar -cf archive.tar} 2202@kbd{tar -cfarchive.tar} 2203@kbd{tar -f archive.tar --create} 2204@kbd{tar -f archive.tar -c} 2205@kbd{tar -farchive.tar --create} 2206@kbd{tar -farchive.tar -c} 2207@kbd{tar c --file=archive.tar} 2208@kbd{tar c -f archive.tar} 2209@kbd{tar c -farchive.tar} 2210@kbd{tar cf archive.tar} 2211@kbd{tar f archive.tar --create} 2212@kbd{tar f archive.tar -c} 2213@kbd{tar fc archive.tar} 2214@end smallexample 2215 2216On the other hand, the following commands are @emph{not} equivalent to 2217the previous set: 2218 2219@smallexample 2220@kbd{tar -f -c archive.tar} 2221@kbd{tar -fc archive.tar} 2222@kbd{tar -fcarchive.tar} 2223@kbd{tar -farchive.tarc} 2224@kbd{tar cfarchive.tar} 2225@end smallexample 2226 2227@noindent 2228These last examples mean something completely different from what the 2229user intended (judging based on the example in the previous set which 2230uses long options, whose intent is therefore very clear). The first 2231four specify that the @command{tar} archive would be a file named 2232@option{-c}, @samp{c}, @samp{carchive.tar} or @samp{archive.tarc}, 2233respectively. The first two examples also specify a single non-option, 2234@var{name} argument having the value @samp{archive.tar}. The last 2235example contains only old style option letters (repeating option 2236@samp{c} twice), not all of which are meaningful (eg., @samp{.}, 2237@samp{h}, or @samp{i}), with no argument value. @FIXME{not sure i liked 2238the first sentence of this paragraph..} 2239 2240@node All Options 2241@section All @command{tar} Options 2242 2243The coming manual sections contain an alphabetical listing of all 2244@command{tar} operations and options, with brief descriptions and cross 2245references to more in-depth explanations in the body of the manual. 2246They also contain an alphabetically arranged table of the short option 2247forms with their corresponding long option. You can use this table as 2248a reference for deciphering @command{tar} commands in scripts. 2249 2250@menu 2251* Operation Summary:: 2252* Option Summary:: 2253* Short Option Summary:: 2254@end menu 2255 2256@node Operation Summary 2257@subsection Operations 2258 2259@table @option 2260 2261@opsummary{append} 2262@item --append 2263@itemx -r 2264 2265Appends files to the end of the archive. @xref{append}. 2266 2267@opsummary{catenate} 2268@item --catenate 2269@itemx -A 2270 2271Same as @option{--concatenate}. @xref{concatenate}. 2272 2273@opsummary{compare} 2274@item --compare 2275@itemx -d 2276 2277Compares archive members with their counterparts in the file 2278system, and reports differences in file size, mode, owner, 2279modification date and contents. @xref{compare}. 2280 2281@opsummary{concatenate} 2282@item --concatenate 2283@itemx -A 2284 2285Appends other @command{tar} archives to the end of the archive. 2286@xref{concatenate}. 2287 2288@opsummary{create} 2289@item --create 2290@itemx -c 2291 2292Creates a new @command{tar} archive. @xref{create}. 2293 2294@opsummary{delete} 2295@item --delete 2296 2297Deletes members from the archive. Don't try this on a archive on a 2298tape! @xref{delete}. 2299 2300@opsummary{diff} 2301@item --diff 2302@itemx -d 2303 2304Same @option{--compare}. @xref{compare}. 2305 2306@opsummary{extract} 2307@item --extract 2308@itemx -x 2309 2310Extracts members from the archive into the file system. @xref{extract}. 2311 2312@opsummary{get} 2313@item --get 2314@itemx -x 2315 2316Same as @option{--extract}. @xref{extract}. 2317 2318@opsummary{list} 2319@item --list 2320@itemx -t 2321 2322Lists the members in an archive. @xref{list}. 2323 2324@opsummary{update} 2325@item --update 2326@itemx -u 2327 2328Adds files to the end of the archive, but only if they are newer than 2329their counterparts already in the archive, or if they do not already 2330exist in the archive. @xref{update}. 2331 2332@end table 2333 2334@node Option Summary 2335@subsection @command{tar} Options 2336 2337@table @option 2338 2339@opsummary{absolute-names} 2340@item --absolute-names 2341@itemx -P 2342 2343Normally when creating an archive, @command{tar} strips an initial 2344@samp{/} from member names. This option disables that behavior. 2345@xref{absolute}. 2346 2347@opsummary{after-date} 2348@item --after-date 2349 2350(See @option{--newer}, @pxref{after}) 2351 2352@opsummary{anchored} 2353@item --anchored 2354A pattern must match an initial subsequence of the name's components. 2355@xref{controlling pattern-matching}. 2356 2357@opsummary{atime-preserve} 2358@item --atime-preserve 2359@itemx --atime-preserve=replace 2360@itemx --atime-preserve=system 2361 2362Attempt to preserve the access time of files when reading them. This 2363option currently is effective only on files that you own, unless you 2364have superuser privileges. 2365 2366@option{--atime-preserve=replace} remembers the access time of a file 2367before reading it, and then restores the access time afterwards. This 2368may cause problems if other programs are reading the file at the same 2369time, as the times of their accesses will be lost. On most platforms 2370restoring the access time also requires @command{tar} to restore the 2371data modification time too, so this option may also cause problems if 2372other programs are writing the file at the same time. (Tar attempts 2373to detect this situation, but cannot do so reliably due to race 2374conditions.) Worse, on most platforms restoring the access time also 2375updates the status change time, which means that this option is 2376incompatible with incremental backups. 2377 2378@option{--atime-preserve=system} avoids changing time stamps on files, 2379without interfering with time stamp updates 2380caused by other programs, so it works better with incremental backups. 2381However, it requires a special @code{O_NOATIME} option from the 2382underlying operating and file system implementation, and it also requires 2383that searching directories does not update their access times. As of 2384this writing (November 2005) this works only with Linux, and only with 2385Linux kernels 2.6.8 and later. Worse, there is currently no reliable 2386way to know whether this feature actually works. Sometimes 2387@command{tar} knows that it does not work, and if you use 2388@option{--atime-preserve=system} then @command{tar} complains and 2389exits right away. But other times @command{tar} might think that the 2390option works when it actually does not. 2391 2392Currently @option{--atime-preserve} with no operand defaults to 2393@option{--atime-preserve=replace}, but this may change in the future 2394as support for @option{--atime-preserve=system} improves. 2395 2396If your operating system does not support 2397@option{--atime-preserve=@-system}, you might be able to preserve access 2398times reliably by by using the @command{mount} command. For example, 2399you can mount the file system read-only, or access the file system via 2400a read-only loopback mount, or use the @samp{noatime} mount option 2401available on some systems. However, mounting typically requires 2402superuser privileges and can be a pain to manage. 2403 2404@opsummary{backup} 2405@item --backup=@var{backup-type} 2406 2407Rather than deleting files from the file system, @command{tar} will 2408back them up using simple or numbered backups, depending upon 2409@var{backup-type}. @xref{backup}. 2410 2411@opsummary{block-number} 2412@item --block-number 2413@itemx -R 2414 2415With this option present, @command{tar} prints error messages for read errors 2416with the block number in the archive file. @xref{block-number}. 2417 2418@opsummary{blocking-factor} 2419@item --blocking-factor=@var{blocking} 2420@itemx -b @var{blocking} 2421 2422Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per 2423record. @xref{Blocking Factor}. 2424 2425@opsummary{bzip2} 2426@item --bzip2 2427@itemx -j 2428 2429This option tells @command{tar} to read or write archives through 2430@code{bzip2}. @xref{gzip}. 2431 2432@opsummary{checkpoint} 2433@item --checkpoint[=@var{number}] 2434 2435This option directs @command{tar} to print periodic checkpoint 2436messages as it reads through the archive. It is intended for when you 2437want a visual indication that @command{tar} is still running, but 2438don't want to see @option{--verbose} output. For a detailed 2439description, see @ref{Progress information}. 2440 2441@opsummary{check-links} 2442@item --check-links 2443@itemx -l 2444If this option was given, @command{tar} will check the number of links 2445dumped for each processed file. If this number does not match the 2446total number of hard links for the file, a warning message will be 2447output @footnote{Earlier versions of @GNUTAR{} understood @option{-l} as a 2448synonym for @option{--one-file-system}. The current semantics, which 2449complies to UNIX98, was introduced with version 24501.15.91. @xref{Changes}, for more information.}. 2451 2452@opsummary{compress} 2453@opsummary{uncompress} 2454@item --compress 2455@itemx --uncompress 2456@itemx -Z 2457 2458@command{tar} will use the @command{compress} program when reading or 2459writing the archive. This allows you to directly act on archives 2460while saving space. @xref{gzip}. 2461 2462@opsummary{confirmation} 2463@item --confirmation 2464 2465(See @option{--interactive}.) @xref{interactive}. 2466 2467@opsummary{delay-directory-restore} 2468@item --delay-directory-restore 2469 2470Delay setting modification times and permissions of extracted 2471directories until the end of extraction. @xref{Directory Modification Times and Permissions}. 2472 2473@opsummary{dereference} 2474@item --dereference 2475@itemx -h 2476 2477When creating a @command{tar} archive, @command{tar} will archive the 2478file that a symbolic link points to, rather than archiving the 2479symlink. @xref{dereference}. 2480 2481@opsummary{directory} 2482@item --directory=@var{dir} 2483@itemx -C @var{dir} 2484 2485When this option is specified, @command{tar} will change its current directory 2486to @var{dir} before performing any operations. When this option is used 2487during archive creation, it is order sensitive. @xref{directory}. 2488 2489@opsummary{exclude} 2490@item --exclude=@var{pattern} 2491 2492When performing operations, @command{tar} will skip files that match 2493@var{pattern}. @xref{exclude}. 2494 2495@opsummary{exclude-from} 2496@item --exclude-from=@var{file} 2497@itemx -X @var{file} 2498 2499Similar to @option{--exclude}, except @command{tar} will use the list of 2500patterns in the file @var{file}. @xref{exclude}. 2501 2502@opsummary{exclude-caches} 2503@item --exclude-caches 2504 2505Exclude from dump any directory containing a valid cache directory 2506tag file, but still dump the directory node and the tag file itself. 2507 2508@xref{exclude}. 2509 2510@opsummary{exclude-caches-under} 2511@item --exclude-caches-under 2512 2513Exclude from dump any directory containing a valid cache directory 2514tag file, but still dump the directory node itself. 2515 2516@xref{exclude}. 2517 2518@opsummary{exclude-caches-all} 2519@item --exclude-caches-all 2520 2521Exclude from dump any directory containing a valid cache directory 2522tag file. @xref{exclude}. 2523 2524@opsummary{exclude-tag} 2525@item --exclude-tag=@var{file} 2526 2527Exclude from dump any directory containing file named @var{file}, but 2528dump the directory node and @var{file} itself. @xref{exclude}. 2529 2530@opsummary{exclude-tag-under} 2531@item --exclude-tag-under=@var{file} 2532 2533Exclude from dump the contents of any directory containing file 2534named @var{file}, but dump the directory node itself. @xref{exclude}. 2535 2536@opsummary{exclude-tag-all} 2537@item --exclude-tag-all=@var{file} 2538 2539Exclude from dump any directory containing file named @var{file}. 2540@xref{exclude}. 2541 2542@opsummary{file} 2543@item --file=@var{archive} 2544@itemx -f @var{archive} 2545 2546@command{tar} will use the file @var{archive} as the @command{tar} archive it 2547performs operations on, rather than @command{tar}'s compilation dependent 2548default. @xref{file tutorial}. 2549 2550@opsummary{files-from} 2551@item --files-from=@var{file} 2552@itemx -T @var{file} 2553 2554@command{tar} will use the contents of @var{file} as a list of archive members 2555or files to operate on, in addition to those specified on the 2556command-line. @xref{files}. 2557 2558@opsummary{force-local} 2559@item --force-local 2560 2561Forces @command{tar} to interpret the file name given to @option{--file} 2562as a local file, even if it looks like a remote tape drive name. 2563@xref{local and remote archives}. 2564 2565@opsummary{format} 2566@item --format=@var{format} 2567@itemx -H @var{format} 2568 2569Selects output archive format. @var{Format} may be one of the 2570following: 2571 2572@table @samp 2573@item v7 2574Creates an archive that is compatible with Unix V7 @command{tar}. 2575 2576@item oldgnu 2577Creates an archive that is compatible with GNU @command{tar} version 25781.12 or earlier. 2579 2580@item gnu 2581Creates archive in GNU tar 1.13 format. Basically it is the same as 2582@samp{oldgnu} with the only difference in the way it handles long 2583numeric fields. 2584 2585@item ustar 2586Creates a @acronym{POSIX.1-1988} compatible archive. 2587 2588@item posix 2589Creates a @acronym{POSIX.1-2001 archive}. 2590 2591@end table 2592 2593@xref{Formats}, for a detailed discussion of these formats. 2594 2595@opsummary{group} 2596@item --group=@var{group} 2597 2598Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group}, 2599rather than the group from the source file. @var{group} is first decoded 2600as a group symbolic name, but if this interpretation fails, it has to be 2601a decimal numeric group @acronym{ID}. @xref{override}. 2602 2603Also see the comments for the @option{--owner=@var{user}} option. 2604 2605@opsummary{gzip} 2606@opsummary{gunzip} 2607@opsummary{ungzip} 2608@item --gzip 2609@itemx --gunzip 2610@itemx --ungzip 2611@itemx -z 2612 2613This option tells @command{tar} to read or write archives through 2614@command{gzip}, allowing @command{tar} to directly operate on several 2615kinds of compressed archives transparently. @xref{gzip}. 2616 2617@opsummary{help} 2618@item --help 2619@itemx -? 2620 2621@command{tar} will print out a short message summarizing the operations and 2622options to @command{tar} and exit. @xref{help}. 2623 2624@opsummary{ignore-case} 2625@item --ignore-case 2626Ignore case when matching member or file names with 2627patterns. @xref{controlling pattern-matching}. 2628 2629@opsummary{ignore-command-error} 2630@item --ignore-command-error 2631Ignore exit codes of subprocesses. @xref{Writing to an External Program}. 2632 2633@opsummary{ignore-failed-read} 2634@item --ignore-failed-read 2635 2636Do not exit unsuccessfully merely because an unreadable file was encountered. 2637@xref{Reading}. 2638 2639@opsummary{ignore-zeros} 2640@item --ignore-zeros 2641@itemx -i 2642 2643With this option, @command{tar} will ignore zeroed blocks in the 2644archive, which normally signals EOF. @xref{Reading}. 2645 2646@opsummary{incremental} 2647@item --incremental 2648@itemx -G 2649 2650Informs @command{tar} that it is working with an old 2651@acronym{GNU}-format incremental backup archive. It is intended 2652primarily for backwards compatibility only. @xref{Incremental Dumps}, 2653for a detailed discussion of incremental archives. 2654 2655@opsummary{index-file} 2656@item --index-file=@var{file} 2657 2658Send verbose output to @var{file} instead of to standard output. 2659 2660@opsummary{info-script} 2661@opsummary{new-volume-script} 2662@item --info-script=@var{script-file} 2663@itemx --new-volume-script=@var{script-file} 2664@itemx -F @var{script-file} 2665 2666When @command{tar} is performing multi-tape backups, @var{script-file} is run 2667at the end of each tape. If @var{script-file} exits with nonzero status, 2668@command{tar} fails immediately. @xref{info-script}, for a detailed 2669discussion of @var{script-file}. 2670 2671@opsummary{interactive} 2672@item --interactive 2673@itemx --confirmation 2674@itemx -w 2675 2676Specifies that @command{tar} should ask the user for confirmation before 2677performing potentially destructive options, such as overwriting files. 2678@xref{interactive}. 2679 2680@opsummary{keep-newer-files} 2681@item --keep-newer-files 2682 2683Do not replace existing files that are newer than their archive copies 2684when extracting files from an archive. 2685 2686@opsummary{keep-old-files} 2687@item --keep-old-files 2688@itemx -k 2689 2690Do not overwrite existing files when extracting files from an archive. 2691@xref{Keep Old Files}. 2692 2693@opsummary{label} 2694@item --label=@var{name} 2695@itemx -V @var{name} 2696 2697When creating an archive, instructs @command{tar} to write @var{name} 2698as a name record in the archive. When extracting or listing archives, 2699@command{tar} will only operate on archives that have a label matching 2700the pattern specified in @var{name}. @xref{Tape Files}. 2701 2702@opsummary{listed-incremental} 2703@item --listed-incremental=@var{snapshot-file} 2704@itemx -g @var{snapshot-file} 2705 2706During a @option{--create} operation, specifies that the archive that 2707@command{tar} creates is a new @acronym{GNU}-format incremental 2708backup, using @var{snapshot-file} to determine which files to backup. 2709With other operations, informs @command{tar} that the archive is in 2710incremental format. @xref{Incremental Dumps}. 2711 2712@opsummary{mode} 2713@item --mode=@var{permissions} 2714 2715When adding files to an archive, @command{tar} will use 2716@var{permissions} for the archive members, rather than the permissions 2717from the files. @var{permissions} can be specified either as an octal 2718number or as symbolic permissions, like with 2719@command{chmod}. @xref{override}. 2720 2721@opsummary{mtime} 2722@item --mtime=@var{date} 2723 2724When adding files to an archive, @command{tar} will use @var{date} as 2725the modification time of members when creating archives, instead of 2726their actual modification times. The value of @var{date} can be 2727either a textual date representation (@pxref{Date input formats}) or a 2728name of the existing file, starting with @samp{/} or @samp{.}. In the 2729latter case, the modification time of that file is used. @xref{override}. 2730 2731@opsummary{multi-volume} 2732@item --multi-volume 2733@itemx -M 2734 2735Informs @command{tar} that it should create or otherwise operate on a 2736multi-volume @command{tar} archive. @xref{Using Multiple Tapes}. 2737 2738@opsummary{new-volume-script} 2739@item --new-volume-script 2740 2741(see --info-script) 2742 2743@opsummary{newer} 2744@item --newer=@var{date} 2745@itemx --after-date=@var{date} 2746@itemx -N 2747 2748When creating an archive, @command{tar} will only add files that have changed 2749since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it 2750is taken to be the name of a file whose data modification time specifies 2751the date. @xref{after}. 2752 2753@opsummary{newer-mtime} 2754@item --newer-mtime=@var{date} 2755 2756Like @option{--newer}, but add only files whose 2757contents have changed (as opposed to just @option{--newer}, which will 2758also back up files for which any status information has 2759changed). @xref{after}. 2760 2761@opsummary{no-anchored} 2762@item --no-anchored 2763An exclude pattern can match any subsequence of the name's components. 2764@xref{controlling pattern-matching}. 2765 2766@opsummary{no-delay-directory-restore} 2767@item --no-delay-directory-restore 2768 2769Modification times and permissions of extracted 2770directories are set when all files from this directory have been 2771extracted. This is the default. 2772@xref{Directory Modification Times and Permissions}. 2773 2774@opsummary{no-ignore-case} 2775@item --no-ignore-case 2776Use case-sensitive matching. 2777@xref{controlling pattern-matching}. 2778 2779@opsummary{no-ignore-command-error} 2780@item --no-ignore-command-error 2781Print warnings about subprocesses that terminated with a nonzero exit 2782code. @xref{Writing to an External Program}. 2783 2784@opsummary{no-overwrite-dir} 2785@item --no-overwrite-dir 2786 2787Preserve metadata of existing directories when extracting files 2788from an archive. @xref{Overwrite Old Files}. 2789 2790@opsummary{no-quote-chars} 2791@item --no-quote-chars=@var{string} 2792Remove characters listed in @var{string} from the list of quoted 2793characters set by the previous @option{--quote-chars} option 2794(@pxref{quoting styles}). 2795 2796@opsummary{no-recursion} 2797@item --no-recursion 2798 2799With this option, @command{tar} will not recurse into directories. 2800@xref{recurse}. 2801 2802@opsummary{no-same-owner} 2803@item --no-same-owner 2804@itemx -o 2805 2806When extracting an archive, do not attempt to preserve the owner 2807specified in the @command{tar} archive. This the default behavior 2808for ordinary users. 2809 2810@opsummary{no-same-permissions} 2811@item --no-same-permissions 2812 2813When extracting an archive, subtract the user's umask from files from 2814the permissions specified in the archive. This is the default behavior 2815for ordinary users. 2816 2817@opsummary{no-unquote} 2818@item --no-unquote 2819Treat all input file or member names literally, do not interpret 2820escape sequences. @xref{input name quoting}. 2821 2822@opsummary{no-wildcards} 2823@item --no-wildcards 2824Do not use wildcards. 2825@xref{controlling pattern-matching}. 2826 2827@opsummary{no-wildcards-match-slash} 2828@item --no-wildcards-match-slash 2829Wildcards do not match @samp{/}. 2830@xref{controlling pattern-matching}. 2831 2832@opsummary{null} 2833@item --null 2834 2835When @command{tar} is using the @option{--files-from} option, this option 2836instructs @command{tar} to expect file names terminated with @acronym{NUL}, so 2837@command{tar} can correctly work with file names that contain newlines. 2838@xref{nul}. 2839 2840@opsummary{numeric-owner} 2841@item --numeric-owner 2842 2843This option will notify @command{tar} that it should use numeric user 2844and group IDs when creating a @command{tar} file, rather than names. 2845@xref{Attributes}. 2846 2847@item -o 2848The function of this option depends on the action @command{tar} is 2849performing. When extracting files, @option{-o} is a synonym for 2850@option{--no-same-owner}, i.e., it prevents @command{tar} from 2851restoring ownership of files being extracted. 2852 2853When creating an archive, it is a synonym for 2854@option{--old-archive}. This behavior is for compatibility 2855with previous versions of @GNUTAR{}, and will be 2856removed in future releases. 2857 2858@xref{Changes}, for more information. 2859 2860@opsummary{occurrence} 2861@item --occurrence[=@var{number}] 2862 2863This option can be used in conjunction with one of the subcommands 2864@option{--delete}, @option{--diff}, @option{--extract} or 2865@option{--list} when a list of files is given either on the command 2866line or via @option{-T} option. 2867 2868This option instructs @command{tar} to process only the @var{number}th 2869occurrence of each named file. @var{Number} defaults to 1, so 2870 2871@smallexample 2872tar -x -f archive.tar --occurrence filename 2873@end smallexample 2874 2875@noindent 2876will extract the first occurrence of the member @file{filename} from @file{archive.tar} 2877and will terminate without scanning to the end of the archive. 2878 2879@opsummary{old-archive} 2880@item --old-archive 2881Synonym for @option{--format=v7}. 2882 2883@opsummary{one-file-system} 2884@item --one-file-system 2885Used when creating an archive. Prevents @command{tar} from recursing into 2886directories that are on different file systems from the current 2887directory @footnote{Earlier versions of @GNUTAR{} understood @option{-l} as a 2888synonym for @option{--one-file-system}. This has changed in version 28891.15.91. @xref{Changes}, for more information.}. 2890 2891@opsummary{overwrite} 2892@item --overwrite 2893 2894Overwrite existing files and directory metadata when extracting files 2895from an archive. @xref{Overwrite Old Files}. 2896 2897@opsummary{overwrite-dir} 2898@item --overwrite-dir 2899 2900Overwrite the metadata of existing directories when extracting files 2901from an archive. @xref{Overwrite Old Files}. 2902 2903@opsummary{owner} 2904@item --owner=@var{user} 2905 2906Specifies that @command{tar} should use @var{user} as the owner of members 2907when creating archives, instead of the user associated with the source 2908file. @var{user} is first decoded as a user symbolic name, but if 2909this interpretation fails, it has to be a decimal numeric user @acronym{ID}. 2910@xref{override}. 2911 2912This option does not affect extraction from archives. 2913 2914@opsummary{pax-option} 2915@item --pax-option=@var{keyword-list} 2916This option is meaningful only with @acronym{POSIX.1-2001} archives 2917(@pxref{posix}). It modifies the way @command{tar} handles the 2918extended header keywords. @var{Keyword-list} is a comma-separated 2919list of keyword options. @xref{PAX keywords}, for a detailed 2920discussion. 2921 2922@opsummary{portability} 2923@item --portability 2924@itemx --old-archive 2925Synonym for @option{--format=v7}. 2926 2927@opsummary{posix} 2928@item --posix 2929Same as @option{--format=posix}. 2930 2931@opsummary{preserve} 2932@item --preserve 2933 2934Synonymous with specifying both @option{--preserve-permissions} and 2935@option{--same-order}. @xref{Setting Access Permissions}. 2936 2937@opsummary{preserve-order} 2938@item --preserve-order 2939 2940(See @option{--same-order}; @pxref{Reading}.) 2941 2942@opsummary{preserve-permissions} 2943@opsummary{same-permissions} 2944@item --preserve-permissions 2945@itemx --same-permissions 2946@itemx -p 2947 2948When @command{tar} is extracting an archive, it normally subtracts the 2949users' umask from the permissions specified in the archive and uses 2950that number as the permissions to create the destination file. 2951Specifying this option instructs @command{tar} that it should use the 2952permissions directly from the archive. @xref{Setting Access Permissions}. 2953 2954@opsummary{quote-chars} 2955@item --quote-chars=@var{string} 2956Always quote characters from @var{string}, even if the selected 2957quoting style would not quote them (@pxref{quoting styles}). 2958 2959@opsummary{quoting-style} 2960@item --quoting-style=@var{style} 2961Set quoting style to use when printing member and file names 2962(@pxref{quoting styles}). Valid @var{style} values are: 2963@code{literal}, @code{shell}, @code{shell-always}, @code{c}, 2964@code{escape}, @code{locale}, and @code{clocale}. Default quoting 2965style is @code{escape}, unless overridden while configuring the 2966package. 2967 2968@opsummary{read-full-records} 2969@item --read-full-records 2970@itemx -B 2971 2972Specifies that @command{tar} should reblock its input, for reading 2973from pipes on systems with buggy implementations. @xref{Reading}. 2974 2975@opsummary{record-size} 2976@item --record-size=@var{size} 2977 2978Instructs @command{tar} to use @var{size} bytes per record when accessing the 2979archive. @xref{Blocking Factor}. 2980 2981@opsummary{recursion} 2982@item --recursion 2983 2984With this option, @command{tar} recurses into directories (default). 2985@xref{recurse}. 2986 2987@opsummary{recursive-unlink} 2988@item --recursive-unlink 2989 2990Remove existing 2991directory hierarchies before extracting directories of the same name 2992from the archive. @xref{Recursive Unlink}. 2993 2994@opsummary{remove-files} 2995@item --remove-files 2996 2997Directs @command{tar} to remove the source file from the file system after 2998appending it to an archive. @xref{remove files}. 2999 3000@opsummary{restrict} 3001@item --restrict 3002 3003Disable use of some potentially harmful @command{tar} options. 3004Currently this option disables shell invocation from multi-volume menu 3005(@pxref{Using Multiple Tapes}). 3006 3007@opsummary{rmt-command} 3008@item --rmt-command=@var{cmd} 3009 3010Notifies @command{tar} that it should use @var{cmd} instead of 3011the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}). 3012 3013@opsummary{rsh-command} 3014@item --rsh-command=@var{cmd} 3015 3016Notifies @command{tar} that is should use @var{cmd} to communicate with remote 3017devices. @xref{Device}. 3018 3019@opsummary{same-order} 3020@item --same-order 3021@itemx --preserve-order 3022@itemx -s 3023 3024This option is an optimization for @command{tar} when running on machines with 3025small amounts of memory. It informs @command{tar} that the list of file 3026arguments has already been sorted to match the order of files in the 3027archive. @xref{Reading}. 3028 3029@opsummary{same-owner} 3030@item --same-owner 3031 3032When extracting an archive, @command{tar} will attempt to preserve the owner 3033specified in the @command{tar} archive with this option present. 3034This is the default behavior for the superuser; this option has an 3035effect only for ordinary users. @xref{Attributes}. 3036 3037@opsummary{same-permissions} 3038@item --same-permissions 3039 3040(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.) 3041 3042@opsummary{seek} 3043@item --seek 3044@itemx -n 3045 3046Assume that the archive media supports seeks to arbitrary 3047locations. Usually @command{tar} determines automatically whether 3048the archive can be seeked or not. This option is intended for use 3049in cases when such recognition fails. 3050 3051@opsummary{show-defaults} 3052@item --show-defaults 3053 3054Displays the default options used by @command{tar} and exits 3055successfully. This option is intended for use in shell scripts. 3056Here is an example of what you can see using this option: 3057 3058@smallexample 3059$ tar --show-defaults 3060--format=gnu -f- -b20 --quoting-style=escape \ 3061--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh 3062@end smallexample 3063 3064@opsummary{show-omitted-dirs} 3065@item --show-omitted-dirs 3066 3067Instructs @command{tar} to mention the directories it is skipping when 3068operating on a @command{tar} archive. @xref{show-omitted-dirs}. 3069 3070@opsummary{show-transformed-names} 3071@opsummary{show-stored-names} 3072@item --show-transformed-names 3073@itemx --show-stored-names 3074 3075Display file or member names after applying any transformations 3076(@pxref{transform}). In particular, when used in conjunction with one of 3077the archive creation operations it instructs @command{tar} to list the 3078member names stored in the archive, as opposed to the actual file 3079names. @xref{listing member and file names}. 3080 3081@opsummary{sparse} 3082@item --sparse 3083@itemx -S 3084 3085Invokes a @acronym{GNU} extension when adding files to an archive that handles 3086sparse files efficiently. @xref{sparse}. 3087 3088@opsummary{sparse-version} 3089@item --sparse-version=@var{version} 3090 3091Specifies the @dfn{format version} to use when archiving sparse 3092files. Implies @option{--sparse}. @xref{sparse}. For the description 3093of the supported sparse formats, @xref{Sparse Formats}. 3094 3095@opsummary{starting-file} 3096@item --starting-file=@var{name} 3097@itemx -K @var{name} 3098 3099This option affects extraction only; @command{tar} will skip extracting 3100files in the archive until it finds one that matches @var{name}. 3101@xref{Scarce}. 3102 3103@opsummary{strip-components} 3104@item --strip-components=@var{number} 3105Strip given @var{number} of leading components from file names before 3106extraction. For example, if archive @file{archive.tar} contained 3107@file{/some/file/name}, then running 3108 3109@smallexample 3110tar --extract --file archive.tar --strip-components=2 3111@end smallexample 3112 3113@noindent 3114would extract this file to file @file{name}. 3115 3116@opsummary{suffix}, summary 3117@item --suffix=@var{suffix} 3118 3119Alters the suffix @command{tar} uses when backing up files from the default 3120@samp{~}. @xref{backup}. 3121 3122@opsummary{tape-length} 3123@item --tape-length=@var{num} 3124@itemx -L @var{num} 3125 3126Specifies the length of tapes that @command{tar} is writing as being 3127@w{@var{num} x 1024} bytes long. @xref{Using Multiple Tapes}. 3128 3129@opsummary{test-label} 3130@item --test-label 3131 3132Reads the volume label. If an argument is specified, test whether it 3133matches the volume label. @xref{--test-label option}. 3134 3135@opsummary{to-command} 3136@item --to-command=@var{command} 3137 3138During extraction @command{tar} will pipe extracted files to the 3139standard input of @var{command}. @xref{Writing to an External Program}. 3140 3141@opsummary{to-stdout} 3142@item --to-stdout 3143@itemx -O 3144 3145During extraction, @command{tar} will extract files to stdout rather 3146than to the file system. @xref{Writing to Standard Output}. 3147 3148@opsummary{totals} 3149@item --totals[=@var{signo}] 3150 3151Displays the total number of bytes transferred when processing an 3152archive. If an argument is given, these data are displayed on 3153request, when signal @var{signo} is delivered to @command{tar}. 3154@xref{totals}. 3155 3156@opsummary{touch} 3157@item --touch 3158@itemx -m 3159 3160Sets the data modification time of extracted files to the extraction time, 3161rather than the data modification time stored in the archive. 3162@xref{Data Modification Times}. 3163 3164@opsummary{transform} 3165@item --transform=@var{sed-expr} 3166 3167Transform file or member names using @command{sed} replacement expression 3168@var{sed-expr}. For example, 3169 3170@smallexample 3171$ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .} 3172@end smallexample 3173 3174@noindent 3175will add to @file{archive} files from the current working directory, 3176replacing initial @samp{./} prefix with @samp{usr/}. For the detailed 3177discussion, @xref{transform}. 3178 3179To see transformed member names in verbose listings, use 3180@option{--show-transformed-names} option 3181(@pxref{show-transformed-names}). 3182 3183@opsummary{uncompress} 3184@item --uncompress 3185 3186(See @option{--compress}. @pxref{gzip}) 3187 3188@opsummary{ungzip} 3189@item --ungzip 3190 3191(See @option{--gzip}. @pxref{gzip}) 3192 3193@opsummary{unlink-first} 3194@item --unlink-first 3195@itemx -U 3196 3197Directs @command{tar} to remove the corresponding file from the file 3198system before extracting it from the archive. @xref{Unlink First}. 3199 3200@opsummary{unquote} 3201@item --unquote 3202Enable unquoting input file or member names (default). @xref{input 3203name quoting}. 3204 3205@opsummary{use-compress-program} 3206@item --use-compress-program=@var{prog} 3207 3208Instructs @command{tar} to access the archive through @var{prog}, which is 3209presumed to be a compression program of some sort. @xref{gzip}. 3210 3211@opsummary{utc} 3212@item --utc 3213 3214Display file modification dates in @acronym{UTC}. This option implies 3215@option{--verbose}. 3216 3217@opsummary{verbose} 3218@item --verbose 3219@itemx -v 3220 3221Specifies that @command{tar} should be more verbose about the 3222operations it is performing. This option can be specified multiple 3223times for some operations to increase the amount of information displayed. 3224@xref{verbose}. 3225 3226@opsummary{verify} 3227@item --verify 3228@itemx -W 3229 3230Verifies that the archive was correctly written when creating an 3231archive. @xref{verify}. 3232 3233@opsummary{version} 3234@item --version 3235 3236Print information about the program's name, version, origin and legal 3237status, all on standard output, and then exit successfully. 3238@xref{help}. 3239 3240@opsummary{volno-file} 3241@item --volno-file=@var{file} 3242 3243Used in conjunction with @option{--multi-volume}. @command{tar} will 3244keep track of which volume of a multi-volume archive it is working in 3245@var{file}. @xref{volno-file}. 3246 3247@opsummary{wildcards} 3248@item --wildcards 3249Use wildcards when matching member names with patterns. 3250@xref{controlling pattern-matching}. 3251 3252@opsummary{wildcards-match-slash} 3253@item --wildcards-match-slash 3254Wildcards match @samp{/}. 3255@xref{controlling pattern-matching}. 3256@end table 3257 3258@node Short Option Summary 3259@subsection Short Options Cross Reference 3260 3261Here is an alphabetized list of all of the short option forms, matching 3262them with the equivalent long option. 3263 3264@multitable @columnfractions 0.20 0.80 3265@headitem Short Option @tab Reference 3266 3267@item -A @tab @ref{--concatenate}. 3268 3269@item -B @tab @ref{--read-full-records}. 3270 3271@item -C @tab @ref{--directory}. 3272 3273@item -F @tab @ref{--info-script}. 3274 3275@item -G @tab @ref{--incremental}. 3276 3277@item -K @tab @ref{--starting-file}. 3278 3279@item -L @tab @ref{--tape-length}. 3280 3281@item -M @tab @ref{--multi-volume}. 3282 3283@item -N @tab @ref{--newer}. 3284 3285@item -O @tab @ref{--to-stdout}. 3286 3287@item -P @tab @ref{--absolute-names}. 3288 3289@item -R @tab @ref{--block-number}. 3290 3291@item -S @tab @ref{--sparse}. 3292 3293@item -T @tab @ref{--files-from}. 3294 3295@item -U @tab @ref{--unlink-first}. 3296 3297@item -V @tab @ref{--label}. 3298 3299@item -W @tab @ref{--verify}. 3300 3301@item -X @tab @ref{--exclude-from}. 3302 3303@item -Z @tab @ref{--compress}. 3304 3305@item -b @tab @ref{--blocking-factor}. 3306 3307@item -c @tab @ref{--create}. 3308 3309@item -d @tab @ref{--compare}. 3310 3311@item -f @tab @ref{--file}. 3312 3313@item -g @tab @ref{--listed-incremental}. 3314 3315@item -h @tab @ref{--dereference}. 3316 3317@item -i @tab @ref{--ignore-zeros}. 3318 3319@item -j @tab @ref{--bzip2}. 3320 3321@item -k @tab @ref{--keep-old-files}. 3322 3323@item -l @tab @ref{--check-links}. 3324 3325@item -m @tab @ref{--touch}. 3326 3327@item -o @tab When creating, @ref{--no-same-owner}, when extracting --- 3328@ref{--portability}. 3329 3330The later usage is deprecated. It is retained for compatibility with 3331the earlier versions of @GNUTAR{}. In future releases 3332@option{-o} will be equivalent to @option{--no-same-owner} only. 3333 3334@item -p @tab @ref{--preserve-permissions}. 3335 3336@item -r @tab @ref{--append}. 3337 3338@item -s @tab @ref{--same-order}. 3339 3340@item -t @tab @ref{--list}. 3341 3342@item -u @tab @ref{--update}. 3343 3344@item -v @tab @ref{--verbose}. 3345 3346@item -w @tab @ref{--interactive}. 3347 3348@item -x @tab @ref{--extract}. 3349 3350@item -z @tab @ref{--gzip}. 3351 3352@end multitable 3353 3354@node help 3355@section @GNUTAR{} documentation 3356 3357@cindex Getting program version number 3358@opindex version 3359@cindex Version of the @command{tar} program 3360Being careful, the first thing is really checking that you are using 3361@GNUTAR{}, indeed. The @option{--version} option 3362causes @command{tar} to print information about its name, version, 3363origin and legal status, all on standard output, and then exit 3364successfully. For example, @w{@samp{tar --version}} might print: 3365 3366@smallexample 3367tar (GNU tar) @value{VERSION} 3368Copyright (C) 2006 Free Software Foundation, Inc. 3369This is free software. You may redistribute copies of it under the terms 3370of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. 3371There is NO WARRANTY, to the extent permitted by law. 3372 3373Written by John Gilmore and Jay Fenlason. 3374@end smallexample 3375 3376@noindent 3377The first occurrence of @samp{tar} in the result above is the program 3378name in the package (for example, @command{rmt} is another program), 3379while the second occurrence of @samp{tar} is the name of the package 3380itself, containing possibly many programs. The package is currently 3381named @samp{tar}, after the name of the main program it 3382contains@footnote{There are plans to merge the @command{cpio} and 3383@command{tar} packages into a single one which would be called 3384@code{paxutils}. So, who knows if, one of this days, the 3385@option{--version} would not output @w{@samp{tar (@acronym{GNU} 3386paxutils) 3.2}}}. 3387 3388@cindex Obtaining help 3389@cindex Listing all @command{tar} options 3390@xopindex{help, introduction} 3391Another thing you might want to do is checking the spelling or meaning 3392of some particular @command{tar} option, without resorting to this 3393manual, for once you have carefully read it. @GNUTAR{} 3394has a short help feature, triggerable through the 3395@option{--help} option. By using this option, @command{tar} will 3396print a usage message listing all available options on standard 3397output, then exit successfully, without doing anything else and 3398ignoring all other options. Even if this is only a brief summary, it 3399may be several screens long. So, if you are not using some kind of 3400scrollable window, you might prefer to use something like: 3401 3402@smallexample 3403$ @kbd{tar --help | less} 3404@end smallexample 3405 3406@noindent 3407presuming, here, that you like using @command{less} for a pager. Other 3408popular pagers are @command{more} and @command{pg}. If you know about some 3409@var{keyword} which interests you and do not want to read all the 3410@option{--help} output, another common idiom is doing: 3411 3412@smallexample 3413tar --help | grep @var{keyword} 3414@end smallexample 3415 3416@noindent 3417for getting only the pertinent lines. Notice, however, that some 3418@command{tar} options have long description lines and the above 3419command will list only the first of them. 3420 3421The exact look of the option summary displayed by @kbd{tar --help} is 3422configurable. @xref{Configuring Help Summary}, for a detailed description. 3423 3424@opindex usage 3425If you only wish to check the spelling of an option, running @kbd{tar 3426--usage} may be a better choice. This will display a terse list of 3427@command{tar} option without accompanying explanations. 3428 3429The short help output is quite succinct, and you might have to get 3430back to the full documentation for precise points. If you are reading 3431this paragraph, you already have the @command{tar} manual in some 3432form. This manual is available in a variety of forms from 3433@url{http://www.gnu.org/software/tar/manual}. It may be printed out of the @GNUTAR{} 3434distribution, provided you have @TeX{} already installed somewhere, 3435and a laser printer around. Just configure the distribution, execute 3436the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the 3437usual way (contact your local guru to know how). If @GNUTAR{} 3438has been conveniently installed at your place, this 3439manual is also available in interactive, hypertextual form as an Info 3440file. Just call @w{@samp{info tar}} or, if you do not have the 3441@command{info} program handy, use the Info reader provided within 3442@acronym{GNU} Emacs, calling @samp{tar} from the main Info menu. 3443 3444There is currently no @code{man} page for @GNUTAR{}. 3445If you observe such a @code{man} page on the system you are running, 3446either it does not belong to @GNUTAR{}, or it has not 3447been produced by @acronym{GNU}. Some package maintainers convert 3448@kbd{tar --help} output to a man page, using @command{help2man}. In 3449any case, please bear in mind that the authoritative source of 3450information about @GNUTAR{} is this Texinfo documentation. 3451 3452@node defaults 3453@section Obtaining @GNUTAR{} default values 3454 3455@opindex show-defaults 3456@GNUTAR{} has some predefined defaults that are used when you do not 3457explicitly specify another values. To obtain a list of such 3458defaults, use @option{--show-defaults} option. This will output the 3459values in the form of @command{tar} command line options: 3460 3461@smallexample 3462@group 3463@kbd{tar --show-defaults} 3464--format=gnu -f- -b20 --quoting-style=escape 3465--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh 3466@end group 3467@end smallexample 3468 3469@noindent 3470Notice, that this option outputs only one line. The example output above 3471has been split to fit page boundaries. 3472 3473@noindent 3474The above output shows that this version of @GNUTAR{} defaults to 3475using @samp{gnu} archive format (@pxref{Formats}), it uses standard 3476output as the archive, if no @option{--file} option has been given 3477(@pxref{file tutorial}), the default blocking factor is 20 3478(@pxref{Blocking Factor}). It also shows the default locations where 3479@command{tar} will look for @command{rmt} and @command{rsh} binaries. 3480 3481@node verbose 3482@section Checking @command{tar} progress 3483 3484Typically, @command{tar} performs most operations without reporting any 3485information to the user except error messages. When using @command{tar} 3486with many options, particularly ones with complicated or 3487difficult-to-predict behavior, it is possible to make serious mistakes. 3488@command{tar} provides several options that make observing @command{tar} 3489easier. These options cause @command{tar} to print information as it 3490progresses in its job, and you might want to use them just for being 3491more careful about what is going on, or merely for entertaining 3492yourself. If you have encountered a problem when operating on an 3493archive, however, you may need more information than just an error 3494message in order to solve the problem. The following options can be 3495helpful diagnostic tools. 3496 3497@cindex Verbose operation 3498@opindex verbose 3499Normally, the @option{--list} (@option{-t}) command to list an archive 3500prints just the file names (one per line) and the other commands are 3501silent. When used with most operations, the @option{--verbose} 3502(@option{-v}) option causes @command{tar} to print the name of each 3503file or archive member as it is processed. This and the other options 3504which make @command{tar} print status information can be useful in 3505monitoring @command{tar}. 3506 3507With @option{--create} or @option{--extract}, @option{--verbose} used 3508once just prints the names of the files or members as they are processed. 3509Using it twice causes @command{tar} to print a longer listing 3510(@xref{verbose member listing}, for the description) for each member. 3511Since @option{--list} already prints the names of the members, 3512@option{--verbose} used once with @option{--list} causes @command{tar} 3513to print an @samp{ls -l} type listing of the files in the archive. 3514The following examples both extract members with long list output: 3515 3516@smallexample 3517$ @kbd{tar --extract --file=archive.tar --verbose --verbose} 3518$ @kbd{tar xvvf archive.tar} 3519@end smallexample 3520 3521Verbose output appears on the standard output except when an archive is 3522being written to the standard output, as with @samp{tar --create 3523--file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the 3524installer let standard output be the default archive). In that case 3525@command{tar} writes verbose output to the standard error stream. 3526 3527If @option{--index-file=@var{file}} is specified, @command{tar} sends 3528verbose output to @var{file} rather than to standard output or standard 3529error. 3530 3531@anchor{totals} 3532@cindex Obtaining total status information 3533@opindex totals 3534The @option{--totals} option causes @command{tar} to print on the 3535standard error the total amount of bytes transferred when processing 3536an archive. When creating or appending to an archive, this option 3537prints the number of bytes written to the archive and the average 3538speed at which they have been written, e.g.: 3539 3540@smallexample 3541@group 3542$ @kbd{tar -c -f archive.tar --totals /home} 3543Total bytes written: 7924664320 (7.4GiB, 85MiB/s) 3544@end group 3545@end smallexample 3546 3547When reading an archive, this option displays the number of bytes 3548read: 3549 3550@smallexample 3551@group 3552$ @kbd{tar -x -f archive.tar --totals} 3553Total bytes read: 7924664320 (7.4GiB, 95MiB/s) 3554@end group 3555@end smallexample 3556 3557Finally, when deleting from an archive, the @option{--totals} option 3558displays both numbers plus number of bytes removed from the archive: 3559 3560@smallexample 3561@group 3562$ @kbd{tar --delete -f foo.tar --totals --wildcards '*~'} 3563Total bytes read: 9543680 (9.2MiB, 201MiB/s) 3564Total bytes written: 3829760 (3.7MiB, 81MiB/s) 3565Total bytes deleted: 1474048 3566@end group 3567@end smallexample 3568 3569You can also obtain this information on request. When 3570@option{--totals} is used with an argument, this argument is 3571interpreted as a symbolic name of a signal, upon delivery of which the 3572statistics is to be printed: 3573 3574@table @option 3575@item --totals=@var{signo} 3576Print statistics upon delivery of signal @var{signo}. Valid arguments 3577are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and 3578@code{SIGUSR2}. Shortened names without @samp{SIG} prefix are also 3579accepted. 3580@end table 3581 3582Both forms of @option{--totals} option can be used simultaneously. 3583Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to 3584extract all members from its default archive and print statistics 3585after finishing the extraction, as well as when receiving signal 3586@code{SIGUSR1}. 3587 3588@anchor{Progress information} 3589@cindex Progress information 3590@opindex checkpoint 3591The @option{--checkpoint} option prints an occasional message 3592as @command{tar} reads or writes the archive. It is designed for 3593those who don't need the more detailed (and voluminous) output of 3594@option{--block-number} (@option{-R}), but do want visual confirmation 3595that @command{tar} is actually making forward progress. By default it 3596prints a message each 10 records read or written. This can be changed 3597by giving it a numeric argument after an equal sign: 3598 3599@smallexample 3600$ @kbd{tar -c --checkpoint=1000} /var 3601tar: Write checkpoint 1000 3602tar: Write checkpoint 2000 3603tar: Write checkpoint 3000 3604@end smallexample 3605 3606This example shows the default checkpoint message used by 3607@command{tar}. If you place a dot immediately after the equal 3608sign, it will print a @samp{.} at each checkpoint. For example: 3609 3610@smallexample 3611$ @kbd{tar -c --checkpoint=.1000} /var 3612... 3613@end smallexample 3614 3615@opindex show-omitted-dirs 3616@anchor{show-omitted-dirs} 3617The @option{--show-omitted-dirs} option, when reading an archive---with 3618@option{--list} or @option{--extract}, for example---causes a message 3619to be printed for each directory in the archive which is skipped. 3620This happens regardless of the reason for skipping: the directory might 3621not have been named on the command line (implicitly or explicitly), 3622it might be excluded by the use of the 3623@option{--exclude=@var{pattern}} option, or some other reason. 3624 3625@opindex block-number 3626@cindex Block number where error occurred 3627@anchor{block-number} 3628If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along with 3629every message it would normally produce, the block number within the 3630archive where the message was triggered. Also, supplementary messages 3631are triggered when reading blocks full of NULs, or when hitting end of 3632file on the archive. As of now, if the archive if properly terminated 3633with a NUL block, the reading of the file may stop before end of file 3634is met, so the position of end of file will not usually show when 3635@option{--block-number} (@option{-R}) is used. Note that @GNUTAR{} 3636drains the archive before exiting when reading the 3637archive from a pipe. 3638 3639@cindex Error message, block number of 3640This option is especially useful when reading damaged archives, since 3641it helps pinpoint the damaged sections. It can also be used with 3642@option{--list} (@option{-t}) when listing a file-system backup tape, allowing you to 3643choose among several backup tapes when retrieving a file later, in 3644favor of the tape where the file appears earliest (closest to the 3645front of the tape). @xref{backup}. 3646 3647@node interactive 3648@section Asking for Confirmation During Operations 3649@cindex Interactive operation 3650 3651Typically, @command{tar} carries out a command without stopping for 3652further instructions. In some situations however, you may want to 3653exclude some files and archive members from the operation (for instance 3654if disk or storage space is tight). You can do this by excluding 3655certain files automatically (@pxref{Choosing}), or by performing 3656an operation interactively, using the @option{--interactive} (@option{-w}) option. 3657@command{tar} also accepts @option{--confirmation} for this option. 3658 3659@opindex interactive 3660When the @option{--interactive} (@option{-w}) option is specified, before 3661reading, writing, or deleting files, @command{tar} first prints a message 3662for each such file, telling what operation it intends to take, then asks 3663for confirmation on the terminal. The actions which require 3664confirmation include adding a file to the archive, extracting a file 3665from the archive, deleting a file from the archive, and deleting a file 3666from disk. To confirm the action, you must type a line of input 3667beginning with @samp{y}. If your input line begins with anything other 3668than @samp{y}, @command{tar} skips that file. 3669 3670If @command{tar} is reading the archive from the standard input, 3671@command{tar} opens the file @file{/dev/tty} to support the interactive 3672communications. 3673 3674Verbose output is normally sent to standard output, separate from 3675other error messages. However, if the archive is produced directly 3676on standard output, then verbose output is mixed with errors on 3677@code{stderr}. Producing the archive on standard output may be used 3678as a way to avoid using disk space, when the archive is soon to be 3679consumed by another process reading it, say. Some people felt the need 3680of producing an archive on stdout, still willing to segregate between 3681verbose output and error output. A possible approach would be using a 3682named pipe to receive the archive, and having the consumer process to 3683read from that named pipe. This has the advantage of letting standard 3684output free to receive verbose output, all separate from errors. 3685 3686@node operations 3687@chapter @GNUTAR{} Operations 3688 3689@menu 3690* Basic tar:: 3691* Advanced tar:: 3692* create options:: 3693* extract options:: 3694* backup:: 3695* Applications:: 3696* looking ahead:: 3697@end menu 3698 3699@node Basic tar 3700@section Basic @GNUTAR{} Operations 3701 3702The basic @command{tar} operations, @option{--create} (@option{-c}), 3703@option{--list} (@option{-t}) and @option{--extract} (@option{--get}, 3704@option{-x}), are currently presented and described in the tutorial 3705chapter of this manual. This section provides some complementary notes 3706for these operations. 3707 3708@table @option 3709@xopindex{create, complementary notes} 3710@item --create 3711@itemx -c 3712 3713Creating an empty archive would have some kind of elegance. One can 3714initialize an empty archive and later use @option{--append} 3715(@option{-r}) for adding all members. Some applications would not 3716welcome making an exception in the way of adding the first archive 3717member. On the other hand, many people reported that it is 3718dangerously too easy for @command{tar} to destroy a magnetic tape with 3719an empty archive@footnote{This is well described in @cite{Unix-haters 3720Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG 3721Books, ISBN 1-56884-203-1.}. The two most common errors are: 3722 3723@enumerate 3724@item 3725Mistakingly using @code{create} instead of @code{extract}, when the 3726intent was to extract the full contents of an archive. This error 3727is likely: keys @kbd{c} and @kbd{x} are right next to each other on 3728the QWERTY keyboard. Instead of being unpacked, the archive then 3729gets wholly destroyed. When users speak about @dfn{exploding} an 3730archive, they usually mean something else :-). 3731 3732@item 3733Forgetting the argument to @code{file}, when the intent was to create 3734an archive with a single file in it. This error is likely because a 3735tired user can easily add the @kbd{f} key to the cluster of option 3736letters, by the mere force of habit, without realizing the full 3737consequence of doing so. The usual consequence is that the single 3738file, which was meant to be saved, is rather destroyed. 3739@end enumerate 3740 3741So, recognizing the likelihood and the catastrophic nature of these 3742errors, @GNUTAR{} now takes some distance from elegance, and 3743cowardly refuses to create an archive when @option{--create} option is 3744given, there are no arguments besides options, and 3745@option{--files-from} (@option{-T}) option is @emph{not} used. To get 3746around the cautiousness of @GNUTAR{} and nevertheless create an 3747archive with nothing in it, one may still use, as the value for the 3748@option{--files-from} option, a file with no names in it, as shown in 3749the following commands: 3750 3751@smallexample 3752@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null} 3753@kbd{tar cfT empty-archive.tar /dev/null} 3754@end smallexample 3755 3756@xopindex{extract, complementary notes} 3757@item --extract 3758@itemx --get 3759@itemx -x 3760 3761A socket is stored, within a @GNUTAR{} archive, as a pipe. 3762 3763@item @option{--list} (@option{-t}) 3764 3765@GNUTAR{} now shows dates as @samp{1996-08-30}, 3766while it used to show them as @samp{Aug 30 1996}. Preferably, 3767people should get used to ISO 8601 dates. Local American dates should 3768be made available again with full date localization support, once 3769ready. In the meantime, programs not being localizable for dates 3770should prefer international dates, that's really the way to go. 3771 3772Look up @url{http://www.cl.cam.ac.uk/@/~mgk25/@/iso-time.html} if you 3773are curious, it contains a detailed explanation of the ISO 8601 standard. 3774 3775@end table 3776 3777@node Advanced tar 3778@section Advanced @GNUTAR{} Operations 3779 3780Now that you have learned the basics of using @GNUTAR{}, you may want 3781to learn about further ways in which @command{tar} can help you. 3782 3783This chapter presents five, more advanced operations which you probably 3784won't use on a daily basis, but which serve more specialized functions. 3785We also explain the different styles of options and why you might want 3786to use one or another, or a combination of them in your @command{tar} 3787commands. Additionally, this chapter includes options which allow you to 3788define the output from @command{tar} more carefully, and provide help and 3789error correction in special circumstances. 3790 3791@FIXME{check this after the chapter is actually revised to make sure 3792it still introduces the info in the chapter correctly : ).} 3793 3794@menu 3795* Operations:: 3796* append:: 3797* update:: 3798* concatenate:: 3799* delete:: 3800* compare:: 3801@end menu 3802 3803@node Operations 3804@subsection The Five Advanced @command{tar} Operations 3805@UNREVISED 3806 3807In the last chapter, you learned about the first three operations to 3808@command{tar}. This chapter presents the remaining five operations to 3809@command{tar}: @option{--append}, @option{--update}, @option{--concatenate}, 3810@option{--delete}, and @option{--compare}. 3811 3812You are not likely to use these operations as frequently as those 3813covered in the last chapter; however, since they perform specialized 3814functions, they are quite useful when you do need to use them. We 3815will give examples using the same directory and files that you created 3816in the last chapter. As you may recall, the directory is called 3817@file{practice}, the files are @samp{jazz}, @samp{blues}, @samp{folk}, 3818@samp{rock}, and the two archive files you created are 3819@samp{collection.tar} and @samp{music.tar}. 3820 3821We will also use the archive files @samp{afiles.tar} and 3822@samp{bfiles.tar}. The archive @samp{afiles.tar} contains the members @samp{apple}, 3823@samp{angst}, and @samp{aspic}; @samp{bfiles.tar} contains the members 3824@samp{./birds}, @samp{baboon}, and @samp{./box}. 3825 3826Unless we state otherwise, all practicing you do and examples you follow 3827in this chapter will take place in the @file{practice} directory that 3828you created in the previous chapter; see @ref{prepare for examples}. 3829(Below in this section, we will remind you of the state of the examples 3830where the last chapter left them.) 3831 3832The five operations that we will cover in this chapter are: 3833 3834@table @option 3835@item --append 3836@itemx -r 3837Add new entries to an archive that already exists. 3838@item --update 3839@itemx -r 3840Add more recent copies of archive members to the end of an archive, if 3841they exist. 3842@item --concatenate 3843@itemx --catenate 3844@itemx -A 3845Add one or more pre-existing archives to the end of another archive. 3846@item --delete 3847Delete items from an archive (does not work on tapes). 3848@item --compare 3849@itemx --diff 3850@itemx -d 3851Compare archive members to their counterparts in the file system. 3852@end table 3853 3854@node append 3855@subsection How to Add Files to Existing Archives: @option{--append} 3856@UNREVISED 3857 3858@opindex append 3859If you want to add files to an existing archive, you don't need to 3860create a new archive; you can use @option{--append} (@option{-r}). 3861The archive must already exist in order to use @option{--append}. (A 3862related operation is the @option{--update} operation; you can use this 3863to add newer versions of archive members to an existing archive. To learn how to 3864do this with @option{--update}, @pxref{update}.) 3865 3866If you use @option{--append} to add a file that has the same name as an 3867archive member to an archive containing that archive member, then the 3868old member is not deleted. What does happen, however, is somewhat 3869complex. @command{tar} @emph{allows} you to have infinite number of files 3870with the same name. Some operations treat these same-named members no 3871differently than any other set of archive members: for example, if you 3872view an archive with @option{--list} (@option{-t}), you will see all 3873of those members listed, with their data modification times, owners, etc. 3874 3875Other operations don't deal with these members as perfectly as you might 3876prefer; if you were to use @option{--extract} to extract the archive, 3877only the most recently added copy of a member with the same name as four 3878other members would end up in the working directory. This is because 3879@option{--extract} extracts an archive in the order the members appeared 3880in the archive; the most recently archived members will be extracted 3881last. Additionally, an extracted member will @emph{replace} a file of 3882the same name which existed in the directory already, and @command{tar} 3883will not prompt you about this@footnote{Unless you give it 3884@option{--keep-old-files} option, or the disk copy is newer than the 3885the one in the archive and you invoke @command{tar} with 3886@option{--keep-newer-files} option}. Thus, only the most recently archived 3887member will end up being extracted, as it will replace the one 3888extracted before it, and so on. 3889 3890There exists a special option that allows you to get around this 3891behavior and extract (or list) only a particular copy of the file. 3892This is @option{--occurrence} option. If you run @command{tar} with 3893this option, it will extract only the first copy of the file. You 3894may also give this option an argument specifying the number of 3895copy to be extracted. Thus, for example if the archive 3896@file{archive.tar} contained three copies of file @file{myfile}, then 3897the command 3898 3899@smallexample 3900tar --extract --file archive.tar --occurrence=2 myfile 3901@end smallexample 3902 3903@noindent 3904would extract only the second copy. @xref{Option 3905Summary,---occurrence}, for the description of @option{--occurrence} 3906option. 3907 3908@FIXME{ hag -- you might want to incorporate some of the above into the 3909MMwtSN node; not sure. i didn't know how to make it simpler... 3910 3911There are a few ways to get around this. (maybe xref Multiple Members 3912with the Same Name.} 3913 3914@cindex Members, replacing with other members 3915@cindex Replacing members with other members 3916If you want to replace an archive member, use @option{--delete} to 3917delete the member you want to remove from the archive, , and then use 3918@option{--append} to add the member you want to be in the archive. Note 3919that you can not change the order of the archive; the most recently 3920added member will still appear last. In this sense, you cannot truly 3921``replace'' one member with another. (Replacing one member with another 3922will not work on certain types of media, such as tapes; see @ref{delete} 3923and @ref{Media}, for more information.) 3924 3925@menu 3926* appending files:: Appending Files to an Archive 3927* multiple:: 3928@end menu 3929 3930@node appending files 3931@subsubsection Appending Files to an Archive 3932@UNREVISED 3933@cindex Adding files to an Archive 3934@cindex Appending files to an Archive 3935@cindex Archives, Appending files to 3936 3937The simplest way to add a file to an already existing archive is the 3938@option{--append} (@option{-r}) operation, which writes specified 3939files into the archive whether or not they are already among the 3940archived files. 3941 3942When you use @option{--append}, you @emph{must} specify file name 3943arguments, as there is no default. If you specify a file that already 3944exists in the archive, another copy of the file will be added to the 3945end of the archive. As with other operations, the member names of the 3946newly added files will be exactly the same as their names given on the 3947command line. The @option{--verbose} (@option{-v}) option will print 3948out the names of the files as they are written into the archive. 3949 3950@option{--append} cannot be performed on some tape drives, unfortunately, 3951due to deficiencies in the formats those tape drives use. The archive 3952must be a valid @command{tar} archive, or else the results of using this 3953operation will be unpredictable. @xref{Media}. 3954 3955To demonstrate using @option{--append} to add a file to an archive, 3956create a file called @file{rock} in the @file{practice} directory. 3957Make sure you are in the @file{practice} directory. Then, run the 3958following @command{tar} command to add @file{rock} to 3959@file{collection.tar}: 3960 3961@smallexample 3962$ @kbd{tar --append --file=collection.tar rock} 3963@end smallexample 3964 3965@noindent 3966If you now use the @option{--list} (@option{-t}) operation, you will see that 3967@file{rock} has been added to the archive: 3968 3969@smallexample 3970$ @kbd{tar --list --file=collection.tar} 3971-rw-r--r-- me user 28 1996-10-18 16:31 jazz 3972-rw-r--r-- me user 21 1996-09-23 16:44 blues 3973-rw-r--r-- me user 20 1996-09-23 16:44 folk 3974-rw-r--r-- me user 20 1996-09-23 16:44 rock 3975@end smallexample 3976 3977@node multiple 3978@subsubsection Multiple Members with the Same Name 3979 3980You can use @option{--append} (@option{-r}) to add copies of files 3981which have been updated since the archive was created. (However, we 3982do not recommend doing this since there is another @command{tar} 3983option called @option{--update}; @xref{update}, for more information. 3984We describe this use of @option{--append} here for the sake of 3985completeness.) When you extract the archive, the older version will 3986be effectively lost. This works because files are extracted from an 3987archive in the order in which they were archived. Thus, when the 3988archive is extracted, a file archived later in time will replace a 3989file of the same name which was archived earlier, even though the 3990older version of the file will remain in the archive unless you delete 3991all versions of the file. 3992 3993Supposing you change the file @file{blues} and then append the changed 3994version to @file{collection.tar}. As you saw above, the original 3995@file{blues} is in the archive @file{collection.tar}. If you change the 3996file and append the new version of the file to the archive, there will 3997be two copies in the archive. When you extract the archive, the older 3998version of the file will be extracted first, and then replaced by the 3999newer version when it is extracted. 4000 4001You can append the new, changed copy of the file @file{blues} to the 4002archive in this way: 4003 4004@smallexample 4005$ @kbd{tar --append --verbose --file=collection.tar blues} 4006blues 4007@end smallexample 4008 4009@noindent 4010Because you specified the @option{--verbose} option, @command{tar} has 4011printed the name of the file being appended as it was acted on. Now 4012list the contents of the archive: 4013 4014@smallexample 4015$ @kbd{tar --list --verbose --file=collection.tar} 4016-rw-r--r-- me user 28 1996-10-18 16:31 jazz 4017-rw-r--r-- me user 21 1996-09-23 16:44 blues 4018-rw-r--r-- me user 20 1996-09-23 16:44 folk 4019-rw-r--r-- me user 20 1996-09-23 16:44 rock 4020-rw-r--r-- me user 58 1996-10-24 18:30 blues 4021@end smallexample 4022 4023@noindent 4024The newest version of @file{blues} is now at the end of the archive 4025(note the different creation dates and file sizes). If you extract 4026the archive, the older version of the file @file{blues} will be 4027replaced by the newer version. You can confirm this by extracting 4028the archive and running @samp{ls} on the directory. 4029 4030If you wish to extract the first occurrence of the file @file{blues} 4031from the archive, use @option{--occurrence} option, as shown in 4032the following example: 4033 4034@smallexample 4035$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues} 4036-rw-r--r-- me user 21 1996-09-23 16:44 blues 4037@end smallexample 4038 4039@xref{Writing}, for more information on @option{--extract} and 4040@xref{Option Summary, --occurrence}, for the description of 4041@option{--occurrence} option. 4042 4043@node update 4044@subsection Updating an Archive 4045@UNREVISED 4046@cindex Updating an archive 4047 4048@opindex update 4049In the previous section, you learned how to use @option{--append} to 4050add a file to an existing archive. A related operation is 4051@option{--update} (@option{-u}). The @option{--update} operation 4052updates a @command{tar} archive by comparing the date of the specified 4053archive members against the date of the file with the same name. If 4054the file has been modified more recently than the archive member, then 4055the newer version of the file is added to the archive (as with 4056@option{--append}). 4057 4058Unfortunately, you cannot use @option{--update} with magnetic tape drives. 4059The operation will fail. 4060 4061@FIXME{other examples of media on which --update will fail? need to ask 4062charles and/or mib/thomas/dave shevett..} 4063 4064Both @option{--update} and @option{--append} work by adding to the end 4065of the archive. When you extract a file from the archive, only the 4066version stored last will wind up in the file system, unless you use 4067the @option{--backup} option. @xref{multiple}, for a detailed discussion. 4068 4069@menu 4070* how to update:: 4071@end menu 4072 4073@node how to update 4074@subsubsection How to Update an Archive Using @option{--update} 4075 4076You must use file name arguments with the @option{--update} 4077(@option{-u}) operation. If you don't specify any files, 4078@command{tar} won't act on any files and won't tell you that it didn't 4079do anything (which may end up confusing you). 4080 4081@c note: the above parenthetical added because in fact, this 4082@c behavior just confused the author. :-) 4083 4084To see the @option{--update} option at work, create a new file, 4085@file{classical}, in your practice directory, and some extra text to the 4086file @file{blues}, using any text editor. Then invoke @command{tar} with 4087the @samp{update} operation and the @option{--verbose} (@option{-v}) 4088option specified, using the names of all the files in the practice 4089directory as file name arguments: 4090 4091@smallexample 4092$ @kbd{tar --update -v -f collection.tar blues folk rock classical} 4093blues 4094classical 4095$ 4096@end smallexample 4097 4098@noindent 4099Because we have specified verbose mode, @command{tar} prints out the names 4100of the files it is working on, which in this case are the names of the 4101files that needed to be updated. If you run @samp{tar --list} and look 4102at the archive, you will see @file{blues} and @file{classical} at its 4103end. There will be a total of two versions of the member @samp{blues}; 4104the one at the end will be newer and larger, since you added text before 4105updating it. 4106 4107(The reason @command{tar} does not overwrite the older file when updating 4108it is because writing to the middle of a section of tape is a difficult 4109process. Tapes are not designed to go backward. @xref{Media}, for more 4110information about tapes. 4111 4112@option{--update} (@option{-u}) is not suitable for performing backups for two 4113reasons: it does not change directory content entries, and it 4114lengthens the archive every time it is used. The @GNUTAR{} 4115options intended specifically for backups are more 4116efficient. If you need to run backups, please consult @ref{Backups}. 4117 4118@node concatenate 4119@subsection Combining Archives with @option{--concatenate} 4120 4121@cindex Adding archives to an archive 4122@cindex Concatenating Archives 4123@opindex concatenate 4124@opindex catenate 4125@c @cindex @option{-A} described 4126Sometimes it may be convenient to add a second archive onto the end of 4127an archive rather than adding individual files to the archive. To add 4128one or more archives to the end of another archive, you should use the 4129@option{--concatenate} (@option{--catenate}, @option{-A}) operation. 4130 4131To use @option{--concatenate}, give the first archive with 4132@option{--file} option and name the rest of archives to be 4133concatenated on the command line. The members, and their member 4134names, will be copied verbatim from those archives to the first one. 4135@footnote{This can cause multiple members to have the same name, for 4136information on how this affects reading the archive, @ref{multiple}.} 4137The new, concatenated archive will be called by the same name as the 4138one given with the @option{--file} option. As usual, if you omit 4139@option{--file}, @command{tar} will use the value of the environment 4140variable @env{TAPE}, or, if this has not been set, the default archive name. 4141 4142@FIXME{There is no way to specify a new name...} 4143 4144To demonstrate how @option{--concatenate} works, create two small archives 4145called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant 4146files from @file{practice}: 4147 4148@smallexample 4149$ @kbd{tar -cvf bluesrock.tar blues rock} 4150blues 4151rock 4152$ @kbd{tar -cvf folkjazz.tar folk jazz} 4153folk 4154jazz 4155@end smallexample 4156 4157@noindent 4158If you like, You can run @samp{tar --list} to make sure the archives 4159contain what they are supposed to: 4160 4161@smallexample 4162$ @kbd{tar -tvf bluesrock.tar} 4163-rw-r--r-- melissa user 105 1997-01-21 19:42 blues 4164-rw-r--r-- melissa user 33 1997-01-20 15:34 rock 4165$ @kbd{tar -tvf jazzfolk.tar} 4166-rw-r--r-- melissa user 20 1996-09-23 16:44 folk 4167-rw-r--r-- melissa user 65 1997-01-30 14:15 jazz 4168@end smallexample 4169 4170We can concatenate these two archives with @command{tar}: 4171 4172@smallexample 4173$ @kbd{cd ..} 4174$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar} 4175@end smallexample 4176 4177If you now list the contents of the @file{bluesrock.tar}, you will see 4178that now it also contains the archive members of @file{jazzfolk.tar}: 4179 4180@smallexample 4181$ @kbd{tar --list --file=bluesrock.tar} 4182blues 4183rock 4184folk 4185jazz 4186@end smallexample 4187 4188When you use @option{--concatenate}, the source and target archives must 4189already exist and must have been created using compatible format 4190parameters. Notice, that @command{tar} does not check whether the 4191archives it concatenates have compatible formats, it does not 4192even check if the files are really tar archives. 4193 4194Like @option{--append} (@option{-r}), this operation cannot be performed on some 4195tape drives, due to deficiencies in the formats those tape drives use. 4196 4197@cindex @code{concatenate} vs @command{cat} 4198@cindex @command{cat} vs @code{concatenate} 4199It may seem more intuitive to you to want or try to use @command{cat} to 4200concatenate two archives instead of using the @option{--concatenate} 4201operation; after all, @command{cat} is the utility for combining files. 4202 4203However, @command{tar} archives incorporate an end-of-file marker which 4204must be removed if the concatenated archives are to be read properly as 4205one archive. @option{--concatenate} removes the end-of-archive marker 4206from the target archive before each new archive is appended. If you use 4207@command{cat} to combine the archives, the result will not be a valid 4208@command{tar} format archive. If you need to retrieve files from an 4209archive that was added to using the @command{cat} utility, use the 4210@option{--ignore-zeros} (@option{-i}) option. @xref{Ignore Zeros}, for further 4211information on dealing with archives improperly combined using the 4212@command{cat} shell utility. 4213 4214@node delete 4215@subsection Removing Archive Members Using @option{--delete} 4216@UNREVISED 4217@cindex Deleting files from an archive 4218@cindex Removing files from an archive 4219 4220@opindex delete 4221You can remove members from an archive by using the @option{--delete} 4222option. Specify the name of the archive with @option{--file} 4223(@option{-f}) and then specify the names of the members to be deleted; 4224if you list no member names, nothing will be deleted. The 4225@option{--verbose} option will cause @command{tar} to print the names 4226of the members as they are deleted. As with @option{--extract}, you 4227must give the exact member names when using @samp{tar --delete}. 4228@option{--delete} will remove all versions of the named file from the 4229archive. The @option{--delete} operation can run very slowly. 4230 4231Unlike other operations, @option{--delete} has no short form. 4232 4233@cindex Tapes, using @option{--delete} and 4234@cindex Deleting from tape archives 4235This operation will rewrite the archive. You can only use 4236@option{--delete} on an archive if the archive device allows you to 4237write to any point on the media, such as a disk; because of this, it 4238does not work on magnetic tapes. Do not try to delete an archive member 4239from a magnetic tape; the action will not succeed, and you will be 4240likely to scramble the archive and damage your tape. There is no safe 4241way (except by completely re-writing the archive) to delete files from 4242most kinds of magnetic tape. @xref{Media}. 4243 4244To delete all versions of the file @file{blues} from the archive 4245@file{collection.tar} in the @file{practice} directory, make sure you 4246are in that directory, and then, 4247 4248@smallexample 4249$ @kbd{tar --list --file=collection.tar} 4250blues 4251folk 4252jazz 4253rock 4254$ @kbd{tar --delete --file=collection.tar blues} 4255$ @kbd{tar --list --file=collection.tar} 4256folk 4257jazz 4258rock 4259$ 4260@end smallexample 4261 4262@FIXME{Check if the above listing is actually produced after running 4263all the examples on collection.tar.} 4264 4265The @option{--delete} option has been reported to work properly when 4266@command{tar} acts as a filter from @code{stdin} to @code{stdout}. 4267 4268@node compare 4269@subsection Comparing Archive Members with the File System 4270@cindex Verifying the currency of an archive 4271@UNREVISED 4272 4273@opindex compare 4274The @option{--compare} (@option{-d}), or @option{--diff} operation compares 4275specified archive members against files with the same names, and then 4276reports differences in file size, mode, owner, modification date and 4277contents. You should @emph{only} specify archive member names, not file 4278names. If you do not name any members, then @command{tar} will compare the 4279entire archive. If a file is represented in the archive but does not 4280exist in the file system, @command{tar} reports a difference. 4281 4282You have to specify the record size of the archive when modifying an 4283archive with a non-default record size. 4284 4285@command{tar} ignores files in the file system that do not have 4286corresponding members in the archive. 4287 4288The following example compares the archive members @file{rock}, 4289@file{blues} and @file{funk} in the archive @file{bluesrock.tar} with 4290files of the same name in the file system. (Note that there is no file, 4291@file{funk}; @command{tar} will report an error message.) 4292 4293@smallexample 4294$ @kbd{tar --compare --file=bluesrock.tar rock blues funk} 4295rock 4296blues 4297tar: funk not found in archive 4298@end smallexample 4299 4300The spirit behind the @option{--compare} (@option{--diff}, 4301@option{-d}) option is to check whether the archive represents the 4302current state of files on disk, more than validating the integrity of 4303the archive media. For this later goal, @xref{verify}. 4304 4305@node create options 4306@section Options Used by @option{--create} 4307 4308@xopindex{create, additional options} 4309The previous chapter described the basics of how to use 4310@option{--create} (@option{-c}) to create an archive from a set of files. 4311@xref{create}. This section described advanced options to be used with 4312@option{--create}. 4313 4314@menu 4315* override:: Overriding File Metadata. 4316* Ignore Failed Read:: 4317@end menu 4318 4319@node override 4320@subsection Overriding File Metadata 4321 4322As described above, a @command{tar} archive keeps, for each member it contains, 4323its @dfn{metadata}, such as modification time, mode and ownership of 4324the file. @GNUTAR{} allows to replace these data with other values 4325when adding files to the archive. The options described in this 4326section affect creation of archives of any type. For POSIX archives, 4327see also @ref{PAX keywords}, for additional ways of controlling 4328metadata, stored in the archive. 4329 4330@table @option 4331@opindex mode 4332@item --mode=@var{permissions} 4333 4334When adding files to an archive, @command{tar} will use 4335@var{permissions} for the archive members, rather than the permissions 4336from the files. @var{permissions} can be specified either as an octal 4337number or as symbolic permissions, like with 4338@command{chmod} (@xref{File permissions, Permissions, File 4339permissions, fileutils, @acronym{GNU} file utilities}. This reference 4340also has useful information for those not being overly familiar with 4341the UNIX permission system). Using latter syntax allows for 4342more flexibility. For example, the value @samp{a+rw} adds read and write 4343permissions for everybody, while retaining executable bits on directories 4344or on any other file already marked as executable: 4345 4346@smallexample 4347$ @kbd{tar -c -f archive.tar --mode='a+rw' .} 4348@end smallexample 4349 4350@item --mtime=@var{date} 4351@opindex mtime 4352 4353When adding files to an archive, @command{tar} will use @var{date} as 4354the modification time of members when creating archives, instead of 4355their actual modification times. The argument @var{date} can be 4356either a textual date representation in almost arbitrary format 4357(@pxref{Date input formats}) or a name of the existing file, starting 4358with @samp{/} or @samp{.}. In the latter case, the modification time 4359of that file will be used. 4360 4361The following example will set the modification date to 00:00:00 UTC, 4362January 1, 1970: 4363 4364@smallexample 4365$ @kbd{tar -c -f archive.tar --mtime='1970-01-01' .} 4366@end smallexample 4367 4368@noindent 4369When used with @option{--verbose} (@pxref{verbose tutorial}) @GNUTAR{} 4370will try to convert the specified date back to its textual 4371representation and compare it with the one given with 4372@option{--mtime} options. If the two dates differ, @command{tar} will 4373print a warning saying what date it will use. This is to help user 4374ensure he is using the right date. 4375 4376For example: 4377 4378@smallexample 4379$ @kbd{tar -c -f archive.tar -v --mtime=yesterday .} 4380tar: Option --mtime: Treating date `yesterday' as 2006-06-20 438113:06:29.152478 4382@dots{} 4383@end smallexample 4384 4385@item --owner=@var{user} 4386@opindex owner 4387 4388Specifies that @command{tar} should use @var{user} as the owner of members 4389when creating archives, instead of the user associated with the source 4390file. The argument @var{user} can be either an existing user symbolic 4391name, or a decimal numeric user @acronym{ID}. 4392 4393There is no value indicating a missing number, and @samp{0} usually means 4394@code{root}. Some people like to force @samp{0} as the value to offer in 4395their distributions for the owner of files, because the @code{root} user is 4396anonymous anyway, so that might as well be the owner of anonymous 4397archives. For example: 4398 4399@smallexample 4400@group 4401$ @kbd{tar -c -f archive.tar --owner=0 .} 4402# @r{Or:} 4403$ @kbd{tar -c -f archive.tar --owner=root .} 4404@end group 4405@end smallexample 4406 4407@item --group=@var{group} 4408@opindex group 4409 4410Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group}, 4411rather than the group from the source file. The argument @var{group} 4412can be either an existing group symbolic name, or a decimal numeric group @acronym{ID}. 4413@end table 4414 4415@node Ignore Failed Read 4416@subsection Ignore Fail Read 4417 4418@table @option 4419@item --ignore-failed-read 4420@opindex ignore-failed-read 4421Do not exit with nonzero on unreadable files or directories. 4422@end table 4423 4424@node extract options 4425@section Options Used by @option{--extract} 4426@UNREVISED 4427 4428@xopindex{extract, additional options} 4429The previous chapter showed how to use @option{--extract} to extract 4430an archive into the file system. Various options cause @command{tar} to 4431extract more information than just file contents, such as the owner, 4432the permissions, the modification date, and so forth. This section 4433presents options to be used with @option{--extract} when certain special 4434considerations arise. You may review the information presented in 4435@ref{extract} for more basic information about the 4436@option{--extract} operation. 4437 4438@menu 4439* Reading:: Options to Help Read Archives 4440* Writing:: Changing How @command{tar} Writes Files 4441* Scarce:: Coping with Scarce Resources 4442@end menu 4443 4444@node Reading 4445@subsection Options to Help Read Archives 4446@cindex Options when reading archives 4447@UNREVISED 4448 4449@cindex Reading incomplete records 4450@cindex Records, incomplete 4451@opindex read-full-records 4452Normally, @command{tar} will request data in full record increments from 4453an archive storage device. If the device cannot return a full record, 4454@command{tar} will report an error. However, some devices do not always 4455return full records, or do not require the last record of an archive to 4456be padded out to the next record boundary. To keep reading until you 4457obtain a full record, or to accept an incomplete record if it contains 4458an end-of-archive marker, specify the @option{--read-full-records} (@option{-B}) option 4459in conjunction with the @option{--extract} or @option{--list} operations. 4460@xref{Blocking}. 4461 4462The @option{--read-full-records} (@option{-B}) option is turned on by default when 4463@command{tar} reads an archive from standard input, or from a remote 4464machine. This is because on @acronym{BSD} Unix systems, attempting to read a 4465pipe returns however much happens to be in the pipe, even if it is 4466less than was requested. If this option were not enabled, @command{tar} 4467would fail as soon as it read an incomplete record from the pipe. 4468 4469If you're not sure of the blocking factor of an archive, you can 4470read the archive by specifying @option{--read-full-records} (@option{-B}) and 4471@option{--blocking-factor=@var{512-size}} (@option{-b 4472@var{512-size}}), using a blocking factor larger than what the archive 4473uses. This lets you avoid having to determine the blocking factor 4474of an archive. @xref{Blocking Factor}. 4475 4476@menu 4477* read full records:: 4478* Ignore Zeros:: 4479@end menu 4480 4481@node read full records 4482@unnumberedsubsubsec Reading Full Records 4483 4484@FIXME{need sentence or so of intro here} 4485 4486@table @option 4487@opindex read-full-records 4488@item --read-full-records 4489@item -B 4490Use in conjunction with @option{--extract} (@option{--get}, 4491@option{-x}) to read an archive which contains incomplete records, or 4492one which has a blocking factor less than the one specified. 4493@end table 4494 4495@node Ignore Zeros 4496@unnumberedsubsubsec Ignoring Blocks of Zeros 4497 4498@cindex End-of-archive blocks, ignoring 4499@cindex Ignoring end-of-archive blocks 4500@opindex ignore-zeros 4501Normally, @command{tar} stops reading when it encounters a block of zeros 4502between file entries (which usually indicates the end of the archive). 4503@option{--ignore-zeros} (@option{-i}) allows @command{tar} to 4504completely read an archive which contains a block of zeros before the 4505end (i.e., a damaged archive, or one that was created by concatenating 4506several archives together). 4507 4508The @option{--ignore-zeros} (@option{-i}) option is turned off by default because many 4509versions of @command{tar} write garbage after the end-of-archive entry, 4510since that part of the media is never supposed to be read. @GNUTAR{} 4511does not write after the end of an archive, but seeks to 4512maintain compatibility among archiving utilities. 4513 4514@table @option 4515@item --ignore-zeros 4516@itemx -i 4517To ignore blocks of zeros (i.e., end-of-archive entries) which may be 4518encountered while reading an archive. Use in conjunction with 4519@option{--extract} or @option{--list}. 4520@end table 4521 4522@node Writing 4523@subsection Changing How @command{tar} Writes Files 4524@UNREVISED 4525 4526@FIXME{Introductory paragraph} 4527 4528@menu 4529* Dealing with Old Files:: 4530* Overwrite Old Files:: 4531* Keep Old Files:: 4532* Keep Newer Files:: 4533* Unlink First:: 4534* Recursive Unlink:: 4535* Data Modification Times:: 4536* Setting Access Permissions:: 4537* Directory Modification Times and Permissions:: 4538* Writing to Standard Output:: 4539* Writing to an External Program:: 4540* remove files:: 4541@end menu 4542 4543@node Dealing with Old Files 4544@unnumberedsubsubsec Options Controlling the Overwriting of Existing Files 4545 4546@xopindex{overwrite-dir, introduced} 4547When extracting files, if @command{tar} discovers that the extracted 4548file already exists, it normally replaces the file by removing it before 4549extracting it, to prevent confusion in the presence of hard or symbolic 4550links. (If the existing file is a symbolic link, it is removed, not 4551followed.) However, if a directory cannot be removed because it is 4552nonempty, @command{tar} normally overwrites its metadata (ownership, 4553permission, etc.). The @option{--overwrite-dir} option enables this 4554default behavior. To be more cautious and preserve the metadata of 4555such a directory, use the @option{--no-overwrite-dir} option. 4556 4557@cindex Overwriting old files, prevention 4558@xopindex{keep-old-files, introduced} 4559To be even more cautious and prevent existing files from being replaced, use 4560the @option{--keep-old-files} (@option{-k}) option. It causes @command{tar} to refuse 4561to replace or update a file that already exists, i.e., a file with the 4562same name as an archive member prevents extraction of that archive 4563member. Instead, it reports an error. 4564 4565@xopindex{overwrite, introduced} 4566To be more aggressive about altering existing files, use the 4567@option{--overwrite} option. It causes @command{tar} to overwrite 4568existing files and to follow existing symbolic links when extracting. 4569 4570@cindex Protecting old files 4571Some people argue that @GNUTAR{} should not hesitate 4572to overwrite files with other files when extracting. When extracting 4573a @command{tar} archive, they expect to see a faithful copy of the 4574state of the file system when the archive was created. It is debatable 4575that this would always be a proper behavior. For example, suppose one 4576has an archive in which @file{usr/local} is a link to 4577@file{usr/local2}. Since then, maybe the site removed the link and 4578renamed the whole hierarchy from @file{/usr/local2} to 4579@file{/usr/local}. Such things happen all the time. I guess it would 4580not be welcome at all that @GNUTAR{} removes the 4581whole hierarchy just to make room for the link to be reinstated 4582(unless it @emph{also} simultaneously restores the full 4583@file{/usr/local2}, of course!) @GNUTAR{} is indeed 4584able to remove a whole hierarchy to reestablish a symbolic link, for 4585example, but @emph{only if} @option{--recursive-unlink} is specified 4586to allow this behavior. In any case, single files are silently 4587removed. 4588 4589@xopindex{unlink-first, introduced} 4590Finally, the @option{--unlink-first} (@option{-U}) option can improve performance in 4591some cases by causing @command{tar} to remove files unconditionally 4592before extracting them. 4593 4594@node Overwrite Old Files 4595@unnumberedsubsubsec Overwrite Old Files 4596 4597@table @option 4598@opindex overwrite 4599@item --overwrite 4600Overwrite existing files and directory metadata when extracting files 4601from an archive. 4602 4603This causes @command{tar} to write extracted files into the file system without 4604regard to the files already on the system; i.e., files with the same 4605names as archive members are overwritten when the archive is extracted. 4606It also causes @command{tar} to extract the ownership, permissions, 4607and time stamps onto any preexisting files or directories. 4608If the name of a corresponding file name is a symbolic link, the file 4609pointed to by the symbolic link will be overwritten instead of the 4610symbolic link itself (if this is possible). Moreover, special devices, 4611empty directories and even symbolic links are automatically removed if 4612they are in the way of extraction. 4613 4614Be careful when using the @option{--overwrite} option, particularly when 4615combined with the @option{--absolute-names} (@option{-P}) option, as this combination 4616can change the contents, ownership or permissions of any file on your 4617system. Also, many systems do not take kindly to overwriting files that 4618are currently being executed. 4619 4620@opindex overwrite-dir 4621@item --overwrite-dir 4622Overwrite the metadata of directories when extracting files from an 4623archive, but remove other files before extracting. 4624@end table 4625 4626@node Keep Old Files 4627@unnumberedsubsubsec Keep Old Files 4628 4629@table @option 4630@opindex keep-old-files 4631@item --keep-old-files 4632@itemx -k 4633Do not replace existing files from archive. The 4634@option{--keep-old-files} (@option{-k}) option prevents @command{tar} 4635from replacing existing files with files with the same name from the 4636archive. The @option{--keep-old-files} option is meaningless with 4637@option{--list} (@option{-t}). Prevents @command{tar} from replacing 4638files in the file system during extraction. 4639@end table 4640 4641@node Keep Newer Files 4642@unnumberedsubsubsec Keep Newer Files 4643 4644@table @option 4645@opindex keep-newer-files 4646@item --keep-newer-files 4647Do not replace existing files that are newer than their archive 4648copies. This option is meaningless with @option{--list} (@option{-t}). 4649@end table 4650 4651@node Unlink First 4652@unnumberedsubsubsec Unlink First 4653 4654@table @option 4655@opindex unlink-first 4656@item --unlink-first 4657@itemx -U 4658Remove files before extracting over them. 4659This can make @command{tar} run a bit faster if you know in advance 4660that the extracted files all need to be removed. Normally this option 4661slows @command{tar} down slightly, so it is disabled by default. 4662@end table 4663 4664@node Recursive Unlink 4665@unnumberedsubsubsec Recursive Unlink 4666 4667@table @option 4668@opindex recursive-unlink 4669@item --recursive-unlink 4670When this option is specified, try removing files and directory hierarchies 4671before extracting over them. @emph{This is a dangerous option!} 4672@end table 4673 4674If you specify the @option{--recursive-unlink} option, 4675@command{tar} removes @emph{anything} that keeps you from extracting a file 4676as far as current permissions will allow it. This could include removal 4677of the contents of a full directory hierarchy. 4678 4679@node Data Modification Times 4680@unnumberedsubsubsec Setting Data Modification Times 4681 4682@cindex Data modification times of extracted files 4683@cindex Modification times of extracted files 4684Normally, @command{tar} sets the data modification times of extracted 4685files to the corresponding times recorded for the files in the archive, but 4686limits the permissions of extracted files by the current @code{umask} 4687setting. 4688 4689To set the data modification times of extracted files to the time when 4690the files were extracted, use the @option{--touch} (@option{-m}) option in 4691conjunction with @option{--extract} (@option{--get}, @option{-x}). 4692 4693@table @option 4694@opindex touch 4695@item --touch 4696@itemx -m 4697Sets the data modification time of extracted archive members to the time 4698they were extracted, not the time recorded for them in the archive. 4699Use in conjunction with @option{--extract} (@option{--get}, @option{-x}). 4700@end table 4701 4702@node Setting Access Permissions 4703@unnumberedsubsubsec Setting Access Permissions 4704 4705@cindex Permissions of extracted files 4706@cindex Modes of extracted files 4707To set the modes (access permissions) of extracted files to those 4708recorded for those files in the archive, use @option{--same-permissions} 4709in conjunction with the @option{--extract} (@option{--get}, 4710@option{-x}) operation. 4711 4712@table @option 4713@opindex preserve-permissions 4714@opindex same-permissions 4715@item --preserve-permissions 4716@itemx --same-permissions 4717@c @itemx --ignore-umask 4718@itemx -p 4719Set modes of extracted archive members to those recorded in the 4720archive, instead of current umask settings. Use in conjunction with 4721@option{--extract} (@option{--get}, @option{-x}). 4722@end table 4723 4724@node Directory Modification Times and Permissions 4725@unnumberedsubsubsec Directory Modification Times and Permissions 4726 4727After successfully extracting a file member, @GNUTAR{} normally 4728restores its permissions and modification times, as described in the 4729previous sections. This cannot be done for directories, because 4730after extracting a directory @command{tar} will almost certainly 4731extract files into that directory and this will cause the directory 4732modification time to be updated. Moreover, restoring that directory 4733permissions may not permit file creation within it. Thus, restoring 4734directory permissions and modification times must be delayed at least 4735until all files have been extracted into that directory. @GNUTAR{} 4736restores directories using the following approach. 4737 4738The extracted directories are created with the mode specified in the 4739archive, as modified by the umask of the user, which gives sufficient 4740permissions to allow file creation. The meta-information about the 4741directory is recorded in the temporary list of directories. When 4742preparing to extract next archive member, @GNUTAR{} checks if the 4743directory prefix of this file contains the remembered directory. If 4744it does not, the program assumes that all files have been extracted 4745into that directory, restores its modification time and permissions 4746and removes its entry from the internal list. This approach allows 4747to correctly restore directory meta-information in the majority of 4748cases, while keeping memory requirements sufficiently small. It is 4749based on the fact, that most @command{tar} archives use the predefined 4750order of members: first the directory, then all the files and 4751subdirectories in that directory. 4752 4753However, this is not always true. The most important exception are 4754incremental archives (@pxref{Incremental Dumps}). The member order in 4755an incremental archive is reversed: first all directory members are 4756stored, followed by other (non-directory) members. So, when extracting 4757from incremental archives, @GNUTAR{} alters the above procedure. It 4758remembers all restored directories, and restores their meta-data 4759only after the entire archive has been processed. Notice, that you do 4760not need to specify any special options for that, as @GNUTAR{} 4761automatically detects archives in incremental format. 4762 4763There may be cases, when such processing is required for normal archives 4764too. Consider the following example: 4765 4766@smallexample 4767@group 4768$ @kbd{tar --no-recursion -cvf archive \ 4769 foo foo/file1 bar bar/file foo/file2} 4770foo/ 4771foo/file1 4772bar/ 4773bar/file 4774foo/file2 4775@end group 4776@end smallexample 4777 4778During the normal operation, after encountering @file{bar} 4779@GNUTAR{} will assume that all files from the directory @file{foo} 4780were already extracted and will therefore restore its timestamp and 4781permission bits. However, after extracting @file{foo/file2} the 4782directory timestamp will be offset again. 4783 4784To correctly restore directory meta-information in such cases, use 4785@option{delay-directory-restore} command line option: 4786 4787@table @option 4788@opindex delay-directory-restore 4789@item --delay-directory-restore 4790Delays restoring of the modification times and permissions of extracted 4791directories until the end of extraction. This way, correct 4792meta-information is restored even if the archive has unusual member 4793ordering. 4794 4795@opindex no-delay-directory-restore 4796@item --no-delay-directory-restore 4797Cancel the effect of the previous @option{--delay-directory-restore}. 4798Use this option if you have used @option{--delay-directory-restore} in 4799@env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to 4800temporarily disable it. 4801@end table 4802 4803@node Writing to Standard Output 4804@unnumberedsubsubsec Writing to Standard Output 4805 4806@cindex Writing extracted files to standard output 4807@cindex Standard output, writing extracted files to 4808To write the extracted files to the standard output, instead of 4809creating the files on the file system, use @option{--to-stdout} (@option{-O}) in 4810conjunction with @option{--extract} (@option{--get}, @option{-x}). This option is useful if you are 4811extracting files to send them through a pipe, and do not need to 4812preserve them in the file system. If you extract multiple members, 4813they appear on standard output concatenated, in the order they are 4814found in the archive. 4815 4816@table @option 4817@opindex to-stdout 4818@item --to-stdout 4819@itemx -O 4820Writes files to the standard output. Use only in conjunction with 4821@option{--extract} (@option{--get}, @option{-x}). When this option is 4822used, instead of creating the files specified, @command{tar} writes 4823the contents of the files extracted to its standard output. This may 4824be useful if you are only extracting the files in order to send them 4825through a pipe. This option is meaningless with @option{--list} 4826(@option{-t}). 4827@end table 4828 4829This can be useful, for example, if you have a tar archive containing 4830a big file and don't want to store the file on disk before processing 4831it. You can use a command like this: 4832 4833@smallexample 4834tar -xOzf foo.tgz bigfile | process 4835@end smallexample 4836 4837or even like this if you want to process the concatenation of the files: 4838 4839@smallexample 4840tar -xOzf foo.tgz bigfile1 bigfile2 | process 4841@end smallexample 4842 4843However, @option{--to-command} may be more convenient for use with 4844multiple files. See the next section. 4845 4846@node Writing to an External Program 4847@unnumberedsubsubsec Writing to an External Program 4848 4849You can instruct @command{tar} to send the contents of each extracted 4850file to the standard input of an external program: 4851 4852@table @option 4853@opindex to-command 4854@item --to-command=@var{command} 4855Extract files and pipe their contents to the standard input of 4856@var{command}. When this option is used, instead of creating the 4857files specified, @command{tar} invokes @var{command} and pipes the 4858contents of the files to its standard output. @var{Command} may 4859contain command line arguments. The program is executed via 4860@code{sh -c}. Notice, that @var{command} is executed once for each regular file 4861extracted. Non-regular files (directories, etc.) are ignored when this 4862option is used. 4863@end table 4864 4865The command can obtain the information about the file it processes 4866from the following environment variables: 4867 4868@table @var 4869@vrindex TAR_FILETYPE, to-command environment 4870@item TAR_FILETYPE 4871Type of the file. It is a single letter with the following meaning: 4872 4873@multitable @columnfractions 0.10 0.90 4874@item f @tab Regular file 4875@item d @tab Directory 4876@item l @tab Symbolic link 4877@item h @tab Hard link 4878@item b @tab Block device 4879@item c @tab Character device 4880@end multitable 4881 4882Currently only regular files are supported. 4883 4884@vrindex TAR_MODE, to-command environment 4885@item TAR_MODE 4886File mode, an octal number. 4887 4888@vrindex TAR_FILENAME, to-command environment 4889@item TAR_FILENAME 4890The name of the file. 4891 4892@vrindex TAR_REALNAME, to-command environment 4893@item TAR_REALNAME 4894Name of the file as stored in the archive. 4895 4896@vrindex TAR_UNAME, to-command environment 4897@item TAR_UNAME 4898Name of the file owner. 4899 4900@vrindex TAR_GNAME, to-command environment 4901@item TAR_GNAME 4902Name of the file owner group. 4903 4904@vrindex TAR_ATIME, to-command environment 4905@item TAR_ATIME 4906Time of last access. It is a decimal number, representing seconds 4907since the epoch. If the archive provides times with nanosecond 4908precision, the nanoseconds are appended to the timestamp after a 4909decimal point. 4910 4911@vrindex TAR_MTIME, to-command environment 4912@item TAR_MTIME 4913Time of last modification. 4914 4915@vrindex TAR_CTIME, to-command environment 4916@item TAR_CTIME 4917Time of last status change. 4918 4919@vrindex TAR_SIZE, to-command environment 4920@item TAR_SIZE 4921Size of the file. 4922 4923@vrindex TAR_UID, to-command environment 4924@item TAR_UID 4925UID of the file owner. 4926 4927@vrindex TAR_GID, to-command environment 4928@item TAR_GID 4929GID of the file owner. 4930@end table 4931 4932In addition to these variables, @env{TAR_VERSION} contains the 4933@GNUTAR{} version number. 4934 4935If @var{command} exits with a non-0 status, @command{tar} will print 4936an error message similar to the following: 4937 4938@smallexample 4939tar: 2345: Child returned status 1 4940@end smallexample 4941 4942Here, @samp{2345} is the PID of the finished process. 4943 4944If this behavior is not wanted, use @option{--ignore-command-error}: 4945 4946@table @option 4947@opindex ignore-command-error 4948@item --ignore-command-error 4949Ignore exit codes of subprocesses. Notice that if the program 4950exits on signal or otherwise terminates abnormally, the error message 4951will be printed even if this option is used. 4952 4953@opindex no-ignore-command-error 4954@item --no-ignore-command-error 4955Cancel the effect of any previous @option{--ignore-command-error} 4956option. This option is useful if you have set 4957@option{--ignore-command-error} in @env{TAR_OPTIONS} 4958(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it. 4959@end table 4960 4961@node remove files 4962@unnumberedsubsubsec Removing Files 4963 4964@FIXME{The section is too terse. Something more to add? An example, 4965maybe?} 4966 4967@table @option 4968@opindex remove-files 4969@item --remove-files 4970Remove files after adding them to the archive. 4971@end table 4972 4973@node Scarce 4974@subsection Coping with Scarce Resources 4975@UNREVISED 4976 4977@cindex Small memory 4978@cindex Running out of space 4979 4980@menu 4981* Starting File:: 4982* Same Order:: 4983@end menu 4984 4985@node Starting File 4986@unnumberedsubsubsec Starting File 4987 4988@table @option 4989@opindex starting-file 4990@item --starting-file=@var{name} 4991@itemx -K @var{name} 4992Starts an operation in the middle of an archive. Use in conjunction 4993with @option{--extract} (@option{--get}, @option{-x}) or @option{--list} (@option{-t}). 4994@end table 4995 4996@cindex Middle of the archive, starting in the 4997If a previous attempt to extract files failed due to lack of disk 4998space, you can use @option{--starting-file=@var{name}} (@option{-K 4999@var{name}}) to start extracting only after member @var{name} of the 5000archive. This assumes, of course, that there is now free space, or 5001that you are now extracting into a different file system. (You could 5002also choose to suspend @command{tar}, remove unnecessary files from 5003the file system, and then restart the same @command{tar} operation. 5004In this case, @option{--starting-file} is not necessary. 5005@xref{Incremental Dumps}, @xref{interactive}, and @ref{exclude}.) 5006 5007@node Same Order 5008@unnumberedsubsubsec Same Order 5009 5010@table @option 5011@cindex Large lists of file names on small machines 5012@opindex same-order 5013@opindex preserve-order 5014@item --same-order 5015@itemx --preserve-order 5016@itemx -s 5017To process large lists of file names on machines with small amounts of 5018memory. Use in conjunction with @option{--compare} (@option{--diff}, 5019@option{-d}), @option{--list} (@option{-t}) or @option{--extract} 5020(@option{--get}, @option{-x}). 5021@end table 5022 5023The @option{--same-order} (@option{--preserve-order}, @option{-s}) option tells @command{tar} that the list of file 5024names to be listed or extracted is sorted in the same order as the 5025files in the archive. This allows a large list of names to be used, 5026even on a small machine that would not otherwise be able to hold all 5027the names in memory at the same time. Such a sorted list can easily be 5028created by running @samp{tar -t} on the archive and editing its output. 5029 5030This option is probably never needed on modern computer systems. 5031 5032@node backup 5033@section Backup options 5034 5035@cindex backup options 5036 5037@GNUTAR{} offers options for making backups of files 5038before writing new versions. These options control the details of 5039these backups. They may apply to the archive itself before it is 5040created or rewritten, as well as individual extracted members. Other 5041@acronym{GNU} programs (@command{cp}, @command{install}, @command{ln}, 5042and @command{mv}, for example) offer similar options. 5043 5044Backup options may prove unexpectedly useful when extracting archives 5045containing many members having identical name, or when extracting archives 5046on systems having file name limitations, making different members appear 5047has having similar names through the side-effect of name truncation. 5048(This is true only if we have a good scheme for truncated backup names, 5049which I'm not sure at all: I suspect work is needed in this area.) 5050When any existing file is backed up before being overwritten by extraction, 5051then clashing files are automatically be renamed to be unique, and the 5052true name is kept for only the last file of a series of clashing files. 5053By using verbose mode, users may track exactly what happens. 5054 5055At the detail level, some decisions are still experimental, and may 5056change in the future, we are waiting comments from our users. So, please 5057do not learn to depend blindly on the details of the backup features. 5058For example, currently, directories themselves are never renamed through 5059using these options, so, extracting a file over a directory still has 5060good chances to fail. Also, backup options apply to created archives, 5061not only to extracted members. For created archives, backups will not 5062be attempted when the archive is a block or character device, or when it 5063refers to a remote file. 5064 5065For the sake of simplicity and efficiency, backups are made by renaming old 5066files prior to creation or extraction, and not by copying. The original 5067name is restored if the file creation fails. If a failure occurs after a 5068partial extraction of a file, both the backup and the partially extracted 5069file are kept. 5070 5071@table @samp 5072@item --backup[=@var{method}] 5073@opindex backup 5074@vindex VERSION_CONTROL 5075@cindex backups 5076Back up files that are about to be overwritten or removed. 5077Without this option, the original versions are destroyed. 5078 5079Use @var{method} to determine the type of backups made. 5080If @var{method} is not specified, use the value of the @env{VERSION_CONTROL} 5081environment variable. And if @env{VERSION_CONTROL} is not set, 5082use the @samp{existing} method. 5083 5084@vindex version-control @r{Emacs variable} 5085This option corresponds to the Emacs variable @samp{version-control}; 5086the same values for @var{method} are accepted as in Emacs. This option 5087also allows more descriptive names. The valid @var{method}s are: 5088 5089@table @samp 5090@item t 5091@itemx numbered 5092@cindex numbered @r{backup method} 5093Always make numbered backups. 5094 5095@item nil 5096@itemx existing 5097@cindex existing @r{backup method} 5098Make numbered backups of files that already have them, simple backups 5099of the others. 5100 5101@item never 5102@itemx simple 5103@cindex simple @r{backup method} 5104Always make simple backups. 5105 5106@end table 5107 5108@item --suffix=@var{suffix} 5109@opindex suffix 5110@cindex backup suffix 5111@vindex SIMPLE_BACKUP_SUFFIX 5112Append @var{suffix} to each backup file made with @option{--backup}. If this 5113option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX} 5114environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not 5115set, the default is @samp{~}, just as in Emacs. 5116 5117@end table 5118 5119@node Applications 5120@section Notable @command{tar} Usages 5121@UNREVISED 5122 5123@FIXME{Using Unix file linking capability to recreate directory 5124structures---linking files into one subdirectory and then 5125@command{tar}ring that directory.} 5126 5127@FIXME{Nice hairy example using absolute-names, newer, etc.} 5128 5129@findex uuencode 5130You can easily use archive files to transport a group of files from 5131one system to another: put all relevant files into an archive on one 5132computer system, transfer the archive to another system, and extract 5133the contents there. The basic transfer medium might be magnetic tape, 5134Internet FTP, or even electronic mail (though you must encode the 5135archive with @command{uuencode} in order to transport it properly by 5136mail). Both machines do not have to use the same operating system, as 5137long as they both support the @command{tar} program. 5138 5139For example, here is how you might copy a directory's contents from 5140one disk to another, while preserving the dates, modes, owners and 5141link-structure of all the files therein. In this case, the transfer 5142medium is a @dfn{pipe}, which is one a Unix redirection mechanism: 5143 5144@smallexample 5145$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)} 5146@end smallexample 5147 5148@noindent 5149You can avoid subshells by using @option{-C} option: 5150 5151@smallexample 5152$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -} 5153@end smallexample 5154 5155@noindent 5156The command also works using short option forms: 5157 5158@smallexample 5159$ @kbd{(cd sourcedir; tar --create --file=- . ) \ 5160 | (cd targetdir; tar --extract --file=-)} 5161# Or: 5162$ @kbd{tar --directory sourcedir --create --file=- . ) \ 5163 | tar --directory targetdir --extract --file=-} 5164@end smallexample 5165 5166@noindent 5167This is one of the easiest methods to transfer a @command{tar} archive. 5168 5169@node looking ahead 5170@section Looking Ahead: The Rest of this Manual 5171 5172You have now seen how to use all eight of the operations available to 5173@command{tar}, and a number of the possible options. The next chapter 5174explains how to choose and change file and archive names, how to use 5175files to store names of other files which you can then call as 5176arguments to @command{tar} (this can help you save time if you expect to 5177archive the same list of files a number of times), and so forth. 5178@FIXME{in case it's not obvious, i'm making this up in some sense 5179based on my limited memory of what the next chapter *really* does. i 5180just wanted to flesh out this final section a little bit so i'd 5181remember to stick it in here. :-)} 5182 5183If there are too many files to conveniently list on the command line, 5184you can list the names in a file, and @command{tar} will read that file. 5185@xref{files}. 5186 5187There are various ways of causing @command{tar} to skip over some files, 5188and not archive them. @xref{Choosing}. 5189 5190@node Backups 5191@chapter Performing Backups and Restoring Files 5192@UNREVISED 5193 5194@GNUTAR{} is distributed along with the scripts 5195which the Free Software Foundation uses for performing backups. There 5196is no corresponding scripts available yet for doing restoration of 5197files. Even if there is a good chance those scripts may be satisfying 5198to you, they are not the only scripts or methods available for doing 5199backups and restore. You may well create your own, or use more 5200sophisticated packages dedicated to that purpose. 5201 5202Some users are enthusiastic about @code{Amanda} (The Advanced Maryland 5203Automatic Network Disk Archiver), a backup system developed by James 5204da Silva @file{jds@@cs.umd.edu} and available on many Unix systems. 5205This is free software, and it is available at these places: 5206 5207@smallexample 5208http://www.cs.umd.edu/projects/amanda/amanda.html 5209ftp://ftp.cs.umd.edu/pub/amanda 5210@end smallexample 5211 5212@FIXME{ 5213 5214Here is a possible plan for a future documentation about the backuping 5215scripts which are provided within the @GNUTAR{} 5216distribution. 5217 5218@itemize @bullet 5219@item dumps 5220 @itemize @minus 5221 @item what are dumps 5222 @item different levels of dumps 5223 @itemize + 5224 @item full dump = dump everything 5225 @item level 1, level 2 dumps etc 5226 A level @var{n} dump dumps everything changed since the last level 5227 @var{n}-1 dump (?) 5228 @end itemize 5229 @item how to use scripts for dumps (ie, the concept) 5230 @itemize + 5231 @item scripts to run after editing backup specs (details) 5232 @end itemize 5233 @item Backup Specs, what is it. 5234 @itemize + 5235 @item how to customize 5236 @item actual text of script [/sp/dump/backup-specs] 5237 @end itemize 5238 @item Problems 5239 @itemize + 5240 @item rsh doesn't work 5241 @item rtape isn't installed 5242 @item (others?) 5243 @end itemize 5244 @item the @option{--incremental} option of tar 5245 @item tapes 5246 @itemize + 5247 @item write protection 5248 @item types of media, different sizes and types, useful for different things 5249 @item files and tape marks 5250 one tape mark between files, two at end. 5251 @item positioning the tape 5252 MT writes two at end of write, 5253 backspaces over one when writing again. 5254 @end itemize 5255 @end itemize 5256@end itemize 5257} 5258 5259This chapter documents both the provided shell scripts and @command{tar} 5260options which are more specific to usage as a backup tool. 5261 5262To @dfn{back up} a file system means to create archives that contain 5263all the files in that file system. Those archives can then be used to 5264restore any or all of those files (for instance if a disk crashes or a 5265file is accidentally deleted). File system @dfn{backups} are also 5266called @dfn{dumps}. 5267 5268@menu 5269* Full Dumps:: Using @command{tar} to Perform Full Dumps 5270* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps 5271* Backup Levels:: Levels of Backups 5272* Backup Parameters:: Setting Parameters for Backups and Restoration 5273* Scripted Backups:: Using the Backup Scripts 5274* Scripted Restoration:: Using the Restore Script 5275@end menu 5276 5277@node Full Dumps 5278@section Using @command{tar} to Perform Full Dumps 5279@UNREVISED 5280 5281@cindex full dumps 5282@cindex dumps, full 5283 5284@cindex corrupted archives 5285Full dumps should only be made when no other people or programs 5286are modifying files in the file system. If files are modified while 5287@command{tar} is making the backup, they may not be stored properly in 5288the archive, in which case you won't be able to restore them if you 5289have to. (Files not being modified are written with no trouble, and do 5290not corrupt the entire archive.) 5291 5292You will want to use the @option{--label=@var{archive-label}} 5293(@option{-V @var{archive-label}}) option to give the archive a 5294volume label, so you can tell what this archive is even if the label 5295falls off the tape, or anything like that. 5296 5297Unless the file system you are dumping is guaranteed to fit on 5298one volume, you will need to use the @option{--multi-volume} (@option{-M}) option. 5299Make sure you have enough tapes on hand to complete the backup. 5300 5301If you want to dump each file system separately you will need to use 5302the @option{--one-file-system} option to prevent 5303@command{tar} from crossing file system boundaries when storing 5304(sub)directories. 5305 5306The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps}) 5307option is not needed, since this is a complete copy of everything in 5308the file system, and a full restore from this backup would only be 5309done onto a completely 5310empty disk. 5311 5312Unless you are in a hurry, and trust the @command{tar} program (and your 5313tapes), it is a good idea to use the @option{--verify} (@option{-W}) 5314option, to make sure your files really made it onto the dump properly. 5315This will also detect cases where the file was modified while (or just 5316after) it was being archived. Not all media (notably cartridge tapes) 5317are capable of being verified, unfortunately. 5318 5319@node Incremental Dumps 5320@section Using @command{tar} to Perform Incremental Dumps 5321 5322@dfn{Incremental backup} is a special form of @GNUTAR{} archive that 5323stores additional metadata so that exact state of the file system 5324can be restored when extracting the archive. 5325 5326@GNUTAR{} currently offers two options for handling incremental 5327backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g 5328@var{snapshot-file}}) and @option{--incremental} (@option{-G}). 5329 5330@opindex listed-incremental 5331The option @option{--listed-incremental} instructs tar to operate on 5332an incremental archive with additional metadata stored in a standalone 5333file, called a @dfn{snapshot file}. The purpose of this file is to help 5334determine which files have been changed, added or deleted since the 5335last backup, so that the next incremental backup will contain only 5336modified files. The name of the snapshot file is given as an argument 5337to the option: 5338 5339@table @option 5340@item --listed-incremental=@var{file} 5341@itemx -g @var{file} 5342 Handle incremental backups with snapshot data in @var{file}. 5343@end table 5344 5345To create an incremental backup, you would use 5346@option{--listed-incremental} together with @option{--create} 5347(@pxref{create}). For example: 5348 5349@smallexample 5350$ @kbd{tar --create \ 5351 --file=archive.1.tar \ 5352 --listed-incremental=/var/log/usr.snar \ 5353 /usr} 5354@end smallexample 5355 5356This will create in @file{archive.1.tar} an incremental backup of 5357the @file{/usr} file system, storing additional metadata in the file 5358@file{/var/log/usr.snar}. If this file does not exist, it will be 5359created. The created archive will then be a @dfn{level 0 backup}; 5360please see the next section for more on backup levels. 5361 5362Otherwise, if the file @file{/var/log/usr.snar} exists, it 5363determines which files are modified. In this case only these files will be 5364stored in the archive. Suppose, for example, that after running the 5365above command, you delete file @file{/usr/doc/old} and create 5366directory @file{/usr/local/db} with the following contents: 5367 5368@smallexample 5369$ @kbd{ls /usr/local/db} 5370/usr/local/db/data 5371/usr/local/db/index 5372@end smallexample 5373 5374Some time later you create another incremental backup. You will 5375then see: 5376 5377@smallexample 5378$ @kbd{tar --create \ 5379 --file=archive.2.tar \ 5380 --listed-incremental=/var/log/usr.snar \ 5381 /usr} 5382tar: usr/local/db: Directory is new 5383usr/local/db/ 5384usr/local/db/data 5385usr/local/db/index 5386@end smallexample 5387 5388@noindent 5389The created archive @file{archive.2.tar} will contain only these 5390three members. This archive is called a @dfn{level 1 backup}. Notice 5391that @file{/var/log/usr.snar} will be updated with the new data, so if 5392you plan to create more @samp{level 1} backups, it is necessary to 5393create a working copy of the snapshot file before running 5394@command{tar}. The above example will then be modified as follows: 5395 5396@smallexample 5397$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1} 5398$ @kbd{tar --create \ 5399 --file=archive.2.tar \ 5400 --listed-incremental=/var/log/usr.snar-1 \ 5401 /usr} 5402@end smallexample 5403 5404Incremental dumps depend crucially on time stamps, so the results are 5405unreliable if you modify a file's time stamps during dumping (e.g., 5406with the @option{--atime-preserve=replace} option), or if you set the clock 5407backwards. 5408 5409Metadata stored in snapshot files include device numbers, which, 5410obviously is supposed to be a non-volatile value. However, it turns 5411out that NFS devices have undependable values when an automounter 5412gets in the picture. This can lead to a great deal of spurious 5413redumping in incremental dumps, so it is somewhat useless to compare 5414two NFS devices numbers over time. The solution implemented currently 5415is to considers all NFS devices as being equal when it comes to 5416comparing directories; this is fairly gross, but there does not seem 5417to be a better way to go. 5418 5419Note that incremental archives use @command{tar} extensions and may 5420not be readable by non-@acronym{GNU} versions of the @command{tar} program. 5421 5422@xopindex{listed-incremental, using with @option{--extract}} 5423@xopindex{extract, using with @option{--listed-incremental}} 5424To extract from the incremental dumps, use 5425@option{--listed-incremental} together with @option{--extract} 5426option (@pxref{extracting files}). In this case, @command{tar} does 5427not need to access snapshot file, since all the data necessary for 5428extraction are stored in the archive itself. So, when extracting, you 5429can give whatever argument to @option{--listed-incremental}, the usual 5430practice is to use @option{--listed-incremental=/dev/null}. 5431Alternatively, you can use @option{--incremental}, which needs no 5432arguments. In general, @option{--incremental} (@option{-G}) can be 5433used as a shortcut for @option{--listed-incremental} when listing or 5434extracting incremental backups (for more information, regarding this 5435option, @pxref{incremental-op}). 5436 5437When extracting from the incremental backup @GNUTAR{} attempts to 5438restore the exact state the file system had when the archive was 5439created. In particular, it will @emph{delete} those files in the file 5440system that did not exist in their directories when the archive was 5441created. If you have created several levels of incremental files, 5442then in order to restore the exact contents the file system had when 5443the last level was created, you will need to restore from all backups 5444in turn. Continuing our example, to restore the state of @file{/usr} 5445file system, one would do@footnote{Notice, that since both archives 5446were created without @option{-P} option (@pxref{absolute}), these 5447commands should be run from the root file system.}: 5448 5449@smallexample 5450$ @kbd{tar --extract \ 5451 --listed-incremental=/dev/null \ 5452 --file archive.1.tar} 5453$ @kbd{tar --extract \ 5454 --listed-incremental=/dev/null \ 5455 --file archive.2.tar} 5456@end smallexample 5457 5458To list the contents of an incremental archive, use @option{--list} 5459(@pxref{list}), as usual. To obtain more information about the 5460archive, use @option{--listed-incremental} or @option{--incremental} 5461combined with two @option{--verbose} options@footnote{Two 5462@option{--verbose} options were selected to avoid breaking usual 5463verbose listing output (@option{--list --verbose}) when using in 5464scripts. 5465 5466@xopindex{incremental, using with @option{--list}} 5467@xopindex{listed-incremental, using with @option{--list}} 5468@xopindex{list, using with @option{--incremental}} 5469@xopindex{list, using with @option{--listed-incremental}} 5470Versions of @GNUTAR{} up to 1.15.1 used to dump verbatim binary 5471contents of the DUMPDIR header (with terminating nulls) when 5472@option{--incremental} or @option{--listed-incremental} option was 5473given, no matter what the verbosity level. This behavior, and, 5474especially, the binary output it produced were considered inconvenient 5475and were changed in version 1.16}: 5476 5477@smallexample 5478@kbd{tar --list --incremental --verbose --verbose archive.tar} 5479@end smallexample 5480 5481This command will print, for each directory in the archive, the list 5482of files in that directory at the time the archive was created. This 5483information is put out in a format which is both human-readable and 5484unambiguous for a program: each file name is printed as 5485 5486@smallexample 5487@var{x} @var{file} 5488@end smallexample 5489 5490@noindent 5491where @var{x} is a letter describing the status of the file: @samp{Y} 5492if the file is present in the archive, @samp{N} if the file is not 5493included in the archive, or a @samp{D} if the file is a directory (and 5494is included in the archive). @xref{Dumpdir}, for the detailed 5495description of dumpdirs and status codes. Each such 5496line is terminated by a newline character. The last line is followed 5497by an additional newline to indicate the end of the data. 5498 5499@anchor{incremental-op}The option @option{--incremental} (@option{-G}) 5500gives the same behavior as @option{--listed-incremental} when used 5501with @option{--list} and @option{--extract} options. When used with 5502@option{--create} option, it creates an incremental archive without 5503creating snapshot file. Thus, it is impossible to create several 5504levels of incremental backups with @option{--incremental} option. 5505 5506@node Backup Levels 5507@section Levels of Backups 5508 5509An archive containing all the files in the file system is called a 5510@dfn{full backup} or @dfn{full dump}. You could insure your data by 5511creating a full dump every day. This strategy, however, would waste a 5512substantial amount of archive media and user time, as unchanged files 5513are daily re-archived. 5514 5515It is more efficient to do a full dump only occasionally. To back up 5516files between full dumps, you can use @dfn{incremental dumps}. A @dfn{level 5517one} dump archives all the files that have changed since the last full 5518dump. 5519 5520A typical dump strategy would be to perform a full dump once a week, 5521and a level one dump once a day. This means some versions of files 5522will in fact be archived more than once, but this dump strategy makes 5523it possible to restore a file system to within one day of accuracy by 5524only extracting two archives---the last weekly (full) dump and the 5525last daily (level one) dump. The only information lost would be in 5526files changed or created since the last daily backup. (Doing dumps 5527more than once a day is usually not worth the trouble). 5528 5529@GNUTAR{} comes with scripts you can use to do full 5530and level-one (actually, even level-two and so on) dumps. Using 5531scripts (shell programs) to perform backups and restoration is a 5532convenient and reliable alternative to typing out file name lists 5533and @command{tar} commands by hand. 5534 5535Before you use these scripts, you need to edit the file 5536@file{backup-specs}, which specifies parameters used by the backup 5537scripts and by the restore script. This file is usually located 5538in @file{/etc/backup} directory. @xref{Backup Parameters}, for its 5539detailed description. Once the backup parameters are set, you can 5540perform backups or restoration by running the appropriate script. 5541 5542The name of the backup script is @code{backup}. The name of the 5543restore script is @code{restore}. The following sections describe 5544their use in detail. 5545 5546@emph{Please Note:} The backup and restoration scripts are 5547designed to be used together. While it is possible to restore files by 5548hand from an archive which was created using a backup script, and to create 5549an archive by hand which could then be extracted using the restore script, 5550it is easier to use the scripts. @xref{Incremental Dumps}, before 5551making such an attempt. 5552 5553@node Backup Parameters 5554@section Setting Parameters for Backups and Restoration 5555 5556The file @file{backup-specs} specifies backup parameters for the 5557backup and restoration scripts provided with @command{tar}. You must 5558edit @file{backup-specs} to fit your system configuration and schedule 5559before using these scripts. 5560 5561Syntactically, @file{backup-specs} is a shell script, containing 5562mainly variable assignments. However, any valid shell construct 5563is allowed in this file. Particularly, you may wish to define 5564functions within that script (e.g., see @code{RESTORE_BEGIN} below). 5565For more information about shell script syntax, please refer to 5566@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta 5567g_02, the definition of the Shell Command Language}. See also 5568@ref{Top,,Bash Features,bashref,Bash Reference Manual}. 5569 5570The shell variables controlling behavior of @code{backup} and 5571@code{restore} are described in the following subsections. 5572 5573@menu 5574* General-Purpose Variables:: 5575* Magnetic Tape Control:: 5576* User Hooks:: 5577* backup-specs example:: An Example Text of @file{Backup-specs} 5578@end menu 5579 5580@node General-Purpose Variables 5581@subsection General-Purpose Variables 5582 5583@defvr {Backup variable} ADMINISTRATOR 5584The user name of the backup administrator. @code{Backup} scripts 5585sends a backup report to this address. 5586@end defvr 5587 5588@defvr {Backup variable} BACKUP_HOUR 5589The hour at which the backups are done. This can be a number from 0 5590to 23, or the time specification in form @var{hours}:@var{minutes}, 5591or the string @samp{now}. 5592 5593This variable is used by @code{backup}. Its value may be overridden 5594using @option{--time} option (@pxref{Scripted Backups}). 5595@end defvr 5596 5597@defvr {Backup variable} TAPE_FILE 5598 5599The device @command{tar} writes the archive to. If @var{TAPE_FILE} 5600is a remote archive (@pxref{remote-dev}), backup script will suppose 5601that your @command{mt} is able to access remote devices. If @var{RSH} 5602(@pxref{RSH}) is set, @option{--rsh-command} option will be added to 5603invocations of @command{mt}. 5604@end defvr 5605 5606@defvr {Backup variable} BLOCKING 5607 5608The blocking factor @command{tar} will use when writing the dump archive. 5609@xref{Blocking Factor}. 5610@end defvr 5611 5612@defvr {Backup variable} BACKUP_DIRS 5613 5614A list of file systems to be dumped (for @code{backup}), or restored 5615(for @code{restore}). You can include any directory 5616name in the list --- subdirectories on that file system will be 5617included, regardless of how they may look to other networked machines. 5618Subdirectories on other file systems will be ignored. 5619 5620The host name specifies which host to run @command{tar} on, and should 5621normally be the host that actually contains the file system. However, 5622the host machine must have @GNUTAR{} installed, and 5623must be able to access the directory containing the backup scripts and 5624their support files using the same file name that is used on the 5625machine where the scripts are run (i.e., what @command{pwd} will print 5626when in that directory on that machine). If the host that contains 5627the file system does not have this capability, you can specify another 5628host as long as it can access the file system through NFS. 5629 5630If the list of file systems is very long you may wish to put it 5631in a separate file. This file is usually named 5632@file{/etc/backup/dirs}, but this name may be overridden in 5633@file{backup-specs} using @code{DIRLIST} variable. 5634@end defvr 5635 5636@defvr {Backup variable} DIRLIST 5637 5638The name of the file that contains a list of file systems to backup 5639or restore. By default it is @file{/etc/backup/dirs}. 5640@end defvr 5641 5642@defvr {Backup variable} BACKUP_FILES 5643 5644A list of individual files to be dumped (for @code{backup}), or restored 5645(for @code{restore}). These should be accessible from the machine on 5646which the backup script is run. 5647 5648If the list of file systems is very long you may wish to store it 5649in a separate file. This file is usually named 5650@file{/etc/backup/files}, but this name may be overridden in 5651@file{backup-specs} using @code{FILELIST} variable. 5652@end defvr 5653 5654@defvr {Backup variable} FILELIST 5655 5656The name of the file that contains a list of individual files to backup 5657or restore. By default it is @file{/etc/backup/files}. 5658@end defvr 5659 5660@defvr {Backup variable} MT 5661 5662Full file name of @command{mt} binary. 5663@end defvr 5664 5665@defvr {Backup variable} RSH 5666@anchor{RSH} 5667Full file name of @command{rsh} binary or its equivalent. You may wish to 5668set it to @code{ssh}, to improve security. In this case you will have 5669to use public key authentication. 5670@end defvr 5671 5672@defvr {Backup variable} RSH_COMMAND 5673 5674Full file name of @command{rsh} binary on remote machines. This will 5675be passed via @option{--rsh-command} option to the remote invocation 5676of @GNUTAR{}. 5677@end defvr 5678 5679@defvr {Backup variable} VOLNO_FILE 5680 5681Name of temporary file to hold volume numbers. This needs to be accessible 5682by all the machines which have file systems to be dumped. 5683@end defvr 5684 5685@defvr {Backup variable} XLIST 5686 5687Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file 5688located on the remote machine and containing the list of files to 5689be excluded from the backup. Exclude file lists are searched in 5690/etc/tar-backup directory. A common use for exclude file lists 5691is to exclude files containing security-sensitive information 5692(e.g., @file{/etc/shadow} from backups). 5693 5694This variable affects only @code{backup}. 5695@end defvr 5696 5697@defvr {Backup variable} SLEEP_TIME 5698 5699Time to sleep between dumps of any two successive file systems 5700 5701This variable affects only @code{backup}. 5702@end defvr 5703 5704@defvr {Backup variable} DUMP_REMIND_SCRIPT 5705 5706Script to be run when it's time to insert a new tape in for the next 5707volume. Administrators may want to tailor this script for their site. 5708If this variable isn't set, @GNUTAR{} will display its built-in 5709prompt, and will expect confirmation from the console. For the 5710description of the default prompt, see @ref{change volume prompt}. 5711 5712@end defvr 5713 5714@defvr {Backup variable} SLEEP_MESSAGE 5715 5716Message to display on the terminal while waiting for dump time. Usually 5717this will just be some literal text. 5718@end defvr 5719 5720@defvr {Backup variable} TAR 5721 5722Full file name of the @GNUTAR{} executable. If this is not set, backup 5723scripts will search @command{tar} in the current shell path. 5724@end defvr 5725 5726@node Magnetic Tape Control 5727@subsection Magnetic Tape Control 5728 5729Backup scripts access tape device using special @dfn{hook functions}. 5730These functions take a single argument -- the name of the tape 5731device. Their names are kept in the following variables: 5732 5733@defvr {Backup variable} MT_BEGIN 5734The name of @dfn{begin} function. This function is called before 5735accessing the drive. By default it retensions the tape: 5736 5737@smallexample 5738MT_BEGIN=mt_begin 5739 5740mt_begin() @{ 5741 mt -f "$1" retension 5742@} 5743@end smallexample 5744@end defvr 5745 5746@defvr {Backup variable} MT_REWIND 5747The name of @dfn{rewind} function. The default definition is as 5748follows: 5749 5750@smallexample 5751MT_REWIND=mt_rewind 5752 5753mt_rewind() @{ 5754 mt -f "$1" rewind 5755@} 5756@end smallexample 5757 5758@end defvr 5759 5760@defvr {Backup variable} MT_OFFLINE 5761The name of the function switching the tape off line. By default 5762it is defined as follows: 5763 5764@smallexample 5765MT_OFFLINE=mt_offline 5766 5767mt_offline() @{ 5768 mt -f "$1" offl 5769@} 5770@end smallexample 5771@end defvr 5772 5773@defvr {Backup variable} MT_STATUS 5774The name of the function used to obtain the status of the archive device, 5775including error count. Default definition: 5776 5777@smallexample 5778MT_STATUS=mt_status 5779 5780mt_status() @{ 5781 mt -f "$1" status 5782@} 5783@end smallexample 5784@end defvr 5785 5786@node User Hooks 5787@subsection User Hooks 5788 5789@dfn{User hooks} are shell functions executed before and after 5790each @command{tar} invocation. Thus, there are @dfn{backup 5791hooks}, which are executed before and after dumping each file 5792system, and @dfn{restore hooks}, executed before and 5793after restoring a file system. Each user hook is a shell function 5794taking four arguments: 5795 5796@deffn {User Hook Function} hook @var{level} @var{host} @var{fs} @var{fsname} 5797Its arguments are: 5798 5799@table @var 5800@item level 5801Current backup or restore level. 5802 5803@item host 5804Name or IP address of the host machine being dumped or restored. 5805 5806@item fs 5807Full file name of the file system being dumped or restored. 5808 5809@item fsname 5810File system name with directory separators replaced with colons. This 5811is useful, e.g., for creating unique files. 5812@end table 5813@end deffn 5814 5815Following variables keep the names of user hook functions 5816 5817@defvr {Backup variable} DUMP_BEGIN 5818Dump begin function. It is executed before dumping the file system. 5819@end defvr 5820 5821@defvr {Backup variable} DUMP_END 5822Executed after dumping the file system. 5823@end defvr 5824 5825@defvr {Backup variable} RESTORE_BEGIN 5826Executed before restoring the file system. 5827@end defvr 5828 5829@defvr {Backup variable} RESTORE_END 5830Executed after restoring the file system. 5831@end defvr 5832 5833@node backup-specs example 5834@subsection An Example Text of @file{Backup-specs} 5835 5836The following is an example of @file{backup-specs}: 5837 5838@smallexample 5839# site-specific parameters for file system backup. 5840 5841ADMINISTRATOR=friedman 5842BACKUP_HOUR=1 5843TAPE_FILE=/dev/nrsmt0 5844 5845# Use @code{ssh} instead of the less secure @code{rsh} 5846RSH=/usr/bin/ssh 5847RSH_COMMAND=/usr/bin/ssh 5848 5849# Override MT_STATUS function: 5850my_status() @{ 5851 mts -t $TAPE_FILE 5852@} 5853MT_STATUS=my_status 5854 5855# Disable MT_OFFLINE function 5856MT_OFFLINE=: 5857 5858BLOCKING=124 5859BACKUP_DIRS=" 5860 albert:/fs/fsf 5861 apple-gunkies:/gd 5862 albert:/fs/gd2 5863 albert:/fs/gp 5864 geech:/usr/jla 5865 churchy:/usr/roland 5866 albert:/ 5867 albert:/usr 5868 apple-gunkies:/ 5869 apple-gunkies:/usr 5870 gnu:/hack 5871 gnu:/u 5872 apple-gunkies:/com/mailer/gnu 5873 apple-gunkies:/com/archive/gnu" 5874 5875BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]" 5876 5877@end smallexample 5878 5879@node Scripted Backups 5880@section Using the Backup Scripts 5881 5882The syntax for running a backup script is: 5883 5884@smallexample 5885backup --level=@var{level} --time=@var{time} 5886@end smallexample 5887 5888The @option{level} option requests the dump level. Thus, to produce 5889a full dump, specify @code{--level=0} (this is the default, so 5890@option{--level} may be omitted if its value is @code{0}). 5891@footnote{For backward compatibility, the @code{backup} will also 5892try to deduce the requested dump level from the name of the 5893script itself. If the name consists of a string @samp{level-} 5894followed by a single decimal digit, that digit is taken as 5895the dump level number. Thus, you may create a link from @code{backup} 5896to @code{level-1} and then run @code{level-1} whenever you need to 5897create a level one dump.} 5898 5899The @option{--time} option determines when should the backup be 5900run. @var{Time} may take three forms: 5901 5902@table @asis 5903@item @var{hh}:@var{mm} 5904 5905The dump must be run at @var{hh} hours @var{mm} minutes. 5906 5907@item @var{hh} 5908 5909The dump must be run at @var{hh} hours 5910 5911@item now 5912 5913The dump must be run immediately. 5914@end table 5915 5916You should start a script with a tape or disk mounted. Once you 5917start a script, it prompts you for new tapes or disks as it 5918needs them. Media volumes don't have to correspond to archive 5919files --- a multi-volume archive can be started in the middle of a 5920tape that already contains the end of another multi-volume archive. 5921The @code{restore} script prompts for media by its archive volume, 5922so to avoid an error message you should keep track of which tape 5923(or disk) contains which volume of the archive (@pxref{Scripted 5924Restoration}). 5925 5926The backup scripts write two files on the file system. The first is a 5927record file in @file{/etc/tar-backup/}, which is used by the scripts 5928to store and retrieve information about which files were dumped. This 5929file is not meant to be read by humans, and should not be deleted by 5930them. @xref{Snapshot Files}, for a more detailed explanation of this 5931file. 5932 5933The second file is a log file containing the names of the file systems 5934and files dumped, what time the backup was made, and any error 5935messages that were generated, as well as how much space was left in 5936the media volume after the last volume of the archive was written. 5937You should check this log file after every backup. The file name is 5938@file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy} 5939represents current date, and @var{n} represents current dump level number. 5940 5941The script also prints the name of each system being dumped to the 5942standard output. 5943 5944Following is the full list of options accepted by @code{backup} 5945script: 5946 5947@table @option 5948@item -l @var{level} 5949@itemx --level=@var{level} 5950Do backup level @var{level} (default 0). 5951 5952@item -f 5953@itemx --force 5954Force backup even if today's log file already exists. 5955 5956@item -v[@var{level}] 5957@itemx --verbose[=@var{level}] 5958Set verbosity level. The higher the level is, the more debugging 5959information will be output during execution. Default @var{level} 5960is 100, which means the highest debugging level. 5961 5962@item -t @var{start-time} 5963@itemx --time=@var{start-time} 5964Wait till @var{time}, then do backup. 5965 5966@item -h 5967@itemx --help 5968Display short help message and exit. 5969 5970@item -V 5971@itemx --version 5972Display information about the program's name, version, origin and legal 5973status, all on standard output, and then exit successfully. 5974@end table 5975 5976 5977@node Scripted Restoration 5978@section Using the Restore Script 5979 5980To restore files that were archived using a scripted backup, use the 5981@code{restore} script. Its usage is quite straightforward. In the 5982simplest form, invoke @code{restore --all}, it will 5983then restore all the file systems and files specified in 5984@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}). 5985 5986You may select the file systems (and/or files) to restore by 5987giving @code{restore} list of @dfn{patterns} in its command 5988line. For example, running 5989 5990@smallexample 5991restore 'albert:*' 5992@end smallexample 5993 5994@noindent 5995will restore all file systems on the machine @samp{albert}. A more 5996complicated example: 5997 5998@smallexample 5999restore 'albert:*' '*:/var' 6000@end smallexample 6001 6002@noindent 6003This command will restore all file systems on the machine @samp{albert} 6004as well as @file{/var} file system on all machines. 6005 6006By default @code{restore} will start restoring files from the lowest 6007available dump level (usually zero) and will continue through 6008all available dump levels. There may be situations where such a 6009thorough restore is not necessary. For example, you may wish to 6010restore only files from the recent level one backup. To do so, 6011use @option{--level} option, as shown in the example below: 6012 6013@smallexample 6014restore --level=1 6015@end smallexample 6016 6017The full list of options accepted by @code{restore} follows: 6018 6019@table @option 6020@item -a 6021@itemx --all 6022Restore all file systems and files specified in @file{backup-specs} 6023 6024@item -l @var{level} 6025@itemx --level=@var{level} 6026Start restoring from the given backup level, instead of the default 0. 6027 6028@item -v[@var{level}] 6029@itemx --verbose[=@var{level}] 6030Set verbosity level. The higher the level is, the more debugging 6031information will be output during execution. Default @var{level} 6032is 100, which means the highest debugging level. 6033 6034@item -h 6035@itemx --help 6036Display short help message and exit. 6037 6038@item -V 6039@itemx --version 6040Display information about the program's name, version, origin and legal 6041status, all on standard output, and then exit successfully. 6042@end table 6043 6044You should start the restore script with the media containing the 6045first volume of the archive mounted. The script will prompt for other 6046volumes as they are needed. If the archive is on tape, you don't need 6047to rewind the tape to to its beginning---if the tape head is 6048positioned past the beginning of the archive, the script will rewind 6049the tape as needed. @xref{Tape Positioning}, for a discussion of tape 6050positioning. 6051 6052@quotation 6053@strong{Warning:} The script will delete files from the active file 6054system if they were not in the file system when the archive was made. 6055@end quotation 6056 6057@xref{Incremental Dumps}, for an explanation of how the script makes 6058that determination. 6059 6060@node Choosing 6061@chapter Choosing Files and Names for @command{tar} 6062@UNREVISED 6063 6064Certain options to @command{tar} enable you to specify a name for your 6065archive. Other options let you decide which files to include or exclude 6066from the archive, based on when or whether files were modified, whether 6067the file names do or don't match specified patterns, or whether files 6068are in specified directories. 6069 6070This chapter discusses these options in detail. 6071 6072@menu 6073* file:: Choosing the Archive's Name 6074* Selecting Archive Members:: 6075* files:: Reading Names from a File 6076* exclude:: Excluding Some Files 6077* wildcards:: Wildcards Patterns and Matching 6078* quoting styles:: Ways of Quoting Special Characters in Names 6079* transform:: Modifying File and Member Names 6080* after:: Operating Only on New Files 6081* recurse:: Descending into Directories 6082* one:: Crossing File System Boundaries 6083@end menu 6084 6085@node file 6086@section Choosing and Naming Archive Files 6087@UNREVISED 6088 6089@cindex Naming an archive 6090@cindex Archive Name 6091@cindex Choosing an archive file 6092@cindex Where is the archive? 6093By default, @command{tar} uses an archive file name that was compiled when 6094it was built on the system; usually this name refers to some physical 6095tape drive on the machine. However, the person who installed @command{tar} 6096on the system may not have set the default to a meaningful value as far as 6097most users are concerned. As a result, you will usually want to tell 6098@command{tar} where to find (or create) the archive. The 6099@option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) 6100option allows you to either specify or name a file to use as the archive 6101instead of the default archive file location. 6102 6103@table @option 6104@xopindex{file, short description} 6105@item --file=@var{archive-name} 6106@itemx -f @var{archive-name} 6107Name the archive to create or operate on. Use in conjunction with 6108any operation. 6109@end table 6110 6111For example, in this @command{tar} command, 6112 6113@smallexample 6114$ @kbd{tar -cvf collection.tar blues folk jazz} 6115@end smallexample 6116 6117@noindent 6118@file{collection.tar} is the name of the archive. It must directly 6119follow the @option{-f} option, since whatever directly follows @option{-f} 6120@emph{will} end up naming the archive. If you neglect to specify an 6121archive name, you may end up overwriting a file in the working directory 6122with the archive you create since @command{tar} will use this file's name 6123for the archive name. 6124 6125An archive can be saved as a file in the file system, sent through a 6126pipe or over a network, or written to an I/O device such as a tape, 6127floppy disk, or CD write drive. 6128 6129@cindex Writing new archives 6130@cindex Archive creation 6131If you do not name the archive, @command{tar} uses the value of the 6132environment variable @env{TAPE} as the file name for the archive. If 6133that is not available, @command{tar} uses a default, compiled-in archive 6134name, usually that for tape unit zero (i.e., @file{/dev/tu00}). 6135 6136@cindex Standard input and output 6137@cindex tar to standard input and output 6138If you use @file{-} as an @var{archive-name}, @command{tar} reads the 6139archive from standard input (when listing or extracting files), or 6140writes it to standard output (when creating an archive). If you use 6141@file{-} as an @var{archive-name} when modifying an archive, 6142@command{tar} reads the original archive from its standard input and 6143writes the entire new archive to its standard output. 6144 6145The following example is a convenient way of copying directory 6146hierarchy from @file{sourcedir} to @file{targetdir}. 6147 6148@smallexample 6149$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)} 6150@end smallexample 6151 6152The @option{-C} option allows to avoid using subshells: 6153 6154@smallexample 6155$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -} 6156@end smallexample 6157 6158In both examples above, the leftmost @command{tar} invocation archives 6159the contents of @file{sourcedir} to the standard output, while the 6160rightmost one reads this archive from its standard input and 6161extracts it. The @option{-p} option tells it to restore permissions 6162of the extracted files. 6163 6164@cindex Remote devices 6165@cindex tar to a remote device 6166@anchor{remote-dev} 6167To specify an archive file on a device attached to a remote machine, 6168use the following: 6169 6170@smallexample 6171@kbd{--file=@var{hostname}:/@var{dev}/@var{file-name}} 6172@end smallexample 6173 6174@noindent 6175@command{tar} will complete the remote connection, if possible, and 6176prompt you for a username and password. If you use 6177@option{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar} 6178will complete the remote connection, if possible, using your username 6179as the username on the remote machine. 6180 6181@cindex Local and remote archives 6182@anchor{local and remote archives} 6183If the archive file name includes a colon (@samp{:}), then it is assumed 6184to be a file on another machine. If the archive file is 6185@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the 6186host @var{host}. The remote host is accessed using the @command{rsh} 6187program, with a username of @var{user}. If the username is omitted 6188(along with the @samp{@@} sign), then your user name will be used. 6189(This is the normal @command{rsh} behavior.) It is necessary for the 6190remote machine, in addition to permitting your @command{rsh} access, to 6191have the @file{rmt} program installed (This command is included in 6192the @GNUTAR{} distribution and by default is installed under 6193@file{@var{prefix}/libexec/rmt}, were @var{prefix} means your 6194installation prefix). If you need to use a file whose name includes a 6195colon, then the remote tape drive behavior 6196can be inhibited by using the @option{--force-local} option. 6197 6198When the archive is being created to @file{/dev/null}, @GNUTAR{} 6199tries to minimize input and output operations. The Amanda backup 6200system, when used with @GNUTAR{}, has an initial sizing pass which 6201uses this feature. 6202 6203@node Selecting Archive Members 6204@section Selecting Archive Members 6205@cindex Specifying files to act on 6206@cindex Specifying archive members 6207 6208@dfn{File Name arguments} specify which files in the file system 6209@command{tar} operates on, when creating or adding to an archive, or which 6210archive members @command{tar} operates on, when reading or deleting from 6211an archive. @xref{Operations}. 6212 6213To specify file names, you can include them as the last arguments on 6214the command line, as follows: 6215@smallexample 6216@kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}] 6217@end smallexample 6218 6219If a file name begins with dash (@samp{-}), precede it with 6220@option{--add-file} option to prevent it from being treated as an 6221option. 6222 6223@anchor{input name quoting} 6224By default @GNUTAR{} attempts to @dfn{unquote} each file or member 6225name, replacing @dfn{escape sequences} according to the following 6226table: 6227 6228@multitable @columnfractions 0.20 0.60 6229@headitem Escape @tab Replaced with 6230@item \a @tab Audible bell (@acronym{ASCII} 7) 6231@item \b @tab Backspace (@acronym{ASCII} 8) 6232@item \f @tab Form feed (@acronym{ASCII} 12) 6233@item \n @tab New line (@acronym{ASCII} 10) 6234@item \r @tab Carriage return (@acronym{ASCII} 13) 6235@item \t @tab Horizontal tabulation (@acronym{ASCII} 9) 6236@item \v @tab Vertical tabulation (@acronym{ASCII} 11) 6237@item \? @tab @acronym{ASCII} 127 6238@item \@var{n} @tab @acronym{ASCII} @var{n} (@var{n} should be an octal number 6239 of up to 3 digits) 6240@end multitable 6241 6242A backslash followed by any other symbol is retained. 6243 6244This default behavior is controlled by the following command line 6245option: 6246 6247@table @option 6248@opindex unquote 6249@item --unquote 6250Enable unquoting input file or member names (default). 6251 6252@opindex no-unquote 6253@item --no-unquote 6254Disable unquoting input file or member names. 6255@end table 6256 6257If you specify a directory name as a file name argument, all the files 6258in that directory are operated on by @command{tar}. 6259 6260If you do not specify files, @command{tar} behavior differs depending 6261on the operation mode as described below: 6262 6263When @command{tar} is invoked with @option{--create} (@option{-c}), 6264@command{tar} will stop immediately, reporting the following: 6265 6266@smallexample 6267@group 6268$ @kbd{tar cf a.tar} 6269tar: Cowardly refusing to create an empty archive 6270Try `tar --help' or `tar --usage' for more information. 6271@end group 6272@end smallexample 6273 6274If you specify either @option{--list} (@option{-t}) or 6275@option{--extract} (@option{--get}, @option{-x}), @command{tar} 6276operates on all the archive members in the archive. 6277 6278If run with @option{--diff} option, tar will compare the archive with 6279the contents of the current working directory. 6280 6281If you specify any other operation, @command{tar} does nothing. 6282 6283By default, @command{tar} takes file names from the command line. However, 6284there are other ways to specify file or member names, or to modify the 6285manner in which @command{tar} selects the files or members upon which to 6286operate. In general, these methods work both for specifying the names 6287of files and archive members. 6288 6289@node files 6290@section Reading Names from a File 6291 6292@cindex Reading file names from a file 6293@cindex Lists of file names 6294@cindex File Name arguments, alternatives 6295Instead of giving the names of files or archive members on the command 6296line, you can put the names into a file, and then use the 6297@option{--files-from=@var{file-of-names}} (@option{-T 6298@var{file-of-names}}) option to @command{tar}. Give the name of the 6299file which contains the list of files to include as the argument to 6300@option{--files-from}. In the list, the file names should be separated by 6301newlines. You will frequently use this option when you have generated 6302the list of files to archive with the @command{find} utility. 6303 6304@table @option 6305@opindex files-from 6306@item --files-from=@var{file-name} 6307@itemx -T @var{file-name} 6308Get names to extract or create from file @var{file-name}. 6309@end table 6310 6311If you give a single dash as a file name for @option{--files-from}, (i.e., 6312you specify either @code{--files-from=-} or @code{-T -}), then the file 6313names are read from standard input. 6314 6315Unless you are running @command{tar} with @option{--create}, you can not use 6316both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same 6317command. 6318 6319Any number of @option{-T} options can be given in the command line. 6320 6321The following example shows how to use @command{find} to generate a list of 6322files smaller than 400K in length and put that list into a file 6323called @file{small-files}. You can then use the @option{-T} option to 6324@command{tar} to specify the files from that file, @file{small-files}, to 6325create the archive @file{little.tgz}. (The @option{-z} option to 6326@command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for 6327more information.) 6328 6329@smallexample 6330$ @kbd{find . -size -400 -print > small-files} 6331$ @kbd{tar -c -v -z -T small-files -f little.tgz} 6332@end smallexample 6333 6334@noindent 6335In the file list given by @option{-T} option, any file name beginning 6336with @samp{-} character is considered a @command{tar} option and is 6337processed accordingly.@footnote{Versions of @GNUTAR{} up to 1.15.1 6338recognized only @option{-C} option in file lists, and only if the 6339option and its argument occupied two consecutive lines.} For example, 6340the common use of this feature is to change to another directory by 6341specifying @option{-C} option: 6342 6343@smallexample 6344@group 6345$ @kbd{cat list} 6346-C/etc 6347passwd 6348hosts 6349-C/lib 6350libc.a 6351$ @kbd{tar -c -f foo.tar --files-from list} 6352@end group 6353@end smallexample 6354 6355@noindent 6356In this example, @command{tar} will first switch to @file{/etc} 6357directory and add files @file{passwd} and @file{hosts} to the 6358archive. Then it will change to @file{/lib} directory and will archive 6359the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will 6360contain: 6361 6362@smallexample 6363@group 6364$ @kbd{tar tf foo.tar} 6365passwd 6366hosts 6367libc.a 6368@end group 6369@end smallexample 6370 6371@noindent 6372@xopindex{directory, using in @option{--files-from} argument} 6373Notice that the option parsing algorithm used with @option{-T} is 6374stricter than the one used by shell. Namely, when specifying option 6375arguments, you should observe the following rules: 6376 6377@itemize @bullet 6378@item 6379When using short (single-letter) option form, its argument must 6380immediately follow the option letter, without any intervening 6381whitespace. For example: @code{-Cdir}. 6382 6383@item 6384When using long option form, the option argument must be separated 6385from the option by a single equal sign. No whitespace is allowed on 6386any side of the equal sign. For example: @code{--directory=dir}. 6387 6388@item 6389For both short and long option forms, the option argument can be given 6390on the next line after the option name, e.g.: 6391 6392@smallexample 6393@group 6394--directory 6395dir 6396@end group 6397@end smallexample 6398 6399@noindent 6400and 6401 6402@smallexample 6403@group 6404-C 6405dir 6406@end group 6407@end smallexample 6408@end itemize 6409 6410@opindex add-file 6411If you happen to have a file whose name starts with @samp{-}, 6412precede it with @option{--add-file} option to prevent it from 6413being recognized as an option. For example: @code{--add-file=--my-file}. 6414 6415@menu 6416* nul:: 6417@end menu 6418 6419@node nul 6420@subsection @code{NUL} Terminated File Names 6421 6422@cindex File names, terminated by @code{NUL} 6423@cindex @code{NUL} terminated file names 6424The @option{--null} option causes 6425@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) 6426to read file names terminated by a @code{NUL} instead of a newline, so 6427files whose names contain newlines can be archived using 6428@option{--files-from}. 6429 6430@table @option 6431@opindex null 6432@item --null 6433Only consider @code{NUL} terminated file names, instead of files that 6434terminate in a newline. 6435@end table 6436 6437The @option{--null} option is just like the one in @acronym{GNU} 6438@command{xargs} and @command{cpio}, and is useful with the 6439@option{-print0} predicate of @acronym{GNU} @command{find}. In 6440@command{tar}, @option{--null} also disables special handling for 6441file names that begin with dash. 6442 6443This example shows how to use @command{find} to generate a list of files 6444larger than 800K in length and put that list into a file called 6445@file{long-files}. The @option{-print0} option to @command{find} is just 6446like @option{-print}, except that it separates files with a @code{NUL} 6447rather than with a newline. You can then run @command{tar} with both the 6448@option{--null} and @option{-T} options to specify that @command{tar} get the 6449files from that file, @file{long-files}, to create the archive 6450@file{big.tgz}. The @option{--null} option to @command{tar} will cause 6451@command{tar} to recognize the @code{NUL} separator between files. 6452 6453@smallexample 6454$ @kbd{find . -size +800 -print0 > long-files} 6455$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar} 6456@end smallexample 6457 6458@FIXME{say anything else here to conclude the section?} 6459 6460@node exclude 6461@section Excluding Some Files 6462@UNREVISED 6463 6464@cindex File names, excluding files by 6465@cindex Excluding files by name and pattern 6466@cindex Excluding files by file system 6467To avoid operating on files whose names match a particular pattern, 6468use the @option{--exclude} or @option{--exclude-from} options. 6469 6470@table @option 6471@opindex exclude 6472@item --exclude=@var{pattern} 6473Causes @command{tar} to ignore files that match the @var{pattern}. 6474@end table 6475 6476@findex exclude 6477The @option{--exclude=@var{pattern}} option prevents any file or 6478member whose name matches the shell wildcard (@var{pattern}) from 6479being operated on. 6480For example, to create an archive with all the contents of the directory 6481@file{src} except for files whose names end in @file{.o}, use the 6482command @samp{tar -cf src.tar --exclude='*.o' src}. 6483 6484You may give multiple @option{--exclude} options. 6485 6486@table @option 6487@opindex exclude-from 6488@item --exclude-from=@var{file} 6489@itemx -X @var{file} 6490Causes @command{tar} to ignore files that match the patterns listed in 6491@var{file}. 6492@end table 6493 6494@findex exclude-from 6495Use the @option{--exclude-from} option to read a 6496list of patterns, one per line, from @var{file}; @command{tar} will 6497ignore files matching those patterns. Thus if @command{tar} is 6498called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a 6499single line @file{*.o}, no files whose names end in @file{.o} will be 6500added to the archive. 6501 6502@findex exclude-caches 6503When creating an archive, the @option{--exclude-caches} option family 6504causes @command{tar} to exclude all directories that contain a @dfn{cache 6505directory tag}. A cache directory tag is a short file with the 6506well-known name @file{CACHEDIR.TAG} and having a standard header 6507specified in @url{http://www.brynosaurus.com/cachedir/spec.html}. 6508Various applications write cache directory tags into directories they 6509use to hold regenerable, non-precious data, so that such data can be 6510more easily excluded from backups. 6511 6512There are three @samp{exclude-caches} option, providing a different 6513exclusion semantics: 6514 6515@table @option 6516@opindex exclude-caches 6517@item --exclude-caches 6518Do not archive the contents of the directory, but archive the 6519directory itself and the @file{CACHEDIR.TAG} file. 6520 6521@opindex exclude-caches-under 6522@item --exclude-caches-under 6523Do not archive the contents of the directory, nor the 6524@file{CACHEDIR.TAG} file, archive only the directory itself. 6525 6526@opindex exclude-caches-all 6527@item --exclude-caches-all 6528Omit directories containing @file{CACHEDIR.TAG} file entirely. 6529@end table 6530 6531@findex exclude-tag 6532Another option family, @option{--exclude-tag}, provides a generalization of 6533this concept. It takes a single argument, a file name to look for. 6534Any directory that contains this file will be excluded from the dump. 6535Similarly to @samp{exclude-caches}, there are three options in this 6536option family: 6537 6538@table @option 6539@opindex exclude-tag 6540@item --exclude-tag=@var{file} 6541Do not dump the contents of the directory, but dump the 6542directory itself and the @var{file}. 6543 6544@opindex exclude-tag-under 6545@item --exclude-tag-under=@var{file} 6546Do not dump the contents of the directory, nor the 6547@var{file}, archive only the directory itself. 6548 6549@opindex exclude-tag-all 6550@item --exclude-tag-all=@var{file} 6551Omit directories containing @var{file} file entirely. 6552@end table 6553 6554Multiple @option{--exclude-tag*} options can be given. 6555 6556For example, given this directory: 6557 6558@smallexample 6559@group 6560$ @kbd{find dir} 6561dir 6562dir/blues 6563dir/jazz 6564dir/folk 6565dir/folk/tagfile 6566dir/folk/sanjuan 6567dir/folk/trote 6568@end group 6569@end smallexample 6570 6571The @option{--exclude-tag} will produce the following: 6572 6573@smallexample 6574$ @kbd{tar -cf archive.tar --exclude-tag=tagfile -v dir} 6575dir/ 6576dir/blues 6577dir/jazz 6578dir/folk/ 6579tar: dir/folk/: contains a cache directory tag tagfile; 6580 contents not dumped 6581dir/folk/tagfile 6582@end smallexample 6583 6584Both the @file{dir/folk} directory and its tagfile are preserved in 6585the archive, however the rest of files in this directory are not. 6586 6587Now, using the @option{--exclude-tag-under} option will exclude 6588@file{tagfile} from the dump, while still preserving the directory 6589itself, as shown in this example: 6590 6591@smallexample 6592$ @kbd{tar -cf archive.tar --exclude-tag-under=tagfile -v dir} 6593dir/ 6594dir/blues 6595dir/jazz 6596dir/folk/ 6597./tar: dir/folk/: contains a cache directory tag tagfile; 6598 contents not dumped 6599@end smallexample 6600 6601Finally, using @option{--exclude-tag-all} omits the @file{dir/folk} 6602directory entirely: 6603 6604@smallexample 6605$ @kbd{tar -cf archive.tar --exclude-tag-all=tagfile -v dir} 6606dir/ 6607dir/blues 6608dir/jazz 6609./tar: dir/folk/: contains a cache directory tag tagfile; 6610 directory not dumped 6611@end smallexample 6612 6613@menu 6614* problems with exclude:: 6615@end menu 6616 6617@node problems with exclude 6618@unnumberedsubsec Problems with Using the @code{exclude} Options 6619 6620@xopindex{exclude, potential problems with} 6621Some users find @samp{exclude} options confusing. Here are some common 6622pitfalls: 6623 6624@itemize @bullet 6625@item 6626The main operating mode of @command{tar} does not act on a file name 6627explicitly listed on the command line, if one of its file name 6628components is excluded. In the example above, if 6629you create an archive and exclude files that end with @samp{*.o}, but 6630explicitly name the file @samp{dir.o/foo} after all the options have been 6631listed, @samp{dir.o/foo} will be excluded from the archive. 6632 6633@item 6634You can sometimes confuse the meanings of @option{--exclude} and 6635@option{--exclude-from}. Be careful: use @option{--exclude} when files 6636to be excluded are given as a pattern on the command line. Use 6637@option{--exclude-from} to introduce the name of a file which contains 6638a list of patterns, one per line; each of these patterns can exclude 6639zero, one, or many files. 6640 6641@item 6642When you use @option{--exclude=@var{pattern}}, be sure to quote the 6643@var{pattern} parameter, so @GNUTAR{} sees wildcard characters 6644like @samp{*}. If you do not do this, the shell might expand the 6645@samp{*} itself using files at hand, so @command{tar} might receive a 6646list of files instead of one pattern, or none at all, making the 6647command somewhat illegal. This might not correspond to what you want. 6648 6649For example, write: 6650 6651@smallexample 6652$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}} 6653@end smallexample 6654 6655@noindent 6656rather than: 6657 6658@smallexample 6659# @emph{Wrong!} 6660$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}} 6661@end smallexample 6662 6663@item 6664You must use use shell syntax, or globbing, rather than @code{regexp} 6665syntax, when using exclude options in @command{tar}. If you try to use 6666@code{regexp} syntax to describe files to be excluded, your command 6667might fail. 6668 6669@item 6670@FIXME{The change in semantics must have occurred before 1.11, 6671so I doubt if it is worth mentioning at all. Anyway, should at 6672least specify in which version the semantics changed.} 6673In earlier versions of @command{tar}, what is now the 6674@option{--exclude-from} option was called @option{--exclude} instead. 6675Now, @option{--exclude} applies to patterns listed on the command 6676line and @option{--exclude-from} applies to patterns listed in a 6677file. 6678 6679@end itemize 6680 6681@node wildcards 6682@section Wildcards Patterns and Matching 6683 6684@dfn{Globbing} is the operation by which @dfn{wildcard} characters, 6685@samp{*} or @samp{?} for example, are replaced and expanded into all 6686existing files matching the given pattern. @GNUTAR{} can use wildcard 6687patterns for matching (or globbing) archive members when extracting 6688from or listing an archive. Wildcard patterns are also used for 6689verifying volume labels of @command{tar} archives. This section has the 6690purpose of explaining wildcard syntax for @command{tar}. 6691 6692@FIXME{the next few paragraphs need work.} 6693 6694A @var{pattern} should be written according to shell syntax, using wildcard 6695characters to effect globbing. Most characters in the pattern stand 6696for themselves in the matched string, and case is significant: @samp{a} 6697will match only @samp{a}, and not @samp{A}. The character @samp{?} in the 6698pattern matches any single character in the matched string. The character 6699@samp{*} in the pattern matches zero, one, or more single characters in 6700the matched string. The character @samp{\} says to take the following 6701character of the pattern @emph{literally}; it is useful when one needs to 6702match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves. 6703 6704The character @samp{[}, up to the matching @samp{]}, introduces a character 6705class. A @dfn{character class} is a list of acceptable characters 6706for the next single character of the matched string. For example, 6707@samp{[abcde]} would match any of the first five letters of the alphabet. 6708Note that within a character class, all of the ``special characters'' 6709listed above other than @samp{\} lose their special meaning; for example, 6710@samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\}, 6711@samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints, 6712the characters @samp{-} and @samp{]} must either come @emph{first} or 6713@emph{last} in a character class.) 6714 6715@cindex Excluding characters from a character class 6716@cindex Character class, excluding characters from 6717If the first character of the class after the opening @samp{[} 6718is @samp{!} or @samp{^}, then the meaning of the class is reversed. 6719Rather than listing character to match, it lists those characters which 6720are @emph{forbidden} as the next single character of the matched string. 6721 6722Other characters of the class stand for themselves. The special 6723construction @samp{[@var{a}-@var{e}]}, using an hyphen between two 6724letters, is meant to represent all characters between @var{a} and 6725@var{e}, inclusive. 6726 6727@FIXME{need to add a sentence or so here to make this clear for those 6728who don't have dan around.} 6729 6730Periods (@samp{.}) or forward slashes (@samp{/}) are not considered 6731special for wildcard matches. However, if a pattern completely matches 6732a directory prefix of a matched string, then it matches the full matched 6733string: thus, excluding a directory also excludes all the files beneath it. 6734 6735@menu 6736* controlling pattern-matching:: 6737@end menu 6738 6739@node controlling pattern-matching 6740@unnumberedsubsec Controlling Pattern-Matching 6741 6742For the purposes of this section, we call @dfn{exclusion members} all 6743member names obtained while processing @option{--exclude} and 6744@option{--exclude-from} options, and @dfn{inclusion members} those 6745member names that were given in the command line or read from the file 6746specified with @option{--files-from} option. 6747 6748These two pairs of member lists are used in the following operations: 6749@option{--diff}, @option{--extract}, @option{--list}, 6750@option{--update}. 6751 6752There are no inclusion members in create mode (@option{--create} and 6753@option{--append}), since in this mode the names obtained from the 6754command line refer to @emph{files}, not archive members. 6755 6756By default, inclusion members are compared with archive members 6757literally @footnote{Notice that earlier @GNUTAR{} versions used 6758globbing for inclusion members, which contradicted to UNIX98 6759specification and was not documented. @xref{Changes}, for more 6760information on this and other changes.} and exclusion members are 6761treated as globbing patterns. For example: 6762 6763@smallexample 6764@group 6765$ @kbd{tar tf foo.tar} 6766a.c 6767b.c 6768a.txt 6769[remarks] 6770# @i{Member names are used verbatim:} 6771$ @kbd{tar -xf foo.tar -v '[remarks]'} 6772[remarks] 6773# @i{Exclude member names are globbed:} 6774$ @kbd{tar -xf foo.tar -v --exclude '*.c'} 6775a.txt 6776[remarks] 6777@end group 6778@end smallexample 6779 6780This behavior can be altered by using the following options: 6781 6782@table @option 6783@opindex wildcards 6784@item --wildcards 6785Treat all member names as wildcards. 6786 6787@opindex no-wildcards 6788@item --no-wildcards 6789Treat all member names as literal strings. 6790@end table 6791 6792Thus, to extract files whose names end in @samp{.c}, you can use: 6793 6794@smallexample 6795$ @kbd{tar -xf foo.tar -v --wildcards '*.c'} 6796a.c 6797b.c 6798@end smallexample 6799 6800@noindent 6801Notice quoting of the pattern to prevent the shell from interpreting 6802it. 6803 6804The effect of @option{--wildcards} option is canceled by 6805@option{--no-wildcards}. This can be used to pass part of 6806the command line arguments verbatim and other part as globbing 6807patterns. For example, the following invocation: 6808 6809@smallexample 6810$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'} 6811@end smallexample 6812 6813@noindent 6814instructs @command{tar} to extract from @file{foo.tar} all files whose 6815names end in @samp{.txt} and the file named @file{[remarks]}. 6816 6817Normally, a pattern matches a name if an initial subsequence of the 6818name's components matches the pattern, where @samp{*}, @samp{?}, and 6819@samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards, 6820and wildcards can match @samp{/}. 6821 6822Other than optionally stripping leading @samp{/} from names 6823(@pxref{absolute}), patterns and names are used as-is. For 6824example, trailing @samp{/} is not trimmed from a user-specified name 6825before deciding whether to exclude it. 6826 6827However, this matching procedure can be altered by the options listed 6828below. These options accumulate. For example: 6829 6830@smallexample 6831--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme' 6832@end smallexample 6833 6834@noindent 6835ignores case when excluding @samp{makefile}, but not when excluding 6836@samp{readme}. 6837 6838@table @option 6839@opindex anchored 6840@opindex no-anchored 6841@item --anchored 6842@itemx --no-anchored 6843If anchored, a pattern must match an initial subsequence 6844of the name's components. Otherwise, the pattern can match any 6845subsequence. Default is @option{--no-anchored} for exclusion members 6846and @option{--anchored} inclusion members. 6847 6848@opindex ignore-case 6849@opindex no-ignore-case 6850@item --ignore-case 6851@itemx --no-ignore-case 6852When ignoring case, upper-case patterns match lower-case names and vice versa. 6853When not ignoring case (the default), matching is case-sensitive. 6854 6855@opindex wildcards-match-slash 6856@opindex no-wildcards-match-slash 6857@item --wildcards-match-slash 6858@itemx --no-wildcards-match-slash 6859When wildcards match slash (the default for exclusion members), a 6860wildcard like @samp{*} in the pattern can match a @samp{/} in the 6861name. Otherwise, @samp{/} is matched only by @samp{/}. 6862 6863@end table 6864 6865The @option{--recursion} and @option{--no-recursion} options 6866(@pxref{recurse}) also affect how member patterns are interpreted. If 6867recursion is in effect, a pattern matches a name if it matches any of 6868the name's parent directories. 6869 6870The following table summarizes pattern-matching default values: 6871 6872@multitable @columnfractions .3 .7 6873@headitem Members @tab Default settings 6874@item Inclusion @tab @option{--no-wildcards --anchored --no-wildcards-match-slash} 6875@item Exclusion @tab @option{--wildcards --no-anchored --wildcards-match-slash} 6876@end multitable 6877 6878@node quoting styles 6879@section Quoting Member Names 6880 6881When displaying member names, @command{tar} takes care to avoid 6882ambiguities caused by certain characters. This is called @dfn{name 6883quoting}. The characters in question are: 6884 6885@itemize @bullet 6886@item Non-printable control characters: 6887 6888@multitable @columnfractions 0.20 0.10 0.60 6889@headitem Character @tab @acronym{ASCII} @tab Character name 6890@item \a @tab 7 @tab Audible bell 6891@item \b @tab 8 @tab Backspace 6892@item \f @tab 12 @tab Form feed 6893@item \n @tab 10 @tab New line 6894@item \r @tab 13 @tab Carriage return 6895@item \t @tab 9 @tab Horizontal tabulation 6896@item \v @tab 11 @tab Vertical tabulation 6897@end multitable 6898 6899@item Space (@acronym{ASCII} 32) 6900 6901@item Single and double quotes (@samp{'} and @samp{"}) 6902 6903@item Backslash (@samp{\}) 6904@end itemize 6905 6906The exact way @command{tar} uses to quote these characters depends on 6907the @dfn{quoting style}. The default quoting style, called 6908@dfn{escape} (see below), uses backslash notation to represent control 6909characters, space and backslash. Using this quoting style, control 6910characters are represented as listed in column @samp{Character} in the 6911above table, a space is printed as @samp{\ } and a backslash as @samp{\\}. 6912 6913@GNUTAR{} offers seven distinct quoting styles, which can be selected 6914using @option{--quoting-style} option: 6915 6916@table @option 6917@item --quoting-style=@var{style} 6918@opindex quoting-style 6919 6920Sets quoting style. Valid values for @var{style} argument are: 6921literal, shell, shell-always, c, escape, locale, clocale. 6922@end table 6923 6924These styles are described in detail below. To illustrate their 6925effect, we will use an imaginary tar archive @file{arch.tar} 6926containing the following members: 6927 6928@smallexample 6929@group 6930# 1. Contains horizontal tabulation character. 6931a tab 6932# 2. Contains newline character 6933a 6934newline 6935# 3. Contains a space 6936a space 6937# 4. Contains double quotes 6938a"double"quote 6939# 5. Contains single quotes 6940a'single'quote 6941# 6. Contains a backslash character: 6942a\backslash 6943@end group 6944@end smallexample 6945 6946Here is how usual @command{ls} command would have listed them, if they 6947had existed in the current working directory: 6948 6949@smallexample 6950@group 6951$ @kbd{ls} 6952a\ttab 6953a\nnewline 6954a\ space 6955a"double"quote 6956a'single'quote 6957a\\backslash 6958@end group 6959@end smallexample 6960 6961Quoting styles: 6962 6963@table @samp 6964@item literal 6965No quoting, display each character as is: 6966 6967@smallexample 6968@group 6969$ @kbd{tar tf arch.tar --quoting-style=literal} 6970./ 6971./a space 6972./a'single'quote 6973./a"double"quote 6974./a\backslash 6975./a tab 6976./a 6977newline 6978@end group 6979@end smallexample 6980 6981@item shell 6982Display characters the same way Bourne shell does: 6983control characters, except @samp{\t} and @samp{\n}, are printed using 6984backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a 6985single quote is printed as @samp{\'}. If a name contains any quoted 6986characters, it is enclosed in single quotes. In particular, if a name 6987contains single quotes, it is printed as several single-quoted strings: 6988 6989@smallexample 6990@group 6991$ @kbd{tar tf arch.tar --quoting-style=shell} 6992./ 6993'./a space' 6994'./a'\''single'\''quote' 6995'./a"double"quote' 6996'./a\backslash' 6997'./a tab' 6998'./a 6999newline' 7000@end group 7001@end smallexample 7002 7003@item shell-always 7004Same as @samp{shell}, but the names are always enclosed in single 7005quotes: 7006 7007@smallexample 7008@group 7009$ @kbd{tar tf arch.tar --quoting-style=shell-always} 7010'./' 7011'./a space' 7012'./a'\''single'\''quote' 7013'./a"double"quote' 7014'./a\backslash' 7015'./a tab' 7016'./a 7017newline' 7018@end group 7019@end smallexample 7020 7021@item c 7022Use the notation of the C programming language. All names are 7023enclosed in double quotes. Control characters are quoted using 7024backslash notations, double quotes are represented as @samp{\"}, 7025backslash characters are represented as @samp{\\}. Single quotes and 7026spaces are not quoted: 7027 7028@smallexample 7029@group 7030$ @kbd{tar tf arch.tar --quoting-style=c} 7031"./" 7032"./a space" 7033"./a'single'quote" 7034"./a\"double\"quote" 7035"./a\\backslash" 7036"./a\ttab" 7037"./a\nnewline" 7038@end group 7039@end smallexample 7040 7041@item escape 7042Control characters are printed using backslash notation, a space is 7043printed as @samp{\ } and a backslash as @samp{\\}. This is the 7044default quoting style, unless it was changed when configured the 7045package. 7046 7047@smallexample 7048@group 7049$ @kbd{tar tf arch.tar --quoting-style=escape} 7050./ 7051./a space 7052./a'single'quote 7053./a"double"quote 7054./a\\backslash 7055./a\ttab 7056./a\nnewline 7057@end group 7058@end smallexample 7059 7060@item locale 7061Control characters, single quote and backslash are printed using 7062backslash notation. All names are quoted using left and right 7063quotation marks, appropriate to the current locale. If it does not 7064define quotation marks, use @samp{`} as left and @samp{'} as right 7065quotation marks. Any occurrences of the right quotation mark in a 7066name are escaped with @samp{\}, for example: 7067 7068For example: 7069 7070@smallexample 7071@group 7072$ @kbd{tar tf arch.tar --quoting-style=locale} 7073`./' 7074`./a space' 7075`./a\'single\'quote' 7076`./a"double"quote' 7077`./a\\backslash' 7078`./a\ttab' 7079`./a\nnewline' 7080@end group 7081@end smallexample 7082 7083@item clocale 7084Same as @samp{locale}, but @samp{"} is used for both left and right 7085quotation marks, if not provided by the currently selected locale: 7086 7087@smallexample 7088@group 7089$ @kbd{tar tf arch.tar --quoting-style=clocale} 7090"./" 7091"./a space" 7092"./a'single'quote" 7093"./a\"double\"quote" 7094"./a\\backslash" 7095"./a\ttab" 7096"./a\nnewline" 7097@end group 7098@end smallexample 7099@end table 7100 7101You can specify which characters should be quoted in addition to those 7102implied by the current quoting style: 7103 7104@table @option 7105@item --quote-chars=@var{string} 7106Always quote characters from @var{string}, even if the selected 7107quoting style would not quote them. 7108@end table 7109 7110For example, using @samp{escape} quoting (compare with the usual 7111escape listing above): 7112 7113@smallexample 7114@group 7115$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'} 7116./ 7117./a\ space 7118./a'single'quote 7119./a\"double\"quote 7120./a\\backslash 7121./a\ttab 7122./a\nnewline 7123@end group 7124@end smallexample 7125 7126To disable quoting of such additional characters, use the following 7127option: 7128 7129@table @option 7130@item --no-quote-chars=@var{string} 7131Remove characters listed in @var{string} from the list of quoted 7132characters set by the previous @option{--quote-chars} option. 7133@end table 7134 7135This option is particularly useful if you have added 7136@option{--quote-chars} to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS}) 7137and wish to disable it for the current invocation. 7138 7139Note, that @option{--no-quote-chars} does @emph{not} disable those 7140characters that are quoted by default in the selected quoting style. 7141 7142@node transform 7143@section Modifying File and Member Names 7144 7145@command{Tar} archives contain detailed information about files stored 7146in them and full file names are part of that information. When 7147storing file to an archive, its file name is recorded in the archive 7148along with the actual file contents. When restoring from an archive, 7149a file is created on disk with exactly the same name as that stored 7150in the archive. In the majority of cases this is the desired behavior 7151of a file archiver. However, there are some cases when it is not. 7152 7153First of all, it is often unsafe to extract archive members with 7154absolute file names or those that begin with a @file{../}. @GNUTAR{} 7155takes special precautions when extracting such names and provides a 7156special option for handling them, which is described in 7157@ref{absolute}. 7158 7159Secondly, you may wish to extract file names without some leading 7160directory components, or with otherwise modified names. In other 7161cases it is desirable to store files under differing names in the 7162archive. 7163 7164@GNUTAR{} provides two options for these needs. 7165 7166@table @option 7167@opindex strip-components 7168@item --strip-components=@var{number} 7169Strip given @var{number} of leading components from file names before 7170extraction. 7171@end table 7172 7173For example, suppose you have archived whole @file{/usr} hierarchy to 7174a tar archive named @file{usr.tar}. Among other files, this archive 7175contains @file{usr/include/stdlib.h}, which you wish to extract to 7176the current working directory. To do so, you type: 7177 7178@smallexample 7179$ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h} 7180@end smallexample 7181 7182The option @option{--strip=2} instructs @command{tar} to strip the 7183two leading components (@file{usr/} and @file{include/}) off the file 7184name. 7185 7186If you add to the above invocation @option{--verbose} (@option{-v}) 7187option, you will note that the verbose listing still contains the 7188full file name, with the two removed components still in place. This 7189can be inconvenient, so @command{tar} provides a special option for 7190altering this behavior: 7191 7192@anchor{show-transformed-names} 7193@table @option 7194@opindex show-transformed-names 7195@item --show-transformed-names 7196Display file or member names with all requested transformations 7197applied. 7198@end table 7199 7200@noindent 7201For example: 7202 7203@smallexample 7204@group 7205$ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h} 7206usr/include/stdlib.h 7207$ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h} 7208stdlib.h 7209@end group 7210@end smallexample 7211 7212Notice that in both cases the file is @file{stdlib.h} extracted to the 7213current working directory, @option{--show-transformed-names} affects 7214only the way its name is displayed. 7215 7216This option is especially useful for verifying whether the invocation 7217will have the desired effect. Thus, before running 7218 7219@smallexample 7220$ @kbd{tar -x --strip=@var{n}} 7221@end smallexample 7222 7223@noindent 7224it is often advisable to run 7225 7226@smallexample 7227$ @kbd{tar -t -v --show-transformed --strip=@var{n}} 7228@end smallexample 7229 7230@noindent 7231to make sure the command will produce the intended results. 7232 7233In case you need to apply more complex modifications to the file name, 7234@GNUTAR{} provides a general-purpose transformation option: 7235 7236@table @option 7237@opindex transform 7238@item --transform=@var{expression} 7239Modify file names using supplied @var{expression}. 7240@end table 7241 7242@noindent 7243The @var{expression} is a @command{sed}-like replace expression of the 7244form: 7245 7246@smallexample 7247s/@var{regexp}/@var{replace}/[@var{flags}] 7248@end smallexample 7249 7250@noindent 7251where @var{regexp} is a @dfn{regular expression}, @var{replace} is a 7252replacement for each file name part that matches @var{regexp}. Both 7253@var{regexp} and @var{replace} are described in detail in 7254@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}. 7255 7256Supported @var{flags} are: 7257 7258@table @samp 7259@item g 7260Apply the replacement to @emph{all} matches to the @var{regexp}, not 7261just the first. 7262 7263@item i 7264Use case-insensitive matching 7265 7266@item x 7267@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended 7268regexps, Extended regular expressions, Extended regular expressions, 7269sed, GNU sed}). 7270 7271@item @var{number} 7272Only replace the @var{number}th match of the @var{regexp}. 7273 7274Note: the @var{posix} standard does not specify what should happen 7275when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{} 7276follows the GNU @command{sed} implementation in this regard, so 7277the interaction is defined to be: ignore matches before the 7278@var{number}th, and then match and replace all matches from the 7279@var{number}th on. 7280 7281@end table 7282 7283Any delimiter can be used in lieue of @samp{/}, the only requirement being 7284that it be used consistently throughout the expression. For example, 7285the following two expressions are equivalent: 7286 7287@smallexample 7288@group 7289s/one/two/ 7290s,one,two, 7291@end group 7292@end smallexample 7293 7294Changing delimiters is often useful when the @var{regex} contains 7295slashes. For example, it is more convenient to write @code{s,/,-,} than 7296@code{s/\//-/}. 7297 7298Here are several examples of @option{--transform} usage: 7299 7300@enumerate 7301@item Extract @file{usr/} hierarchy into @file{usr/local/}: 7302 7303@smallexample 7304$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar} 7305@end smallexample 7306 7307@item Strip two leading directory components (equivalent to 7308@option{--strip-components=2}): 7309 7310@smallexample 7311$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar} 7312@end smallexample 7313 7314@item Prepend @file{/prefix/} to each file name: 7315 7316@smallexample 7317$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar} 7318@end smallexample 7319 7320@item Convert each file name to lower case: 7321 7322@smallexample 7323$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar} 7324@end smallexample 7325 7326@end enumerate 7327 7328Unlike @option{--strip-components}, @option{--transform} can be used 7329in any @GNUTAR{} operation mode. For example, the following command 7330adds files to the archive while replacing the leading @file{usr/} 7331component with @file{var/}: 7332 7333@smallexample 7334$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /} 7335@end smallexample 7336 7337To test @option{--transform} effect we suggest using 7338@option{--show-transformed-names} option: 7339 7340@smallexample 7341$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \ 7342 --verbose --show-transformed-names /} 7343@end smallexample 7344 7345If both @option{--strip-components} and @option{--transform} are used 7346together, then @option{--transform} is applied first, and the required 7347number of components is then stripped from its result. 7348 7349@node after 7350@section Operating Only on New Files 7351@UNREVISED 7352 7353@cindex Excluding file by age 7354@cindex Data Modification time, excluding files by 7355@cindex Modification time, excluding files by 7356@cindex Age, excluding files by 7357The @option{--after-date=@var{date}} (@option{--newer=@var{date}}, 7358@option{-N @var{date}}) option causes @command{tar} to only work on 7359files whose data modification or status change times are newer than 7360the @var{date} given. If @var{date} starts with @samp{/} or @samp{.}, 7361it is taken to be a file name; the data modification time of that file 7362is used as the date. If you use this option when creating or appending 7363to an archive, the archive will only include new files. If you use 7364@option{--after-date} when extracting an archive, @command{tar} will 7365only extract files newer than the @var{date} you specify. 7366 7367If you only want @command{tar} to make the date comparison based on 7368modification of the file's data (rather than status 7369changes), then use the @option{--newer-mtime=@var{date}} option. 7370 7371You may use these options with any operation. Note that these options 7372differ from the @option{--update} (@option{-u}) operation in that they 7373allow you to specify a particular date against which @command{tar} can 7374compare when deciding whether or not to archive the files. 7375 7376@table @option 7377@opindex after-date 7378@opindex newer 7379@item --after-date=@var{date} 7380@itemx --newer=@var{date} 7381@itemx -N @var{date} 7382Only store files newer than @var{date}. 7383 7384Acts on files only if their data modification or status change times are 7385later than @var{date}. Use in conjunction with any operation. 7386 7387If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file 7388name; the data modification time of that file is used as the date. 7389 7390@opindex newer-mtime 7391@item --newer-mtime=@var{date} 7392Acts like @option{--after-date}, but only looks at data modification times. 7393@end table 7394 7395These options limit @command{tar} to operate only on files which have 7396been modified after the date specified. A file's status is considered to have 7397changed if its contents have been modified, or if its owner, 7398permissions, and so forth, have been changed. (For more information on 7399how to specify a date, see @ref{Date input formats}; remember that the 7400entire date argument must be quoted if it contains any spaces.) 7401 7402Gurus would say that @option{--after-date} tests both the data 7403modification time (@code{mtime}, the time the contents of the file 7404were last modified) and the status change time (@code{ctime}, the time 7405the file's status was last changed: owner, permissions, etc.@:) 7406fields, while @option{--newer-mtime} tests only the @code{mtime} 7407field. 7408 7409To be precise, @option{--after-date} checks @emph{both} @code{mtime} and 7410@code{ctime} and processes the file if either one is more recent than 7411@var{date}, while @option{--newer-mtime} only checks @code{mtime} and 7412disregards @code{ctime}. Neither does it use @code{atime} (the last time the 7413contents of the file were looked at). 7414 7415Date specifiers can have embedded spaces. Because of this, you may need 7416to quote date arguments to keep the shell from parsing them as separate 7417arguments. For example, the following command will add to the archive 7418all the files modified less than two days ago: 7419 7420@smallexample 7421$ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'} 7422@end smallexample 7423 7424When any of these options is used with the option @option{--verbose} 7425(@pxref{verbose tutorial}) @GNUTAR{} will try to convert the specified 7426date back to its textual representation and compare that with the 7427one given with the option. If the two dates differ, @command{tar} will 7428print a warning saying what date it will use. This is to help user 7429ensure he is using the right date. For example: 7430 7431@smallexample 7432@group 7433$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .} 7434tar: Option --after-date: Treating date `10 days ago' as 2006-06-11 743513:19:37.232434 7436@end group 7437@end smallexample 7438 7439@quotation 7440@strong{Please Note:} @option{--after-date} and @option{--newer-mtime} 7441should not be used for incremental backups. @xref{Incremental Dumps}, 7442for proper way of creating incremental backups. 7443@end quotation 7444 7445@node recurse 7446@section Descending into Directories 7447@UNREVISED 7448@cindex Avoiding recursion in directories 7449@cindex Descending directories, avoiding 7450@cindex Directories, avoiding recursion 7451@cindex Recursion in directories, avoiding 7452 7453@FIXME{arrggh! this is still somewhat confusing to me. :-< } 7454 7455Usually, @command{tar} will recursively explore all directories (either 7456those given on the command line or through the @option{--files-from} 7457option) for the various files they contain. However, you may not always 7458want @command{tar} to act this way. 7459 7460@opindex no-recursion 7461The @option{--no-recursion} option inhibits @command{tar}'s recursive descent 7462into specified directories. If you specify @option{--no-recursion}, you can 7463use the @command{find} utility for hunting through levels of directories to 7464construct a list of file names which you could then pass to @command{tar}. 7465@command{find} allows you to be more selective when choosing which files to 7466archive; see @ref{files}, for more information on using @command{find} with 7467@command{tar}, or look. 7468 7469@table @option 7470@item --no-recursion 7471Prevents @command{tar} from recursively descending directories. 7472 7473@opindex recursion 7474@item --recursion 7475Requires @command{tar} to recursively descend directories. 7476This is the default. 7477@end table 7478 7479When you use @option{--no-recursion}, @GNUTAR{} grabs 7480directory entries themselves, but does not descend on them 7481recursively. Many people use @command{find} for locating files they 7482want to back up, and since @command{tar} @emph{usually} recursively 7483descends on directories, they have to use the @samp{@w{-not -type d}} 7484test in their @command{find} invocation (@pxref{Type, Type, Type test, 7485find, Finding Files}), as they usually do not want all the files in a 7486directory. They then use the @option{--files-from} option to archive 7487the files located via @command{find}. 7488 7489The problem when restoring files archived in this manner is that the 7490directories themselves are not in the archive; so the 7491@option{--same-permissions} (@option{--preserve-permissions}, 7492@option{-p}) option does not affect them---while users might really 7493like it to. Specifying @option{--no-recursion} is a way to tell 7494@command{tar} to grab only the directory entries given to it, adding 7495no new files on its own. To summarize, if you use @command{find} to 7496create a list of files to be stored in an archive, use it as follows: 7497 7498@smallexample 7499@group 7500$ @kbd{find @var{dir} @var{tests} | \ 7501 tar -cf @var{archive} -T - --no-recursion} 7502@end group 7503@end smallexample 7504 7505The @option{--no-recursion} option also applies when extracting: it 7506causes @command{tar} to extract only the matched directory entries, not 7507the files under those directories. 7508 7509The @option{--no-recursion} option also affects how globbing patterns 7510are interpreted (@pxref{controlling pattern-matching}). 7511 7512The @option{--no-recursion} and @option{--recursion} options apply to 7513later options and operands, and can be overridden by later occurrences 7514of @option{--no-recursion} and @option{--recursion}. For example: 7515 7516@smallexample 7517$ @kbd{tar -cf jams.tar --no-recursion grape --recursion grape/concord} 7518@end smallexample 7519 7520@noindent 7521creates an archive with one entry for @file{grape}, and the recursive 7522contents of @file{grape/concord}, but no entries under @file{grape} 7523other than @file{grape/concord}. 7524 7525@node one 7526@section Crossing File System Boundaries 7527@cindex File system boundaries, not crossing 7528@UNREVISED 7529 7530@command{tar} will normally automatically cross file system boundaries in 7531order to archive files which are part of a directory tree. You can 7532change this behavior by running @command{tar} and specifying 7533@option{--one-file-system}. This option only affects files that are 7534archived because they are in a directory that is being archived; 7535@command{tar} will still archive files explicitly named on the command line 7536or through @option{--files-from}, regardless of where they reside. 7537 7538@table @option 7539@opindex one-file-system 7540@item --one-file-system 7541Prevents @command{tar} from crossing file system boundaries when 7542archiving. Use in conjunction with any write operation. 7543@end table 7544 7545The @option{--one-file-system} option causes @command{tar} to modify its 7546normal behavior in archiving the contents of directories. If a file in 7547a directory is not on the same file system as the directory itself, then 7548@command{tar} will not archive that file. If the file is a directory 7549itself, @command{tar} will not archive anything beneath it; in other words, 7550@command{tar} will not cross mount points. 7551 7552This option is useful for making full or incremental archival backups of 7553a file system. If this option is used in conjunction with 7554@option{--verbose} (@option{-v}), files that are excluded are 7555mentioned by name on the standard error. 7556 7557@menu 7558* directory:: Changing Directory 7559* absolute:: Absolute File Names 7560@end menu 7561 7562@node directory 7563@subsection Changing the Working Directory 7564 7565@FIXME{need to read over this node now for continuity; i've switched 7566things around some.} 7567 7568@cindex Changing directory mid-stream 7569@cindex Directory, changing mid-stream 7570@cindex Working directory, specifying 7571To change the working directory in the middle of a list of file names, 7572either on the command line or in a file specified using 7573@option{--files-from} (@option{-T}), use @option{--directory} (@option{-C}). 7574This will change the working directory to the specified directory 7575after that point in the list. 7576 7577@table @option 7578@opindex directory 7579@item --directory=@var{directory} 7580@itemx -C @var{directory} 7581Changes the working directory in the middle of a command line. 7582@end table 7583 7584For example, 7585 7586@smallexample 7587$ @kbd{tar -c -f jams.tar grape prune -C food cherry} 7588@end smallexample 7589 7590@noindent 7591will place the files @file{grape} and @file{prune} from the current 7592directory into the archive @file{jams.tar}, followed by the file 7593@file{cherry} from the directory @file{food}. This option is especially 7594useful when you have several widely separated files that you want to 7595store in the same archive. 7596 7597Note that the file @file{cherry} is recorded in the archive under the 7598precise name @file{cherry}, @emph{not} @file{food/cherry}. Thus, the 7599archive will contain three files that all appear to have come from the 7600same directory; if the archive is extracted with plain @samp{tar 7601--extract}, all three files will be written in the current directory. 7602 7603Contrast this with the command, 7604 7605@smallexample 7606$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry} 7607@end smallexample 7608 7609@noindent 7610which records the third file in the archive under the name 7611@file{red/cherry} so that, if the archive is extracted using 7612@samp{tar --extract}, the third file will be written in a subdirectory 7613named @file{orange-colored}. 7614 7615You can use the @option{--directory} option to make the archive 7616independent of the original name of the directory holding the files. 7617The following command places the files @file{/etc/passwd}, 7618@file{/etc/hosts}, and @file{/lib/libc.a} into the archive 7619@file{foo.tar}: 7620 7621@smallexample 7622$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a} 7623@end smallexample 7624 7625@noindent 7626However, the names of the archive members will be exactly what they were 7627on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}. 7628They will not appear to be related by file name to the original 7629directories where those files were located. 7630 7631Note that @option{--directory} options are interpreted consecutively. If 7632@option{--directory} specifies a relative file name, it is interpreted 7633relative to the then current directory, which might not be the same as 7634the original current working directory of @command{tar}, due to a previous 7635@option{--directory} option. 7636 7637When using @option{--files-from} (@pxref{files}), you can put various 7638@command{tar} options (including @option{-C}) in the file list. Notice, 7639however, that in this case the option and its argument may not be 7640separated by whitespace. If you use short option, its argument must 7641either follow the option letter immediately, without any intervening 7642whitespace, or occupy the next line. Otherwise, if you use long 7643option, separate its argument by an equal sign. 7644 7645For instance, the file list for the above example will be: 7646 7647@smallexample 7648@group 7649-C/etc 7650passwd 7651hosts 7652--directory=/lib 7653libc.a 7654@end group 7655@end smallexample 7656 7657@noindent 7658To use it, you would invoke @command{tar} as follows: 7659 7660@smallexample 7661$ @kbd{tar -c -f foo.tar --files-from list} 7662@end smallexample 7663 7664The interpretation of @option{--directory} is disabled by 7665@option{--null} option. 7666 7667@node absolute 7668@subsection Absolute File Names 7669@UNREVISED 7670 7671@table @option 7672@opindex absolute-names 7673@item --absolute-names 7674@itemx -P 7675Do not strip leading slashes from file names, and permit file names 7676containing a @file{..} file name component. 7677@end table 7678 7679By default, @GNUTAR{} drops a leading @samp{/} on 7680input or output, and complains about file names containing a @file{..} 7681component. This option turns off this behavior. 7682 7683When @command{tar} extracts archive members from an archive, it strips any 7684leading slashes (@samp{/}) from the member name. This causes absolute 7685member names in the archive to be treated as relative file names. This 7686allows you to have such members extracted wherever you want, instead of 7687being restricted to extracting the member in the exact directory named 7688in the archive. For example, if the archive member has the name 7689@file{/etc/passwd}, @command{tar} will extract it as if the name were 7690really @file{etc/passwd}. 7691 7692File names containing @file{..} can cause problems when extracting, so 7693@command{tar} normally warns you about such files when creating an 7694archive, and rejects attempts to extracts such files. 7695 7696Other @command{tar} programs do not do this. As a result, if you 7697create an archive whose member names start with a slash, they will be 7698difficult for other people with a non-@GNUTAR{} 7699program to use. Therefore, @GNUTAR{} also strips 7700leading slashes from member names when putting members into the 7701archive. For example, if you ask @command{tar} to add the file 7702@file{/bin/ls} to an archive, it will do so, but the member name will 7703be @file{bin/ls}.@footnote{A side effect of this is that when 7704@option{--create} is used with @option{--verbose} the resulting output 7705is not, generally speaking, the same as the one you'd get running 7706@kbd{tar --list} command. This may be important if you use some 7707scripts for comparing both outputs. @xref{listing member and file names}, 7708for the information on how to handle this case.} 7709 7710If you use the @option{--absolute-names} (@option{-P}) option, 7711@command{tar} will do none of these transformations. 7712 7713To archive or extract files relative to the root directory, specify 7714the @option{--absolute-names} (@option{-P}) option. 7715 7716Normally, @command{tar} acts on files relative to the working 7717directory---ignoring superior directory names when archiving, and 7718ignoring leading slashes when extracting. 7719 7720When you specify @option{--absolute-names} (@option{-P}), 7721@command{tar} stores file names including all superior directory 7722names, and preserves leading slashes. If you only invoked 7723@command{tar} from the root directory you would never need the 7724@option{--absolute-names} option, but using this option 7725may be more convenient than switching to root. 7726 7727@FIXME{Should be an example in the tutorial/wizardry section using this 7728to transfer files between systems.} 7729 7730@FIXME{Is write access an issue?} 7731 7732@table @option 7733@item --absolute-names 7734Preserves full file names (including superior directory names) when 7735archiving files. Preserves leading slash when extracting files. 7736 7737@end table 7738 7739@FIXME{this is still horrible; need to talk with dan on monday.} 7740 7741@command{tar} prints out a message about removing the @samp{/} from 7742file names. This message appears once per @GNUTAR{} 7743invocation. It represents something which ought to be told; ignoring 7744what it means can cause very serious surprises, later. 7745 7746Some people, nevertheless, do not want to see this message. Wanting to 7747play really dangerously, one may of course redirect @command{tar} standard 7748error to the sink. For example, under @command{sh}: 7749 7750@smallexample 7751$ @kbd{tar -c -f archive.tar /home 2> /dev/null} 7752@end smallexample 7753 7754@noindent 7755Another solution, both nicer and simpler, would be to change to 7756the @file{/} directory first, and then avoid absolute notation. 7757For example: 7758 7759@smallexample 7760$ @kbd{(cd / && tar -c -f archive.tar home)} 7761# @i{or}: 7762$ @kbd{tar -c -f archive.tar -C / home} 7763@end smallexample 7764 7765@include getdate.texi 7766 7767@node Formats 7768@chapter Controlling the Archive Format 7769 7770@cindex Tar archive formats 7771Due to historical reasons, there are several formats of tar archives. 7772All of them are based on the same principles, but have some subtle 7773differences that often make them incompatible with each other. 7774 7775GNU tar is able to create and handle archives in a variety of formats. 7776The most frequently used formats are (in alphabetical order): 7777 7778@table @asis 7779@item gnu 7780Format used by @GNUTAR{} versions up to 1.13.25. This format derived 7781from an early @acronym{POSIX} standard, adding some improvements such as 7782sparse file handling and incremental archives. Unfortunately these 7783features were implemented in a way incompatible with other archive 7784formats. 7785 7786Archives in @samp{gnu} format are able to hold file names of unlimited 7787length. 7788 7789@item oldgnu 7790Format used by @GNUTAR{} of versions prior to 1.12. 7791 7792@item v7 7793Archive format, compatible with the V7 implementation of tar. This 7794format imposes a number of limitations. The most important of them 7795are: 7796 7797@enumerate 7798@item The maximum length of a file name is limited to 99 characters. 7799@item The maximum length of a symbolic link is limited to 99 characters. 7800@item It is impossible to store special files (block and character 7801devices, fifos etc.) 7802@item Maximum value of user or group @acronym{ID} is limited to 2097151 (7777777 7803octal) 7804@item V7 archives do not contain symbolic ownership information (user 7805and group name of the file owner). 7806@end enumerate 7807 7808This format has traditionally been used by Automake when producing 7809Makefiles. This practice will change in the future, in the meantime, 7810however this means that projects containing file names more than 99 7811characters long will not be able to use @GNUTAR{} @value{VERSION} and 7812Automake prior to 1.9. 7813 7814@item ustar 7815Archive format defined by @acronym{POSIX.1-1988} specification. It stores 7816symbolic ownership information. It is also able to store 7817special files. However, it imposes several restrictions as well: 7818 7819@enumerate 7820@item The maximum length of a file name is limited to 256 characters, 7821provided that the file name can be split at a directory separator in 7822two parts, first of them being at most 155 bytes long. So, in most 7823cases the maximum file name length will be shorter than 256 7824characters. 7825@item The maximum length of a symbolic link name is limited to 7826100 characters. 7827@item Maximum size of a file the archive is able to accommodate 7828is 8GB 7829@item Maximum value of UID/GID is 2097151. 7830@item Maximum number of bits in device major and minor numbers is 21. 7831@end enumerate 7832 7833@item star 7834Format used by J@"org Schilling @command{star} 7835implementation. @GNUTAR{} is able to read @samp{star} archives but 7836currently does not produce them. 7837 7838@item posix 7839Archive format defined by @acronym{POSIX.1-2001} specification. This is the 7840most flexible and feature-rich format. It does not impose any 7841restrictions on file sizes or file name lengths. This format is quite 7842recent, so not all tar implementations are able to handle it properly. 7843However, this format is designed in such a way that any tar 7844implementation able to read @samp{ustar} archives will be able to read 7845most @samp{posix} archives as well, with the only exception that any 7846additional information (such as long file names etc.) will in such 7847case be extracted as plain text files along with the files it refers to. 7848 7849This archive format will be the default format for future versions 7850of @GNUTAR{}. 7851 7852@end table 7853 7854The following table summarizes the limitations of each of these 7855formats: 7856 7857@multitable @columnfractions .10 .20 .20 .20 .20 7858@headitem Format @tab UID @tab File Size @tab File Name @tab Devn 7859@item gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63 7860@item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63 7861@item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a 7862@item ustar @tab 2097151 @tab 8GB @tab 256 @tab 21 7863@item posix @tab Unlimited @tab Unlimited @tab Unlimited @tab Unlimited 7864@end multitable 7865 7866The default format for @GNUTAR{} is defined at compilation 7867time. You may check it by running @command{tar --help}, and examining 7868the last lines of its output. Usually, @GNUTAR{} is configured 7869to create archives in @samp{gnu} format, however, future version will 7870switch to @samp{posix}. 7871 7872@menu 7873* Compression:: Using Less Space through Compression 7874* Attributes:: Handling File Attributes 7875* Portability:: Making @command{tar} Archives More Portable 7876* cpio:: Comparison of @command{tar} and @command{cpio} 7877@end menu 7878 7879@node Compression 7880@section Using Less Space through Compression 7881 7882@menu 7883* gzip:: Creating and Reading Compressed Archives 7884* sparse:: Archiving Sparse Files 7885@end menu 7886 7887@node gzip 7888@subsection Creating and Reading Compressed Archives 7889@cindex Compressed archives 7890@cindex Storing archives in compressed format 7891 7892@GNUTAR{} is able to create and read compressed archives. It supports 7893@command{gzip} and @command{bzip2} compression programs. For backward 7894compatibility, it also supports @command{compress} command, although 7895we strongly recommend against using it, since there is a patent 7896covering the algorithm it uses and you could be sued for patent 7897infringement merely by running @command{compress}! Besides, it is less 7898effective than @command{gzip} and @command{bzip2}. 7899 7900Creating a compressed archive is simple: you just specify a 7901@dfn{compression option} along with the usual archive creation 7902commands. The compression option is @option{-z} (@option{--gzip}) to 7903create a @command{gzip} compressed archive, @option{-j} 7904(@option{--bzip2}) to create a @command{bzip2} compressed archive, and 7905@option{-Z} (@option{--compress}) to use @command{compress} program. 7906For example: 7907 7908@smallexample 7909$ @kbd{tar cfz archive.tar.gz .} 7910@end smallexample 7911 7912Reading compressed archive is even simpler: you don't need to specify 7913any additional options as @GNUTAR{} recognizes its format 7914automatically. Thus, the following commands will list and extract the 7915archive created in previous example: 7916 7917@smallexample 7918# List the compressed archive 7919$ @kbd{tar tf archive.tar.gz} 7920# Extract the compressed archive 7921$ @kbd{tar xf archive.tar.gz} 7922@end smallexample 7923 7924The only case when you have to specify a decompression option while 7925reading the archive is when reading from a pipe or from a tape drive 7926that does not support random access. However, in this case @GNUTAR{} 7927will indicate which option you should use. For example: 7928 7929@smallexample 7930$ @kbd{cat archive.tar.gz | tar tf -} 7931tar: Archive is compressed. Use -z option 7932tar: Error is not recoverable: exiting now 7933@end smallexample 7934 7935If you see such diagnostics, just add the suggested option to the 7936invocation of @GNUTAR{}: 7937 7938@smallexample 7939$ @kbd{cat archive.tar.gz | tar tfz -} 7940@end smallexample 7941 7942Notice also, that there are several restrictions on operations on 7943compressed archives. First of all, compressed archives cannot be 7944modified, i.e., you cannot update (@option{--update} (@option{-u})) them or delete 7945(@option{--delete}) members from them. Likewise, you cannot append 7946another @command{tar} archive to a compressed archive using 7947@option{--append} (@option{-r})). Secondly, multi-volume archives cannot be 7948compressed. 7949 7950The following table summarizes compression options used by @GNUTAR{}. 7951 7952@table @option 7953@opindex gzip 7954@opindex ungzip 7955@item -z 7956@itemx --gzip 7957@itemx --ungzip 7958Filter the archive through @command{gzip}. 7959 7960You can use @option{--gzip} and @option{--gunzip} on physical devices 7961(tape drives, etc.) and remote files as well as on normal files; data 7962to or from such devices or remote files is reblocked by another copy 7963of the @command{tar} program to enforce the specified (or default) record 7964size. The default compression parameters are used; if you need to 7965override them, set @env{GZIP} environment variable, e.g.: 7966 7967@smallexample 7968$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir} 7969@end smallexample 7970 7971@noindent 7972Another way would be to avoid the @option{--gzip} (@option{--gunzip}, @option{--ungzip}, @option{-z}) option and run 7973@command{gzip} explicitly: 7974 7975@smallexample 7976$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz} 7977@end smallexample 7978 7979@cindex corrupted archives 7980About corrupted compressed archives: @command{gzip}'ed files have no 7981redundancy, for maximum compression. The adaptive nature of the 7982compression scheme means that the compression tables are implicitly 7983spread all over the archive. If you lose a few blocks, the dynamic 7984construction of the compression tables becomes unsynchronized, and there 7985is little chance that you could recover later in the archive. 7986 7987There are pending suggestions for having a per-volume or per-file 7988compression in @GNUTAR{}. This would allow for viewing the 7989contents without decompression, and for resynchronizing decompression at 7990every volume or file, in case of corrupted archives. Doing so, we might 7991lose some compressibility. But this would have make recovering easier. 7992So, there are pros and cons. We'll see! 7993 7994@opindex bzip2 7995@item -j 7996@itemx --bzip2 7997Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}. 7998 7999@opindex compress 8000@opindex uncompress 8001@item -Z 8002@itemx --compress 8003@itemx --uncompress 8004Filter the archive through @command{compress}. Otherwise like @option{--gzip}. 8005 8006The @acronym{GNU} Project recommends you not use 8007@command{compress}, because there is a patent covering the algorithm it 8008uses. You could be sued for patent infringement merely by running 8009@command{compress}. 8010 8011@opindex use-compress-program 8012@item --use-compress-program=@var{prog} 8013Use external compression program @var{prog}. Use this option if you 8014have a compression program that @GNUTAR{} does not support. There 8015are two requirements to which @var{prog} should comply: 8016 8017First, when called without options, it should read data from standard 8018input, compress it and output it on standard output. 8019 8020Secondly, if called with @option{-d} argument, it should do exactly 8021the opposite, i.e., read the compressed data from the standard input 8022and produce uncompressed data on the standard output. 8023@end table 8024 8025@cindex gpg, using with tar 8026@cindex gnupg, using with tar 8027@cindex Using encrypted archives 8028The @option{--use-compress-program} option, in particular, lets you 8029implement your own filters, not necessarily dealing with 8030compression/decompression. For example, suppose you wish to implement 8031PGP encryption on top of compression, using @command{gpg} (@pxref{Top, 8032gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard 8033Manual}). The following script does that: 8034 8035@smallexample 8036@group 8037#! /bin/sh 8038case $1 in 8039-d) gpg --decrypt - | gzip -d -c;; 8040'') gzip -c | gpg -s ;; 8041*) echo "Unknown option $1">&2; exit 1;; 8042esac 8043@end group 8044@end smallexample 8045 8046Suppose you name it @file{gpgz} and save it somewhere in your 8047@env{PATH}. Then the following command will create a compressed 8048archive signed with your private key: 8049 8050@smallexample 8051$ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .} 8052@end smallexample 8053 8054@noindent 8055Likewise, the following command will list its contents: 8056 8057@smallexample 8058$ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .} 8059@end smallexample 8060 8061@ignore 8062The above is based on the following discussion: 8063 8064 I have one question, or maybe it's a suggestion if there isn't a way 8065 to do it now. I would like to use @option{--gzip}, but I'd also like 8066 the output to be fed through a program like @acronym{GNU} 8067 @command{ecc} (actually, right now that's @samp{exactly} what I'd like 8068 to use :-)), basically adding ECC protection on top of compression. 8069 It seems as if this should be quite easy to do, but I can't work out 8070 exactly how to go about it. Of course, I can pipe the standard output 8071 of @command{tar} through @command{ecc}, but then I lose (though I 8072 haven't started using it yet, I confess) the ability to have 8073 @command{tar} use @command{rmt} for it's I/O (I think). 8074 8075 I think the most straightforward thing would be to let me specify a 8076 general set of filters outboard of compression (preferably ordered, 8077 so the order can be automatically reversed on input operations, and 8078 with the options they require specifiable), but beggars shouldn't be 8079 choosers and anything you decide on would be fine with me. 8080 8081 By the way, I like @command{ecc} but if (as the comments say) it can't 8082 deal with loss of block sync, I'm tempted to throw some time at adding 8083 that capability. Supposing I were to actually do such a thing and 8084 get it (apparently) working, do you accept contributed changes to 8085 utilities like that? (Leigh Clayton @file{loc@@soliton.com}, May 1995). 8086 8087 Isn't that exactly the role of the 8088 @option{--use-compress-prog=@var{program}} option? 8089 I never tried it myself, but I suspect you may want to write a 8090 @var{prog} script or program able to filter stdin to stdout to 8091 way you want. It should recognize the @option{-d} option, for when 8092 extraction is needed rather than creation. 8093 8094 It has been reported that if one writes compressed data (through the 8095 @option{--gzip} or @option{--compress} options) to a DLT and tries to use 8096 the DLT compression mode, the data will actually get bigger and one will 8097 end up with less space on the tape. 8098@end ignore 8099 8100@node sparse 8101@subsection Archiving Sparse Files 8102@cindex Sparse Files 8103 8104Files in the file system occasionally have @dfn{holes}. A @dfn{hole} 8105in a file is a section of the file's contents which was never written. 8106The contents of a hole reads as all zeros. On many operating systems, 8107actual disk storage is not allocated for holes, but they are counted 8108in the length of the file. If you archive such a file, @command{tar} 8109could create an archive longer than the original. To have @command{tar} 8110attempt to recognize the holes in a file, use @option{--sparse} 8111(@option{-S}). When you use this option, then, for any file using 8112less disk space than would be expected from its length, @command{tar} 8113searches the file for consecutive stretches of zeros. It then records 8114in the archive for the file where the consecutive stretches of zeros 8115are, and only archives the ``real contents'' of the file. On 8116extraction (using @option{--sparse} is not needed on extraction) any 8117such files have holes created wherever the continuous stretches of zeros 8118were found. Thus, if you use @option{--sparse}, @command{tar} archives 8119won't take more space than the original. 8120 8121@table @option 8122@opindex sparse 8123@item -S 8124@itemx --sparse 8125This option instructs @command{tar} to test each file for sparseness 8126before attempting to archive it. If the file is found to be sparse it 8127is treated specially, thus allowing to decrease the amount of space 8128used by its image in the archive. 8129 8130This option is meaningful only when creating or updating archives. It 8131has no effect on extraction. 8132@end table 8133 8134Consider using @option{--sparse} when performing file system backups, 8135to avoid archiving the expanded forms of files stored sparsely in the 8136system. 8137 8138Even if your system has no sparse files currently, some may be 8139created in the future. If you use @option{--sparse} while making file 8140system backups as a matter of course, you can be assured the archive 8141will never take more space on the media than the files take on disk 8142(otherwise, archiving a disk filled with sparse files might take 8143hundreds of tapes). @xref{Incremental Dumps}. 8144 8145However, be aware that @option{--sparse} option presents a serious 8146drawback. Namely, in order to determine if the file is sparse 8147@command{tar} has to read it before trying to archive it, so in total 8148the file is read @strong{twice}. So, always bear in mind that the 8149time needed to process all files with this option is roughly twice 8150the time needed to archive them without it. 8151@FIXME{A technical note: 8152 8153Programs like @command{dump} do not have to read the entire file; by 8154examining the file system directly, they can determine in advance 8155exactly where the holes are and thus avoid reading through them. The 8156only data it need read are the actual allocated data blocks. 8157@GNUTAR{} uses a more portable and straightforward 8158archiving approach, it would be fairly difficult that it does 8159otherwise. Elizabeth Zwicky writes to @file{comp.unix.internals}, on 81601990-12-10: 8161 8162@quotation 8163What I did say is that you cannot tell the difference between a hole and an 8164equivalent number of nulls without reading raw blocks. @code{st_blocks} at 8165best tells you how many holes there are; it doesn't tell you @emph{where}. 8166Just as programs may, conceivably, care what @code{st_blocks} is (care 8167to name one that does?), they may also care where the holes are (I have 8168no examples of this one either, but it's equally imaginable). 8169 8170I conclude from this that good archivers are not portable. One can 8171arguably conclude that if you want a portable program, you can in good 8172conscience restore files with as many holes as possible, since you can't 8173get it right. 8174@end quotation 8175} 8176 8177@cindex sparse formats, defined 8178When using @samp{POSIX} archive format, @GNUTAR{} is able to store 8179sparse files using in three distinct ways, called @dfn{sparse 8180formats}. A sparse format is identified by its @dfn{number}, 8181consisting, as usual of two decimal numbers, delimited by a dot. By 8182default, format @samp{1.0} is used. If, for some reason, you wish to 8183use an earlier format, you can select it using 8184@option{--sparse-version} option. 8185 8186@table @option 8187@opindex sparse-version 8188@item --sparse-version=@var{version} 8189 8190Select the format to store sparse files in. Valid @var{version} values 8191are: @samp{0.0}, @samp{0.1} and @samp{1.0}. @xref{Sparse Formats}, 8192for a detailed description of each format. 8193@end table 8194 8195Using @option{--sparse-format} option implies @option{--sparse}. 8196 8197@node Attributes 8198@section Handling File Attributes 8199@UNREVISED 8200 8201When @command{tar} reads files, it updates their access times. To 8202avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either 8203reset the access time retroactively or avoid changing it in the first 8204place. 8205 8206Handling of file attributes 8207 8208@table @option 8209@opindex atime-preserve 8210@item --atime-preserve 8211@itemx --atime-preserve=replace 8212@itemx --atime-preserve=system 8213Preserve the access times of files that are read. This works only for 8214files that you own, unless you have superuser privileges. 8215 8216@option{--atime-preserve=replace} works on most systems, but it also 8217restores the data modification time and updates the status change 8218time. Hence it doesn't interact with incremental dumps nicely 8219(@pxref{Incremental Dumps}), and it can set access or data modification times 8220incorrectly if other programs access the file while @command{tar} is 8221running. 8222 8223@option{--atime-preserve=system} avoids changing the access time in 8224the first place, if the operating system supports this. 8225Unfortunately, this may or may not work on any given operating system 8226or file system. If @command{tar} knows for sure it won't work, it 8227complains right away. 8228 8229Currently @option{--atime-preserve} with no operand defaults to 8230@option{--atime-preserve=replace}, but this is intended to change to 8231@option{--atime-preserve=system} when the latter is better-supported. 8232 8233@opindex touch 8234@item -m 8235@itemx --touch 8236Do not extract data modification time. 8237 8238When this option is used, @command{tar} leaves the data modification times 8239of the files it extracts as the times when the files were extracted, 8240instead of setting it to the times recorded in the archive. 8241 8242This option is meaningless with @option{--list} (@option{-t}). 8243 8244@opindex same-owner 8245@item --same-owner 8246Create extracted files with the same ownership they have in the 8247archive. 8248 8249This is the default behavior for the superuser, 8250so this option is meaningful only for non-root users, when @command{tar} 8251is executed on those systems able to give files away. This is 8252considered as a security flaw by many people, at least because it 8253makes quite difficult to correctly account users for the disk space 8254they occupy. Also, the @code{suid} or @code{sgid} attributes of 8255files are easily and silently lost when files are given away. 8256 8257When writing an archive, @command{tar} writes the user @acronym{ID} and user name 8258separately. If it can't find a user name (because the user @acronym{ID} is not 8259in @file{/etc/passwd}), then it does not write one. When restoring, 8260it tries to look the name (if one was written) up in 8261@file{/etc/passwd}. If it fails, then it uses the user @acronym{ID} stored in 8262the archive instead. 8263 8264@opindex no-same-owner 8265@item --no-same-owner 8266@itemx -o 8267Do not attempt to restore ownership when extracting. This is the 8268default behavior for ordinary users, so this option has an effect 8269only for the superuser. 8270 8271@opindex numeric-owner 8272@item --numeric-owner 8273The @option{--numeric-owner} option allows (ANSI) archives to be written 8274without user/group name information or such information to be ignored 8275when extracting. It effectively disables the generation and/or use 8276of user/group name information. This option forces extraction using 8277the numeric ids from the archive, ignoring the names. 8278 8279This is useful in certain circumstances, when restoring a backup from 8280an emergency floppy with different passwd/group files for example. 8281It is otherwise impossible to extract files with the right ownerships 8282if the password file in use during the extraction does not match the 8283one belonging to the file system(s) being extracted. This occurs, 8284for example, if you are restoring your files after a major crash and 8285had booted from an emergency floppy with no password file or put your 8286disk into another machine to do the restore. 8287 8288The numeric ids are @emph{always} saved into @command{tar} archives. 8289The identifying names are added at create time when provided by the 8290system, unless @option{--old-archive} (@option{-o}) is used. Numeric ids could be 8291used when moving archives between a collection of machines using 8292a centralized management for attribution of numeric ids to users 8293and groups. This is often made through using the NIS capabilities. 8294 8295When making a @command{tar} file for distribution to other sites, it 8296is sometimes cleaner to use a single owner for all files in the 8297distribution, and nicer to specify the write permission bits of the 8298files as stored in the archive independently of their actual value on 8299the file system. The way to prepare a clean distribution is usually 8300to have some Makefile rule creating a directory, copying all needed 8301files in that directory, then setting ownership and permissions as 8302wanted (there are a lot of possible schemes), and only then making a 8303@command{tar} archive out of this directory, before cleaning 8304everything out. Of course, we could add a lot of options to 8305@GNUTAR{} for fine tuning permissions and ownership. 8306This is not the good way, I think. @GNUTAR{} is 8307already crowded with options and moreover, the approach just explained 8308gives you a great deal of control already. 8309 8310@xopindex{same-permissions, short description} 8311@xopindex{preserve-permissions, short description} 8312@item -p 8313@itemx --same-permissions 8314@itemx --preserve-permissions 8315Extract all protection information. 8316 8317This option causes @command{tar} to set the modes (access permissions) of 8318extracted files exactly as recorded in the archive. If this option 8319is not used, the current @code{umask} setting limits the permissions 8320on extracted files. This option is by default enabled when 8321@command{tar} is executed by a superuser. 8322 8323 8324This option is meaningless with @option{--list} (@option{-t}). 8325 8326@opindex preserve 8327@item --preserve 8328Same as both @option{--same-permissions} and @option{--same-order}. 8329 8330The @option{--preserve} option has no equivalent short option name. 8331It is equivalent to @option{--same-permissions} plus @option{--same-order}. 8332 8333@FIXME{I do not see the purpose of such an option. (Neither I. FP.) 8334Neither do I. --Sergey} 8335 8336@end table 8337 8338@node Portability 8339@section Making @command{tar} Archives More Portable 8340 8341Creating a @command{tar} archive on a particular system that is meant to be 8342useful later on many other machines and with other versions of @command{tar} 8343is more challenging than you might think. @command{tar} archive formats 8344have been evolving since the first versions of Unix. Many such formats 8345are around, and are not always compatible with each other. This section 8346discusses a few problems, and gives some advice about making @command{tar} 8347archives more portable. 8348 8349One golden rule is simplicity. For example, limit your @command{tar} 8350archives to contain only regular files and directories, avoiding 8351other kind of special files. Do not attempt to save sparse files or 8352contiguous files as such. Let's discuss a few more problems, in turn. 8353 8354@FIXME{Discuss GNU extensions (incremental backups, multi-volume 8355archives and archive labels) in GNU and PAX formats.} 8356 8357@menu 8358* Portable Names:: Portable Names 8359* dereference:: Symbolic Links 8360* old:: Old V7 Archives 8361* ustar:: Ustar Archives 8362* gnu:: GNU and old GNU format archives. 8363* posix:: @acronym{POSIX} archives 8364* Checksumming:: Checksumming Problems 8365* Large or Negative Values:: Large files, negative time stamps, etc. 8366* Other Tars:: How to Extract GNU-Specific Data Using 8367 Other @command{tar} Implementations 8368@end menu 8369 8370@node Portable Names 8371@subsection Portable Names 8372 8373Use portable file and member names. A name is portable if it contains 8374only @acronym{ASCII} letters and digits, @samp{/}, @samp{.}, @samp{_}, and 8375@samp{-}; it cannot be empty, start with @samp{-} or @samp{//}, or 8376contain @samp{/-}. Avoid deep directory nesting. For portability to 8377old Unix hosts, limit your file name components to 14 characters or 8378less. 8379 8380If you intend to have your @command{tar} archives to be read under 8381MSDOS, you should not rely on case distinction for file names, and you 8382might use the @acronym{GNU} @command{doschk} program for helping you 8383further diagnosing illegal MSDOS names, which are even more limited 8384than System V's. 8385 8386@node dereference 8387@subsection Symbolic Links 8388@cindex File names, using symbolic links 8389@cindex Symbolic link as file name 8390 8391@opindex dereference 8392Normally, when @command{tar} archives a symbolic link, it writes a 8393block to the archive naming the target of the link. In that way, the 8394@command{tar} archive is a faithful record of the file system contents. 8395@option{--dereference} (@option{-h}) is used with @option{--create} (@option{-c}), and causes 8396@command{tar} to archive the files symbolic links point to, instead of 8397the links themselves. When this option is used, when @command{tar} 8398encounters a symbolic link, it will archive the linked-to file, 8399instead of simply recording the presence of a symbolic link. 8400 8401The name under which the file is stored in the file system is not 8402recorded in the archive. To record both the symbolic link name and 8403the file name in the system, archive the file under both names. If 8404all links were recorded automatically by @command{tar}, an extracted file 8405might be linked to a file name that no longer exists in the file 8406system. 8407 8408If a linked-to file is encountered again by @command{tar} while creating 8409the same archive, an entire second copy of it will be stored. (This 8410@emph{might} be considered a bug.) 8411 8412So, for portable archives, do not archive symbolic links as such, 8413and use @option{--dereference} (@option{-h}): many systems do not support 8414symbolic links, and moreover, your distribution might be unusable if 8415it contains unresolved symbolic links. 8416 8417@node old 8418@subsection Old V7 Archives 8419@cindex Format, old style 8420@cindex Old style format 8421@cindex Old style archives 8422@cindex v7 archive format 8423 8424Certain old versions of @command{tar} cannot handle additional 8425information recorded by newer @command{tar} programs. To create an 8426archive in V7 format (not ANSI), which can be read by these old 8427versions, specify the @option{--format=v7} option in 8428conjunction with the @option{--create} (@option{-c}) (@command{tar} also 8429accepts @option{--portability} or @option{--old-archive} for this 8430option). When you specify it, 8431@command{tar} leaves out information about directories, pipes, fifos, 8432contiguous files, and device files, and specifies file ownership by 8433group and user IDs instead of group and user names. 8434 8435When updating an archive, do not use @option{--format=v7} 8436unless the archive was created using this option. 8437 8438In most cases, a @emph{new} format archive can be read by an @emph{old} 8439@command{tar} program without serious trouble, so this option should 8440seldom be needed. On the other hand, most modern @command{tar}s are 8441able to read old format archives, so it might be safer for you to 8442always use @option{--format=v7} for your distributions. Notice, 8443however, that @samp{ustar} format is a better alternative, as it is 8444free from many of @samp{v7}'s drawbacks. 8445 8446@node ustar 8447@subsection Ustar Archive Format 8448 8449@cindex ustar archive format 8450Archive format defined by @acronym{POSIX}.1-1988 specification is called 8451@code{ustar}. Although it is more flexible than the V7 format, it 8452still has many restrictions (@xref{Formats,ustar}, for the detailed 8453description of @code{ustar} format). Along with V7 format, 8454@code{ustar} format is a good choice for archives intended to be read 8455with other implementations of @command{tar}. 8456 8457To create archive in @code{ustar} format, use @option{--format=ustar} 8458option in conjunction with the @option{--create} (@option{-c}). 8459 8460@node gnu 8461@subsection @acronym{GNU} and old @GNUTAR{} format 8462 8463@cindex GNU archive format 8464@cindex Old GNU archive format 8465@GNUTAR{} was based on an early draft of the 8466@acronym{POSIX} 1003.1 @code{ustar} standard. @acronym{GNU} extensions to 8467@command{tar}, such as the support for file names longer than 100 8468characters, use portions of the @command{tar} header record which were 8469specified in that @acronym{POSIX} draft as unused. Subsequent changes in 8470@acronym{POSIX} have allocated the same parts of the header record for 8471other purposes. As a result, @GNUTAR{} format is 8472incompatible with the current @acronym{POSIX} specification, and with 8473@command{tar} programs that follow it. 8474 8475In the majority of cases, @command{tar} will be configured to create 8476this format by default. This will change in future releases, since 8477we plan to make @samp{POSIX} format the default. 8478 8479To force creation a @GNUTAR{} archive, use option 8480@option{--format=gnu}. 8481 8482@node posix 8483@subsection @GNUTAR{} and @acronym{POSIX} @command{tar} 8484 8485@cindex POSIX archive format 8486@cindex PAX archive format 8487Starting from version 1.14 @GNUTAR{} features full support for 8488@acronym{POSIX.1-2001} archives. 8489 8490A @acronym{POSIX} conformant archive will be created if @command{tar} 8491was given @option{--format=posix} (@option{--format=pax}) option. No 8492special option is required to read and extract from a @acronym{POSIX} 8493archive. 8494 8495@menu 8496* PAX keywords:: Controlling Extended Header Keywords. 8497@end menu 8498 8499@node PAX keywords 8500@subsubsection Controlling Extended Header Keywords 8501 8502@table @option 8503@opindex pax-option 8504@item --pax-option=@var{keyword-list} 8505Handle keywords in @acronym{PAX} extended headers. This option is 8506equivalent to @option{-o} option of the @command{pax} utility. 8507@end table 8508 8509@var{Keyword-list} is a comma-separated 8510list of keyword options, each keyword option taking one of 8511the following forms: 8512 8513@table @code 8514@item delete=@var{pattern} 8515When used with one of archive-creation commands, 8516this option instructs @command{tar} to omit from extended header records 8517that it produces any keywords matching the string @var{pattern}. 8518 8519When used in extract or list mode, this option instructs tar 8520to ignore any keywords matching the given @var{pattern} in the extended 8521header records. In both cases, matching is performed using the pattern 8522matching notation described in @acronym{POSIX 1003.2}, 3.13 8523(@pxref{wildcards}). For example: 8524 8525@smallexample 8526--pax-option delete=security.* 8527@end smallexample 8528 8529would suppress security-related information. 8530 8531@item exthdr.name=@var{string} 8532 8533This keyword allows user control over the name that is written into the 8534ustar header blocks for the extended headers. The name is obtained 8535from @var{string} after making the following substitutions: 8536 8537@multitable @columnfractions .25 .55 8538@headitem Meta-character @tab Replaced By 8539@item %d @tab The directory name of the file, equivalent to the 8540result of the @command{dirname} utility on the translated file name. 8541@item %f @tab The name of the file with the directory information 8542stripped, equivalent to the result of the @command{basename} utility 8543on the translated file name. 8544@item %p @tab The process @acronym{ID} of the @command{tar} process. 8545@item %% @tab A @samp{%} character. 8546@end multitable 8547 8548Any other @samp{%} characters in @var{string} produce undefined 8549results. 8550 8551If no option @samp{exthdr.name=string} is specified, @command{tar} 8552will use the following default value: 8553 8554@smallexample 8555%d/PaxHeaders.%p/%f 8556@end smallexample 8557 8558@item globexthdr.name=@var{string} 8559This keyword allows user control over the name that is written into 8560the ustar header blocks for global extended header records. The name 8561is obtained from the contents of @var{string}, after making 8562the following substitutions: 8563 8564@multitable @columnfractions .25 .55 8565@headitem Meta-character @tab Replaced By 8566@item %n @tab An integer that represents the 8567sequence number of the global extended header record in the archive, 8568starting at 1. 8569@item %p @tab The process @acronym{ID} of the @command{tar} process. 8570@item %% @tab A @samp{%} character. 8571@end multitable 8572 8573Any other @samp{%} characters in @var{string} produce undefined results. 8574 8575If no option @samp{globexthdr.name=string} is specified, @command{tar} 8576will use the following default value: 8577 8578@smallexample 8579$TMPDIR/GlobalHead.%p.%n 8580@end smallexample 8581 8582@noindent 8583where @samp{$TMPDIR} represents the value of the @var{TMPDIR} 8584environment variable. If @var{TMPDIR} is not set, @command{tar} 8585uses @samp{/tmp}. 8586 8587@item @var{keyword}=@var{value} 8588When used with one of archive-creation commands, these keyword/value pairs 8589will be included at the beginning of the archive in a global extended 8590header record. When used with one of archive-reading commands, 8591@command{tar} will behave as if it has encountered these keyword/value 8592pairs at the beginning of the archive in a global extended header 8593record. 8594 8595@item @var{keyword}:=@var{value} 8596When used with one of archive-creation commands, these keyword/value pairs 8597will be included as records at the beginning of an extended header for 8598each file. This is effectively equivalent to @var{keyword}=@var{value} 8599form except that it creates no global extended header records. 8600 8601When used with one of archive-reading commands, @command{tar} will 8602behave as if these keyword/value pairs were included as records at the 8603end of each extended header; thus, they will override any global or 8604file-specific extended header record keywords of the same names. 8605For example, in the command: 8606 8607@smallexample 8608tar --format=posix --create \ 8609 --file archive --pax-option gname:=user . 8610@end smallexample 8611 8612the group name will be forced to a new value for all files 8613stored in the archive. 8614@end table 8615 8616@node Checksumming 8617@subsection Checksumming Problems 8618 8619SunOS and HP-UX @command{tar} fail to accept archives created using 8620@GNUTAR{} and containing non-@acronym{ASCII} file names, that 8621is, file names having characters with the eight bit set, because they 8622use signed checksums, while @GNUTAR{} uses unsigned 8623checksums while creating archives, as per @acronym{POSIX} standards. On 8624reading, @GNUTAR{} computes both checksums and 8625accept any. It is somewhat worrying that a lot of people may go 8626around doing backup of their files using faulty (or at least 8627non-standard) software, not learning about it until it's time to 8628restore their missing files with an incompatible file extractor, or 8629vice versa. 8630 8631@GNUTAR{} compute checksums both ways, and accept 8632any on read, so @acronym{GNU} tar can read Sun tapes even with their 8633wrong checksums. @GNUTAR{} produces the standard 8634checksum, however, raising incompatibilities with Sun. That is to 8635say, @GNUTAR{} has not been modified to 8636@emph{produce} incorrect archives to be read by buggy @command{tar}'s. 8637I've been told that more recent Sun @command{tar} now read standard 8638archives, so maybe Sun did a similar patch, after all? 8639 8640The story seems to be that when Sun first imported @command{tar} 8641sources on their system, they recompiled it without realizing that 8642the checksums were computed differently, because of a change in 8643the default signing of @code{char}'s in their compiler. So they 8644started computing checksums wrongly. When they later realized their 8645mistake, they merely decided to stay compatible with it, and with 8646themselves afterwards. Presumably, but I do not really know, HP-UX 8647has chosen that their @command{tar} archives to be compatible with Sun's. 8648The current standards do not favor Sun @command{tar} format. In any 8649case, it now falls on the shoulders of SunOS and HP-UX users to get 8650a @command{tar} able to read the good archives they receive. 8651 8652@node Large or Negative Values 8653@subsection Large or Negative Values 8654@cindex large values 8655@cindex future time stamps 8656@cindex negative time stamps 8657@UNREVISED{} 8658 8659The above sections suggest to use @samp{oldest possible} archive 8660format if in doubt. However, sometimes it is not possible. If you 8661attempt to archive a file whose metadata cannot be represented using 8662required format, @GNUTAR{} will print error message and ignore such a 8663file. You will than have to switch to a format that is able to 8664handle such values. The format summary table (@pxref{Formats}) will 8665help you to do so. 8666 8667In particular, when trying to archive files larger than 8GB or with 8668timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16 866912:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and 8670@acronym{POSIX} archive formats. When considering which format to 8671choose, bear in mind that the @acronym{GNU} format uses 8672two's-complement base-256 notation to store values that do not fit 8673into standard @acronym{ustar} range. Such archives can generally be 8674read only by a @GNUTAR{} implementation. Moreover, they sometimes 8675cannot be correctly restored on another hosts even by @GNUTAR{}. For 8676example, using two's complement representation for negative time 8677stamps that assumes a signed 32-bit @code{time_t} generates archives 8678that are not portable to hosts with differing @code{time_t} 8679representations. 8680 8681On the other hand, @acronym{POSIX} archives, generally speaking, can 8682be extracted by any tar implementation that understands older 8683@acronym{ustar} format. The only exception are files larger than 8GB. 8684 8685@FIXME{Describe how @acronym{POSIX} archives are extracted by non 8686POSIX-aware tars.} 8687 8688@node Other Tars 8689@subsection How to Extract GNU-Specific Data Using Other @command{tar} Implementations 8690 8691In previous sections you became acquainted with various quirks 8692necessary to make your archives portable. Sometimes you may need to 8693extract archives containing GNU-specific members using some 8694third-party @command{tar} implementation or an older version of 8695@GNUTAR{}. Of course your best bet is to have @GNUTAR{} installed, 8696but if it is for some reason impossible, this section will explain 8697how to cope without it. 8698 8699When we speak about @dfn{GNU-specific} members we mean two classes of 8700them: members split between the volumes of a multi-volume archive and 8701sparse members. You will be able to always recover such members if 8702the archive is in PAX format. In addition split members can be 8703recovered from archives in old GNU format. The following subsections 8704describe the required procedures in detail. 8705 8706@menu 8707* Split Recovery:: Members Split Between Volumes 8708* Sparse Recovery:: Sparse Members 8709@end menu 8710 8711@node Split Recovery 8712@subsubsection Extracting Members Split Between Volumes 8713 8714@cindex Mutli-volume archives, extracting using non-GNU tars 8715If a member is split between several volumes of an old GNU format archive 8716most third party @command{tar} implementation will fail to extract 8717it. To extract it, use @command{tarcat} program (@pxref{Tarcat}). 8718This program is available from 8719@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html, @GNUTAR{} 8720home page}. It concatenates several archive volumes into a single 8721valid archive. For example, if you have three volumes named from 8722@file{vol-1.tar} to @file{vol-3.tar}, you can do the following to 8723extract them using a third-party @command{tar}: 8724 8725@smallexample 8726$ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -} 8727@end smallexample 8728 8729@cindex Mutli-volume archives in PAX format, extracting using non-GNU tars 8730You could use this approach for most (although not all) PAX 8731format archives as well. However, extracting split members from a PAX 8732archive is a much easier task, because PAX volumes are constructed in 8733such a way that each part of a split member is extracted to a 8734different file by @command{tar} implementations that are not aware of 8735GNU extensions. More specifically, the very first part retains its 8736original name, and all subsequent parts are named using the pattern: 8737 8738@smallexample 8739%d/GNUFileParts.%p/%f.%n 8740@end smallexample 8741 8742@noindent 8743where symbols preceeded by @samp{%} are @dfn{macro characters} that 8744have the following meaning: 8745 8746@multitable @columnfractions .25 .55 8747@headitem Meta-character @tab Replaced By 8748@item %d @tab The directory name of the file, equivalent to the 8749result of the @command{dirname} utility on its full name. 8750@item %f @tab The file name of the file, equivalent to the result 8751of the @command{basename} utility on its full name. 8752@item %p @tab The process @acronym{ID} of the @command{tar} process that 8753created the archive. 8754@item %n @tab Ordinal number of this particular part. 8755@end multitable 8756 8757For example, if the file @file{var/longfile} was split during archive 8758creation between three volumes, and the creator @command{tar} process 8759had process @acronym{ID} @samp{27962}, then the member names will be: 8760 8761@smallexample 8762var/longfile 8763var/GNUFileParts.27962/longfile.1 8764var/GNUFileParts.27962/longfile.2 8765@end smallexample 8766 8767When you extract your archive using a third-party @command{tar}, these 8768files will be created on your disk, and the only thing you will need 8769to do to restore your file in its original form is concatenate them in 8770the proper order, for example: 8771 8772@smallexample 8773@group 8774$ @kbd{cd var} 8775$ @kbd{cat GNUFileParts.27962/longfile.1 \ 8776 GNUFileParts.27962/longfile.2 >> longfile} 8777$ rm -f GNUFileParts.27962 8778@end group 8779@end smallexample 8780 8781Notice, that if the @command{tar} implementation you use supports PAX 8782format archives, it will probably emit warnings about unknown keywords 8783during extraction. They will look like this: 8784 8785@smallexample 8786@group 8787Tar file too small 8788Unknown extended header keyword 'GNU.volume.filename' ignored. 8789Unknown extended header keyword 'GNU.volume.size' ignored. 8790Unknown extended header keyword 'GNU.volume.offset' ignored. 8791@end group 8792@end smallexample 8793 8794@noindent 8795You can safely ignore these warnings. 8796 8797If your @command{tar} implementation is not PAX-aware, you will get 8798more warnings and more files generated on your disk, e.g.: 8799 8800@smallexample 8801@group 8802$ @kbd{tar xf vol-1.tar} 8803var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as 8804normal file 8805Unexpected EOF in archive 8806$ @kbd{tar xf vol-2.tar} 8807tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file 8808GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type 8809'x', extracted as normal file 8810@end group 8811@end smallexample 8812 8813Ignore these warnings. The @file{PaxHeaders.*} directories created 8814will contain files with @dfn{extended header keywords} describing the 8815extracted files. You can delete them, unless they describe sparse 8816members. Read further to learn more about them. 8817 8818@node Sparse Recovery 8819@subsubsection Extracting Sparse Members 8820 8821@cindex sparse files, extracting with non-GNU tars 8822Any @command{tar} implementation will be able to extract sparse members from a 8823PAX archive. However, the extracted files will be @dfn{condensed}, 8824i.e., any zero blocks will be removed from them. When we restore such 8825a condensed file to its original form, by adding zero blocks (or 8826@dfn{holes}) back to their original locations, we call this process 8827@dfn{expanding} a compressed sparse file. 8828 8829@pindex xsparse 8830To expand a file, you will need a simple auxiliary program called 8831@command{xsparse}. It is available in source form from 8832@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html, @GNUTAR{} 8833home page}. 8834 8835@cindex sparse files v.1.0, extracting with non-GNU tars 8836Let's begin with archive members in @dfn{sparse format 8837version 1.0}@footnote{@xref{PAX 1}.}, which are the easiest to expand. 8838The condensed file will contain both file map and file data, so no 8839additional data will be needed to restore it. If the original file 8840name was @file{@var{dir}/@var{name}}, then the condensed file will be 8841named @file{@var{dir}/@/GNUSparseFile.@var{n}/@/@var{name}}, where 8842@var{n} is a decimal number@footnote{technically speaking, @var{n} is a 8843@dfn{process @acronym{ID}} of the @command{tar} process which created the 8844archive (@pxref{PAX keywords}).}. 8845 8846To expand a version 1.0 file, run @command{xsparse} as follows: 8847 8848@smallexample 8849$ @kbd{xsparse @file{cond-file}} 8850@end smallexample 8851 8852@noindent 8853where @file{cond-file} is the name of the condensed file. The utility 8854will deduce the name for the resulting expanded file using the 8855following algorithm: 8856 8857@enumerate 1 8858@item If @file{cond-file} does not contain any directories, 8859@file{../cond-file} will be used; 8860 8861@item If @file{cond-file} has the form 8862@file{@var{dir}/@var{t}/@var{name}}, where both @var{t} and @var{name} 8863are simple names, with no @samp{/} characters in them, the output file 8864name will be @file{@var{dir}/@var{name}}. 8865 8866@item Otherwise, if @file{cond-file} has the form 8867@file{@var{dir}/@var{name}}, the output file name will be 8868@file{@var{name}}. 8869@end enumerate 8870 8871In the unlikely case when this algorithm does not suit your needs, 8872you can explicitly specify output file name as a second argument to 8873the command: 8874 8875@smallexample 8876$ @kbd{xsparse @file{cond-file} @file{out-file}} 8877@end smallexample 8878 8879It is often a good idea to run @command{xsparse} in @dfn{dry run} mode 8880first. In this mode, the command does not actually expand the file, 8881but verbosely lists all actions it would be taking to do so. The dry 8882run mode is enabled by @option{-n} command line argument: 8883 8884@smallexample 8885@group 8886$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile} 8887Reading v.1.0 sparse map 8888Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to 8889`/home/gray/sparsefile' 8890Finished dry run 8891@end group 8892@end smallexample 8893 8894To actually expand the file, you would run: 8895 8896@smallexample 8897$ @kbd{xsparse /home/gray/GNUSparseFile.6058/sparsefile} 8898@end smallexample 8899 8900@noindent 8901The program behaves the same way all UNIX utilities do: it will keep 8902quiet unless it has simething important to tell you (e.g. an error 8903condition or something). If you wish it to produce verbose output, 8904similar to that from the dry run mode, use @option{-v} option: 8905 8906@smallexample 8907@group 8908$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile} 8909Reading v.1.0 sparse map 8910Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to 8911`/home/gray/sparsefile' 8912Done 8913@end group 8914@end smallexample 8915 8916Additionally, if your @command{tar} implementation has extracted the 8917@dfn{extended headers} for this file, you can instruct @command{xstar} 8918to use them in order to verify the integrity of the expanded file. 8919The option @option{-x} sets the name of the extended header file to 8920use. Continuing our example: 8921 8922@smallexample 8923@group 8924$ @kbd{xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \ 8925 /home/gray/GNUSparseFile.6058/sparsefile} 8926Reading extended header file 8927Found variable GNU.sparse.major = 1 8928Found variable GNU.sparse.minor = 0 8929Found variable GNU.sparse.name = sparsefile 8930Found variable GNU.sparse.realsize = 217481216 8931Reading v.1.0 sparse map 8932Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to 8933`/home/gray/sparsefile' 8934Done 8935@end group 8936@end smallexample 8937 8938@anchor{extracting sparse v.0.x} 8939@cindex sparse files v.0.1, extracting with non-GNU tars 8940@cindex sparse files v.0.0, extracting with non-GNU tars 8941An @dfn{extended header} is a special @command{tar} archive header 8942that precedes an archive member and contains a set of 8943@dfn{variables}, describing the member properties that cannot be 8944stored in the standard @code{ustar} header. While optional for 8945expanding sparse version 1.0 members, the use of extended headers is 8946mandatory when expanding sparse members in older sparse formats: v.0.0 8947and v.0.1 (The sparse formats are described in detail in @ref{Sparse 8948Formats}.) So, for these formats, the question is: how to obtain 8949extended headers from the archive? 8950 8951If you use a @command{tar} implementation that does not support PAX 8952format, extended headers for each member will be extracted as a 8953separate file. If we represent the member name as 8954@file{@var{dir}/@var{name}}, then the extended header file will be 8955named @file{@var{dir}/@/PaxHeaders.@var{n}/@/@var{name}}, where 8956@var{n} is an integer number. 8957 8958Things become more difficult if your @command{tar} implementation 8959does support PAX headers, because in this case you will have to 8960manually extract the headers. We recommend the following algorithm: 8961 8962@enumerate 1 8963@item 8964Consult the documentation of your @command{tar} implementation for an 8965option that prints @dfn{block numbers} along with the archive 8966listing (analogous to @GNUTAR{}'s @option{-R} option). For example, 8967@command{star} has @option{-block-number}. 8968 8969@item 8970Obtain verbose listing using the @samp{block number} option, and 8971find block numbers of the sparse member in question and the member 8972immediately following it. For example, running @command{star} on our 8973archive we obtain: 8974 8975@smallexample 8976@group 8977$ @kbd{star -t -v -block-number -f arc.tar} 8978@dots{} 8979star: Unknown extended header keyword 'GNU.sparse.size' ignored. 8980star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored. 8981star: Unknown extended header keyword 'GNU.sparse.name' ignored. 8982star: Unknown extended header keyword 'GNU.sparse.map' ignored. 8983block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile 8984block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README 8985@dots{} 8986@end group 8987@end smallexample 8988 8989@noindent 8990(as usual, ignore the warnings about unknown keywords.) 8991 8992@item 8993Let @var{size} be the size of the sparse member, @var{Bs} be its block number 8994and @var{Bn} be the block number of the next member. 8995Compute: 8996 8997@smallexample 8998@var{N} = @var{Bs} - @var{Bn} - @var{size}/512 - 2 8999@end smallexample 9000 9001@noindent 9002This number gives the size of the extended header part in tar @dfn{blocks}. 9003In our example, this formula gives: @code{897 - 56 - 425984 / 512 - 2 9004= 7}. 9005 9006@item 9007Use @command{dd} to extract the headers: 9008 9009@smallexample 9010@kbd{dd if=@var{archive} of=@var{hname} bs=512 skip=@var{Bs} count=@var{N}} 9011@end smallexample 9012 9013@noindent 9014where @var{archive} is the archive name, @var{hname} is a name of the 9015file to store the extended header in, @var{Bs} and @var{N} are 9016computed in previous steps. 9017 9018In our example, this command will be 9019 9020@smallexample 9021$ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56 count=7} 9022@end smallexample 9023@end enumerate 9024 9025Finally, you can expand the condensed file, using the obtained header: 9026 9027@smallexample 9028@group 9029$ @kbd{xsparse -v -x xhdr GNUSparseFile.6058/sparsefile} 9030Reading extended header file 9031Found variable GNU.sparse.size = 217481216 9032Found variable GNU.sparse.numblocks = 208 9033Found variable GNU.sparse.name = sparsefile 9034Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{} 9035Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile' 9036Done 9037@end group 9038@end smallexample 9039 9040@node cpio 9041@section Comparison of @command{tar} and @command{cpio} 9042@UNREVISED 9043 9044@FIXME{Reorganize the following material} 9045 9046The @command{cpio} archive formats, like @command{tar}, do have maximum 9047file name lengths. The binary and old @acronym{ASCII} formats have a maximum file 9048length of 256, and the new @acronym{ASCII} and @acronym{CRC ASCII} formats have a max 9049file length of 1024. @acronym{GNU} @command{cpio} can read and write archives 9050with arbitrary file name lengths, but other @command{cpio} implementations 9051may crash unexplainedly trying to read them. 9052 9053@command{tar} handles symbolic links in the form in which it comes in @acronym{BSD}; 9054@command{cpio} doesn't handle symbolic links in the form in which it comes 9055in System V prior to SVR4, and some vendors may have added symlinks 9056to their system without enhancing @command{cpio} to know about them. 9057Others may have enhanced it in a way other than the way I did it 9058at Sun, and which was adopted by AT&T (and which is, I think, also 9059present in the @command{cpio} that Berkeley picked up from AT&T and put 9060into a later @acronym{BSD} release---I think I gave them my changes). 9061 9062(SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio} 9063can handle @command{tar} format input, and write it on output, and it 9064probably handles symbolic links. They may not have bothered doing 9065anything to enhance @command{tar} as a result.) 9066 9067@command{cpio} handles special files; traditional @command{tar} doesn't. 9068 9069@command{tar} comes with V7, System III, System V, and @acronym{BSD} source; 9070@command{cpio} comes only with System III, System V, and later @acronym{BSD} 9071(4.3-tahoe and later). 9072 9073@command{tar}'s way of handling multiple hard links to a file can handle 9074file systems that support 32-bit inumbers (e.g., the @acronym{BSD} file system); 9075@command{cpio}s way requires you to play some games (in its ``binary'' 9076format, i-numbers are only 16 bits, and in its ``portable @acronym{ASCII}'' format, 9077they're 18 bits---it would have to play games with the "file system @acronym{ID}" 9078field of the header to make sure that the file system @acronym{ID}/i-number pairs 9079of different files were always different), and I don't know which 9080@command{cpio}s, if any, play those games. Those that don't might get 9081confused and think two files are the same file when they're not, and 9082make hard links between them. 9083 9084@command{tar}s way of handling multiple hard links to a file places only 9085one copy of the link on the tape, but the name attached to that copy 9086is the @emph{only} one you can use to retrieve the file; @command{cpio}s 9087way puts one copy for every link, but you can retrieve it using any 9088of the names. 9089 9090@quotation 9091What type of check sum (if any) is used, and how is this calculated. 9092@end quotation 9093 9094See the attached manual pages for @command{tar} and @command{cpio} format. 9095@command{tar} uses a checksum which is the sum of all the bytes in the 9096@command{tar} header for a file; @command{cpio} uses no checksum. 9097 9098@quotation 9099If anyone knows why @command{cpio} was made when @command{tar} was present 9100at the unix scene, 9101@end quotation 9102 9103It wasn't. @command{cpio} first showed up in PWB/UNIX 1.0; no 9104generally-available version of UNIX had @command{tar} at the time. I don't 9105know whether any version that was generally available @emph{within AT&T} 9106had @command{tar}, or, if so, whether the people within AT&T who did 9107@command{cpio} knew about it. 9108 9109On restore, if there is a corruption on a tape @command{tar} will stop at 9110that point, while @command{cpio} will skip over it and try to restore the 9111rest of the files. 9112 9113The main difference is just in the command syntax and header format. 9114 9115@command{tar} is a little more tape-oriented in that everything is blocked 9116to start on a record boundary. 9117 9118@quotation 9119Is there any differences between the ability to recover crashed 9120archives between the two of them. (Is there any chance of recovering 9121crashed archives at all.) 9122@end quotation 9123 9124Theoretically it should be easier under @command{tar} since the blocking 9125lets you find a header with some variation of @samp{dd skip=@var{nn}}. 9126However, modern @command{cpio}'s and variations have an option to just 9127search for the next file header after an error with a reasonable chance 9128of resyncing. However, lots of tape driver software won't allow you to 9129continue past a media error which should be the only reason for getting 9130out of sync unless a file changed sizes while you were writing the 9131archive. 9132 9133@quotation 9134If anyone knows why @command{cpio} was made when @command{tar} was present 9135at the unix scene, please tell me about this too. 9136@end quotation 9137 9138Probably because it is more media efficient (by not blocking everything 9139and using only the space needed for the headers where @command{tar} 9140always uses 512 bytes per file header) and it knows how to archive 9141special files. 9142 9143You might want to look at the freely available alternatives. The 9144major ones are @command{afio}, @GNUTAR{}, and 9145@command{pax}, each of which have their own extensions with some 9146backwards compatibility. 9147 9148Sparse files were @command{tar}red as sparse files (which you can 9149easily test, because the resulting archive gets smaller, and 9150@acronym{GNU} @command{cpio} can no longer read it). 9151 9152@node Media 9153@chapter Tapes and Other Archive Media 9154@UNREVISED 9155 9156A few special cases about tape handling warrant more detailed 9157description. These special cases are discussed below. 9158 9159Many complexities surround the use of @command{tar} on tape drives. Since 9160the creation and manipulation of archives located on magnetic tape was 9161the original purpose of @command{tar}, it contains many features making 9162such manipulation easier. 9163 9164Archives are usually written on dismountable media---tape cartridges, 9165mag tapes, or floppy disks. 9166 9167The amount of data a tape or disk holds depends not only on its size, 9168but also on how it is formatted. A 2400 foot long reel of mag tape 9169holds 40 megabytes of data when formatted at 1600 bits per inch. The 9170physically smaller EXABYTE tape cartridge holds 2.3 gigabytes. 9171 9172Magnetic media are re-usable---once the archive on a tape is no longer 9173needed, the archive can be erased and the tape or disk used over. 9174Media quality does deteriorate with use, however. Most tapes or disks 9175should be discarded when they begin to produce data errors. EXABYTE 9176tape cartridges should be discarded when they generate an @dfn{error 9177count} (number of non-usable bits) of more than 10k. 9178 9179Magnetic media are written and erased using magnetic fields, and 9180should be protected from such fields to avoid damage to stored data. 9181Sticking a floppy disk to a filing cabinet using a magnet is probably 9182not a good idea. 9183 9184@menu 9185* Device:: Device selection and switching 9186* Remote Tape Server:: 9187* Common Problems and Solutions:: 9188* Blocking:: Blocking 9189* Many:: Many archives on one tape 9190* Using Multiple Tapes:: Using Multiple Tapes 9191* label:: Including a Label in the Archive 9192* verify:: 9193* Write Protection:: 9194@end menu 9195 9196@node Device 9197@section Device Selection and Switching 9198@UNREVISED 9199 9200@table @option 9201@item -f [@var{hostname}:]@var{file} 9202@itemx --file=[@var{hostname}:]@var{file} 9203Use archive file or device @var{file} on @var{hostname}. 9204@end table 9205 9206This option is used to specify the file name of the archive @command{tar} 9207works on. 9208 9209If the file name is @samp{-}, @command{tar} reads the archive from standard 9210input (when listing or extracting), or writes it to standard output 9211(when creating). If the @samp{-} file name is given when updating an 9212archive, @command{tar} will read the original archive from its standard 9213input, and will write the entire new archive to its standard output. 9214 9215If the file name contains a @samp{:}, it is interpreted as 9216@samp{hostname:file name}. If the @var{hostname} contains an @dfn{at} 9217sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}. In 9218either case, @command{tar} will invoke the command @command{rsh} (or 9219@command{remsh}) to start up an @command{/usr/libexec/rmt} on the remote 9220machine. If you give an alternate login name, it will be given to the 9221@command{rsh}. 9222Naturally, the remote machine must have an executable 9223@command{/usr/libexec/rmt}. This program is free software from the 9224University of California, and a copy of the source code can be found 9225with the sources for @command{tar}; it's compiled and installed by default. 9226The exact path to this utility is determined when configuring the package. 9227It is @file{@var{prefix}/libexec/rmt}, where @var{prefix} stands for 9228your installation prefix. This location may also be overridden at 9229runtime by using @option{rmt-command=@var{command}} option (@xref{Option Summary, 9230---rmt-command}, for detailed description of this option. @xref{Remote 9231Tape Server}, for the description of @command{rmt} command). 9232 9233If this option is not given, but the environment variable @env{TAPE} 9234is set, its value is used; otherwise, old versions of @command{tar} 9235used a default archive name (which was picked when @command{tar} was 9236compiled). The default is normally set up to be the @dfn{first} tape 9237drive or other transportable I/O medium on the system. 9238 9239Starting with version 1.11.5, @GNUTAR{} uses 9240standard input and standard output as the default device, and I will 9241not try anymore supporting automatic device detection at installation 9242time. This was failing really in too many cases, it was hopeless. 9243This is now completely left to the installer to override standard 9244input and standard output for default device, if this seems 9245preferable. Further, I think @emph{most} actual usages of 9246@command{tar} are done with pipes or disks, not really tapes, 9247cartridges or diskettes. 9248 9249Some users think that using standard input and output is running 9250after trouble. This could lead to a nasty surprise on your screen if 9251you forget to specify an output file name---especially if you are going 9252through a network or terminal server capable of buffering large amounts 9253of output. We had so many bug reports in that area of configuring 9254default tapes automatically, and so many contradicting requests, that 9255we finally consider the problem to be portably intractable. We could 9256of course use something like @samp{/dev/tape} as a default, but this 9257is @emph{also} running after various kind of trouble, going from hung 9258processes to accidental destruction of real tapes. After having seen 9259all this mess, using standard input and output as a default really 9260sounds like the only clean choice left, and a very useful one too. 9261 9262@GNUTAR{} reads and writes archive in records, I 9263suspect this is the main reason why block devices are preferred over 9264character devices. Most probably, block devices are more efficient 9265too. The installer could also check for @samp{DEFTAPE} in 9266@file{<sys/mtio.h>}. 9267 9268@table @option 9269@xopindex{force-local, short description} 9270@item --force-local 9271Archive file is local even if it contains a colon. 9272 9273@opindex rsh-command 9274@item --rsh-command=@var{command} 9275Use remote @var{command} instead of @command{rsh}. This option exists 9276so that people who use something other than the standard @command{rsh} 9277(e.g., a Kerberized @command{rsh}) can access a remote device. 9278 9279When this command is not used, the shell command found when 9280the @command{tar} program was installed is used instead. This is 9281the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh}, 9282@file{/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}. 9283The installer may have overridden this by defining the environment 9284variable @env{RSH} @emph{at installation time}. 9285 9286@item -[0-7][lmh] 9287Specify drive and density. 9288 9289@xopindex{multi-volume, short description} 9290@item -M 9291@itemx --multi-volume 9292Create/list/extract multi-volume archive. 9293 9294This option causes @command{tar} to write a @dfn{multi-volume} archive---one 9295that may be larger than will fit on the medium used to hold it. 9296@xref{Multi-Volume Archives}. 9297 9298@xopindex{tape-length, short description} 9299@item -L @var{num} 9300@itemx --tape-length=@var{num} 9301Change tape after writing @var{num} x 1024 bytes. 9302 9303This option might be useful when your tape drivers do not properly 9304detect end of physical tapes. By being slightly conservative on the 9305maximum tape length, you might avoid the problem entirely. 9306 9307@xopindex{info-script, short description} 9308@xopindex{new-volume-script, short description} 9309@item -F @var{file} 9310@itemx --info-script=@var{file} 9311@itemx --new-volume-script=@var{file} 9312Execute @file{file} at end of each tape. This implies 9313@option{--multi-volume} (@option{-M}). @xref{info-script}, for a detailed 9314description of this option. 9315@end table 9316 9317@node Remote Tape Server 9318@section The Remote Tape Server 9319 9320@cindex remote tape drive 9321@pindex rmt 9322In order to access the tape drive on a remote machine, @command{tar} 9323uses the remote tape server written at the University of California at 9324Berkeley. The remote tape server must be installed as 9325@file{@var{prefix}/libexec/rmt} on any machine whose tape drive you 9326want to use. @command{tar} calls @command{rmt} by running an 9327@command{rsh} or @command{remsh} to the remote machine, optionally 9328using a different login name if one is supplied. 9329 9330A copy of the source for the remote tape server is provided. It is 9331Copyright @copyright{} 1983 by the Regents of the University of 9332California, but can be freely distributed. It is compiled and 9333installed by default. 9334 9335@cindex absolute file names 9336Unless you use the @option{--absolute-names} (@option{-P}) option, 9337@GNUTAR{} will not allow you to create an archive that contains 9338absolute file names (a file name beginning with @samp{/}.) If you try, 9339@command{tar} will automatically remove the leading @samp{/} from the 9340file names it stores in the archive. It will also type a warning 9341message telling you what it is doing. 9342 9343When reading an archive that was created with a different 9344@command{tar} program, @GNUTAR{} automatically 9345extracts entries in the archive which have absolute file names as if 9346the file names were not absolute. This is an important feature. A 9347visitor here once gave a @command{tar} tape to an operator to restore; 9348the operator used Sun @command{tar} instead of @GNUTAR{}, 9349and the result was that it replaced large portions of 9350our @file{/bin} and friends with versions from the tape; needless to 9351say, we were unhappy about having to recover the file system from 9352backup tapes. 9353 9354For example, if the archive contained a file @file{/usr/bin/computoy}, 9355@GNUTAR{} would extract the file to @file{usr/bin/computoy}, 9356relative to the current directory. If you want to extract the files in 9357an archive to the same absolute names that they had when the archive 9358was created, you should do a @samp{cd /} before extracting the files 9359from the archive, or you should either use the @option{--absolute-names} 9360option, or use the command @samp{tar -C / @dots{}}. 9361 9362@cindex Ultrix 3.1 and write failure 9363Some versions of Unix (Ultrix 3.1 is known to have this problem), 9364can claim that a short write near the end of a tape succeeded, 9365when it actually failed. This will result in the -M option not 9366working correctly. The best workaround at the moment is to use a 9367significantly larger blocking factor than the default 20. 9368 9369In order to update an archive, @command{tar} must be able to backspace the 9370archive in order to reread or rewrite a record that was just read (or 9371written). This is currently possible only on two kinds of files: normal 9372disk files (or any other file that can be backspaced with @samp{lseek}), 9373and industry-standard 9-track magnetic tape (or any other kind of tape 9374that can be backspaced with the @code{MTIOCTOP} @code{ioctl}. 9375 9376This means that the @option{--append}, @option{--concatenate}, and 9377@option{--delete} commands will not work on any other kind of file. 9378Some media simply cannot be backspaced, which means these commands and 9379options will never be able to work on them. These non-backspacing 9380media include pipes and cartridge tape drives. 9381 9382Some other media can be backspaced, and @command{tar} will work on them 9383once @command{tar} is modified to do so. 9384 9385Archives created with the @option{--multi-volume}, @option{--label}, and 9386@option{--incremental} (@option{-G}) options may not be readable by other version 9387of @command{tar}. In particular, restoring a file that was split over 9388a volume boundary will require some careful work with @command{dd}, if 9389it can be done at all. Other versions of @command{tar} may also create 9390an empty file whose name is that of the volume header. Some versions 9391of @command{tar} may create normal files instead of directories archived 9392with the @option{--incremental} (@option{-G}) option. 9393 9394@node Common Problems and Solutions 9395@section Some Common Problems and their Solutions 9396 9397@ifclear PUBLISH 9398 9399@format 9400errors from system: 9401permission denied 9402no such file or directory 9403not owner 9404 9405errors from @command{tar}: 9406directory checksum error 9407header format error 9408 9409errors from media/system: 9410i/o error 9411device busy 9412@end format 9413 9414@end ifclear 9415 9416@node Blocking 9417@section Blocking 9418@UNREVISED 9419 9420@dfn{Block} and @dfn{record} terminology is rather confused, and it 9421is also confusing to the expert reader. On the other hand, readers 9422who are new to the field have a fresh mind, and they may safely skip 9423the next two paragraphs, as the remainder of this manual uses those 9424two terms in a quite consistent way. 9425 9426John Gilmore, the writer of the public domain @command{tar} from which 9427@GNUTAR{} was originally derived, wrote (June 1995): 9428 9429@quotation 9430The nomenclature of tape drives comes from IBM, where I believe 9431they were invented for the IBM 650 or so. On IBM mainframes, what 9432is recorded on tape are tape blocks. The logical organization of 9433data is into records. There are various ways of putting records into 9434blocks, including @code{F} (fixed sized records), @code{V} (variable 9435sized records), @code{FB} (fixed blocked: fixed size records, @var{n} 9436to a block), @code{VB} (variable size records, @var{n} to a block), 9437@code{VSB} (variable spanned blocked: variable sized records that can 9438occupy more than one block), etc. The @code{JCL} @samp{DD RECFORM=} 9439parameter specified this to the operating system. 9440 9441The Unix man page on @command{tar} was totally confused about this. 9442When I wrote @code{PD TAR}, I used the historically correct terminology 9443(@command{tar} writes data records, which are grouped into blocks). 9444It appears that the bogus terminology made it into @acronym{POSIX} (no surprise 9445here), and now Fran@,{c}ois has migrated that terminology back 9446into the source code too. 9447@end quotation 9448 9449The term @dfn{physical block} means the basic transfer chunk from or 9450to a device, after which reading or writing may stop without anything 9451being lost. In this manual, the term @dfn{block} usually refers to 9452a disk physical block, @emph{assuming} that each disk block is 512 9453bytes in length. It is true that some disk devices have different 9454physical blocks, but @command{tar} ignore these differences in its own 9455format, which is meant to be portable, so a @command{tar} block is always 9456512 bytes in length, and @dfn{block} always mean a @command{tar} block. 9457The term @dfn{logical block} often represents the basic chunk of 9458allocation of many disk blocks as a single entity, which the operating 9459system treats somewhat atomically; this concept is only barely used 9460in @GNUTAR{}. 9461 9462The term @dfn{physical record} is another way to speak of a physical 9463block, those two terms are somewhat interchangeable. In this manual, 9464the term @dfn{record} usually refers to a tape physical block, 9465@emph{assuming} that the @command{tar} archive is kept on magnetic tape. 9466It is true that archives may be put on disk or used with pipes, 9467but nevertheless, @command{tar} tries to read and write the archive one 9468@dfn{record} at a time, whatever the medium in use. One record is made 9469up of an integral number of blocks, and this operation of putting many 9470disk blocks into a single tape block is called @dfn{reblocking}, or 9471more simply, @dfn{blocking}. The term @dfn{logical record} refers to 9472the logical organization of many characters into something meaningful 9473to the application. The term @dfn{unit record} describes a small set 9474of characters which are transmitted whole to or by the application, 9475and often refers to a line of text. Those two last terms are unrelated 9476to what we call a @dfn{record} in @GNUTAR{}. 9477 9478When writing to tapes, @command{tar} writes the contents of the archive 9479in chunks known as @dfn{records}. To change the default blocking 9480factor, use the @option{--blocking-factor=@var{512-size}} (@option{-b 9481@var{512-size}}) option. Each record will then be composed of 9482@var{512-size} blocks. (Each @command{tar} block is 512 bytes. 9483@xref{Standard}.) Each file written to the archive uses at least one 9484full record. As a result, using a larger record size can result in 9485more wasted space for small files. On the other hand, a larger record 9486size can often be read and written much more efficiently. 9487 9488Further complicating the problem is that some tape drives ignore the 9489blocking entirely. For these, a larger record size can still improve 9490performance (because the software layers above the tape drive still 9491honor the blocking), but not as dramatically as on tape drives that 9492honor blocking. 9493 9494When reading an archive, @command{tar} can usually figure out the 9495record size on itself. When this is the case, and a non-standard 9496record size was used when the archive was created, @command{tar} will 9497print a message about a non-standard blocking factor, and then operate 9498normally. On some tape devices, however, @command{tar} cannot figure 9499out the record size itself. On most of those, you can specify a 9500blocking factor (with @option{--blocking-factor}) larger than the 9501actual blocking factor, and then use the @option{--read-full-records} 9502(@option{-B}) option. (If you specify a blocking factor with 9503@option{--blocking-factor} and don't use the 9504@option{--read-full-records} option, then @command{tar} will not 9505attempt to figure out the recording size itself.) On some devices, 9506you must always specify the record size exactly with 9507@option{--blocking-factor} when reading, because @command{tar} cannot 9508figure it out. In any case, use @option{--list} (@option{-t}) before 9509doing any extractions to see whether @command{tar} is reading the archive 9510correctly. 9511 9512@command{tar} blocks are all fixed size (512 bytes), and its scheme for 9513putting them into records is to put a whole number of them (one or 9514more) into each record. @command{tar} records are all the same size; 9515at the end of the file there's a block containing all zeros, which 9516is how you tell that the remainder of the last record(s) are garbage. 9517 9518In a standard @command{tar} file (no options), the block size is 512 9519and the record size is 10240, for a blocking factor of 20. What the 9520@option{--blocking-factor} option does is sets the blocking factor, 9521changing the record size while leaving the block size at 512 bytes. 952220 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives; 9523most tape drives these days prefer much bigger records in order to 9524stream and not waste tape. When writing tapes for myself, some tend 9525to use a factor of the order of 2048, say, giving a record size of 9526around one megabyte. 9527 9528If you use a blocking factor larger than 20, older @command{tar} 9529programs might not be able to read the archive, so we recommend this 9530as a limit to use in practice. @GNUTAR{}, however, 9531will support arbitrarily large record sizes, limited only by the 9532amount of virtual memory or the physical characteristics of the tape 9533device. 9534 9535@menu 9536* Format Variations:: Format Variations 9537* Blocking Factor:: The Blocking Factor of an Archive 9538@end menu 9539 9540@node Format Variations 9541@subsection Format Variations 9542@cindex Format Parameters 9543@cindex Format Options 9544@cindex Options, archive format specifying 9545@cindex Options, format specifying 9546@UNREVISED 9547 9548Format parameters specify how an archive is written on the archive 9549media. The best choice of format parameters will vary depending on 9550the type and number of files being archived, and on the media used to 9551store the archive. 9552 9553To specify format parameters when accessing or creating an archive, 9554you can use the options described in the following sections. 9555If you do not specify any format parameters, @command{tar} uses 9556default parameters. You cannot modify a compressed archive. 9557If you create an archive with the @option{--blocking-factor} option 9558specified (@pxref{Blocking Factor}), you must specify that 9559blocking-factor when operating on the archive. @xref{Formats}, for other 9560examples of format parameter considerations. 9561 9562@node Blocking Factor 9563@subsection The Blocking Factor of an Archive 9564@cindex Blocking Factor 9565@cindex Record Size 9566@cindex Number of blocks per record 9567@cindex Number of bytes per record 9568@cindex Bytes per record 9569@cindex Blocks per record 9570@UNREVISED 9571 9572@opindex blocking-factor 9573The data in an archive is grouped into blocks, which are 512 bytes. 9574Blocks are read and written in whole number multiples called 9575@dfn{records}. The number of blocks in a record (i.e., the size of a 9576record in units of 512 bytes) is called the @dfn{blocking factor}. 9577The @option{--blocking-factor=@var{512-size}} (@option{-b 9578@var{512-size}}) option specifies the blocking factor of an archive. 9579The default blocking factor is typically 20 (i.e., 10240 bytes), but 9580can be specified at installation. To find out the blocking factor of 9581an existing archive, use @samp{tar --list --file=@var{archive-name}}. 9582This may not work on some devices. 9583 9584Records are separated by gaps, which waste space on the archive media. 9585If you are archiving on magnetic tape, using a larger blocking factor 9586(and therefore larger records) provides faster throughput and allows you 9587to fit more data on a tape (because there are fewer gaps). If you are 9588archiving on cartridge, a very large blocking factor (say 126 or more) 9589greatly increases performance. A smaller blocking factor, on the other 9590hand, may be useful when archiving small files, to avoid archiving lots 9591of nulls as @command{tar} fills out the archive to the end of the record. 9592In general, the ideal record size depends on the size of the 9593inter-record gaps on the tape you are using, and the average size of the 9594files you are archiving. @xref{create}, for information on 9595writing archives. 9596 9597@FIXME{Need example of using a cartridge with blocking factor=126 or more.} 9598 9599Archives with blocking factors larger than 20 cannot be read 9600by very old versions of @command{tar}, or by some newer versions 9601of @command{tar} running on old machines with small address spaces. 9602With @GNUTAR{}, the blocking factor of an archive is limited 9603only by the maximum record size of the device containing the archive, 9604or by the amount of available virtual memory. 9605 9606Also, on some systems, not using adequate blocking factors, as sometimes 9607imposed by the device drivers, may yield unexpected diagnostics. For 9608example, this has been reported: 9609 9610@smallexample 9611Cannot write to /dev/dlt: Invalid argument 9612@end smallexample 9613 9614@noindent 9615In such cases, it sometimes happen that the @command{tar} bundled by 9616the system is aware of block size idiosyncrasies, while @GNUTAR{} 9617requires an explicit specification for the block size, 9618which it cannot guess. This yields some people to consider 9619@GNUTAR{} is misbehaving, because by comparison, 9620@cite{the bundle @command{tar} works OK}. Adding @w{@kbd{-b 256}}, 9621for example, might resolve the problem. 9622 9623If you use a non-default blocking factor when you create an archive, you 9624must specify the same blocking factor when you modify that archive. Some 9625archive devices will also require you to specify the blocking factor when 9626reading that archive, however this is not typically the case. Usually, you 9627can use @option{--list} (@option{-t}) without specifying a blocking factor---@command{tar} 9628reports a non-default record size and then lists the archive members as 9629it would normally. To extract files from an archive with a non-standard 9630blocking factor (particularly if you're not sure what the blocking factor 9631is), you can usually use the @option{--read-full-records} (@option{-B}) option while 9632specifying a blocking factor larger then the blocking factor of the archive 9633(i.e., @samp{tar --extract --read-full-records --blocking-factor=300}. 9634@xref{list}, for more information on the @option{--list} (@option{-t}) 9635operation. @xref{Reading}, for a more detailed explanation of that option. 9636 9637@table @option 9638@item --blocking-factor=@var{number} 9639@itemx -b @var{number} 9640Specifies the blocking factor of an archive. Can be used with any 9641operation, but is usually not necessary with @option{--list} (@option{-t}). 9642@end table 9643 9644Device blocking 9645 9646@table @option 9647@item -b @var{blocks} 9648@itemx --blocking-factor=@var{blocks} 9649Set record size to @math{@var{blocks} * 512} bytes. 9650 9651This option is used to specify a @dfn{blocking factor} for the archive. 9652When reading or writing the archive, @command{tar}, will do reads and writes 9653of the archive in records of @math{@var{block}*512} bytes. This is true 9654even when the archive is compressed. Some devices requires that all 9655write operations be a multiple of a certain size, and so, @command{tar} 9656pads the archive out to the next record boundary. 9657 9658The default blocking factor is set when @command{tar} is compiled, and is 9659typically 20. Blocking factors larger than 20 cannot be read by very 9660old versions of @command{tar}, or by some newer versions of @command{tar} 9661running on old machines with small address spaces. 9662 9663With a magnetic tape, larger records give faster throughput and fit 9664more data on a tape (because there are fewer inter-record gaps). 9665If the archive is in a disk file or a pipe, you may want to specify 9666a smaller blocking factor, since a large one will result in a large 9667number of null bytes at the end of the archive. 9668 9669When writing cartridge or other streaming tapes, a much larger 9670blocking factor (say 126 or more) will greatly increase performance. 9671However, you must specify the same blocking factor when reading or 9672updating the archive. 9673 9674Apparently, Exabyte drives have a physical block size of 8K bytes. 9675If we choose our blocksize as a multiple of 8k bytes, then the problem 9676seems to disappear. Id est, we are using block size of 112 right 9677now, and we haven't had the problem since we switched@dots{} 9678 9679With @GNUTAR{} the blocking factor is limited only 9680by the maximum record size of the device containing the archive, or by 9681the amount of available virtual memory. 9682 9683However, deblocking or reblocking is virtually avoided in a special 9684case which often occurs in practice, but which requires all the 9685following conditions to be simultaneously true: 9686@itemize @bullet 9687@item 9688the archive is subject to a compression option, 9689@item 9690the archive is not handled through standard input or output, nor 9691redirected nor piped, 9692@item 9693the archive is directly handled to a local disk, instead of any special 9694device, 9695@item 9696@option{--blocking-factor} is not explicitly specified on the @command{tar} 9697invocation. 9698@end itemize 9699 9700If the output goes directly to a local disk, and not through 9701stdout, then the last write is not extended to a full record size. 9702Otherwise, reblocking occurs. Here are a few other remarks on this 9703topic: 9704 9705@itemize @bullet 9706 9707@item 9708@command{gzip} will complain about trailing garbage if asked to 9709uncompress a compressed archive on tape, there is an option to turn 9710the message off, but it breaks the regularity of simply having to use 9711@samp{@var{prog} -d} for decompression. It would be nice if gzip was 9712silently ignoring any number of trailing zeros. I'll ask Jean-loup 9713Gailly, by sending a copy of this message to him. 9714 9715@item 9716@command{compress} does not show this problem, but as Jean-loup pointed 9717out to Michael, @samp{compress -d} silently adds garbage after 9718the result of decompression, which tar ignores because it already 9719recognized its end-of-file indicator. So this bug may be safely 9720ignored. 9721 9722@item 9723@samp{gzip -d -q} will be silent about the trailing zeros indeed, 9724but will still return an exit status of 2 which tar reports in turn. 9725@command{tar} might ignore the exit status returned, but I hate doing 9726that, as it weakens the protection @command{tar} offers users against 9727other possible problems at decompression time. If @command{gzip} was 9728silently skipping trailing zeros @emph{and} also avoiding setting the 9729exit status in this innocuous case, that would solve this situation. 9730 9731@item 9732@command{tar} should become more solid at not stopping to read a pipe at 9733the first null block encountered. This inelegantly breaks the pipe. 9734@command{tar} should rather drain the pipe out before exiting itself. 9735@end itemize 9736 9737@xopindex{ignore-zeros, short description} 9738@item -i 9739@itemx --ignore-zeros 9740Ignore blocks of zeros in archive (means EOF). 9741 9742The @option{--ignore-zeros} (@option{-i}) option causes @command{tar} to ignore blocks 9743of zeros in the archive. Normally a block of zeros indicates the 9744end of the archive, but when reading a damaged archive, or one which 9745was created by concatenating several archives together, this option 9746allows @command{tar} to read the entire archive. This option is not on 9747by default because many versions of @command{tar} write garbage after 9748the zeroed blocks. 9749 9750Note that this option causes @command{tar} to read to the end of the 9751archive file, which may sometimes avoid problems when multiple files 9752are stored on a single physical tape. 9753 9754@xopindex{read-full-records, short description} 9755@item -B 9756@itemx --read-full-records 9757Reblock as we read (for reading 4.2@acronym{BSD} pipes). 9758 9759If @option{--read-full-records} is used, @command{tar} 9760will not panic if an attempt to read a record from the archive does 9761not return a full record. Instead, @command{tar} will keep reading 9762until it has obtained a full 9763record. 9764 9765This option is turned on by default when @command{tar} is reading 9766an archive from standard input, or from a remote machine. This is 9767because on @acronym{BSD} Unix systems, a read of a pipe will return however 9768much happens to be in the pipe, even if it is less than @command{tar} 9769requested. If this option was not used, @command{tar} would fail as 9770soon as it read an incomplete record from the pipe. 9771 9772This option is also useful with the commands for updating an archive. 9773 9774@end table 9775 9776Tape blocking 9777 9778@FIXME{Appropriate options should be moved here from elsewhere.} 9779 9780@cindex blocking factor 9781@cindex tape blocking 9782 9783When handling various tapes or cartridges, you have to take care of 9784selecting a proper blocking, that is, the number of disk blocks you 9785put together as a single tape block on the tape, without intervening 9786tape gaps. A @dfn{tape gap} is a small landing area on the tape 9787with no information on it, used for decelerating the tape to a 9788full stop, and for later regaining the reading or writing speed. 9789When the tape driver starts reading a record, the record has to 9790be read whole without stopping, as a tape gap is needed to stop the 9791tape motion without loosing information. 9792 9793@cindex Exabyte blocking 9794@cindex DAT blocking 9795Using higher blocking (putting more disk blocks per tape block) will use 9796the tape more efficiently as there will be less tape gaps. But reading 9797such tapes may be more difficult for the system, as more memory will be 9798required to receive at once the whole record. Further, if there is a 9799reading error on a huge record, this is less likely that the system will 9800succeed in recovering the information. So, blocking should not be too 9801low, nor it should be too high. @command{tar} uses by default a blocking of 980220 for historical reasons, and it does not really matter when reading or 9803writing to disk. Current tape technology would easily accommodate higher 9804blockings. Sun recommends a blocking of 126 for Exabytes and 96 for DATs. 9805We were told that for some DLT drives, the blocking should be a multiple 9806of 4Kb, preferably 64Kb (@w{@kbd{-b 128}}) or 256 for decent performance. 9807Other manufacturers may use different recommendations for the same tapes. 9808This might also depends of the buffering techniques used inside modern 9809tape controllers. Some imposes a minimum blocking, or a maximum blocking. 9810Others request blocking to be some exponent of two. 9811 9812So, there is no fixed rule for blocking. But blocking at read time 9813should ideally be the same as blocking used at write time. At one place 9814I know, with a wide variety of equipment, they found it best to use a 9815blocking of 32 to guarantee that their tapes are fully interchangeable. 9816 9817I was also told that, for recycled tapes, prior erasure (by the same 9818drive unit that will be used to create the archives) sometimes lowers 9819the error rates observed at rewriting time. 9820 9821I might also use @option{--number-blocks} instead of 9822@option{--block-number}, so @option{--block} will then expand to 9823@option{--blocking-factor} unambiguously. 9824 9825@node Many 9826@section Many Archives on One Tape 9827 9828@FIXME{Appropriate options should be moved here from elsewhere.} 9829 9830@findex ntape @r{device} 9831Most tape devices have two entries in the @file{/dev} directory, or 9832entries that come in pairs, which differ only in the minor number for 9833this device. Let's take for example @file{/dev/tape}, which often 9834points to the only or usual tape device of a given system. There might 9835be a corresponding @file{/dev/nrtape} or @file{/dev/ntape}. The simpler 9836name is the @emph{rewinding} version of the device, while the name 9837having @samp{nr} in it is the @emph{no rewinding} version of the same 9838device. 9839 9840A rewinding tape device will bring back the tape to its beginning point 9841automatically when this device is opened or closed. Since @command{tar} 9842opens the archive file before using it and closes it afterwards, this 9843means that a simple: 9844 9845@smallexample 9846$ @kbd{tar cf /dev/tape @var{directory}} 9847@end smallexample 9848 9849@noindent 9850will reposition the tape to its beginning both prior and after saving 9851@var{directory} contents to it, thus erasing prior tape contents and 9852making it so that any subsequent write operation will destroy what has 9853just been saved. 9854 9855@cindex tape positioning 9856So, a rewinding device is normally meant to hold one and only one file. 9857If you want to put more than one @command{tar} archive on a given tape, you 9858will need to avoid using the rewinding version of the tape device. You 9859will also have to pay special attention to tape positioning. Errors in 9860positioning may overwrite the valuable data already on your tape. Many 9861people, burnt by past experiences, will only use rewinding devices and 9862limit themselves to one file per tape, precisely to avoid the risk of 9863such errors. Be fully aware that writing at the wrong position on a 9864tape loses all information past this point and most probably until the 9865end of the tape, and this destroyed information @emph{cannot} be 9866recovered. 9867 9868To save @var{directory-1} as a first archive at the beginning of a 9869tape, and leave that tape ready for a second archive, you should use: 9870 9871@smallexample 9872$ @kbd{mt -f /dev/nrtape rewind} 9873$ @kbd{tar cf /dev/nrtape @var{directory-1}} 9874@end smallexample 9875 9876@cindex tape marks 9877@dfn{Tape marks} are special magnetic patterns written on the tape 9878media, which are later recognizable by the reading hardware. These 9879marks are used after each file, when there are many on a single tape. 9880An empty file (that is to say, two tape marks in a row) signal the 9881logical end of the tape, after which no file exist. Usually, 9882non-rewinding tape device drivers will react to the close request issued 9883by @command{tar} by first writing two tape marks after your archive, and by 9884backspacing over one of these. So, if you remove the tape at that time 9885from the tape drive, it is properly terminated. But if you write 9886another file at the current position, the second tape mark will be 9887erased by the new information, leaving only one tape mark between files. 9888 9889So, you may now save @var{directory-2} as a second archive after the 9890first on the same tape by issuing the command: 9891 9892@smallexample 9893$ @kbd{tar cf /dev/nrtape @var{directory-2}} 9894@end smallexample 9895 9896@noindent 9897and so on for all the archives you want to put on the same tape. 9898 9899Another usual case is that you do not write all the archives the same 9900day, and you need to remove and store the tape between two archive 9901sessions. In general, you must remember how many files are already 9902saved on your tape. Suppose your tape already has 16 files on it, and 9903that you are ready to write the 17th. You have to take care of skipping 9904the first 16 tape marks before saving @var{directory-17}, say, by using 9905these commands: 9906 9907@smallexample 9908$ @kbd{mt -f /dev/nrtape rewind} 9909$ @kbd{mt -f /dev/nrtape fsf 16} 9910$ @kbd{tar cf /dev/nrtape @var{directory-17}} 9911@end smallexample 9912 9913In all the previous examples, we put aside blocking considerations, but 9914you should do the proper things for that as well. @xref{Blocking}. 9915 9916@menu 9917* Tape Positioning:: Tape Positions and Tape Marks 9918* mt:: The @command{mt} Utility 9919@end menu 9920 9921@node Tape Positioning 9922@subsection Tape Positions and Tape Marks 9923@UNREVISED 9924 9925Just as archives can store more than one file from the file system, 9926tapes can store more than one archive file. To keep track of where 9927archive files (or any other type of file stored on tape) begin and 9928end, tape archive devices write magnetic @dfn{tape marks} on the 9929archive media. Tape drives write one tape mark between files, 9930two at the end of all the file entries. 9931 9932If you think of data as a series of records "rrrr"'s, and tape marks as 9933"*"'s, a tape might look like the following: 9934 9935@smallexample 9936rrrr*rrrrrr*rrrrr*rr*rrrrr**------------------------- 9937@end smallexample 9938 9939Tape devices read and write tapes using a read/write @dfn{tape 9940head}---a physical part of the device which can only access one 9941point on the tape at a time. When you use @command{tar} to read or 9942write archive data from a tape device, the device will begin reading 9943or writing from wherever on the tape the tape head happens to be, 9944regardless of which archive or what part of the archive the tape 9945head is on. Before writing an archive, you should make sure that no 9946data on the tape will be overwritten (unless it is no longer needed). 9947Before reading an archive, you should make sure the tape head is at 9948the beginning of the archive you want to read. You can do it manually 9949via @code{mt} utility (@pxref{mt}). The @code{restore} script does 9950that automatically (@pxref{Scripted Restoration}). 9951 9952If you want to add new archive file entries to a tape, you should 9953advance the tape to the end of the existing file entries, backspace 9954over the last tape mark, and write the new archive file. If you were 9955to add two archives to the example above, the tape might look like the 9956following: 9957 9958@smallexample 9959rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- 9960@end smallexample 9961 9962@node mt 9963@subsection The @command{mt} Utility 9964@UNREVISED 9965 9966@FIXME{Is it true that this only works on non-block devices? 9967should explain the difference, (fixed or variable).} 9968@xref{Blocking Factor}. 9969 9970You can use the @command{mt} utility to advance or rewind a tape past a 9971specified number of archive files on the tape. This will allow you 9972to move to the beginning of an archive before extracting or reading 9973it, or to the end of all the archives before writing a new one. 9974@FIXME{Why isn't there an "advance 'til you find two tape marks 9975together"?} 9976 9977The syntax of the @command{mt} command is: 9978 9979@smallexample 9980@kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]} 9981@end smallexample 9982 9983where @var{tapename} is the name of the tape device, @var{number} is 9984the number of times an operation is performed (with a default of one), 9985and @var{operation} is one of the following: 9986 9987@FIXME{is there any use for record operations?} 9988 9989@table @option 9990@item eof 9991@itemx weof 9992Writes @var{number} tape marks at the current position on the tape. 9993 9994@item fsf 9995Moves tape position forward @var{number} files. 9996 9997@item bsf 9998Moves tape position back @var{number} files. 9999 10000@item rewind 10001Rewinds the tape. (Ignores @var{number}). 10002 10003@item offline 10004@itemx rewoff1 10005Rewinds the tape and takes the tape device off-line. (Ignores @var{number}). 10006 10007@item status 10008Prints status information about the tape unit. 10009 10010@end table 10011 10012@FIXME{Is there a better way to frob the spacing on the list?} 10013 10014If you don't specify a @var{tapename}, @command{mt} uses the environment 10015variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use 10016the default device specified in your @file{sys/mtio.h} file 10017(@code{DEFTAPE} variable). If this is not defined, the program will 10018display a descriptive error message and exit with code 1. 10019 10020@command{mt} returns a 0 exit status when the operation(s) were 10021successful, 1 if the command was unrecognized, and 2 if an operation 10022failed. 10023 10024@node Using Multiple Tapes 10025@section Using Multiple Tapes 10026 10027Often you might want to write a large archive, one larger than will fit 10028on the actual tape you are using. In such a case, you can run multiple 10029@command{tar} commands, but this can be inconvenient, particularly if you 10030are using options like @option{--exclude=@var{pattern}} or dumping entire file systems. 10031Therefore, @command{tar} provides a special mode for creating 10032multi-volume archives. 10033 10034@dfn{Multi-volume} archive is a single @command{tar} archive, stored 10035on several media volumes of fixed size. Although in this section we will 10036often call @samp{volume} a @dfn{tape}, there is absolutely no 10037requirement for multi-volume archives to be stored on tapes. Instead, 10038they can use whatever media type the user finds convenient, they can 10039even be located on files. 10040 10041When creating a multi-volume archive, @GNUTAR{} continues to fill 10042current volume until it runs out of space, then it switches to 10043next volume (usually the operator is queried to replace the tape on 10044this point), and continues working on the new volume. This operation 10045continues until all requested files are dumped. If @GNUTAR{} detects 10046end of media while dumping a file, such a file is archived in split 10047form. Some very big files can even be split across several volumes. 10048 10049Each volume is itself a valid @GNUTAR{} archive, so it can be read 10050without any special options. Consequently any file member residing 10051entirely on one volume can be extracted or otherwise operated upon 10052without needing the other volume. Sure enough, to extract a split 10053member you would need all volumes its parts reside on. 10054 10055Multi-volume archives suffer from several limitations. In particular, 10056they cannot be compressed. 10057 10058@GNUTAR{} is able to create multi-volume archives of two formats 10059(@pxref{Formats}): @samp{GNU} and @samp{POSIX}. 10060 10061@menu 10062* Multi-Volume Archives:: Archives Longer than One Tape or Disk 10063* Tape Files:: Tape Files 10064* Tarcat:: Concatenate Volumes into a Single Archive 10065 10066@end menu 10067 10068@node Multi-Volume Archives 10069@subsection Archives Longer than One Tape or Disk 10070@cindex Multi-volume archives 10071 10072@opindex multi-volume 10073To create an archive that is larger than will fit on a single unit of 10074the media, use the @option{--multi-volume} (@option{-M}) option in conjunction with 10075the @option{--create} option (@pxref{create}). A @dfn{multi-volume} 10076archive can be manipulated like any other archive (provided the 10077@option{--multi-volume} option is specified), but is stored on more 10078than one tape or disk. 10079 10080When you specify @option{--multi-volume}, @command{tar} does not report an 10081error when it comes to the end of an archive volume (when reading), or 10082the end of the media (when writing). Instead, it prompts you to load 10083a new storage volume. If the archive is on a magnetic tape, you 10084should change tapes when you see the prompt; if the archive is on a 10085floppy disk, you should change disks; etc. 10086 10087@table @option 10088@item --multi-volume 10089@itemx -M 10090Creates a multi-volume archive, when used in conjunction with 10091@option{--create} (@option{-c}). To perform any other operation on a multi-volume 10092archive, specify @option{--multi-volume} in conjunction with that 10093operation. 10094For example: 10095 10096@smallexample 10097$ @kbd{tar --create --multi-volume --file=/dev/tape @var{files}} 10098@end smallexample 10099@end table 10100 10101The method @command{tar} uses to detect end of tape is not perfect, and 10102fails on some operating systems or on some devices. If @command{tar} 10103cannot detect the end of the tape itself, you can use 10104@option{--tape-length} option to inform it about the capacity of the 10105tape: 10106 10107@anchor{tape-length} 10108@table @option 10109@opindex tape-length 10110@item --tape-length=@var{size} 10111@itemx -L @var{size} 10112Set maximum length of a volume. The @var{size} argument should then 10113be the usable size of the tape in units of 1024 bytes. This option 10114selects @option{--multi-volume} automatically. For example: 10115 10116@smallexample 10117$ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}} 10118@end smallexample 10119@end table 10120 10121@anchor{change volume prompt} 10122When @GNUTAR{} comes to the end of a storage media, it asks you to 10123change the volume. The built-in prompt for POSIX locale 10124is@footnote{If you run @GNUTAR{} under a different locale, the 10125translation to the locale's language will be used.}: 10126 10127@smallexample 10128Prepare volume #@var{n} for `@var{archive}' and hit return: 10129@end smallexample 10130 10131@noindent 10132where @var{n} is the ordinal number of the volume to be created and 10133@var{archive} is archive file or device name. 10134 10135When prompting for a new tape, @command{tar} accepts any of the following 10136responses: 10137 10138@table @kbd 10139@item ? 10140Request @command{tar} to explain possible responses 10141@item q 10142Request @command{tar} to exit immediately. 10143@item n @var{file-name} 10144Request @command{tar} to write the next volume on the file @var{file-name}. 10145@item ! 10146Request @command{tar} to run a subshell. This option can be disabled 10147by giving @option{--restrict} command line option to 10148@command{tar}@footnote{@xref{--restrict}, for more information about 10149this option}. 10150@item y 10151Request @command{tar} to begin writing the next volume. 10152@end table 10153 10154(You should only type @samp{y} after you have changed the tape; 10155otherwise @command{tar} will write over the volume it just finished.) 10156 10157@cindex Volume number file 10158@cindex volno file 10159@anchor{volno-file} 10160@opindex volno-file 10161The volume number used by @command{tar} in its tape-changing prompt 10162can be changed; if you give the 10163@option{--volno-file=@var{file-of-number}} option, then 10164@var{file-of-number} should be an non-existing file to be created, or 10165else, a file already containing a decimal number. That number will be 10166used as the volume number of the first volume written. When 10167@command{tar} is finished, it will rewrite the file with the 10168now-current volume number. (This does not change the volume number 10169written on a tape label, as per @ref{label}, it @emph{only} affects 10170the number used in the prompt.) 10171 10172@cindex End-of-archive info script 10173@cindex Info script 10174@anchor{info-script} 10175@opindex info-script 10176@opindex new-volume-script 10177If you want more elaborate behavior than this, you can write a special 10178@dfn{new volume script}, that will be responsible for changing the 10179volume, and instruct @command{tar} to use it instead of its normal 10180prompting procedure: 10181 10182@table @option 10183@item --info-script=@var{script-name} 10184@itemx --new-volume-script=@var{script-name} 10185@itemx -F @var{script-name} 10186Specify the full name of the volume script to use. The script can be 10187used to eject cassettes, or to broadcast messages such as 10188@samp{Someone please come change my tape} when performing unattended 10189backups. 10190@end table 10191 10192The @var{script-name} is executed without any command line 10193arguments. It inherits @command{tar}'s shell environment. 10194Additional data is passed to it via the following 10195environment variables: 10196 10197@table @env 10198@vrindex TAR_VERSION, info script environment variable 10199@item TAR_VERSION 10200@GNUTAR{} version number. 10201 10202@vrindex TAR_ARCHIVE, info script environment variable 10203@item TAR_ARCHIVE 10204The name of the archive @command{tar} is processing. 10205 10206@vrindex TAR_VOLUME, info script environment variable 10207@item TAR_VOLUME 10208Ordinal number of the volume @command{tar} is about to start. 10209 10210@vrindex TAR_SUBCOMMAND, info script environment variable 10211@item TAR_SUBCOMMAND 10212Short option describing the operation @command{tar} is executing 10213@xref{Operations}, for a complete list of subcommand options. 10214 10215@vrindex TAR_FORMAT, info script environment variable 10216@item TAR_FORMAT 10217Format of the archive being processed. @xref{Formats}, for a complete 10218list of archive format names. 10219 10220@vrindex TAR_FD, info script environment variable 10221@item TAR_FD 10222File descriptor which can be used to communicate the new volume 10223name to @command{tar}. 10224@end table 10225 10226The volume script can instruct @command{tar} to use new archive name, 10227by writing in to file descriptor @env{$TAR_FD} (see below for an example). 10228 10229If the info script fails, @command{tar} exits; otherwise, it begins 10230writing the next volume. 10231 10232If you want @command{tar} to cycle through a series of files or tape 10233drives, there are three approaches to choose from. First of all, you 10234can give @command{tar} multiple @option{--file} options. In this case 10235the specified files will be used, in sequence, as the successive 10236volumes of the archive. Only when the first one in the sequence needs 10237to be used again will @command{tar} prompt for a tape change (or run 10238the info script). For example, suppose someone has two tape drives on 10239a system named @file{/dev/tape0} and @file{/dev/tape1}. For having 10240@GNUTAR{} to switch to the second drive when it needs to write the 10241second tape, and then back to the first tape, etc., just do either of: 10242 10243@smallexample 10244$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}} 10245$ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}} 10246@end smallexample 10247 10248The second method is to use the @samp{n} response to the tape-change 10249prompt. 10250 10251Finally, the most flexible approach is to use a volume script, that 10252writes new archive name to the file descriptor @env{$TAR_FD}. For example, the 10253following volume script will create a series of archive files, named 10254@file{@var{archive}-@var{vol}}, where @var{archive} is the name of the 10255archive being created (as given by @option{--file} option) and 10256@var{vol} is the ordinal number of the archive being created: 10257 10258@smallexample 10259@group 10260#! /bin/sh 10261echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE. 10262 10263name=`expr $TAR_ARCHIVE : '\(.*\)-.*'` 10264case $TAR_SUBCOMMAND in 10265-c) ;; 10266-d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1 10267 ;; 10268*) exit 1 10269esac 10270 10271echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&$TAR_FD 10272@end group 10273@end smallexample 10274 10275The same script cant be used while listing, comparing or extracting 10276from the created archive. For example: 10277 10278@smallexample 10279@group 10280# @r{Create a multi-volume archive:} 10281$ @kbd{tar -c -L1024 -f archive.tar -F new-volume .} 10282# @r{Extract from the created archive:} 10283$ @kbd{tar -x -f archive.tar -F new-volume .} 10284@end group 10285@end smallexample 10286 10287@noindent 10288Notice, that the first command had to use @option{-L} option, since 10289otherwise @GNUTAR{} will end up writing everything to file 10290@file{archive.tar}. 10291 10292You can read each individual volume of a multi-volume archive as if it 10293were an archive by itself. For example, to list the contents of one 10294volume, use @option{--list}, without @option{--multi-volume} specified. 10295To extract an archive member from one volume (assuming it is described 10296that volume), use @option{--extract}, again without 10297@option{--multi-volume}. 10298 10299If an archive member is split across volumes (i.e., its entry begins on 10300one volume of the media and ends on another), you need to specify 10301@option{--multi-volume} to extract it successfully. In this case, you 10302should load the volume where the archive member starts, and use 10303@samp{tar --extract --multi-volume}---@command{tar} will prompt for later 10304volumes as it needs them. @xref{extracting archives}, for more 10305information about extracting archives. 10306 10307Multi-volume archives can be modified like any other archive. To add 10308files to a multi-volume archive, you need to only mount the last 10309volume of the archive media (and new volumes, if needed). For all 10310other operations, you need to use the entire archive. 10311 10312If a multi-volume archive was labeled using 10313@option{--label=@var{archive-label}} (@pxref{label}) when it was 10314created, @command{tar} will not automatically label volumes which are 10315added later. To label subsequent volumes, specify 10316@option{--label=@var{archive-label}} again in conjunction with the 10317@option{--append}, @option{--update} or @option{--concatenate} operation. 10318 10319Notice that multi-volume support is a GNU extension and the archives 10320created in this mode should be read only using @GNUTAR{}. If you 10321absolutely have to process such archives using a third-party @command{tar} 10322implementation, read @ref{Split Recovery}. 10323 10324@node Tape Files 10325@subsection Tape Files 10326@UNREVISED 10327 10328To give the archive a name which will be recorded in it, use the 10329@option{--label=@var{volume-label}} (@option{-V @var{volume-label}}) 10330option. This will write a special block identifying 10331@var{volume-label} as the name of the archive to the front of the 10332archive which will be displayed when the archive is listed with 10333@option{--list}. If you are creating a multi-volume archive with 10334@option{--multi-volume} (@pxref{Using Multiple Tapes}), then the 10335volume label will have @samp{Volume @var{nnn}} appended to the name 10336you give, where @var{nnn} is the number of the volume of the archive. 10337(If you use the @option{--label=@var{volume-label}}) option when 10338reading an archive, it checks to make sure the label on the tape 10339matches the one you give. @xref{label}. 10340 10341When @command{tar} writes an archive to tape, it creates a single 10342tape file. If multiple archives are written to the same tape, one 10343after the other, they each get written as separate tape files. When 10344extracting, it is necessary to position the tape at the right place 10345before running @command{tar}. To do this, use the @command{mt} command. 10346For more information on the @command{mt} command and on the organization 10347of tapes into a sequence of tape files, see @ref{mt}. 10348 10349People seem to often do: 10350 10351@smallexample 10352@kbd{--label="@var{some-prefix} `date +@var{some-format}`"} 10353@end smallexample 10354 10355or such, for pushing a common date in all volumes or an archive set. 10356 10357@node Tarcat 10358@subsection Concatenate Volumes into a Single Archive 10359 10360@pindex tarcat 10361 Sometimes it is necessary to convert existing @GNUTAR{} multi-volume 10362archive to a single @command{tar} archive. Simply concatenating all 10363volumes into one will not work, since each volume carries an additional 10364information at the beginning. @GNUTAR{} is shipped with the shell 10365script @command{tarcat} designed for this purpose. 10366 10367 The script takes a list of files comprising a multi-volume archive 10368and creates the resulting archive at the standard output. For example: 10369 10370@smallexample 10371@kbd{tarcat vol.1 vol.2 vol.3 | tar tf -} 10372@end smallexample 10373 10374 The script implements a simple heuristics to determine the format of 10375the first volume file and to decide how to process the rest of the 10376files. However, it makes no attempt to verify whether the files are 10377given in order or even if they are valid @command{tar} archives. 10378It uses @command{dd} and does not filter its standard error, so you 10379will usually see lots of spurious messages. 10380 10381@FIXME{The script is not installed. Should we install it?} 10382 10383@node label 10384@section Including a Label in the Archive 10385@cindex Labeling an archive 10386@cindex Labels on the archive media 10387@cindex Labeling multi-volume archives 10388@UNREVISED 10389 10390@opindex label 10391 To avoid problems caused by misplaced paper labels on the archive 10392media, you can include a @dfn{label} entry---an archive member which 10393contains the name of the archive---in the archive itself. Use the 10394@option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) 10395option in conjunction with the @option{--create} operation to include 10396a label entry in the archive as it is being created. 10397 10398@table @option 10399@item --label=@var{archive-label} 10400@itemx -V @var{archive-label} 10401Includes an @dfn{archive-label} at the beginning of the archive when 10402the archive is being created, when used in conjunction with the 10403@option{--create} operation. Checks to make sure the archive label 10404matches the one specified (when used in conjunction with any other 10405operation. 10406@end table 10407 10408 If you create an archive using both 10409@option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) 10410and @option{--multi-volume} (@option{-M}), each volume of the archive 10411will have an archive label of the form @samp{@var{archive-label} 10412Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the 10413next, and so on. @xref{Using Multiple Tapes}, for information on 10414creating multiple volume archives. 10415 10416@cindex Volume label, listing 10417@cindex Listing volume label 10418 The volume label will be displayed by @option{--list} along with 10419the file contents. If verbose display is requested, it will also be 10420explicitly marked as in the example below: 10421 10422@smallexample 10423@group 10424$ @kbd{tar --verbose --list --file=iamanarchive} 10425V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header-- 10426-rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename 10427@end group 10428@end smallexample 10429 10430@opindex test-label 10431@anchor{--test-label option} 10432 However, @option{--list} option will cause listing entire 10433contents of the archive, which may be undesirable (for example, if the 10434archive is stored on a tape). You can request checking only the volume 10435by specifying @option{--test-label} option. This option reads only the 10436first block of an archive, so it can be used with slow storage 10437devices. For example: 10438 10439@smallexample 10440@group 10441$ @kbd{tar --test-label --file=iamanarchive} 10442iamalabel 10443@end group 10444@end smallexample 10445 10446 If @option{--test-label} is used with a single command line 10447argument, @command{tar} compares the volume label with the 10448argument. It exits with code 0 if the two strings match, and with code 104492 otherwise. In this case no output is displayed. For example: 10450 10451@smallexample 10452@group 10453$ @kbd{tar --test-label --file=iamanarchive 'iamalable'} 10454@result{} 0 10455$ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel} 10456@result{} 1 10457@end group 10458@end smallexample 10459 10460 If you request any operation, other than @option{--create}, along 10461with using @option{--label} option, @command{tar} will first check if 10462the archive label matches the one specified and will refuse to proceed 10463if it does not. Use this as a safety precaution to avoid accidentally 10464overwriting existing archives. For example, if you wish to add files 10465to @file{archive}, presumably labeled with string @samp{My volume}, 10466you will get: 10467 10468@smallexample 10469@group 10470$ @kbd{tar -rf archive --label 'My volume' .} 10471tar: Archive not labeled to match `My volume' 10472@end group 10473@end smallexample 10474 10475@noindent 10476in case its label does not match. This will work even if 10477@file{archive} is not labeled at all. 10478 10479 Similarly, @command{tar} will refuse to list or extract the 10480archive if its label doesn't match the @var{archive-label} 10481specified. In those cases, @var{archive-label} argument is interpreted 10482as a globbing-style pattern which must match the actual magnetic 10483volume label. @xref{exclude}, for a precise description of how match 10484is attempted@footnote{Previous versions of @command{tar} used full 10485regular expression matching, or before that, only exact string 10486matching, instead of wildcard matchers. We decided for the sake of 10487simplicity to use a uniform matching device through 10488@command{tar}.}. If the switch @option{--multi-volume} (@option{-M}) is being used, 10489the volume label matcher will also suffix @var{archive-label} by 10490@w{@samp{ Volume [1-9]*}} if the initial match fails, before giving 10491up. Since the volume numbering is automatically added in labels at 10492creation time, it sounded logical to equally help the user taking care 10493of it when the archive is being read. 10494 10495 The @option{--label} was once called @option{--volume}, but is not 10496available under that name anymore. 10497 10498 You can also use @option{--label} to get a common information on 10499all tapes of a series. For having this information different in each 10500series created through a single script used on a regular basis, just 10501manage to get some date string as part of the label. For example: 10502 10503@smallexample 10504@group 10505$ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"} 10506$ @kbd{tar --create --file=/dev/tape --multi-volume \ 10507 --volume="Daily backup for `date +%Y-%m-%d`"} 10508@end group 10509@end smallexample 10510 10511 Also note that each label has its own date and time, which corresponds 10512to when @GNUTAR{} initially attempted to write it, 10513often soon after the operator launches @command{tar} or types the 10514carriage return telling that the next tape is ready. Comparing date 10515labels does give an idea of tape throughput only if the delays for 10516rewinding tapes and the operator switching them were negligible, which 10517is usually not the case. 10518 10519@node verify 10520@section Verifying Data as It is Stored 10521@cindex Verifying a write operation 10522@cindex Double-checking a write operation 10523 10524@table @option 10525@item -W 10526@itemx --verify 10527@opindex verify, short description 10528Attempt to verify the archive after writing. 10529@end table 10530 10531This option causes @command{tar} to verify the archive after writing it. 10532Each volume is checked after it is written, and any discrepancies 10533are recorded on the standard error output. 10534 10535Verification requires that the archive be on a back-space-able medium. 10536This means pipes, some cartridge tape drives, and some other devices 10537cannot be verified. 10538 10539You can insure the accuracy of an archive by comparing files in the 10540system with archive members. @command{tar} can compare an archive to the 10541file system as the archive is being written, to verify a write 10542operation, or can compare a previously written archive, to insure that 10543it is up to date. 10544 10545@xopindex{verify, using with @option{--create}} 10546@xopindex{create, using with @option{--verify}} 10547To check for discrepancies in an archive immediately after it is 10548written, use the @option{--verify} (@option{-W}) option in conjunction with 10549the @option{--create} operation. When this option is 10550specified, @command{tar} checks archive members against their counterparts 10551in the file system, and reports discrepancies on the standard error. 10552 10553To verify an archive, you must be able to read it from before the end 10554of the last written entry. This option is useful for detecting data 10555errors on some tapes. Archives written to pipes, some cartridge tape 10556drives, and some other devices cannot be verified. 10557 10558One can explicitly compare an already made archive with the file 10559system by using the @option{--compare} (@option{--diff}, @option{-d}) 10560option, instead of using the more automatic @option{--verify} option. 10561@xref{compare}. 10562 10563Note that these two options have a slightly different intent. The 10564@option{--compare} option checks how identical are the logical contents of some 10565archive with what is on your disks, while the @option{--verify} option is 10566really for checking if the physical contents agree and if the recording 10567media itself is of dependable quality. So, for the @option{--verify} 10568operation, @command{tar} tries to defeat all in-memory cache pertaining to 10569the archive, while it lets the speed optimization undisturbed for the 10570@option{--compare} option. If you nevertheless use @option{--compare} for 10571media verification, you may have to defeat the in-memory cache yourself, 10572maybe by opening and reclosing the door latch of your recording unit, 10573forcing some doubt in your operating system about the fact this is really 10574the same volume as the one just written or read. 10575 10576The @option{--verify} option would not be necessary if drivers were indeed 10577able to detect dependably all write failures. This sometimes require many 10578magnetic heads, some able to read after the writes occurred. One would 10579not say that drivers unable to detect all cases are necessarily flawed, 10580as long as programming is concerned. 10581 10582The @option{--verify} (@option{-W}) option will not work in 10583conjunction with the @option{--multi-volume} (@option{-M}) option or 10584the @option{--append} (@option{-r}), @option{--update} (@option{-u}) 10585and @option{--delete} operations. @xref{Operations}, for more 10586information on these operations. 10587 10588Also, since @command{tar} normally strips leading @samp{/} from file 10589names (@pxref{absolute}), a command like @samp{tar --verify -cf 10590/tmp/foo.tar /etc} will work as desired only if the working directory is 10591@file{/}, as @command{tar} uses the archive's relative member names 10592(e.g., @file{etc/motd}) when verifying the archive. 10593 10594@node Write Protection 10595@section Write Protection 10596 10597Almost all tapes and diskettes, and in a few rare cases, even disks can 10598be @dfn{write protected}, to protect data on them from being changed. 10599Once an archive is written, you should write protect the media to prevent 10600the archive from being accidentally overwritten or deleted. (This will 10601protect the archive from being changed with a tape or floppy drive---it 10602will not protect it from magnet fields or other physical hazards). 10603 10604The write protection device itself is usually an integral part of the 10605physical media, and can be a two position (write enabled/write 10606disabled) switch, a notch which can be popped out or covered, a ring 10607which can be removed from the center of a tape reel, or some other 10608changeable feature. 10609 10610@node Changes 10611@appendix Changes 10612 10613This appendix lists some important user-visible changes between 10614version @GNUTAR{} @value{VERSION} and previous versions. An up-to-date 10615version of this document is available at 10616@uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the 10617@GNUTAR{} documentation page}. 10618 10619@table @asis 10620@item Use of globbing patterns when listing and extracting. 10621 10622Previous versions of GNU tar assumed shell-style globbing when 10623extracting from or listing an archive. For example: 10624 10625@smallexample 10626$ @kbd{tar xf foo.tar '*.c'} 10627@end smallexample 10628 10629would extract all files whose names end in @samp{.c}. This behavior 10630was not documented and was incompatible with traditional tar 10631implementations. Therefore, starting from version 1.15.91, GNU tar 10632no longer uses globbing by default. For example, the above invocation 10633is now interpreted as a request to extract from the archive the file 10634named @file{*.c}. 10635 10636To facilitate transition to the new behavior for those users who got 10637used to the previous incorrect one, @command{tar} will print a warning 10638if it finds out that a requested member was not found in the archive 10639and its name looks like a globbing pattern. For example: 10640 10641@smallexample 10642$ @kbd{tar xf foo.tar '*.c'} 10643tar: Pattern matching characters used in file names. Please, 10644tar: use --wildcards to enable pattern matching, or --no-wildcards to 10645tar: suppress this warning. 10646tar: *.c: Not found in archive 10647tar: Error exit delayed from previous errors 10648@end smallexample 10649 10650To treat member names as globbing patterns, use --wildcards option. 10651If you want to tar to mimic the behavior of versions prior to 1.15.91, 10652add this option to your @env{TAR_OPTIONS} variable. 10653 10654@xref{wildcards}, for the detailed discussion of the use of globbing 10655patterns by @GNUTAR{}. 10656 10657@item Use of short option @option{-o}. 10658 10659Earlier versions of @GNUTAR{} understood @option{-o} command line 10660option as a synonym for @option{--old-archive}. 10661 10662@GNUTAR{} starting from version 1.13.90 understands this option as 10663a synonym for @option{--no-same-owner}. This is compatible with 10664UNIX98 @command{tar} implementations. 10665 10666However, to facilitate transition, @option{-o} option retains its 10667old semantics when it is used with one of archive-creation commands. 10668Users are encouraged to use @option{--format=oldgnu} instead. 10669 10670It is especially important, since versions of @acronym{GNU} Automake 10671up to and including 1.8.4 invoke tar with this option to produce 10672distribution tarballs. @xref{Formats,v7}, for the detailed discussion 10673of this issue and its implications. 10674 10675@FIXME{Change the first argument to tar-formats when the new Automake is 10676out. The proposition to add @anchor{} to the appropriate place of its 10677docs was accepted by Automake people --Sergey 2006-05-25}. 10678@xref{Options, tar-v7, Changing Automake's Behavior, 10679automake, GNU Automake}, for a description on how to use various 10680archive formats with @command{automake}. 10681 10682Future versions of @GNUTAR{} will understand @option{-o} only as a 10683synonym for @option{--no-same-owner}. 10684 10685@item Use of short option @option{-l} 10686 10687Earlier versions of @GNUTAR{} understood @option{-l} option as a 10688synonym for @option{--one-file-system}. Since such usage contradicted 10689to UNIX98 specification and harmed compatibility with other 10690implementation, it was declared deprecated in version 1.14. However, 10691to facilitate transition to its new semantics, it was supported by 10692versions 1.15 and 1.15.90. The present use of @option{-l} as a short 10693variant of @option{--check-links} was introduced in version 1.15.91. 10694 10695@item Use of options @option{--portability} and @option{--old-archive} 10696 10697These options are deprecated. Please use @option{--format=v7} instead. 10698 10699@item Use of option @option{--posix} 10700 10701This option is deprecated. Please use @option{--format=posix} instead. 10702@end table 10703 10704@node Configuring Help Summary 10705@appendix Configuring Help Summary 10706 10707Running @kbd{tar --help} displays the short @command{tar} option 10708summary (@pxref{help}). This summary is organized by @dfn{groups} of 10709semantically close options. The options within each group are printed 10710in the following order: a short option, eventually followed by a list 10711of corresponding long option names, followed by a short description of 10712the option. For example, here is an excerpt from the actual @kbd{tar 10713--help} output: 10714 10715@verbatim 10716 Main operation mode: 10717 10718 -A, --catenate, --concatenate append tar files to an archive 10719 -c, --create create a new archive 10720 -d, --diff, --compare find differences between archive and 10721 file system 10722 --delete delete from the archive 10723@end verbatim 10724 10725@vrindex ARGP_HELP_FMT, environment variable 10726The exact visual representation of the help output is configurable via 10727@env{ARGP_HELP_FMT} environment variable. The value of this variable 10728is a comma-separated list of @dfn{format variable} assignments. There 10729are two kinds of format variables. An @dfn{offset variable} keeps the 10730offset of some part of help output text from the leftmost column on 10731the screen. A @dfn{boolean} variable is a flag that toggles some 10732output feature on or off. Depending on the type of the corresponding 10733variable, there are two kinds of assignments: 10734 10735@table @asis 10736@item Offset assignment 10737 10738The assignment to an offset variable has the following syntax: 10739 10740@smallexample 10741@var{variable}=@var{value} 10742@end smallexample 10743 10744@noindent 10745where @var{variable} is the variable name, and @var{value} is a 10746numeric value to be assigned to the variable. 10747 10748@item Boolean assignment 10749 10750To assign @code{true} value to a variable, simply put this variable name. To 10751assign @code{false} value, prefix the variable name with @samp{no-}. For 10752example: 10753 10754@smallexample 10755@group 10756# Assign @code{true} value: 10757dup-args 10758# Assign @code{false} value: 10759no-dup-args 10760@end group 10761@end smallexample 10762@end table 10763 10764Following variables are declared: 10765 10766@deftypevr {Help Output} boolean dup-args 10767If true, arguments for an option are shown with both short and long 10768options, even when a given option has both forms, for example: 10769 10770@smallexample 10771 -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE 10772@end smallexample 10773 10774If false, then if an option has both short and long forms, the 10775argument is only shown with the long one, for example: 10776 10777@smallexample 10778 -f, --file=ARCHIVE use archive file or device ARCHIVE 10779@end smallexample 10780 10781@noindent 10782and a message indicating that the argument is applicable to both 10783forms is printed below the options. This message can be disabled 10784using @code{dup-args-note} (see below). 10785 10786The default is false. 10787@end deftypevr 10788 10789@deftypevr {Help Output} boolean dup-args-note 10790If this variable is true, which is the default, the following notice 10791is displayed at the end of the help output: 10792 10793@quotation 10794Mandatory or optional arguments to long options are also mandatory or 10795optional for any corresponding short options. 10796@end quotation 10797 10798Setting @code{no-dup-args-note} inhibits this message. Normally, only one of 10799variables @code{dup-args} or @code{dup-args-note} should be set. 10800@end deftypevr 10801 10802@deftypevr {Help Output} offset short-opt-col 10803Column in which short options start. Default is 2. 10804 10805@smallexample 10806@group 10807$ @kbd{tar --help|grep ARCHIVE} 10808 -f, --file=ARCHIVE use archive file or device ARCHIVE 10809$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE} 10810 -f, --file=ARCHIVE use archive file or device ARCHIVE 10811@end group 10812@end smallexample 10813@end deftypevr 10814 10815@deftypevr {Help Output} offset long-opt-col 10816Column in which long options start. Default is 6. For example: 10817 10818@smallexample 10819@group 10820$ @kbd{tar --help|grep ARCHIVE} 10821 -f, --file=ARCHIVE use archive file or device ARCHIVE 10822$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE} 10823 -f, --file=ARCHIVE use archive file or device ARCHIVE 10824@end group 10825@end smallexample 10826@end deftypevr 10827 10828@deftypevr {Help Output} offset doc-opt-col 10829Column in which @dfn{doc options} start. A doc option isn't actually 10830an option, but rather an arbitrary piece of documentation that is 10831displayed in much the same manner as the options. For example, in 10832the description of @option{--format} option: 10833 10834@smallexample 10835@group 10836 -H, --format=FORMAT create archive of the given format. 10837 10838 FORMAT is one of the following: 10839 10840 gnu GNU tar 1.13.x format 10841 oldgnu GNU format as per tar <= 1.12 10842 pax POSIX 1003.1-2001 (pax) format 10843 posix same as pax 10844 ustar POSIX 1003.1-1988 (ustar) format 10845 v7 old V7 tar format 10846@end group 10847@end smallexample 10848 10849@noindent 10850the format names are doc options. Thus, if you set 10851@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output 10852will look as follows: 10853 10854@smallexample 10855@group 10856 -H, --format=FORMAT create archive of the given format. 10857 10858 FORMAT is one of the following: 10859 10860 gnu GNU tar 1.13.x format 10861 oldgnu GNU format as per tar <= 1.12 10862 pax POSIX 1003.1-2001 (pax) format 10863 posix same as pax 10864 ustar POSIX 1003.1-1988 (ustar) format 10865 v7 old V7 tar format 10866@end group 10867@end smallexample 10868@end deftypevr 10869 10870@deftypevr {Help Output} offset opt-doc-col 10871Column in which option description starts. Default is 29. 10872 10873@smallexample 10874@group 10875$ @kbd{tar --help|grep ARCHIVE} 10876 -f, --file=ARCHIVE use archive file or device ARCHIVE 10877$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE} 10878 -f, --file=ARCHIVE use archive file or device ARCHIVE 10879$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE} 10880 -f, --file=ARCHIVE 10881 use archive file or device ARCHIVE 10882@end group 10883@end smallexample 10884 10885@noindent 10886Notice, that the description starts on a separate line if 10887@code{opt-doc-col} value is too small. 10888@end deftypevr 10889 10890@deftypevr {Help Output} offset header-col 10891Column in which @dfn{group headers} are printed. A group header is a 10892descriptive text preceding an option group. For example, in the 10893following text: 10894 10895@verbatim 10896 Main operation mode: 10897 10898 -A, --catenate, --concatenate append tar files to 10899 an archive 10900 -c, --create create a new archive 10901@end verbatim 10902@noindent 10903@samp{Main operation mode:} is the group header. 10904 10905The default value is 1. 10906@end deftypevr 10907 10908@deftypevr {Help Output} offset usage-indent 10909Indentation of wrapped usage lines. Affects @option{--usage} 10910output. Default is 12. 10911@end deftypevr 10912 10913@deftypevr {Help Output} offset rmargin 10914Right margin of the text output. Used for wrapping. 10915@end deftypevr 10916 10917@node Tar Internals 10918@appendix Tar Internals 10919@include intern.texi 10920 10921@node Genfile 10922@appendix Genfile 10923@include genfile.texi 10924 10925@node Free Software Needs Free Documentation 10926@appendix Free Software Needs Free Documentation 10927@include freemanuals.texi 10928 10929@node Copying This Manual 10930@appendix Copying This Manual 10931 10932@menu 10933* GNU Free Documentation License:: License for copying this manual 10934@end menu 10935 10936@include fdl.texi 10937 10938@node Index of Command Line Options 10939@appendix Index of Command Line Options 10940 10941This appendix contains an index of all @GNUTAR{} long command line 10942options. The options are listed without the preceding double-dash. 10943For a cross-reference of short command line options, @ref{Short Option Summary}. 10944 10945@printindex op 10946 10947@node Index 10948@appendix Index 10949 10950@printindex cp 10951 10952@summarycontents 10953@contents 10954@bye 10955 10956@c Local variables: 10957@c texinfo-column-for-description: 32 10958@c End: 10959