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@defcodeindex kw 25 26@c Put everything in one index (arbitrarily chosen to be the concept index). 27@syncodeindex fn cp 28@syncodeindex ky cp 29@syncodeindex pg cp 30@syncodeindex vr cp 31@syncodeindex kw cp 32 33@copying 34 35This manual is for @acronym{GNU} @command{tar} (version 36@value{VERSION}, @value{UPDATED}), which creates and extracts files 37from archives. 38 39Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2017, 2021 40Free Software Foundation, Inc. 41 42@quotation 43Permission is granted to copy, distribute and/or modify this document 44under the terms of the GNU Free Documentation License, Version 1.3 or 45any later version published by the Free Software Foundation; with the 46Invariant Sections being ``GNU General Public License'', with the 47Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts 48as in (a) below. A copy of the license is included in the section 49entitled ``GNU Free Documentation License''. 50 51(a) The FSF's Back-Cover Text is: ``You have the freedom to 52copy and modify this GNU manual.'' 53@end quotation 54@end copying 55 56@dircategory Archiving 57@direntry 58* Tar: (tar). Making tape (or disk) archives. 59@end direntry 60 61@dircategory Individual utilities 62@direntry 63* tar: (tar)tar invocation. Invoking @GNUTAR{}. 64@end direntry 65 66@shorttitlepage @acronym{GNU} @command{tar} 67 68@titlepage 69@title @acronym{GNU} tar: an archiver tool 70@subtitle @value{RENDITION} @value{VERSION}, @value{UPDATED} 71@author John Gilmore, Jay Fenlason et al. 72 73@page 74@vskip 0pt plus 1filll 75@insertcopying 76@end titlepage 77 78@ifnottex 79@node Top 80@top @acronym{GNU} tar: an archiver tool 81 82@insertcopying 83 84@cindex file archival 85@cindex archiving files 86 87The first part of this master menu lists the major nodes in this Info 88document. The rest of the menu lists all the lower level nodes. 89@end ifnottex 90 91@c The master menu goes here. 92@c 93@c NOTE: To update it from within Emacs, make sure mastermenu.el is 94@c loaded and run texinfo-master-menu. 95@c To update it from the command line, run 96@c 97@c make master-menu 98 99@menu 100* Introduction:: 101* Tutorial:: 102* tar invocation:: 103* operations:: 104* Backups:: 105* Choosing:: 106* Date input formats:: 107* Formats:: 108* Media:: 109* Reliability and security:: 110 111Appendices 112 113* Changes:: 114* Recipes:: Frequently used tar recipes 115* Configuring Help Summary:: 116* Fixing Snapshot Files:: 117* Tar Internals:: 118* Genfile:: 119* GNU Free Documentation License:: 120* Index of Command Line Options:: 121* Index:: 122 123@detailmenu 124 --- The Detailed Node Listing --- 125 126Introduction 127 128* Book Contents:: What this Book Contains 129* Definitions:: Some Definitions 130* What tar Does:: What @command{tar} Does 131* Naming tar Archives:: How @command{tar} Archives are Named 132* Authors:: @GNUTAR{} Authors 133* Reports:: Reporting bugs or suggestions 134 135Tutorial Introduction to @command{tar} 136 137* assumptions:: 138* stylistic conventions:: 139* basic tar options:: Basic @command{tar} Operations and Options 140* frequent operations:: 141* Two Frequent Options:: 142* create:: How to Create Archives 143* list:: How to List Archives 144* extract:: How to Extract Members from an Archive 145* going further:: 146 147Two Frequently Used Options 148 149* file tutorial:: 150* verbose tutorial:: 151* help tutorial:: 152 153How to Create Archives 154 155* prepare for examples:: 156* Creating the archive:: 157* create verbose:: 158* short create:: 159* create dir:: 160 161How to List Archives 162 163* list dir:: 164 165How to Extract Members from an Archive 166 167* extracting archives:: 168* extracting files:: 169* extract dir:: 170* extracting untrusted archives:: 171* failing commands:: 172 173Invoking @GNUTAR{} 174 175* Synopsis:: 176* using tar options:: 177* Styles:: 178* All Options:: 179* help:: 180* defaults:: 181* verbose:: 182* checkpoints:: 183* warnings:: 184* interactive:: 185 186The Three Option Styles 187 188* Long Options:: Long Option Style 189* Short Options:: Short Option Style 190* Old Options:: Old Option Style 191* Mixing:: Mixing Option Styles 192 193All @command{tar} Options 194 195* Operation Summary:: 196* Option Summary:: 197* Short Option Summary:: 198* Position-Sensitive Options:: 199 200@GNUTAR{} Operations 201 202* Basic tar:: 203* Advanced tar:: 204* create options:: 205* extract options:: 206* backup:: 207* looking ahead:: 208 209Advanced @GNUTAR{} Operations 210 211* Operations:: 212* append:: 213* update:: 214* concatenate:: 215* delete:: 216* compare:: 217 218How to Add Files to Existing Archives: @option{--append} 219 220* appending files:: Appending Files to an Archive 221* multiple:: 222 223Updating an Archive 224 225* how to update:: 226 227Options Used by @option{--create} 228 229* override:: Overriding File Metadata. 230* Extended File Attributes:: 231* Ignore Failed Read:: 232 233Options Used by @option{--extract} 234 235* Reading:: Options to Help Read Archives 236* Writing:: Changing How @command{tar} Writes Files 237* Scarce:: Coping with Scarce Resources 238 239Options to Help Read Archives 240 241* read full records:: 242* Ignore Zeros:: 243 244Changing How @command{tar} Writes Files 245 246* Dealing with Old Files:: 247* Overwrite Old Files:: 248* Keep Old Files:: 249* Keep Newer Files:: 250* Unlink First:: 251* Recursive Unlink:: 252* Data Modification Times:: 253* Setting Access Permissions:: 254* Directory Modification Times and Permissions:: 255* Writing to Standard Output:: 256* Writing to an External Program:: 257* remove files:: 258 259Coping with Scarce Resources 260 261* Starting File:: 262* Same Order:: 263 264Performing Backups and Restoring Files 265 266* Full Dumps:: Using @command{tar} to Perform Full Dumps 267* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps 268* Backup Levels:: Levels of Backups 269* Backup Parameters:: Setting Parameters for Backups and Restoration 270* Scripted Backups:: Using the Backup Scripts 271* Scripted Restoration:: Using the Restore Script 272 273Setting Parameters for Backups and Restoration 274 275* General-Purpose Variables:: 276* Magnetic Tape Control:: 277* User Hooks:: 278* backup-specs example:: An Example Text of @file{Backup-specs} 279 280Choosing Files and Names for @command{tar} 281 282* file:: Choosing the Archive's Name 283* Selecting Archive Members:: 284* files:: Reading Names from a File 285* exclude:: Excluding Some Files 286* wildcards:: Wildcards Patterns and Matching 287* quoting styles:: Ways of Quoting Special Characters in Names 288* transform:: Modifying File and Member Names 289* after:: Operating Only on New Files 290* recurse:: Descending into Directories 291* one:: Crossing File System Boundaries 292 293Reading Names from a File 294 295* nul:: 296 297Excluding Some Files 298 299* problems with exclude:: 300 301Wildcards Patterns and Matching 302 303* controlling pattern-matching:: 304 305Crossing File System Boundaries 306 307* directory:: Changing Directory 308* absolute:: Absolute File Names 309 310Date input formats 311 312* General date syntax:: Common rules. 313* Calendar date items:: 19 Dec 1994. 314* Time of day items:: 9:20pm. 315* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}. 316* Day of week items:: Monday and others. 317* Relative items in date strings:: next tuesday, 2 years ago. 318* Pure numbers in date strings:: 19931219, 1440. 319* Seconds since the Epoch:: @@1078100502. 320* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". 321* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al. 322 323Controlling the Archive Format 324 325* Compression:: Using Less Space through Compression 326* Attributes:: Handling File Attributes 327* Portability:: Making @command{tar} Archives More Portable 328* cpio:: Comparison of @command{tar} and @command{cpio} 329 330Using Less Space through Compression 331 332* gzip:: Creating and Reading Compressed Archives 333* sparse:: Archiving Sparse Files 334 335Creating and Reading Compressed Archives 336 337* lbzip2:: Using lbzip2 with @GNUTAR{}. 338 339Making @command{tar} Archives More Portable 340 341* Portable Names:: Portable Names 342* dereference:: Symbolic Links 343* hard links:: Hard Links 344* old:: Old V7 Archives 345* ustar:: Ustar Archives 346* gnu:: GNU and old GNU format archives. 347* posix:: @acronym{POSIX} archives 348* Checksumming:: Checksumming Problems 349* Large or Negative Values:: Large files, negative time stamps, etc. 350* Other Tars:: How to Extract GNU-Specific Data Using 351 Other @command{tar} Implementations 352 353@GNUTAR{} and @acronym{POSIX} @command{tar} 354 355* PAX keywords:: Controlling Extended Header Keywords. 356 357How to Extract GNU-Specific Data Using Other @command{tar} Implementations 358 359* Split Recovery:: Members Split Between Volumes 360* Sparse Recovery:: Sparse Members 361 362Tapes and Other Archive Media 363 364* Device:: Device selection and switching 365* Remote Tape Server:: 366* Common Problems and Solutions:: 367* Blocking:: Blocking 368* Many:: Many archives on one tape 369* Using Multiple Tapes:: Using Multiple Tapes 370* label:: Including a Label in the Archive 371* verify:: 372* Write Protection:: 373 374Blocking 375 376* Format Variations:: Format Variations 377* Blocking Factor:: The Blocking Factor of an Archive 378 379Many Archives on One Tape 380 381* Tape Positioning:: Tape Positions and Tape Marks 382* mt:: The @command{mt} Utility 383 384Using Multiple Tapes 385 386* Multi-Volume Archives:: Archives Longer than One Tape or Disk 387* Tape Files:: Tape Files 388* Tarcat:: Concatenate Volumes into a Single Archive 389 390 391Tar Internals 392 393* Standard:: Basic Tar Format 394* Extensions:: @acronym{GNU} Extensions to the Archive Format 395* Sparse Formats:: Storing Sparse Files 396* Snapshot Files:: 397* Dumpdir:: 398 399Storing Sparse Files 400 401* Old GNU Format:: 402* PAX 0:: PAX Format, Versions 0.0 and 0.1 403* PAX 1:: PAX Format, Version 1.0 404 405Genfile 406 407* Generate Mode:: File Generation Mode. 408* Status Mode:: File Status Mode. 409* Exec Mode:: Synchronous Execution mode. 410 411Copying This Manual 412 413* GNU Free Documentation License:: License for copying this manual 414 415@end detailmenu 416@end menu 417 418@node Introduction 419@chapter Introduction 420 421@GNUTAR{} creates 422and manipulates @dfn{archives} which are actually collections of 423many other files; the program provides users with an organized and 424systematic method for controlling a large amount of data. 425The name ``tar'' originally came from the phrase ``Tape ARchive'', but 426archives need not (and these days, typically do not) reside on tapes. 427 428@menu 429* Book Contents:: What this Book Contains 430* Definitions:: Some Definitions 431* What tar Does:: What @command{tar} Does 432* Naming tar Archives:: How @command{tar} Archives are Named 433* Authors:: @GNUTAR{} Authors 434* Reports:: Reporting bugs or suggestions 435@end menu 436 437@node Book Contents 438@section What this Book Contains 439 440The first part of this chapter introduces you to various terms that will 441recur throughout the book. It also tells you who has worked on @GNUTAR{} 442and its documentation, and where you should send bug reports 443or comments. 444 445The second chapter is a tutorial (@pxref{Tutorial}) which provides a 446gentle introduction for people who are new to using @command{tar}. It is 447meant to be self-contained, not requiring any reading from subsequent 448chapters to make sense. It moves from topic to topic in a logical, 449progressive order, building on information already explained. 450 451Although the tutorial is paced and structured to allow beginners to 452learn how to use @command{tar}, it is not intended solely for beginners. 453The tutorial explains how to use the three most frequently used 454operations (@samp{create}, @samp{list}, and @samp{extract}) as well as 455two frequently used options (@samp{file} and @samp{verbose}). The other 456chapters do not refer to the tutorial frequently; however, if a section 457discusses something which is a complex variant of a basic concept, there 458may be a cross-reference to that basic concept. (The entire book, 459including the tutorial, assumes that the reader understands some basic 460concepts of using a Unix-type operating system; @pxref{Tutorial}.) 461 462The third chapter presents the remaining five operations, and 463information about using @command{tar} options and option syntax. 464 465The other chapters are meant to be used as a reference. Each chapter 466presents everything that needs to be said about a specific topic. 467 468One of the chapters (@pxref{Date input formats}) exists in its 469entirety in other @acronym{GNU} manuals, and is mostly self-contained. 470In addition, one section of this manual (@pxref{Standard}) contains a 471big quote which is taken directly from @command{tar} sources. 472 473In general, we give both long and short (abbreviated) option names 474at least once in each section where the relevant option is covered, so 475that novice readers will become familiar with both styles. (A few 476options have no short versions, and the relevant sections will 477indicate this.) 478 479@node Definitions 480@section Some Definitions 481 482@cindex archive 483@cindex tar archive 484The @command{tar} program is used to create and manipulate @command{tar} 485archives. An @dfn{archive} is a single file which contains the contents 486of many files, while still identifying the names of the files, their 487owner(s), and so forth. (In addition, archives record access 488permissions, user and group, size in bytes, and data modification time. 489Some archives also record the file names in each archived directory, as 490well as other file and directory information.) You can use @command{tar} 491to @dfn{create} a new archive in a specified directory. 492 493@cindex member 494@cindex archive member 495@cindex file name 496@cindex member name 497The files inside an archive are called @dfn{members}. Within this 498manual, we use the term @dfn{file} to refer only to files accessible in 499the normal ways (by @command{ls}, @command{cat}, and so forth), and the term 500@dfn{member} to refer only to the members of an archive. Similarly, a 501@dfn{file name} is the name of a file, as it resides in the file system, 502and a @dfn{member name} is the name of an archive member within the 503archive. 504 505@cindex extraction 506@cindex unpacking 507The term @dfn{extraction} refers to the process of copying an archive 508member (or multiple members) into a file in the file system. Extracting 509all the members of an archive is often called @dfn{extracting the 510archive}. The term @dfn{unpack} can also be used to refer to the 511extraction of many or all the members of an archive. Extracting an 512archive does not destroy the archive's structure, just as creating an 513archive does not destroy the copies of the files that exist outside of 514the archive. You may also @dfn{list} the members in a given archive 515(this is often thought of as ``printing'' them to the standard output, 516or the command line), or @dfn{append} members to a pre-existing archive. 517All of these operations can be performed using @command{tar}. 518 519@node What tar Does 520@section What @command{tar} Does 521 522@cindex tar 523The @command{tar} program provides the ability to create @command{tar} 524archives, as well as various other kinds of manipulation. For example, 525you can use @command{tar} on previously created archives to extract files, 526to store additional files, or to update or list files which were already 527stored. 528 529Initially, @command{tar} archives were used to store files conveniently on 530magnetic tape. The name @command{tar} comes from this use; it stands for 531@code{t}ape @code{ar}chiver. Despite the utility's name, @command{tar} can 532direct its output to available devices, files, or other programs (using 533pipes). @command{tar} may even access remote devices or files (as archives). 534 535You can use @command{tar} archives in many ways. We want to stress a few 536of them: storage, backup, and transportation. 537 538@FIXME{the following table entries need a bit of work.} 539@table @asis 540@item Storage 541Often, @command{tar} archives are used to store related files for 542convenient file transfer over a network. For example, the 543@acronym{GNU} Project distributes its software bundled into 544@command{tar} archives, so that all the files relating to a particular 545program (or set of related programs) can be transferred as a single 546unit. 547 548A magnetic tape can store several files in sequence. However, the tape 549has no names for these files; it only knows their relative position on 550the tape. One way to store several files on one tape and retain their 551names is by creating a @command{tar} archive. Even when the basic transfer 552mechanism can keep track of names, as FTP can, the nuisance of handling 553multiple files, directories, and multiple links makes @command{tar} 554archives useful. 555 556Archive files are also used for long-term storage. You can think of 557this as transportation from the present into the future. (It is a 558science-fiction idiom that you can move through time as well as in 559space; the idea here is that @command{tar} can be used to move archives in 560all dimensions, even time!) 561 562@item Backup 563Because the archive created by @command{tar} is capable of preserving 564file information and directory structure, @command{tar} is commonly 565used for performing full and incremental backups of disks. A backup 566puts a collection of files (possibly pertaining to many users and 567projects) together on a disk or a tape. This guards against 568accidental destruction of the information in those files. 569@GNUTAR{} has special features that allow it to be 570used to make incremental and full dumps of all the files in a 571file system. 572 573@item Transportation 574You can create an archive on one system, transfer it to another system, 575and extract the contents there. This allows you to transport a group of 576files from one system to another. 577@end table 578 579@node Naming tar Archives 580@section How @command{tar} Archives are Named 581 582Conventionally, @command{tar} archives are given names ending with 583@samp{.tar}. This is not necessary for @command{tar} to operate properly, 584but this manual follows that convention in order to accustom readers to 585it and to make examples more clear. 586 587@cindex tar file 588@cindex entry 589@cindex tar entry 590Often, people refer to @command{tar} archives as ``@command{tar} files,'' and 591archive members as ``files'' or ``entries''. For people familiar with 592the operation of @command{tar}, this causes no difficulty. However, in 593this manual, we consistently refer to ``archives'' and ``archive 594members'' to make learning to use @command{tar} easier for novice users. 595 596@node Authors 597@section @GNUTAR{} Authors 598 599@GNUTAR{} was originally written by John Gilmore, 600and modified by many people. The @acronym{GNU} enhancements were 601written by Jay Fenlason, then Joy Kendall, and the whole package has 602been further maintained by Thomas Bushnell, n/BSG, Fran@,{c}ois 603Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of 604numerous and kind users. 605 606We wish to stress that @command{tar} is a collective work, and owes much to 607all those people who reported problems, offered solutions and other 608insights, or shared their thoughts and suggestions. An impressive, yet 609partial list of those contributors can be found in the @file{THANKS} 610file from the @GNUTAR{} distribution. 611 612@FIXME{i want all of these names mentioned, Absolutely. BUT, i'm not 613sure i want to spell out the history in this detail, at least not for 614the printed book. i'm just not sure it needs to be said this way. 615i'll think about it.} 616 617@FIXME{History is more important, and surely more interesting, than 618actual names. Quoting names without history would be meaningless. FP} 619 620Jay Fenlason put together a draft of a @GNUTAR{} 621manual, borrowing notes from the original man page from John Gilmore. 622This was withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy 623Gorin worked on a tutorial and manual for @GNUTAR{}. 624Fran@,{c}ois Pinard put version 1.11.8 of the manual together by 625taking information from all these sources and merging them. Melissa 626Weisshaus finally edited and redesigned the book to create version 6271.12. The book for versions from 1.14 up to @value{VERSION} were edited 628by the current maintainer, Sergey Poznyakoff. 629 630For version 1.12, Daniel Hagerty contributed a great deal of technical 631consulting. In particular, he is the primary author of @ref{Backups}. 632 633In July, 2003 @GNUTAR{} was put on CVS at savannah.gnu.org 634(see @url{http://savannah.gnu.org/projects/tar}), and 635active development and maintenance work has started 636again. Currently @GNUTAR{} is being maintained by Paul Eggert, Sergey 637Poznyakoff and Jeff Bailey. 638 639Support for @acronym{POSIX} archives was added by Sergey Poznyakoff. 640 641@node Reports 642@section Reporting bugs or suggestions 643 644@cindex bug reports 645@cindex reporting bugs 646If you find problems or have suggestions about this program or manual, 647please report them to @file{bug-tar@@gnu.org}. 648 649When reporting a bug, please be sure to include as much detail as 650possible, in order to reproduce it. 651@FIXME{Be more specific, I'd like to make this node as detailed as 652'Bug reporting' node in Emacs manual.} 653 654@node Tutorial 655@chapter Tutorial Introduction to @command{tar} 656 657This chapter guides you through some basic examples of three @command{tar} 658operations: @option{--create}, @option{--list}, and @option{--extract}. If 659you already know how to use some other version of @command{tar}, then you 660may not need to read this chapter. This chapter omits most complicated 661details about how @command{tar} works. 662 663@menu 664* assumptions:: 665* stylistic conventions:: 666* basic tar options:: Basic @command{tar} Operations and Options 667* frequent operations:: 668* Two Frequent Options:: 669* create:: How to Create Archives 670* list:: How to List Archives 671* extract:: How to Extract Members from an Archive 672* going further:: 673@end menu 674 675@node assumptions 676@section Assumptions this Tutorial Makes 677 678This chapter is paced to allow beginners to learn about @command{tar} 679slowly. At the same time, we will try to cover all the basic aspects of 680these three operations. In order to accomplish both of these tasks, we 681have made certain assumptions about your knowledge before reading this 682manual, and the hardware you will be using: 683 684@itemize @bullet 685@item 686Before you start to work through this tutorial, you should understand 687what the terms ``archive'' and ``archive member'' mean 688(@pxref{Definitions}). In addition, you should understand something 689about how Unix-type operating systems work, and you should know how to 690use some basic utilities. For example, you should know how to create, 691list, copy, rename, edit, and delete files and directories; how to 692change between directories; and how to figure out where you are in the 693file system. You should have some basic understanding of directory 694structure and how files are named according to which directory they are 695in. You should understand concepts such as standard output and standard 696input, what various definitions of the term @samp{argument} mean, and the 697differences between relative and absolute file names. 698@FIXME{and what else?} 699 700@item 701This manual assumes that you are working from your own home directory 702(unless we state otherwise). In this tutorial, you will create a 703directory to practice @command{tar} commands in. When we show file names, 704we will assume that those names are relative to your home directory. 705For example, my home directory is @file{/home/fsf/melissa}. All of 706my examples are in a subdirectory of the directory named by that file 707name; the subdirectory is called @file{practice}. 708 709@item 710In general, we show examples of archives which exist on (or can be 711written to, or worked with from) a directory on a hard disk. In most 712cases, you could write those archives to, or work with them on any other 713device, such as a tape drive. However, some of the later examples in 714the tutorial and next chapter will not work on tape drives. 715Additionally, working with tapes is much more complicated than working 716with hard disks. For these reasons, the tutorial does not cover working 717with tape drives. @xref{Media}, for complete information on using 718@command{tar} archives with tape drives. 719 720@FIXME{this is a cop out. need to add some simple tape drive info.} 721@end itemize 722 723@node stylistic conventions 724@section Stylistic Conventions 725 726In the examples, @samp{$} represents a typical shell prompt. It 727precedes lines you should type; to make this more clear, those lines are 728shown in @kbd{this font}, as opposed to lines which represent the 729computer's response; those lines are shown in @code{this font}, or 730sometimes @samp{like this}. 731 732@c When we have lines which are too long to be 733@c displayed in any other way, we will show them like this: 734 735@node basic tar options 736@section Basic @command{tar} Operations and Options 737 738@command{tar} can take a wide variety of arguments which specify and define 739the actions it will have on the particular set of files or the archive. 740The main types of arguments to @command{tar} fall into one of two classes: 741operations, and options. 742 743Some arguments fall into a class called @dfn{operations}; exactly one of 744these is both allowed and required for any instance of using @command{tar}; 745you may @emph{not} specify more than one. People sometimes speak of 746@dfn{operating modes}. You are in a particular operating mode when you 747have specified the operation which specifies it; there are eight 748operations in total, and thus there are eight operating modes. 749 750The other arguments fall into the class known as @dfn{options}. You are 751not required to specify any options, and you are allowed to specify more 752than one at a time (depending on the way you are using @command{tar} at 753that time). Some options are used so frequently, and are so useful for 754helping you type commands more carefully that they are effectively 755``required''. We will discuss them in this chapter. 756 757You can write most of the @command{tar} operations and options in any 758of three forms: long (mnemonic) form, short form, and old style. Some 759of the operations and options have no short or ``old'' forms; however, 760the operations and options which we will cover in this tutorial have 761corresponding abbreviations. We will indicate those abbreviations 762appropriately to get you used to seeing them. Note, that the ``old 763style'' option forms exist in @GNUTAR{} for compatibility with Unix 764@command{tar}. In this book we present a full discussion of this way 765of writing options and operations (@pxref{Old Options}), and we discuss 766the other two styles of writing options (@xref{Long Options}, and 767@pxref{Short Options}). 768 769In the examples and in the text of this tutorial, we usually use the 770long forms of operations and options; but the ``short'' forms produce 771the same result and can make typing long @command{tar} commands easier. 772For example, instead of typing 773 774@smallexample 775@kbd{tar --create --verbose --file=afiles.tar apple angst aspic} 776@end smallexample 777 778@noindent 779you can type 780@smallexample 781@kbd{tar -c -v -f afiles.tar apple angst aspic} 782@end smallexample 783 784@noindent 785or even 786@smallexample 787@kbd{tar -cvf afiles.tar apple angst aspic} 788@end smallexample 789 790@noindent 791For more information on option syntax, see @ref{Advanced tar}. In 792discussions in the text, when we name an option by its long form, we 793also give the corresponding short option in parentheses. 794 795The term, ``option'', can be confusing at times, since ``operations'' 796are often lumped in with the actual, @emph{optional} ``options'' in certain 797general class statements. For example, we just talked about ``short and 798long forms of options and operations''. However, experienced @command{tar} 799users often refer to these by shorthand terms such as, ``short and long 800options''. This term assumes that the ``operations'' are included, also. 801Context will help you determine which definition of ``options'' to use. 802 803Similarly, the term ``command'' can be confusing, as it is often used in 804two different ways. People sometimes refer to @command{tar} ``commands''. 805A @command{tar} @dfn{command} is the entire command line of user input 806which tells @command{tar} what to do --- including the operation, options, 807and any arguments (file names, pipes, other commands, etc.). However, 808you will also sometimes hear the term ``the @command{tar} command''. When 809the word ``command'' is used specifically like this, a person is usually 810referring to the @command{tar} @emph{operation}, not the whole line. 811Again, use context to figure out which of the meanings the speaker 812intends. 813 814@node frequent operations 815@section The Three Most Frequently Used Operations 816 817Here are the three most frequently used operations (both short and long 818forms), as well as a brief description of their meanings. The rest of 819this chapter will cover how to use these operations in detail. We will 820present the rest of the operations in the next chapter. 821 822@table @option 823@item --create 824@itemx -c 825Create a new @command{tar} archive. 826@item --list 827@itemx -t 828List the contents of an archive. 829@item --extract 830@itemx -x 831Extract one or more members from an archive. 832@end table 833 834@node Two Frequent Options 835@section Two Frequently Used Options 836 837To understand how to run @command{tar} in the three operating modes listed 838previously, you also need to understand how to use two of the options to 839@command{tar}: @option{--file} (which takes an archive file as an argument) 840and @option{--verbose}. (You are usually not @emph{required} to specify 841either of these options when you run @command{tar}, but they can be very 842useful in making things more clear and helping you avoid errors.) 843 844@menu 845* file tutorial:: 846* verbose tutorial:: 847* help tutorial:: 848@end menu 849 850@node file tutorial 851@unnumberedsubsec The @option{--file} Option 852 853@table @option 854@xopindex{file, tutorial} 855@item --file=@var{archive-name} 856@itemx -f @var{archive-name} 857Specify the name of an archive file. 858@end table 859 860You can specify an argument for the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option whenever you 861use @command{tar}; this option determines the name of the archive file 862that @command{tar} will work on. 863 864@vrindex TAPE 865If you don't specify this argument, then @command{tar} will examine 866the environment variable @env{TAPE}. If it is set, its value will be 867used as the archive name. Otherwise, @command{tar} will use the 868default archive, determined at compile time. Usually it is 869standard output or some physical tape drive attached to your machine 870(you can verify what the default is by running @kbd{tar 871--show-defaults}, @pxref{defaults}). If there is no tape drive 872attached, or the default is not meaningful, then @command{tar} will 873print an error message. The error message might look roughly like one 874of the following: 875 876@smallexample 877tar: can't open /dev/rmt8 : No such device or address 878tar: can't open /dev/rsmt0 : I/O error 879@end smallexample 880 881@noindent 882To avoid confusion, we recommend that you always specify an archive file 883name by using @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) when writing your @command{tar} commands. 884For more information on using the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option, see 885@ref{file}. 886 887@node verbose tutorial 888@unnumberedsubsec The @option{--verbose} Option 889 890@table @option 891@xopindex{verbose, introduced} 892@item --verbose 893@itemx -v 894Show the files being worked on as @command{tar} is running. 895@end table 896 897@option{--verbose} (@option{-v}) shows details about the results of running 898@command{tar}. This can be especially useful when the results might not be 899obvious. For example, if you want to see the progress of @command{tar} as 900it writes files into the archive, you can use the @option{--verbose} 901option. In the beginning, you may find it useful to use 902@option{--verbose} at all times; when you are more accustomed to 903@command{tar}, you will likely want to use it at certain times but not at 904others. We will use @option{--verbose} at times to help make something 905clear, and we will give many examples both using and not using 906@option{--verbose} to show the differences. 907 908Each instance of @option{--verbose} on the command line increases the 909verbosity level by one, so if you need more details on the output, 910specify it twice. 911 912When reading archives (@option{--list}, @option{--extract}, 913@option{--diff}), @command{tar} by default prints only the names of 914the members being extracted. Using @option{--verbose} will show a full, 915@command{ls} style member listing. 916 917In contrast, when writing archives (@option{--create}, @option{--append}, 918@option{--update}), @command{tar} does not print file names by 919default. So, a single @option{--verbose} option shows the file names 920being added to the archive, while two @option{--verbose} options 921enable the full listing. 922 923For example, to create an archive in verbose mode: 924 925@smallexample 926$ @kbd{tar -cvf afiles.tar apple angst aspic} 927apple 928angst 929aspic 930@end smallexample 931 932@noindent 933Creating the same archive with the verbosity level 2 could give: 934 935@smallexample 936$ @kbd{tar -cvvf afiles.tar apple angst aspic} 937-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple 938-rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst 939-rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic 940@end smallexample 941 942@noindent 943This works equally well using short or long forms of options. Using 944long forms, you would simply write out the mnemonic form of the option 945twice, like this: 946 947@smallexample 948$ @kbd{tar --create --verbose --verbose @dots{}} 949@end smallexample 950 951@noindent 952Note that you must double the hyphens properly each time. 953 954Later in the tutorial, we will give examples using @w{@option{--verbose 955--verbose}}. 956 957@anchor{verbose member listing} 958The full output consists of six fields: 959 960@itemize @bullet 961@item File type and permissions in symbolic form. 962These are displayed in the same format as the first column of 963@command{ls -l} output (@pxref{What information is listed, 964format=verbose, Verbose listing, fileutils, GNU file utilities}). 965 966@item Owner name and group separated by a slash character. 967If these data are not available (for example, when listing a @samp{v7} format 968archive), numeric @acronym{ID} values are printed instead. 969 970@item Size of the file, in bytes. 971 972@item File modification date in ISO 8601 format. 973 974@item File modification time. 975 976@item File name. 977If the name contains any special characters (white space, newlines, 978etc.)@: these are displayed in an unambiguous form using so called 979@dfn{quoting style}. For the detailed discussion of available styles 980and on how to use them, see @ref{quoting styles}. 981 982Depending on the file type, the name can be followed by some 983additional information, described in the following table: 984 985@table @samp 986@item -> @var{link-name} 987The file or archive member is a @dfn{symbolic link} and 988@var{link-name} is the name of file it links to. 989 990@item link to @var{link-name} 991The file or archive member is a @dfn{hard link} and @var{link-name} is 992the name of file it links to. 993 994@item --Long Link-- 995The archive member is an old GNU format long link. You will normally 996not encounter this. 997 998@item --Long Name-- 999The archive member is an old GNU format long name. You will normally 1000not encounter this. 1001 1002@item --Volume Header-- 1003The archive member is a GNU @dfn{volume header} (@pxref{Tape Files}). 1004 1005@item --Continued at byte @var{n}-- 1006Encountered only at the beginning of a multi-volume archive 1007(@pxref{Using Multiple Tapes}). This archive member is a continuation 1008from the previous volume. The number @var{n} gives the offset where 1009the original file was split. 1010 1011@item unknown file type @var{c} 1012An archive member of unknown type. @var{c} is the type character from 1013the archive header. If you encounter such a message, it means that 1014either your archive contains proprietary member types @GNUTAR{} is not 1015able to handle, or the archive is corrupted. 1016@end table 1017 1018@end itemize 1019 1020For example, here is an archive listing containing most of the special 1021suffixes explained above: 1022 1023@smallexample 1024@group 1025V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header-- 1026-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456-- 1027-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple 1028lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple 1029-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues 1030hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues 1031@end group 1032@end smallexample 1033 1034@smallexample 1035@end smallexample 1036 1037@node help tutorial 1038@unnumberedsubsec Getting Help: Using the @option{--help} Option 1039 1040@table @option 1041@opindex help 1042@item --help 1043 1044The @option{--help} option to @command{tar} prints out a very brief list of 1045all operations and option available for the current version of 1046@command{tar} available on your system. 1047@end table 1048 1049@node create 1050@section How to Create Archives 1051 1052@cindex Creation of the archive 1053@cindex Archive, creation of 1054One of the basic operations of @command{tar} is @option{--create} (@option{-c}), which 1055you use to create a @command{tar} archive. We will explain 1056@option{--create} first because, in order to learn about the other 1057operations, you will find it useful to have an archive available to 1058practice on. 1059 1060To make this easier, in this section you will first create a directory 1061containing three files. Then, we will show you how to create an 1062@emph{archive} (inside the new directory). Both the directory, and 1063the archive are specifically for you to practice on. The rest of this 1064chapter and the next chapter will show many examples using this 1065directory and the files you will create: some of those files may be 1066other directories and other archives. 1067 1068The three files you will archive in this example are called 1069@file{blues}, @file{folk}, and @file{jazz}. The archive is called 1070@file{collection.tar}. 1071 1072This section will proceed slowly, detailing how to use @option{--create} 1073in @code{verbose} mode, and showing examples using both short and long 1074forms. In the rest of the tutorial, and in the examples in the next 1075chapter, we will proceed at a slightly quicker pace. This section 1076moves more slowly to allow beginning users to understand how 1077@command{tar} works. 1078 1079@menu 1080* prepare for examples:: 1081* Creating the archive:: 1082* create verbose:: 1083* short create:: 1084* create dir:: 1085@end menu 1086 1087@node prepare for examples 1088@subsection Preparing a Practice Directory for Examples 1089 1090To follow along with this and future examples, create a new directory 1091called @file{practice} containing files called @file{blues}, @file{folk} 1092and @file{jazz}. The files can contain any information you like: 1093ideally, they should contain information which relates to their names, 1094and be of different lengths. Our examples assume that @file{practice} 1095is a subdirectory of your home directory. 1096 1097Now @command{cd} to the directory named @file{practice}; @file{practice} 1098is now your @dfn{working directory}. (@emph{Please note}: Although 1099the full file name of this directory is 1100@file{/@var{homedir}/practice}, in our examples we will refer to 1101this directory as @file{practice}; the @var{homedir} is presumed.) 1102 1103In general, you should check that the files to be archived exist where 1104you think they do (in the working directory) by running @command{ls}. 1105Because you just created the directory and the files and have changed to 1106that directory, you probably don't need to do that this time. 1107 1108It is very important to make sure there isn't already a file in the 1109working directory with the archive name you intend to use (in this case, 1110@samp{collection.tar}), or that you don't care about its contents. 1111Whenever you use @samp{create}, @command{tar} will erase the current 1112contents of the file named by @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) if it exists. @command{tar} 1113will not tell you if you are about to overwrite an archive unless you 1114specify an option which does this (@pxref{backup}, for the 1115information on how to do so). To add files to an existing archive, 1116you need to use a different option, such as @option{--append} (@option{-r}); see 1117@ref{append} for information on how to do this. 1118 1119@node Creating the archive 1120@subsection Creating the Archive 1121 1122@xopindex{create, introduced} 1123To place the files @file{blues}, @file{folk}, and @file{jazz} into an 1124archive named @file{collection.tar}, use the following command: 1125 1126@smallexample 1127$ @kbd{tar --create --file=collection.tar blues folk jazz} 1128@end smallexample 1129 1130The order of the arguments is not very important, @emph{when using long 1131option forms}, however you should always remember to use option as the 1132first argument to tar. For example, the following is wrong: 1133 1134@smallexample 1135$ @kbd{tar blues -c folk -f collection.tar jazz} 1136tar: -c: Invalid blocking factor 1137Try 'tar --help' or 'tar --usage' for more information. 1138@end smallexample 1139 1140The error message is produced because @command{tar} always treats its 1141first argument as an option (or cluster of options), even if it does 1142not start with dash. This is @dfn{traditional} or @dfn{old option} 1143style, called so because all implementations of @command{tar} have 1144used it since the very inception of the tar archiver in 1970s. This 1145option style will be explained later (@pxref{Old Options}), for now 1146just remember to always place option as the first argument. 1147 1148That being said, you could issue the following command: 1149 1150@smallexample 1151$ @kbd{tar --create folk blues --file=collection.tar jazz} 1152@end smallexample 1153 1154@noindent 1155However, you can see that this order is harder to understand; this is 1156why we will list the arguments in the order that makes the commands 1157easiest to understand (and we encourage you to do the same when you use 1158@command{tar}, to avoid errors). 1159 1160Note that the sequence 1161@option{--file=@-collection.tar} is considered to be @emph{one} argument. 1162If you substituted any other string of characters for 1163@kbd{collection.tar}, then that string would become the name of the 1164archive file you create. 1165 1166The order of the options becomes more important when you begin to use 1167short forms. With short forms, if you type commands in the wrong order 1168(even if you type them correctly in all other ways), you may end up with 1169results you don't expect. For this reason, it is a good idea to get 1170into the habit of typing options in the order that makes inherent sense. 1171@xref{short create}, for more information on this. 1172 1173In this example, you type the command as shown above: @option{--create} 1174is the operation which creates the new archive 1175(@file{collection.tar}), and @option{--file} is the option which lets 1176you give it the name you chose. The files, @file{blues}, @file{folk}, 1177and @file{jazz}, are now members of the archive, @file{collection.tar} 1178(they are @dfn{file name arguments} to the @option{--create} operation. 1179@xref{Choosing}, for the detailed discussion on these.) Now that they are 1180in the archive, they are called @emph{archive members}, not files. 1181(@pxref{Definitions,members}). 1182 1183When you create an archive, you @emph{must} specify which files you 1184want placed in the archive. If you do not specify any archive 1185members, @GNUTAR{} will complain. 1186 1187If you now list the contents of the working directory (@command{ls}), you will 1188find the archive file listed as well as the files you saw previously: 1189 1190@smallexample 1191blues folk jazz collection.tar 1192@end smallexample 1193 1194@noindent 1195Creating the archive @samp{collection.tar} did not destroy the copies of 1196the files in the directory. 1197 1198Keep in mind that if you don't indicate an operation, @command{tar} will not 1199run and will prompt you for one. If you don't name any files, @command{tar} 1200will complain. You must have write access to the working directory, 1201or else you will not be able to create an archive in that directory. 1202 1203@emph{Caution}: Do not attempt to use @option{--create} (@option{-c}) to add files to 1204an existing archive; it will delete the archive and write a new one. 1205Use @option{--append} (@option{-r}) instead. @xref{append}. 1206 1207@node create verbose 1208@subsection Running @option{--create} with @option{--verbose} 1209 1210@xopindex{create, using with @option{--verbose}} 1211@xopindex{verbose, using with @option{--create}} 1212If you include the @option{--verbose} (@option{-v}) option on the command line, 1213@command{tar} will list the files it is acting on as it is working. In 1214verbose mode, the @code{create} example above would appear as: 1215 1216@smallexample 1217$ @kbd{tar --create --verbose --file=collection.tar blues folk jazz} 1218blues 1219folk 1220jazz 1221@end smallexample 1222 1223This example is just like the example we showed which did not use 1224@option{--verbose}, except that @command{tar} generated the remaining 1225@iftex 1226lines (note the different font styles). 1227@end iftex 1228@ifinfo 1229lines. 1230@end ifinfo 1231 1232In the rest of the examples in this chapter, we will frequently use 1233@code{verbose} mode so we can show actions or @command{tar} responses that 1234you would otherwise not see, and which are important for you to 1235understand. 1236 1237@node short create 1238@subsection Short Forms with @samp{create} 1239 1240As we said before, the @option{--create} (@option{-c}) operation is one of the most 1241basic uses of @command{tar}, and you will use it countless times. 1242Eventually, you will probably want to use abbreviated (or ``short'') 1243forms of options. A full discussion of the three different forms that 1244options can take appears in @ref{Styles}; for now, here is what the 1245previous example (including the @option{--verbose} (@option{-v}) option) looks like 1246using short option forms: 1247 1248@smallexample 1249$ @kbd{tar -cvf collection.tar blues folk jazz} 1250blues 1251folk 1252jazz 1253@end smallexample 1254 1255@noindent 1256As you can see, the system responds the same no matter whether you use 1257long or short option forms. 1258 1259@FIXME{i don't like how this is worded:} One difference between using 1260short and long option forms is that, although the exact placement of 1261arguments following options is no more specific when using short forms, 1262it is easier to become confused and make a mistake when using short 1263forms. For example, suppose you attempted the above example in the 1264following way: 1265 1266@smallexample 1267$ @kbd{tar -cfv collection.tar blues folk jazz} 1268@end smallexample 1269 1270@noindent 1271In this case, @command{tar} will make an archive file called @file{v}, 1272containing the files @file{blues}, @file{folk}, and @file{jazz}, because 1273the @samp{v} is the closest ``file name'' to the @option{-f} option, and 1274is thus taken to be the chosen archive file name. @command{tar} will try 1275to add a file called @file{collection.tar} to the @file{v} archive file; 1276if the file @file{collection.tar} did not already exist, @command{tar} will 1277report an error indicating that this file does not exist. If the file 1278@file{collection.tar} does already exist (e.g., from a previous command 1279you may have run), then @command{tar} will add this file to the archive. 1280Because the @option{-v} option did not get registered, @command{tar} will not 1281run under @samp{verbose} mode, and will not report its progress. 1282 1283The end result is that you may be quite confused about what happened, 1284and possibly overwrite a file. To illustrate this further, we will show 1285you how an example we showed previously would look using short forms. 1286 1287This example, 1288 1289@smallexample 1290$ @kbd{tar --create folk blues --file=collection.tar jazz} 1291@end smallexample 1292 1293@noindent 1294is confusing as it is. It becomes even more so when using short forms: 1295 1296@smallexample 1297$ @kbd{tar -c folk blues -f collection.tar jazz} 1298@end smallexample 1299 1300@noindent 1301It would be very easy to put the wrong string of characters 1302immediately following the @option{-f}, but doing that could sacrifice 1303valuable data. 1304 1305For this reason, we recommend that you pay very careful attention to 1306the order of options and placement of file and archive names, 1307especially when using short option forms. Not having the option name 1308written out mnemonically can affect how well you remember which option 1309does what, and therefore where different names have to be placed. 1310 1311@node create dir 1312@subsection Archiving Directories 1313 1314@cindex Archiving Directories 1315@cindex Directories, Archiving 1316You can archive a directory by specifying its directory name as a 1317file name argument to @command{tar}. The files in the directory will be 1318archived relative to the working directory, and the directory will be 1319re-created along with its contents when the archive is extracted. 1320 1321To archive a directory, first move to its superior directory. If you 1322have followed the previous instructions in this tutorial, you should 1323type: 1324 1325@smallexample 1326$ @kbd{cd ..} 1327$ 1328@end smallexample 1329 1330@noindent 1331This will put you into the directory which contains @file{practice}, 1332i.e., your home directory. Once in the superior directory, you can 1333specify the subdirectory, @file{practice}, as a file name argument. To 1334store @file{practice} in the new archive file @file{music.tar}, type: 1335 1336@smallexample 1337$ @kbd{tar --create --verbose --file=music.tar practice} 1338@end smallexample 1339 1340@noindent 1341@command{tar} should output: 1342 1343@smallexample 1344practice/ 1345practice/blues 1346practice/folk 1347practice/jazz 1348practice/collection.tar 1349@end smallexample 1350 1351Note that the archive thus created is not in the subdirectory 1352@file{practice}, but rather in the current working directory---the 1353directory from which @command{tar} was invoked. Before trying to archive a 1354directory from its superior directory, you should make sure you have 1355write access to the superior directory itself, not only the directory 1356you are trying archive with @command{tar}. For example, you will probably 1357not be able to store your home directory in an archive by invoking 1358@command{tar} from the root directory; @xref{absolute}. (Note 1359also that @file{collection.tar}, the original archive file, has itself 1360been archived. @command{tar} will accept any file as a file to be 1361archived, regardless of its content. When @file{music.tar} is 1362extracted, the archive file @file{collection.tar} will be re-written 1363into the file system). 1364 1365If you give @command{tar} a command such as 1366 1367@smallexample 1368$ @kbd{tar --create --file=foo.tar .} 1369@end smallexample 1370 1371@noindent 1372@command{tar} will report @samp{tar: ./foo.tar is the archive; not 1373dumped}. This happens because @command{tar} creates the archive 1374@file{foo.tar} in the current directory before putting any files into 1375it. Then, when @command{tar} attempts to add all the files in the 1376directory @file{.} to the archive, it notices that the file 1377@file{./foo.tar} is the same as the archive @file{foo.tar}, and skips 1378it. (It makes no sense to put an archive into itself.) @GNUTAR{} 1379will continue in this case, and create the archive 1380normally, except for the exclusion of that one file. (@emph{Please 1381note:} Other implementations of @command{tar} may not be so clever; 1382they will enter an infinite loop when this happens, so you should not 1383depend on this behavior unless you are certain you are running 1384@GNUTAR{}. In general, it is wise to always place the archive outside 1385of the directory being dumped.) 1386 1387@node list 1388@section How to List Archives 1389 1390@opindex list 1391Frequently, you will find yourself wanting to determine exactly what a 1392particular archive contains. You can use the @option{--list} 1393(@option{-t}) operation to get the member names as they currently 1394appear in the archive, as well as various attributes of the files at 1395the time they were archived. For example, assuming @file{practice} is 1396your working directory, you can examine the archive 1397@file{collection.tar} that you created in the last section with the 1398command, 1399 1400@smallexample 1401$ @kbd{tar --list --file=collection.tar} 1402@end smallexample 1403 1404@noindent 1405The output of @command{tar} would then be: 1406 1407@smallexample 1408blues 1409folk 1410jazz 1411@end smallexample 1412 1413@noindent 1414Be sure to use a @option{--file=@var{archive-name}} (@option{-f 1415@var{archive-name}}) option just as with @option{--create} 1416(@option{-c}) to specify the name of the archive. 1417 1418@cindex File name arguments, using @option{--list} with 1419@xopindex{list, using with file name arguments} 1420You can specify one or more individual member names as arguments when 1421using @samp{list}. In this case, @command{tar} will only list the 1422names of members you identify. For example, @w{@kbd{tar --list 1423--file=collection.tar folk}} would only print @file{folk}: 1424 1425@smallexample 1426$ @kbd{tar --list --file=collection.tar folk} 1427folk 1428@end smallexample 1429 1430@xopindex{list, using with @option{--verbose}} 1431@xopindex{verbose, using with @option{--list}} 1432If you use the @option{--verbose} (@option{-v}) option with 1433@option{--list}, then @command{tar} will print out a listing 1434reminiscent of @w{@samp{ls -l}}, showing owner, file size, and so 1435forth. This output is described in detail in @ref{verbose member listing}. 1436 1437If you had used @option{--verbose} (@option{-v}) mode, the example 1438above would look like: 1439 1440@smallexample 1441$ @kbd{tar --list --verbose --file=collection.tar folk} 1442-rw-r--r-- myself/user 62 1990-05-23 10:55 folk 1443@end smallexample 1444 1445@cindex listing member and file names 1446@anchor{listing member and file names} 1447It is important to notice that the output of @kbd{tar --list 1448--verbose} does not necessarily match that produced by @kbd{tar 1449--create --verbose} while creating the archive. It is because 1450@GNUTAR{}, unless told explicitly not to do so, removes some directory 1451prefixes from file names before storing them in the archive 1452(@xref{absolute}, for more information). In other 1453words, in verbose mode @GNUTAR{} shows @dfn{file names} when creating 1454an archive and @dfn{member names} when listing it. Consider this 1455example, run from your home directory: 1456 1457@smallexample 1458@group 1459$ @kbd{tar --create --verbose --file practice.tar ~/practice} 1460tar: Removing leading '/' from member names 1461/home/myself/practice/ 1462/home/myself/practice/blues 1463/home/myself/practice/folk 1464/home/myself/practice/jazz 1465/home/myself/practice/collection.tar 1466$ @kbd{tar --list --file practice.tar} 1467home/myself/practice/ 1468home/myself/practice/blues 1469home/myself/practice/folk 1470home/myself/practice/jazz 1471home/myself/practice/collection.tar 1472@end group 1473@end smallexample 1474 1475@opindex show-stored-names 1476 This default behavior can sometimes be inconvenient. You can force 1477@GNUTAR{} show member names when creating archive by supplying 1478@option{--show-stored-names} option. 1479 1480@table @option 1481@item --show-stored-names 1482Print member (as opposed to @emph{file}) names when creating the archive. 1483@end table 1484 1485With this option, both commands produce the same output: 1486 1487@smallexample 1488@group 1489$ @kbd{tar --create --verbose --show-stored-names \ 1490 --file practice.tar ~/practice} 1491tar: Removing leading '/' from member names 1492home/myself/practice/ 1493home/myself/practice/blues 1494home/myself/practice/folk 1495home/myself/practice/jazz 1496home/myself/practice/collection.tar 1497$ @kbd{tar --list --file practice.tar} 1498home/myself/practice/ 1499home/myself/practice/blues 1500home/myself/practice/folk 1501home/myself/practice/jazz 1502home/myself/practice/collection.tar 1503@end group 1504@end smallexample 1505 1506Since @command{tar} preserves file names, those you wish to list must be 1507specified as they appear in the archive (i.e., relative to the 1508directory from which the archive was created). Continuing the example 1509above: 1510 1511@smallexample 1512@group 1513$ @kbd{tar --list --file=practice.tar folk} 1514tar: folk: Not found in archive 1515tar: Exiting with failure status due to previous errors 1516@end group 1517@end smallexample 1518 1519the error message is produced because there is no member named 1520@file{folk}, only one named @file{home/myself/folk}. 1521 1522If you are not sure of the exact file name, use @dfn{globbing 1523patterns}, for example: 1524 1525@smallexample 1526$ @kbd{tar --list --file=practice.tar --wildcards '*/folk'} 1527home/myself/practice/folk 1528@end smallexample 1529 1530@noindent 1531@xref{wildcards}, for a detailed discussion of globbing patterns and related 1532@command{tar} command line options. 1533 1534@menu 1535* list dir:: 1536@end menu 1537 1538@node list dir 1539@unnumberedsubsec Listing the Contents of a Stored Directory 1540 1541To get information about the contents of an archived directory, 1542use the directory name as a file name argument in conjunction with 1543@option{--list} (@option{-t}). To find out file attributes, include the 1544@option{--verbose} (@option{-v}) option. 1545 1546For example, to find out about files in the directory @file{practice}, in 1547the archive file @file{music.tar}, type: 1548 1549@smallexample 1550$ @kbd{tar --list --verbose --file=music.tar practice} 1551@end smallexample 1552 1553@command{tar} responds: 1554 1555@smallexample 1556drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/ 1557-rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues 1558-rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk 1559-rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz 1560-rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar 1561@end smallexample 1562 1563When you use a directory name as a file name argument, @command{tar} acts on 1564all the files (including sub-directories) in that directory. 1565 1566@node extract 1567@section How to Extract Members from an Archive 1568@cindex Extraction 1569@cindex Retrieving files from an archive 1570@cindex Resurrecting files from an archive 1571 1572@opindex extract 1573Creating an archive is only half the job---there is no point in storing 1574files in an archive if you can't retrieve them. The act of retrieving 1575members from an archive so they can be used and manipulated as 1576unarchived files again is called @dfn{extraction}. To extract files 1577from an archive, use the @option{--extract} (@option{--get} or 1578@option{-x}) operation. As with @option{--create}, specify the name 1579of the archive with @option{--file} (@option{-f}) option. Extracting 1580an archive does not modify the archive in any way; you can extract it 1581multiple times if you want or need to. 1582 1583Using @option{--extract}, you can extract an entire archive, or specific 1584files. The files can be directories containing other files, or not. As 1585with @option{--create} (@option{-c}) and @option{--list} (@option{-t}), you may use the short or the 1586long form of the operation without affecting the performance. 1587 1588@menu 1589* extracting archives:: 1590* extracting files:: 1591* extract dir:: 1592* extracting untrusted archives:: 1593* failing commands:: 1594@end menu 1595 1596@node extracting archives 1597@subsection Extracting an Entire Archive 1598 1599To extract an entire archive, specify the archive file name only, with 1600no individual file names as arguments. For example, 1601 1602@smallexample 1603$ @kbd{tar -xvf collection.tar} 1604@end smallexample 1605 1606@noindent 1607produces this: 1608 1609@smallexample 1610-rw-r--r-- myself/user 28 1996-10-18 16:31 jazz 1611-rw-r--r-- myself/user 21 1996-09-23 16:44 blues 1612-rw-r--r-- myself/user 20 1996-09-23 16:44 folk 1613@end smallexample 1614 1615@node extracting files 1616@subsection Extracting Specific Files 1617 1618To extract specific archive members, give their exact member names as 1619arguments, as printed by @option{--list} (@option{-t}). If you had 1620mistakenly deleted one of the files you had placed in the archive 1621@file{collection.tar} earlier (say, @file{blues}), you can extract it 1622from the archive without changing the archive's structure. Its 1623contents will be identical to the original file @file{blues} that you 1624deleted. 1625 1626First, make sure you are in the @file{practice} directory, and list the 1627files in the directory. Now, delete the file, @samp{blues}, and list 1628the files in the directory again. 1629 1630You can now extract the member @file{blues} from the archive file 1631@file{collection.tar} like this: 1632 1633@smallexample 1634$ @kbd{tar --extract --file=collection.tar blues} 1635@end smallexample 1636 1637@noindent 1638If you list the files in the directory again, you will see that the file 1639@file{blues} has been restored, with its original permissions, data 1640modification times, and owner.@footnote{This is only accidentally 1641true, but not in general. Whereas modification times are always 1642restored, in most cases, one has to be root for restoring the owner, 1643and use a special option for restoring permissions. Here, it just 1644happens that the restoring user is also the owner of the archived 1645members, and that the current @code{umask} is compatible with original 1646permissions.} (These parameters will be identical to those which 1647the file had when you originally placed it in the archive; any changes 1648you may have made before deleting the file from the file system, 1649however, will @emph{not} have been made to the archive member.) The 1650archive file, @samp{collection.tar}, is the same as it was before you 1651extracted @samp{blues}. You can confirm this by running @command{tar} with 1652@option{--list} (@option{-t}). 1653 1654Remember that as with other operations, specifying the exact member 1655name is important (@xref{failing commands}, for more examples). 1656 1657You can extract a file to standard output by combining the above options 1658with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard 1659Output}). 1660 1661If you give the @option{--verbose} option, then @option{--extract} 1662will print the names of the archive members as it extracts them. 1663 1664@node extract dir 1665@subsection Extracting Files that are Directories 1666 1667Extracting directories which are members of an archive is similar to 1668extracting other files. The main difference to be aware of is that if 1669the extracted directory has the same name as any directory already in 1670the working directory, then files in the extracted directory will be 1671placed into the directory of the same name. Likewise, if there are 1672files in the pre-existing directory with the same names as the members 1673which you extract, the files from the extracted archive will replace 1674the files already in the working directory (and possible 1675subdirectories). This will happen regardless of whether or not the 1676files in the working directory were more recent than those extracted 1677(there exist, however, special options that alter this behavior 1678@pxref{Writing}). 1679 1680However, if a file was stored with a directory name as part of its file 1681name, and that directory does not exist under the working directory when 1682the file is extracted, @command{tar} will create the directory. 1683 1684We can demonstrate how to use @option{--extract} to extract a directory 1685file with an example. Change to the @file{practice} directory if you 1686weren't there, and remove the files @file{folk} and @file{jazz}. Then, 1687go back to the parent directory and extract the archive 1688@file{music.tar}. You may either extract the entire archive, or you may 1689extract only the files you just deleted. To extract the entire archive, 1690don't give any file names as arguments after the archive name 1691@file{music.tar}. To extract only the files you deleted, use the 1692following command: 1693 1694@smallexample 1695$ @kbd{tar -xvf music.tar practice/folk practice/jazz} 1696practice/folk 1697practice/jazz 1698@end smallexample 1699 1700@noindent 1701If you were to specify two @option{--verbose} (@option{-v}) options, @command{tar} 1702would have displayed more detail about the extracted files, as shown 1703in the example below: 1704 1705@smallexample 1706$ @kbd{tar -xvvf music.tar practice/folk practice/jazz} 1707-rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz 1708-rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk 1709@end smallexample 1710 1711@noindent 1712Because you created the directory with @file{practice} as part of the 1713file names of each of the files by archiving the @file{practice} 1714directory as @file{practice}, you must give @file{practice} as part 1715of the file names when you extract those files from the archive. 1716 1717@node extracting untrusted archives 1718@subsection Extracting Archives from Untrusted Sources 1719 1720Extracting files from archives can overwrite files that already exist. 1721If you receive an archive from an untrusted source, you should make a 1722new directory and extract into that directory, so that you don't have 1723to worry about the extraction overwriting one of your existing files. 1724For example, if @file{untrusted.tar} came from somewhere else on the 1725Internet, and you don't necessarily trust its contents, you can 1726extract it as follows: 1727 1728@smallexample 1729$ @kbd{mkdir newdir} 1730$ @kbd{cd newdir} 1731$ @kbd{tar -xvf ../untrusted.tar} 1732@end smallexample 1733 1734It is also a good practice to examine contents of the archive 1735before extracting it, using @option{--list} (@option{-t}) option, possibly combined 1736with @option{--verbose} (@option{-v}). 1737 1738@node failing commands 1739@subsection Commands That Will Fail 1740 1741Here are some sample commands you might try which will not work, and why 1742they won't work. 1743 1744If you try to use this command, 1745 1746@smallexample 1747$ @kbd{tar -xvf music.tar folk jazz} 1748@end smallexample 1749 1750@noindent 1751you will get the following response: 1752 1753@smallexample 1754tar: folk: Not found in archive 1755tar: jazz: Not found in archive 1756@end smallexample 1757 1758@noindent 1759This is because these files were not originally @emph{in} the parent 1760directory @file{..}, where the archive is located; they were in the 1761@file{practice} directory, and their file names reflect this: 1762 1763@smallexample 1764$ @kbd{tar -tvf music.tar} 1765practice/blues 1766practice/folk 1767practice/jazz 1768@end smallexample 1769 1770@noindent 1771Likewise, if you try to use this command, 1772 1773@smallexample 1774$ @kbd{tar -tvf music.tar folk jazz} 1775@end smallexample 1776 1777@noindent 1778you would get a similar response. Members with those names are not in the 1779archive. You must use the correct member names, or wildcards, in order 1780to extract the files from the archive. 1781 1782If you have forgotten the correct names of the files in the archive, 1783use @w{@kbd{tar --list --verbose}} to list them correctly. 1784 1785To extract the member named @file{practice/folk}, you must specify 1786 1787@smallexample 1788$ @kbd{tar --extract --file=music.tar practice/folk} 1789@end smallexample 1790 1791@noindent 1792Notice also, that as explained above, the @file{practice} directory 1793will be created, if it didn't already exist. There are options that 1794allow you to strip away a certain number of leading directory 1795components (@pxref{transform}). For example, 1796 1797@smallexample 1798$ @kbd{tar --extract --file=music.tar --strip-components=1 folk} 1799@end smallexample 1800 1801@noindent 1802will extract the file @file{folk} into the current working directory. 1803 1804@node going further 1805@section Going Further Ahead in this Manual 1806@UNREVISED 1807 1808@FIXME{need to write up a node here about the things that are going to 1809be in the rest of the manual.} 1810 1811@node tar invocation 1812@chapter Invoking @GNUTAR{} 1813 1814This chapter is about how one invokes the @GNUTAR{} 1815command, from the command synopsis (@pxref{Synopsis}). There are 1816numerous options, and many styles for writing them. One mandatory 1817option specifies the operation @command{tar} should perform 1818(@pxref{Operation Summary}), other options are meant to detail how 1819this operation should be performed (@pxref{Option Summary}). 1820Non-option arguments are not always interpreted the same way, 1821depending on what the operation is. 1822 1823You will find in this chapter everything about option styles and rules for 1824writing them (@pxref{Styles}). On the other hand, operations and options 1825are fully described elsewhere, in other chapters. Here, you will find 1826only synthetic descriptions for operations and options, together with 1827pointers to other parts of the @command{tar} manual. 1828 1829Some options are so special they are fully described right in this 1830chapter. They have the effect of inhibiting the normal operation of 1831@command{tar} or else, they globally alter the amount of feedback the user 1832receives about what is going on. These are the @option{--help} and 1833@option{--version} (@pxref{help}), @option{--verbose} (@pxref{verbose}) 1834and @option{--interactive} options (@pxref{interactive}). 1835 1836@menu 1837* Synopsis:: 1838* using tar options:: 1839* Styles:: 1840* All Options:: All @command{tar} Options. 1841* help:: Where to Get Help. 1842* defaults:: What are the Default Values. 1843* verbose:: Checking @command{tar} progress. 1844* checkpoints:: Checkpoints. 1845* warnings:: Controlling Warning Messages. 1846* interactive:: Asking for Confirmation During Operations. 1847* external:: Running External Commands. 1848@end menu 1849 1850@node Synopsis 1851@section General Synopsis of @command{tar} 1852 1853The @GNUTAR{} program is invoked as either one of: 1854 1855@smallexample 1856@kbd{tar @var{option}@dots{} [@var{name}]@dots{}} 1857@kbd{tar @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}} 1858@end smallexample 1859 1860The second form is for when old options are being used. 1861 1862You can use @command{tar} to store files in an archive, to extract them from 1863an archive, and to do other types of archive manipulation. The primary 1864argument to @command{tar}, which is called the @dfn{operation}, specifies 1865which action to take. The other arguments to @command{tar} are either 1866@dfn{options}, which change the way @command{tar} performs an operation, 1867or file names or archive members, which specify the files or members 1868@command{tar} is to act on. 1869 1870You can actually type in arguments in any order, even if in this manual 1871the options always precede the other arguments, to make examples easier 1872to understand. Further, the option stating the main operation mode 1873(the @command{tar} main command) is usually given first. 1874 1875Each @var{name} in the synopsis above is interpreted as an archive member 1876name when the main command is one of @option{--compare} 1877(@option{--diff}, @option{-d}), @option{--delete}, @option{--extract} 1878(@option{--get}, @option{-x}), @option{--list} (@option{-t}) or 1879@option{--update} (@option{-u}). When naming archive members, you 1880must give the exact name of the member in the archive, as it is 1881printed by @option{--list}. For @option{--append} (@option{-r}) and 1882@option{--create} (@option{-c}), these @var{name} arguments specify 1883the names of either files or directory hierarchies to place in the archive. 1884These files or hierarchies should already exist in the file system, 1885prior to the execution of the @command{tar} command. 1886 1887@command{tar} interprets relative file names as being relative to the 1888working directory. @command{tar} will make all file names relative 1889(by removing leading slashes when archiving or restoring files), 1890unless you specify otherwise (using the @option{--absolute-names} 1891option). @xref{absolute}, for more information about 1892@option{--absolute-names}. 1893 1894If you give the name of a directory as either a file name or a member 1895name, then @command{tar} acts recursively on all the files and directories 1896beneath that directory. For example, the name @file{/} identifies all 1897the files in the file system to @command{tar}. 1898 1899The distinction between file names and archive member names is especially 1900important when shell globbing is used, and sometimes a source of confusion 1901for newcomers. @xref{wildcards}, for more information about globbing. 1902The problem is that shells may only glob using existing files in the 1903file system. Only @command{tar} itself may glob on archive members, so when 1904needed, you must ensure that wildcard characters reach @command{tar} without 1905being interpreted by the shell first. Using a backslash before @samp{*} 1906or @samp{?}, or putting the whole argument between quotes, is usually 1907sufficient for this. 1908 1909Even if @var{name}s are often specified on the command line, they 1910can also be read from a text file in the file system, using the 1911@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) option. 1912 1913If you don't use any file name arguments, @option{--append} (@option{-r}), 1914@option{--delete} and @option{--concatenate} (@option{--catenate}, 1915@option{-A}) will do nothing, while @option{--create} (@option{-c}) 1916will usually yield a diagnostic and inhibit @command{tar} execution. 1917The other operations of @command{tar} (@option{--list}, 1918@option{--extract}, @option{--compare}, and @option{--update}) 1919will act on the entire contents of the archive. 1920 1921@anchor{exit status} 1922@cindex exit status 1923@cindex return status 1924Besides successful exits, @GNUTAR{} may fail for 1925many reasons. Some reasons correspond to bad usage, that is, when the 1926@command{tar} command line is improperly written. Errors may be 1927encountered later, while processing the archive or the files. Some 1928errors are recoverable, in which case the failure is delayed until 1929@command{tar} has completed all its work. Some errors are such that 1930it would be not meaningful, or at least risky, to continue processing: 1931@command{tar} then aborts processing immediately. All abnormal exits, 1932whether immediate or delayed, should always be clearly diagnosed on 1933@code{stderr}, after a line stating the nature of the error. 1934 1935Possible exit codes of @GNUTAR{} are summarized in the following 1936table: 1937 1938@table @asis 1939@item 0 1940@samp{Successful termination}. 1941 1942@item 1 1943@samp{Some files differ}. If tar was invoked with @option{--compare} 1944(@option{--diff}, @option{-d}) command line option, this means that 1945some files in the archive differ from their disk counterparts 1946(@pxref{compare}). If tar was given @option{--create}, 1947@option{--append} or @option{--update} option, this exit code means 1948that some files were changed while being archived and so the resulting 1949archive does not contain the exact copy of the file set. 1950 1951@item 2 1952@samp{Fatal error}. This means that some fatal, unrecoverable error 1953occurred. 1954@end table 1955 1956If @command{tar} has invoked a subprocess and that subprocess exited with a 1957nonzero exit code, @command{tar} exits with that code as well. 1958This can happen, for example, if @command{tar} was given some 1959compression option (@pxref{gzip}) and the external compressor program 1960failed. Another example is @command{rmt} failure during backup to the 1961remote device (@pxref{Remote Tape Server}). 1962 1963@node using tar options 1964@section Using @command{tar} Options 1965 1966@GNUTAR{} has a total of eight operating modes which 1967allow you to perform a variety of tasks. You are required to choose 1968one operating mode each time you employ the @command{tar} program by 1969specifying one, and only one operation as an argument to the 1970@command{tar} command (the corresponding options may be found 1971at @ref{frequent operations} and @ref{Operations}). Depending on 1972circumstances, you may also wish to customize how the chosen operating 1973mode behaves. For example, you may wish to change the way the output 1974looks, or the format of the files that you wish to archive may require 1975you to do something special in order to make the archive look right. 1976 1977You can customize and control @command{tar}'s performance by running 1978@command{tar} with one or more options (such as @option{--verbose} 1979(@option{-v}), which we used in the tutorial). As we said in the 1980tutorial, @dfn{options} are arguments to @command{tar} which are (as 1981their name suggests) optional. Depending on the operating mode, you 1982may specify one or more options. Different options will have different 1983effects, but in general they all change details of the operation, such 1984as archive format, archive name, or level of user interaction. Some 1985options make sense with all operating modes, while others are 1986meaningful only with particular modes. You will likely use some 1987options frequently, while you will only use others infrequently, or 1988not at all. (A full list of options is available in @pxref{All Options}.) 1989 1990@vrindex TAR_OPTIONS, environment variable 1991@anchor{TAR_OPTIONS} 1992The @env{TAR_OPTIONS} environment variable specifies default options to 1993be placed in front of any explicit options. For example, if 1994@code{TAR_OPTIONS} is @samp{-v --unlink-first}, @command{tar} behaves as 1995if the two options @option{-v} and @option{--unlink-first} had been 1996specified before any explicit options. Option specifications are 1997separated by whitespace. A backslash escapes the next character, so it 1998can be used to specify an option containing whitespace or a backslash. 1999 2000Note that @command{tar} options are case sensitive. For example, the 2001options @option{-T} and @option{-t} are different; the first requires an 2002argument for stating the name of a file providing a list of @var{name}s, 2003while the second does not require an argument and is another way to 2004write @option{--list} (@option{-t}). 2005 2006In addition to the eight operations, there are many options to 2007@command{tar}, and three different styles for writing both: long (mnemonic) 2008form, short form, and old style. These styles are discussed below. 2009Both the options and the operations can be written in any of these three 2010styles. 2011 2012@FIXME{menu at end of this node. need to think of an actual outline 2013for this chapter; probably do that after stuff from chapter 4 is 2014incorporated.} 2015 2016@node Styles 2017@section The Three Option Styles 2018 2019There are three styles for writing operations and options to the command 2020line invoking @command{tar}. The different styles were developed at 2021different times during the history of @command{tar}. These styles will be 2022presented below, from the most recent to the oldest. 2023 2024Some options must take an argument@footnote{For example, @option{--file} 2025(@option{-f}) takes the name of an archive file as an argument. If 2026you do not supply an archive file name, @command{tar} will use a 2027default, but this can be confusing; thus, we recommend that you always 2028supply a specific archive file name.}. Where you @emph{place} the 2029arguments generally depends on which style of options you choose. We 2030will detail specific information relevant to each option style in the 2031sections on the different option styles, below. The differences are 2032subtle, yet can often be very important; incorrect option placement 2033can cause you to overwrite a number of important files. We urge you 2034to note these differences, and only use the option style(s) which 2035makes the most sense to you until you feel comfortable with the others. 2036 2037Some options @emph{may} take an argument. Such options may have at 2038most long and short forms, they do not have old style equivalent. The 2039rules for specifying an argument for such options are stricter than 2040those for specifying mandatory arguments. Please, pay special 2041attention to them. 2042 2043@menu 2044* Long Options:: Long Option Style 2045* Short Options:: Short Option Style 2046* Old Options:: Old Option Style 2047* Mixing:: Mixing Option Styles 2048@end menu 2049 2050@node Long Options 2051@subsection Long Option Style 2052 2053@cindex long options 2054@cindex options, long style 2055@cindex options, GNU style 2056@cindex options, mnemonic names 2057Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with two 2058dashes in a row, e.g., @option{--list}. The long names are more clear than 2059their corresponding short or old names. It sometimes happens that a 2060single long option has many different names which are 2061synonymous, such as @option{--compare} and @option{--diff}. In addition, 2062long option names can be given unique abbreviations. For example, 2063@option{--cre} can be used in place of @option{--create} because there is no 2064other long option which begins with @samp{cre}. (One way to find 2065this out is by trying it and seeing what happens; if a particular 2066abbreviation could represent more than one option, @command{tar} will tell 2067you that that abbreviation is ambiguous and you'll know that that 2068abbreviation won't work. You may also choose to run @samp{tar --help} 2069to see a list of options. Be aware that if you run @command{tar} with a 2070unique abbreviation for the long name of an option you didn't want to 2071use, you are stuck; @command{tar} will perform the command as ordered.) 2072 2073Long options are meant to be obvious and easy to remember, and their 2074meanings are generally easier to discern than those of their 2075corresponding short options (see below). For example: 2076 2077@smallexample 2078$ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0} 2079@end smallexample 2080 2081@noindent 2082gives a fairly good set of hints about what the command does, even 2083for those not fully acquainted with @command{tar}. 2084 2085@cindex arguments to long options 2086@cindex long options with mandatory arguments 2087Long options which require arguments take those arguments 2088immediately following the option name. There are two ways of 2089specifying a mandatory argument. It can be separated from the 2090option name either by an equal sign, or by any amount of 2091white space characters. For example, the @option{--file} option (which 2092tells the name of the @command{tar} archive) is given a file such as 2093@file{archive.tar} as argument by using any of the following notations: 2094@option{--file=archive.tar} or @option{--file archive.tar}. 2095 2096@cindex optional arguments to long options 2097@cindex long options with optional arguments 2098In contrast, optional arguments must always be introduced using 2099an equal sign. For example, the @option{--backup} option takes 2100an optional argument specifying backup type. It must be used 2101as @option{--backup=@var{backup-type}}. 2102 2103@node Short Options 2104@subsection Short Option Style 2105 2106@cindex short options 2107@cindex options, short style 2108@cindex options, traditional 2109Most options also have a @dfn{short option} name. Short options start with 2110a single dash, and are followed by a single character, e.g., @option{-t} 2111(which is equivalent to @option{--list}). The forms are absolutely 2112identical in function; they are interchangeable. 2113 2114The short option names are faster to type than long option names. 2115 2116@cindex arguments to short options 2117@cindex short options with mandatory arguments 2118Short options which require arguments take their arguments immediately 2119following the option, usually separated by white space. It is also 2120possible to stick the argument right after the short option name, using 2121no intervening space. For example, you might write @w{@option{-f 2122archive.tar}} or @option{-farchive.tar} instead of using 2123@option{--file=archive.tar}. Both @option{--file=@var{archive-name}} and 2124@w{@option{-f @var{archive-name}}} denote the option which indicates a 2125specific archive, here named @file{archive.tar}. 2126 2127@cindex optional arguments to short options 2128@cindex short options with optional arguments 2129Short options which take optional arguments take their arguments 2130immediately following the option letter, @emph{without any intervening 2131white space characters}. 2132 2133Short options' letters may be clumped together, but you are not 2134required to do this (as compared to old options; see below). When 2135short options are clumped as a set, use one (single) dash for them 2136all, e.g., @w{@samp{@command{tar} -cvf}}. Only the last option in 2137such a set is allowed to have an argument@footnote{Clustering many 2138options, the last of which has an argument, is a rather opaque way to 2139write options. Some wonder if @acronym{GNU} @code{getopt} should not 2140even be made helpful enough for considering such usages as invalid.}. 2141 2142When the options are separated, the argument for each option which requires 2143an argument directly follows that option, as is usual for Unix programs. 2144For example: 2145 2146@smallexample 2147$ @kbd{tar -c -v -b 20 -f /dev/rmt0} 2148@end smallexample 2149 2150If you reorder short options' locations, be sure to move any arguments 2151that belong to them. If you do not move the arguments properly, you may 2152end up overwriting files. 2153 2154@node Old Options 2155@subsection Old Option Style 2156@cindex options, old style 2157@cindex old option style 2158@cindex option syntax, traditional 2159 2160As far as we know, all @command{tar} programs, @acronym{GNU} and 2161non-@acronym{GNU}, support @dfn{old options}: that is, if the first 2162argument does not start with @samp{-}, it is assumed to specify option 2163letters. @GNUTAR{} supports old options not only for historical 2164reasons, but also because many people are used to them. If the first 2165argument does not start with a dash, you are announcing the old option 2166style instead of the short option style; old options are decoded 2167differently. 2168 2169Like short options, old options are single letters. However, old options 2170must be written together as a single clumped set, without spaces separating 2171them or dashes preceding them. This set 2172of letters must be the first to appear on the command line, after the 2173@command{tar} program name and some white space; old options cannot appear 2174anywhere else. The letter of an old option is exactly the same letter as 2175the corresponding short option. For example, the old option @samp{t} is 2176the same as the short option @option{-t}, and consequently, the same as the 2177long option @option{--list}. So for example, the command @w{@samp{tar 2178cv}} specifies the option @option{-v} in addition to the operation @option{-c}. 2179 2180@cindex arguments to old options 2181@cindex old options with mandatory arguments 2182When options that need arguments are given together with the command, 2183all the associated arguments follow, in the same order as the options. 2184Thus, the example given previously could also be written in the old 2185style as follows: 2186 2187@smallexample 2188$ @kbd{tar cvbf 20 /dev/rmt0} 2189@end smallexample 2190 2191@noindent 2192Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is 2193the argument of @option{-f}. 2194 2195The old style syntax can make it difficult to match 2196option letters with their corresponding arguments, and is often 2197confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example, 2198@samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the 2199argument for @option{-f}, and @option{-v} does not have a corresponding 2200argument. Even using short options like in @w{@samp{tar -c -v -b 20 -f 2201/dev/rmt0}} is clearer, putting all arguments next to the option they 2202pertain to. 2203 2204If you want to reorder the letters in the old option argument, be 2205sure to reorder any corresponding argument appropriately. 2206 2207This old way of writing @command{tar} options can surprise even experienced 2208users. For example, the two commands: 2209 2210@smallexample 2211@kbd{tar cfz archive.tar.gz file} 2212@kbd{tar -cfz archive.tar.gz file} 2213@end smallexample 2214 2215@noindent 2216are quite different. The first example uses @file{archive.tar.gz} as 2217the value for option @samp{f} and recognizes the option @samp{z}. The 2218second example, however, uses @file{z} as the value for option 2219@samp{f} --- probably not what was intended. 2220 2221This second example could be corrected in many ways, among which the 2222following are equivalent: 2223 2224@smallexample 2225@kbd{tar -czf archive.tar.gz file} 2226@kbd{tar -cf archive.tar.gz -z file} 2227@kbd{tar cf archive.tar.gz -z file} 2228@end smallexample 2229 2230@node Mixing 2231@subsection Mixing Option Styles 2232 2233@cindex options, mixing different styles 2234All three styles may be intermixed in a single @command{tar} command, 2235so long as the rules for each style are fully 2236respected@footnote{Before @GNUTAR{} version 1.11.6, 2237a bug prevented intermixing old style options with long options in 2238some cases.}. Old style options and either of the modern styles of 2239options may be mixed within a single @command{tar} command. However, 2240old style options must be introduced as the first arguments only, 2241following the rule for old options (old options must appear directly 2242after the @command{tar} command and some white space). Modern options 2243may be given only after all arguments to the old options have been 2244collected. If this rule is not respected, a modern option might be 2245falsely interpreted as the value of the argument to one of the old 2246style options. 2247 2248For example, all the following commands are wholly equivalent, and 2249illustrate the many combinations and orderings of option styles. 2250 2251@smallexample 2252@kbd{tar --create --file=archive.tar} 2253@kbd{tar --create -f archive.tar} 2254@kbd{tar --create -farchive.tar} 2255@kbd{tar --file=archive.tar --create} 2256@kbd{tar --file=archive.tar -c} 2257@kbd{tar -c --file=archive.tar} 2258@kbd{tar -c -f archive.tar} 2259@kbd{tar -c -farchive.tar} 2260@kbd{tar -cf archive.tar} 2261@kbd{tar -cfarchive.tar} 2262@kbd{tar -f archive.tar --create} 2263@kbd{tar -f archive.tar -c} 2264@kbd{tar -farchive.tar --create} 2265@kbd{tar -farchive.tar -c} 2266@kbd{tar c --file=archive.tar} 2267@kbd{tar c -f archive.tar} 2268@kbd{tar c -farchive.tar} 2269@kbd{tar cf archive.tar} 2270@kbd{tar f archive.tar --create} 2271@kbd{tar f archive.tar -c} 2272@kbd{tar fc archive.tar} 2273@end smallexample 2274 2275On the other hand, the following commands are @emph{not} equivalent to 2276the previous set: 2277 2278@smallexample 2279@kbd{tar -f -c archive.tar} 2280@kbd{tar -fc archive.tar} 2281@kbd{tar -fcarchive.tar} 2282@kbd{tar -farchive.tarc} 2283@kbd{tar cfarchive.tar} 2284@end smallexample 2285 2286@noindent 2287These last examples mean something completely different from what the 2288user intended (judging based on the example in the previous set which 2289uses long options, whose intent is therefore very clear). The first 2290four specify that the @command{tar} archive would be a file named 2291@option{-c}, @samp{c}, @samp{carchive.tar} or @samp{archive.tarc}, 2292respectively. The first two examples also specify a single non-option, 2293@var{name} argument having the value @samp{archive.tar}. The last 2294example contains only old style option letters (repeating option 2295@samp{c} twice), not all of which are meaningful (eg., @samp{.}, 2296@samp{h}, or @samp{i}), with no argument value. 2297@FIXME{not sure i liked 2298the first sentence of this paragraph..} 2299 2300@node All Options 2301@section All @command{tar} Options 2302 2303The coming manual sections contain an alphabetical listing of all 2304@command{tar} operations and options, with brief descriptions and 2305cross-references to more in-depth explanations in the body of the manual. 2306They also contain an alphabetically arranged table of the short option 2307forms with their corresponding long option. You can use this table as 2308a reference for deciphering @command{tar} commands in scripts. 2309 2310@menu 2311* Operation Summary:: 2312* Option Summary:: 2313* Short Option Summary:: 2314* Position-Sensitive Options:: 2315@end menu 2316 2317@node Operation Summary 2318@subsection Operations 2319 2320@table @option 2321 2322@opsummary{append} 2323@item --append 2324@itemx -r 2325 2326Appends files to the end of the archive. @xref{append}. 2327 2328@opsummary{catenate} 2329@item --catenate 2330@itemx -A 2331 2332Same as @option{--concatenate}. @xref{concatenate}. 2333 2334@opsummary{compare} 2335@item --compare 2336@itemx -d 2337 2338Compares archive members with their counterparts in the file 2339system, and reports differences in file size, mode, owner, 2340modification date and contents. @xref{compare}. 2341 2342@opsummary{concatenate} 2343@item --concatenate 2344@itemx -A 2345 2346Appends other @command{tar} archives to the end of the archive. 2347@xref{concatenate}. 2348 2349@opsummary{create} 2350@item --create 2351@itemx -c 2352 2353Creates a new @command{tar} archive. @xref{create}. 2354 2355@opsummary{delete} 2356@item --delete 2357 2358Deletes members from the archive. Don't try this on an archive on a 2359tape! @xref{delete}. 2360 2361@opsummary{diff} 2362@item --diff 2363@itemx -d 2364 2365Same @option{--compare}. @xref{compare}. 2366 2367@opsummary{extract} 2368@item --extract 2369@itemx -x 2370 2371Extracts members from the archive into the file system. @xref{extract}. 2372 2373@opsummary{get} 2374@item --get 2375@itemx -x 2376 2377Same as @option{--extract}. @xref{extract}. 2378 2379@opsummary{list} 2380@item --list 2381@itemx -t 2382 2383Lists the members in an archive. @xref{list}. 2384 2385@opsummary{update} 2386@item --update 2387@itemx -u 2388 2389Adds files to the end of the archive, but only if they are newer than 2390their counterparts already in the archive, or if they do not already 2391exist in the archive. @xref{update}. 2392 2393@end table 2394 2395@node Option Summary 2396@subsection @command{tar} Options 2397 2398@table @option 2399 2400@opsummary{absolute-names} 2401@item --absolute-names 2402@itemx -P 2403 2404Normally when creating an archive, @command{tar} strips an initial 2405@samp{/} from member names, and when extracting from an archive @command{tar} 2406treats names specially if they have initial @samp{/} or internal 2407@samp{..}. This option disables that behavior. @xref{absolute}. 2408 2409@opsummary{acls} 2410@item --acls 2411Enable POSIX ACLs support. @xref{Extended File Attributes, acls}. 2412 2413@opsummary{after-date} 2414@item --after-date 2415 2416(See @option{--newer}, @pxref{after}) 2417 2418@opsummary{anchored} 2419@item --anchored 2420A pattern must match an initial subsequence of the name's components. 2421@xref{controlling pattern-matching}. 2422 2423@opsummary{atime-preserve} 2424@item --atime-preserve 2425@itemx --atime-preserve=replace 2426@itemx --atime-preserve=system 2427 2428Attempt to preserve the access time of files when reading them. This 2429option currently is effective only on files that you own, unless you 2430have superuser privileges. 2431 2432@option{--atime-preserve=replace} remembers the access time of a file 2433before reading it, and then restores the access time afterwards. This 2434may cause problems if other programs are reading the file at the same 2435time, as the times of their accesses will be lost. On most platforms 2436restoring the access time also requires @command{tar} to restore the 2437data modification time too, so this option may also cause problems if 2438other programs are writing the file at the same time (@command{tar} attempts 2439to detect this situation, but cannot do so reliably due to race 2440conditions). Worse, on most platforms restoring the access time also 2441updates the status change time, which means that this option is 2442incompatible with incremental backups. 2443 2444@option{--atime-preserve=system} avoids changing time stamps on files, 2445without interfering with time stamp updates 2446caused by other programs, so it works better with incremental backups. 2447However, it requires a special @code{O_NOATIME} option from the 2448underlying operating and file system implementation, and it also requires 2449that searching directories does not update their access times. As of 2450this writing (November 2005) this works only with Linux, and only with 2451Linux kernels 2.6.8 and later. Worse, there is currently no reliable 2452way to know whether this feature actually works. Sometimes 2453@command{tar} knows that it does not work, and if you use 2454@option{--atime-preserve=system} then @command{tar} complains and 2455exits right away. But other times @command{tar} might think that the 2456option works when it actually does not. 2457 2458Currently @option{--atime-preserve} with no operand defaults to 2459@option{--atime-preserve=replace}, but this may change in the future 2460as support for @option{--atime-preserve=system} improves. 2461 2462If your operating or file system does not support 2463@option{--atime-preserve=@-system}, you might be able to preserve access 2464times reliably by using the @command{mount} command. For example, 2465you can mount the file system read-only, or access the file system via 2466a read-only loopback mount, or use the @samp{noatime} mount option 2467available on some systems. However, mounting typically requires 2468superuser privileges and can be a pain to manage. 2469 2470@opsummary{auto-compress} 2471@item --auto-compress 2472@itemx -a 2473 2474During a @option{--create} operation, enables automatic compressed 2475format recognition based on the archive suffix. The effect of this 2476option is cancelled by @option{--no-auto-compress}. @xref{gzip}. 2477 2478@opsummary{backup} 2479@item --backup=@var{backup-type} 2480 2481Rather than deleting files from the file system, @command{tar} will 2482back them up using simple or numbered backups, depending upon 2483@var{backup-type}. @xref{backup}. 2484 2485@opsummary{block-number} 2486@item --block-number 2487@itemx -R 2488 2489With this option present, @command{tar} prints error messages for read errors 2490with the block number in the archive file. @xref{block-number}. 2491 2492@opsummary{blocking-factor} 2493@item --blocking-factor=@var{blocking} 2494@itemx -b @var{blocking} 2495 2496Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per 2497record. @xref{Blocking Factor}. 2498 2499@opsummary{bzip2} 2500@item --bzip2 2501@itemx -j 2502 2503This option tells @command{tar} to read or write archives through 2504@code{bzip2}. @xref{gzip}. 2505 2506@opsummary{check-device} 2507@item --check-device 2508Check device numbers when creating a list of modified files for 2509incremental archiving. This is the default. @xref{device numbers}, 2510for a detailed description. 2511 2512@opsummary{checkpoint} 2513@item --checkpoint[=@var{number}] 2514 2515This option directs @command{tar} to print periodic checkpoint 2516messages as it reads through the archive. It is intended for when you 2517want a visual indication that @command{tar} is still running, but 2518don't want to see @option{--verbose} output. You can also instruct 2519@command{tar} to execute a list of actions on each checkpoint, see 2520@option{--checkpoint-action} below. For a detailed description, see 2521@ref{checkpoints}. 2522 2523@opsummary{checkpoint-action} 2524@item --checkpoint-action=@var{action} 2525Instruct @command{tar} to execute an action upon hitting a 2526breakpoint. Here we give only a brief outline. @xref{checkpoints}, 2527for a complete description. 2528 2529The @var{action} argument can be one of the following: 2530 2531@table @asis 2532@item bell 2533Produce an audible bell on the console. 2534 2535@item dot 2536@itemx . 2537Print a single dot on the standard listing stream. 2538 2539@item echo 2540Display a textual message on the standard error, with the status and 2541number of the checkpoint. This is the default. 2542 2543@item echo=@var{string} 2544Display @var{string} on the standard error. Before output, the string 2545is subject to meta-character expansion. 2546 2547@item exec=@var{command} 2548Execute the given @var{command}. 2549 2550@item sleep=@var{time} 2551Wait for @var{time} seconds. 2552 2553@item ttyout=@var{string} 2554Output @var{string} on the current console (@file{/dev/tty}). 2555 2556@item totals 2557Print statistics (see @pxref{totals}). 2558 2559@item wait=@var{signo} 2560Wait for signal @var{signo}. 2561@end table 2562 2563Several @option{--checkpoint-action} options can be specified. The 2564supplied actions will be executed in order of their appearance in the 2565command line. 2566 2567Using @option{--checkpoint-action} without @option{--checkpoint} 2568assumes default checkpoint frequency of one checkpoint per 10 records. 2569 2570@opsummary{check-links} 2571@item --check-links 2572@itemx -l 2573If this option was given, @command{tar} will check the number of links 2574dumped for each processed file. If this number does not match the 2575total number of hard links for the file, a warning message will be 2576output @footnote{Earlier versions of @GNUTAR{} understood @option{-l} as a 2577synonym for @option{--one-file-system}. The current semantics, which 2578complies to UNIX98, was introduced with version 25791.15.91. @xref{Changes}, for more information.}. 2580 2581@xref{hard links}. 2582 2583@opsummary{compress} 2584@opsummary{uncompress} 2585@item --compress 2586@itemx --uncompress 2587@itemx -Z 2588 2589@command{tar} will use the @command{compress} program when reading or 2590writing the archive. This allows you to directly act on archives 2591while saving space. @xref{gzip}. 2592 2593@opsummary{clamp-mtime} 2594@item --clamp-mtime 2595 2596(See @option{--mtime}.) 2597 2598@opsummary{confirmation} 2599@item --confirmation 2600 2601(See @option{--interactive}.) @xref{interactive}. 2602 2603@opsummary{delay-directory-restore} 2604@item --delay-directory-restore 2605 2606Delay setting modification times and permissions of extracted 2607directories until the end of extraction. @xref{Directory Modification Times and Permissions}. 2608 2609@opsummary{dereference} 2610@item --dereference 2611@itemx -h 2612 2613When reading or writing a file to be archived, @command{tar} accesses 2614the file that a symbolic link points to, rather than the symlink 2615itself. @xref{dereference}. 2616 2617@opsummary{directory} 2618@item --directory=@var{dir} 2619@itemx -C @var{dir} 2620 2621When this option is specified, @command{tar} will change its current directory 2622to @var{dir} before performing any operations. When this option is used 2623during archive creation, it is order sensitive. @xref{directory}. 2624 2625@opsummary{exclude} 2626@item --exclude=@var{pattern} 2627 2628When performing operations, @command{tar} will skip files that match 2629@var{pattern}. @xref{exclude}. 2630 2631@opsummary{exclude-backups} 2632@item --exclude-backups 2633Exclude backup and lock files. @xref{exclude,, exclude-backups}. 2634 2635@opsummary{exclude-from} 2636@item --exclude-from=@var{file} 2637@itemx -X @var{file} 2638 2639Similar to @option{--exclude}, except @command{tar} will use the list of 2640patterns in the file @var{file}. @xref{exclude}. 2641 2642@opsummary{exclude-caches} 2643@item --exclude-caches 2644 2645Exclude from dump any directory containing a valid cache directory 2646tag file, but still dump the directory node and the tag file itself. 2647 2648@xref{exclude,, exclude-caches}. 2649 2650@opsummary{exclude-caches-under} 2651@item --exclude-caches-under 2652 2653Exclude from dump any directory containing a valid cache directory 2654tag file, but still dump the directory node itself. 2655 2656@xref{exclude}. 2657 2658@opsummary{exclude-caches-all} 2659@item --exclude-caches-all 2660 2661Exclude from dump any directory containing a valid cache directory 2662tag file. @xref{exclude}. 2663 2664@opsummary{exclude-ignore} 2665@item --exclude-ignore=@var{file} 2666Before dumping a directory, @command{tar} checks if it contains 2667@var{file}. If so, exclusion patterns are read from this file. 2668The patterns affect only the directory itself. @xref{exclude}. 2669 2670@opsummary{exclude-ignore-recursive} 2671@item --exclude-ignore-recursive=@var{file} 2672Before dumping a directory, @command{tar} checks if it contains 2673@var{file}. If so, exclusion patterns are read from this file. 2674The patterns affect the directory and all itssubdirectories. 2675@xref{exclude}. 2676 2677@opsummary{exclude-tag} 2678@item --exclude-tag=@var{file} 2679 2680Exclude from dump any directory containing file named @var{file}, but 2681dump the directory node and @var{file} itself. @xref{exclude,, exclude-tag}. 2682 2683@opsummary{exclude-tag-under} 2684@item --exclude-tag-under=@var{file} 2685 2686Exclude from dump the contents of any directory containing file 2687named @var{file}, but dump the directory node itself. @xref{exclude,, 2688exclude-tag-under}. 2689 2690@opsummary{exclude-tag-all} 2691@item --exclude-tag-all=@var{file} 2692 2693Exclude from dump any directory containing file named @var{file}. 2694@xref{exclude,,exclude-tag-all}. 2695 2696@opsummary{exclude-vcs} 2697@item --exclude-vcs 2698 2699Exclude from dump directories and files, that are internal for some 2700widely used version control systems. 2701 2702@xref{exclude-vcs}. 2703 2704@opsummary{exclude-vcs-ignores} 2705@item --exclude-vcs-ignores 2706Exclude files that match patterns read from VCS-specific ignore 2707files. Supported files are: @file{.cvsignore}, @file{.gitignore}, 2708@file{.bzrignore}, and @file{.hgignore}. The semantics of each file 2709is the same as for the corresponding VCS, e.g. patterns read from 2710@file{.gitignore} affect the directory and all its subdirectories. 2711@xref{exclude-vcs-ignores}. 2712 2713@opsummary{file} 2714@item --file=@var{archive} 2715@itemx -f @var{archive} 2716 2717@command{tar} will use the file @var{archive} as the @command{tar} archive it 2718performs operations on, rather than @command{tar}'s compilation dependent 2719default. @xref{file tutorial}. 2720 2721@opsummary{files-from} 2722@item --files-from=@var{file} 2723@itemx -T @var{file} 2724 2725@command{tar} will use the contents of @var{file} as a list of archive members 2726or files to operate on, in addition to those specified on the 2727command-line. @xref{files}. 2728 2729@opsummary{force-local} 2730@item --force-local 2731 2732Forces @command{tar} to interpret the file name given to @option{--file} 2733as a local file, even if it looks like a remote tape drive name. 2734@xref{local and remote archives}. 2735 2736@opsummary{format} 2737@item --format=@var{format} 2738@itemx -H @var{format} 2739 2740Selects output archive format. @var{Format} may be one of the 2741following: 2742 2743@table @samp 2744@item v7 2745Creates an archive that is compatible with Unix V7 @command{tar}. 2746 2747@item oldgnu 2748Creates an archive that is compatible with GNU @command{tar} version 27491.12 or earlier. 2750 2751@item gnu 2752Creates archive in GNU tar 1.13 format. Basically it is the same as 2753@samp{oldgnu} with the only difference in the way it handles long 2754numeric fields. 2755 2756@item ustar 2757Creates a @acronym{POSIX.1-1988} compatible archive. 2758 2759@item posix 2760Creates a @acronym{POSIX.1-2001 archive}. 2761 2762@end table 2763 2764@xref{Formats}, for a detailed discussion of these formats. 2765 2766@opsummary{full-time} 2767@item --full-time 2768This option instructs @command{tar} to print file times to their full 2769resolution. Usually this means 1-second resolution, but that depends 2770on the underlying file system. The @option{--full-time} option takes 2771effect only when detailed output (verbosity level 2 or higher) has 2772been requested using the @option{--verbose} option, e.g., when listing 2773or extracting archives: 2774 2775@smallexample 2776$ @kbd{tar -t -v --full-time -f archive.tar} 2777@end smallexample 2778 2779@noindent 2780or, when creating an archive: 2781 2782@smallexample 2783$ @kbd{tar -c -vv --full-time -f archive.tar .} 2784@end smallexample 2785 2786Notice, thar when creating the archive you need to specify 2787@option{--verbose} twice to get a detailed output (@pxref{verbose 2788tutorial}). 2789 2790@opsummary{group} 2791@item --group=@var{group} 2792 2793Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group}, 2794rather than the group from the source file. @var{group} can specify a 2795symbolic name, or a numeric @acronym{ID}, or both as 2796@var{name}:@var{id}. @xref{override}. 2797 2798Also see the @option{--group-map} option and comments for the 2799@option{--owner=@var{user}} option. 2800 2801@opsummary{group-map} 2802@item --group-map=@var{file} 2803 2804Read owner group translation map from @var{file}. This option allows to 2805translate only certain group names and/or UIDs. @xref{override}, for a 2806detailed description. When used together with @option{--group} 2807option, the latter affects only those files whose owner group is not listed 2808in the @var{file}. 2809 2810This option does not affect extraction from archives. 2811 2812@opsummary{gzip} 2813@opsummary{gunzip} 2814@opsummary{ungzip} 2815@item --gzip 2816@itemx --gunzip 2817@itemx --ungzip 2818@itemx -z 2819 2820This option tells @command{tar} to read or write archives through 2821@command{gzip}, allowing @command{tar} to directly operate on several 2822kinds of compressed archives transparently. @xref{gzip}. 2823 2824@opsummary{hard-dereference} 2825@item --hard-dereference 2826When creating an archive, dereference hard links and store the files 2827they refer to, instead of creating usual hard link members. 2828 2829@xref{hard links}. 2830 2831@opsummary{help} 2832@item --help 2833@itemx -? 2834 2835@command{tar} will print out a short message summarizing the operations and 2836options to @command{tar} and exit. @xref{help}. 2837 2838@opsummary{hole-detection} 2839@item --hole-detection=@var{method} 2840Use @var{method} to detect holes in sparse files. This option implies 2841@option{--sparse}. Valid methods are @samp{seek} and @samp{raw}. 2842Default is @samp{seek} with fallback to @samp{raw} when not 2843applicable. @xref{sparse}. 2844 2845@opsummary{ignore-case} 2846@item --ignore-case 2847Ignore case when matching member or file names with 2848patterns. @xref{controlling pattern-matching}. 2849 2850@opsummary{ignore-command-error} 2851@item --ignore-command-error 2852Ignore exit codes of subprocesses. @xref{Writing to an External Program}. 2853 2854@opsummary{ignore-failed-read} 2855@item --ignore-failed-read 2856 2857Do not exit unsuccessfully merely because an unreadable file was encountered. 2858@xref{Ignore Failed Read}. 2859 2860@opsummary{ignore-zeros} 2861@item --ignore-zeros 2862@itemx -i 2863 2864With this option, @command{tar} will ignore zeroed blocks in the 2865archive, which normally signals EOF. @xref{Reading}. 2866 2867@opsummary{incremental} 2868@item --incremental 2869@itemx -G 2870 2871Informs @command{tar} that it is working with an old 2872@acronym{GNU}-format incremental backup archive. It is intended 2873primarily for backwards compatibility only. @xref{Incremental Dumps}, 2874for a detailed discussion of incremental archives. 2875 2876@opsummary{index-file} 2877@item --index-file=@var{file} 2878 2879Send verbose output to @var{file} instead of to standard output. 2880 2881@opsummary{info-script} 2882@opsummary{new-volume-script} 2883@item --info-script=@var{command} 2884@itemx --new-volume-script=@var{command} 2885@itemx -F @var{command} 2886 2887When @command{tar} is performing multi-tape backups, @var{command} is run 2888at the end of each tape. If it exits with nonzero status, 2889@command{tar} fails immediately. @xref{info-script}, for a detailed 2890discussion of this feature. 2891 2892@opsummary{interactive} 2893@item --interactive 2894@itemx --confirmation 2895@itemx -w 2896 2897Specifies that @command{tar} should ask the user for confirmation before 2898performing potentially destructive options, such as overwriting files. 2899@xref{interactive}. 2900 2901@opsummary{keep-directory-symlink} 2902@item --keep-directory-symlink 2903 2904This option changes the behavior of tar when it encounters a symlink 2905with the same name as the directory that it is about to extract. By 2906default, in this case tar would first remove the symlink and then 2907proceed extracting the directory. 2908 2909The @option{--keep-directory-symlink} option disables this behavior 2910and instructs tar to follow symlinks to directories when extracting 2911from the archive. 2912 2913It is mainly intended to provide compatibility with the Slackware 2914installation scripts. 2915 2916@opsummary{keep-newer-files} 2917@item --keep-newer-files 2918 2919Do not replace existing files that are newer than their archive copies 2920when extracting files from an archive. 2921 2922@opsummary{keep-old-files} 2923@item --keep-old-files 2924@itemx -k 2925 2926Do not overwrite existing files when extracting files from an 2927archive. Return error if such files exist. See also 2928@ref{--skip-old-files}. 2929 2930@xref{Keep Old Files}. 2931 2932@opsummary{label} 2933@item --label=@var{name} 2934@itemx -V @var{name} 2935 2936When creating an archive, instructs @command{tar} to write @var{name} 2937as a name record in the archive. When extracting or listing archives, 2938@command{tar} will only operate on archives that have a label matching 2939the pattern specified in @var{name}. @xref{Tape Files}. 2940 2941@opsummary{level} 2942@item --level=@var{n} 2943Force incremental backup of level @var{n}. As of @GNUTAR version 2944@value{VERSION}, the option @option{--level=0} truncates the snapshot 2945file, thereby forcing the level 0 dump. Other values of @var{n} are 2946effectively ignored. @xref{--level=0}, for details and examples. 2947 2948The use of this option is valid only in conjunction with the 2949@option{--listed-incremental} option. @xref{Incremental Dumps}, 2950for a detailed description. 2951 2952@opsummary{listed-incremental} 2953@item --listed-incremental=@var{snapshot-file} 2954@itemx -g @var{snapshot-file} 2955 2956During a @option{--create} operation, specifies that the archive that 2957@command{tar} creates is a new @acronym{GNU}-format incremental 2958backup, using @var{snapshot-file} to determine which files to backup. 2959With other operations, informs @command{tar} that the archive is in 2960incremental format. @xref{Incremental Dumps}. 2961 2962@opsummary{lzip} 2963@item --lzip 2964 2965This option tells @command{tar} to read or write archives through 2966@command{lzip}. @xref{gzip}. 2967 2968@opsummary{lzma} 2969@item --lzma 2970 2971This option tells @command{tar} to read or write archives through 2972@command{lzma}. @xref{gzip}. 2973 2974@item --lzop 2975 2976This option tells @command{tar} to read or write archives through 2977@command{lzop}. @xref{gzip}. 2978 2979@opsummary{mode} 2980@item --mode=@var{permissions} 2981 2982When adding files to an archive, @command{tar} will use 2983@var{permissions} for the archive members, rather than the permissions 2984from the files. @var{permissions} can be specified either as an octal 2985number or as symbolic permissions, like with 2986@command{chmod}. @xref{override}. 2987 2988@opsummary{mtime} 2989@item --mtime=@var{date} 2990 2991When adding files to an archive, @command{tar} will use @var{date} as 2992the modification time of members when creating archives, instead of 2993their actual modification times. The value of @var{date} can be 2994either a textual date representation (@pxref{Date input formats}) or a 2995name of the existing file, starting with @samp{/} or @samp{.}. In the 2996latter case, the modification time of that file is used. @xref{override}. 2997 2998When @command{--clamp-mtime} is also specified, files with 2999modification times earlier than @var{date} will retain their actual 3000modification times, and @var{date} will only be used for files whose 3001modification times are later than @var{date}. 3002 3003@opsummary{multi-volume} 3004@item --multi-volume 3005@itemx -M 3006 3007Informs @command{tar} that it should create or otherwise operate on a 3008multi-volume @command{tar} archive. @xref{Using Multiple Tapes}. 3009 3010@opsummary{new-volume-script} 3011@item --new-volume-script 3012 3013(see @option{--info-script}) 3014 3015@opsummary{newer} 3016@item --newer=@var{date} 3017@itemx --after-date=@var{date} 3018@itemx -N 3019 3020When creating an archive, @command{tar} will only add files that have changed 3021since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it 3022is taken to be the name of a file whose data modification time specifies 3023the date. @xref{after}. 3024 3025@opsummary{newer-mtime} 3026@item --newer-mtime=@var{date} 3027 3028Like @option{--newer}, but add only files whose 3029contents have changed (as opposed to just @option{--newer}, which will 3030also back up files for which any status information has 3031changed). @xref{after}. 3032 3033@opsummary{no-acls} 3034@item --no-acls 3035Disable the POSIX ACLs support. @xref{Extended File Attributes, acls}. 3036 3037@opsummary{no-anchored} 3038@item --no-anchored 3039An exclude pattern can match any subsequence of the name's components. 3040@xref{controlling pattern-matching}. 3041 3042@opsummary{no-auto-compress} 3043@item --no-auto-compress 3044 3045Disables automatic compressed format recognition based on the archive 3046suffix. @xref{--auto-compress}. @xref{gzip}. 3047 3048@opsummary{no-check-device} 3049@item --no-check-device 3050Do not check device numbers when creating a list of modified files 3051for incremental archiving. @xref{device numbers}, for 3052a detailed description. 3053 3054@opsummary{no-delay-directory-restore} 3055@item --no-delay-directory-restore 3056 3057Modification times and permissions of extracted 3058directories are set when all files from this directory have been 3059extracted. This is the default. 3060@xref{Directory Modification Times and Permissions}. 3061 3062@opsummary{no-ignore-case} 3063@item --no-ignore-case 3064Use case-sensitive matching. 3065@xref{controlling pattern-matching}. 3066 3067@opsummary{no-ignore-command-error} 3068@item --no-ignore-command-error 3069Print warnings about subprocesses that terminated with a nonzero exit 3070code. @xref{Writing to an External Program}. 3071 3072@opsummary{no-null} 3073@item --no-null 3074 3075If the @option{--null} option was given previously, this option 3076cancels its effect, so that any following @option{--files-from} 3077options will expect their file lists to be newline-terminated. 3078 3079@opsummary{no-overwrite-dir} 3080@item --no-overwrite-dir 3081 3082Preserve metadata of existing directories when extracting files 3083from an archive. @xref{Overwrite Old Files}. 3084 3085@opsummary{no-quote-chars} 3086@item --no-quote-chars=@var{string} 3087Remove characters listed in @var{string} from the list of quoted 3088characters set by the previous @option{--quote-chars} option 3089(@pxref{quoting styles}). 3090 3091@opsummary{no-recursion} 3092@item --no-recursion 3093 3094With this option, @command{tar} will not recurse into directories. 3095@xref{recurse}. 3096 3097@opsummary{no-same-owner} 3098@item --no-same-owner 3099@itemx -o 3100 3101When extracting an archive, do not attempt to preserve the owner 3102specified in the @command{tar} archive. This the default behavior 3103for ordinary users. 3104 3105@opsummary{no-same-permissions} 3106@item --no-same-permissions 3107 3108When extracting an archive, subtract the user's umask from files from 3109the permissions specified in the archive. This is the default behavior 3110for ordinary users. 3111 3112@opsummary{no-seek} 3113@item --no-seek 3114 3115The archive media does not support seeks to arbitrary 3116locations. Usually @command{tar} determines automatically whether 3117the archive can be seeked or not. Use this option to disable this 3118mechanism. 3119 3120@opsummary{no-selinux} 3121@item --no-selinux 3122Disable SELinux context support. @xref{Extended File Attributes, SELinux}. 3123 3124@opsummary{no-unquote} 3125@item --no-unquote 3126Treat all input file or member names literally, do not interpret 3127escape sequences. @xref{input name quoting}. 3128 3129@opsummary{no-verbatim-files-from} 3130@item --no-verbatim-files-from 3131 3132Instructs @GNUTAR{} to treat each line read from a file list as if it 3133were supplied in the command line. I.e., leading and trailing 3134whitespace is removed and, if the result begins with a dash, it is 3135treated as a @GNUTAR{} command line option. 3136 3137This is default behavior. This option is provided as a way to restore 3138it after @option{--verbatim-files-from} option. 3139 3140It is implied by the @option{--no-null} option. 3141 3142@xref{no-verbatim-files-from}. 3143 3144@opsummary{no-wildcards} 3145@item --no-wildcards 3146Do not use wildcards. 3147@xref{controlling pattern-matching}. 3148 3149@opsummary{no-wildcards-match-slash} 3150@item --no-wildcards-match-slash 3151Wildcards do not match @samp{/}. 3152@xref{controlling pattern-matching}. 3153 3154@opsummary{no-xattrs} 3155@item --no-xattrs 3156Disable extended attributes support. @xref{Extended File Attributes, xattrs}. 3157 3158@opsummary{null} 3159@item --null 3160 3161When @command{tar} is using the @option{--files-from} option, this option 3162instructs @command{tar} to expect file names terminated with 3163@acronym{NUL}, and to process file names verbatim. 3164 3165This means that @command{tar} correctly works with file names that 3166contain newlines or begin with a dash. 3167 3168@xref{nul}. 3169 3170See also @ref{verbatim-files-from}. 3171 3172@opsummary{numeric-owner} 3173@item --numeric-owner 3174 3175This option will notify @command{tar} that it should use numeric user 3176and group IDs when creating a @command{tar} file, rather than names. 3177@xref{Attributes}. 3178 3179@item -o 3180The function of this option depends on the action @command{tar} is 3181performing. When extracting files, @option{-o} is a synonym for 3182@option{--no-same-owner}, i.e., it prevents @command{tar} from 3183restoring ownership of files being extracted. 3184 3185When creating an archive, it is a synonym for 3186@option{--old-archive}. This behavior is for compatibility 3187with previous versions of @GNUTAR{}, and will be 3188removed in future releases. 3189 3190@xref{Changes}, for more information. 3191 3192@opsummary{occurrence} 3193@item --occurrence[=@var{number}] 3194 3195This option can be used in conjunction with one of the subcommands 3196@option{--delete}, @option{--diff}, @option{--extract} or 3197@option{--list} when a list of files is given either on the command 3198line or via @option{-T} option. 3199 3200This option instructs @command{tar} to process only the @var{number}th 3201occurrence of each named file. @var{Number} defaults to 1, so 3202 3203@smallexample 3204tar -x -f archive.tar --occurrence filename 3205@end smallexample 3206 3207@noindent 3208will extract the first occurrence of the member @file{filename} from @file{archive.tar} 3209and will terminate without scanning to the end of the archive. 3210 3211@opsummary{old-archive} 3212@item --old-archive 3213Synonym for @option{--format=v7}. 3214 3215@opsummary{one-file-system} 3216@item --one-file-system 3217Used when creating an archive. Prevents @command{tar} from recursing into 3218directories that are on different file systems from the current 3219directory. 3220 3221@opsummary{one-top-level} 3222@item --one-top-level[=@var{dir}] 3223Tells @command{tar} to create a new directory beneath the extraction directory 3224(or the one passed to @option{-C}) and use it to guard against 3225tarbombs. In the absence of @var{dir} argument, the name of the new directory 3226will be equal to the base name of the archive (file name minus the 3227archive suffix, if recognized). Any member names that do not begin 3228with that directory name (after 3229transformations from @option{--transform} and 3230@option{--strip-components}) will be prefixed with it. Recognized 3231file name suffixes are @samp{.tar}, and any compression suffixes 3232recognizable by @xref{--auto-compress}. 3233 3234@opsummary{overwrite} 3235@item --overwrite 3236 3237Overwrite existing files and directory metadata when extracting files 3238from an archive. @xref{Overwrite Old Files}. 3239 3240@opsummary{overwrite-dir} 3241@item --overwrite-dir 3242 3243Overwrite the metadata of existing directories when extracting files 3244from an archive. @xref{Overwrite Old Files}. 3245 3246@opsummary{owner} 3247@item --owner=@var{user} 3248 3249Specifies that @command{tar} should use @var{user} as the owner of members 3250when creating archives, instead of the user associated with the source 3251file. @var{user} can specify a symbolic name, or a numeric 3252@acronym{ID}, or both as @var{name}:@var{id}. 3253@xref{override}. 3254 3255This option does not affect extraction from archives. See also 3256@option{--owner-map}, below. 3257 3258@opsummary{owner-map} 3259@item --owner-map=@var{file} 3260 3261Read owner translation map from @var{file}. This option allows to 3262translate only certain owner names or UIDs. @xref{override}, for a 3263detailed description. When used together with @option{--owner} 3264option, the latter affects only those files whose owner is not listed 3265in the @var{file}. 3266 3267This option does not affect extraction from archives. 3268 3269@opsummary{pax-option} 3270@item --pax-option=@var{keyword-list} 3271This option enables creation of the archive in @acronym{POSIX.1-2001} 3272format (@pxref{posix}) and modifies the way @command{tar} handles the 3273extended header keywords. @var{Keyword-list} is a comma-separated 3274list of keyword options. @xref{PAX keywords}, for a detailed 3275discussion. 3276 3277@opsummary{portability} 3278@item --portability 3279@itemx --old-archive 3280Synonym for @option{--format=v7}. 3281 3282@opsummary{posix} 3283@item --posix 3284Same as @option{--format=posix}. 3285 3286@opsummary{preserve-order} 3287@item --preserve-order 3288 3289(See @option{--same-order}; @pxref{Reading}.) 3290 3291@opsummary{preserve-permissions} 3292@opsummary{same-permissions} 3293@item --preserve-permissions 3294@itemx --same-permissions 3295@itemx -p 3296 3297When @command{tar} is extracting an archive, it normally subtracts the 3298users' umask from the permissions specified in the archive and uses 3299that number as the permissions to create the destination file. 3300Specifying this option instructs @command{tar} that it should use the 3301permissions directly from the archive. @xref{Setting Access Permissions}. 3302 3303@opsummary{quote-chars} 3304@item --quote-chars=@var{string} 3305Always quote characters from @var{string}, even if the selected 3306quoting style would not quote them (@pxref{quoting styles}). 3307 3308@opsummary{quoting-style} 3309@item --quoting-style=@var{style} 3310Set quoting style to use when printing member and file names 3311(@pxref{quoting styles}). Valid @var{style} values are: 3312@code{literal}, @code{shell}, @code{shell-always}, @code{c}, 3313@code{escape}, @code{locale}, and @code{clocale}. Default quoting 3314style is @code{escape}, unless overridden while configuring the 3315package. 3316 3317@opsummary{read-full-records} 3318@item --read-full-records 3319@itemx -B 3320 3321Specifies that @command{tar} should reblock its input, for reading 3322from pipes on systems with buggy implementations. @xref{Reading}. 3323 3324@opsummary{record-size} 3325@item --record-size=@var{size}[@var{suf}] 3326 3327Instructs @command{tar} to use @var{size} bytes per record when accessing the 3328archive. The argument can be suffixed with a @dfn{size suffix}, e.g. 3329@option{--record-size=10K} for 10 Kilobytes. @xref{size-suffixes}, 3330for a list of valid suffixes. @xref{Blocking Factor}, for a detailed 3331description of this option. 3332 3333@opsummary{recursion} 3334@item --recursion 3335 3336With this option, @command{tar} recurses into directories (default). 3337@xref{recurse}. 3338 3339@opsummary{recursive-unlink} 3340@item --recursive-unlink 3341 3342Remove existing 3343directory hierarchies before extracting directories of the same name 3344from the archive. @xref{Recursive Unlink}. 3345 3346@opsummary{remove-files} 3347@item --remove-files 3348 3349Directs @command{tar} to remove the source file from the file system after 3350appending it to an archive. @xref{remove files}. 3351 3352@opsummary{restrict} 3353@item --restrict 3354 3355Disable use of some potentially harmful @command{tar} options. 3356Currently this option disables shell invocation from multi-volume menu 3357(@pxref{Using Multiple Tapes}). 3358 3359@opsummary{rmt-command} 3360@item --rmt-command=@var{cmd} 3361 3362Notifies @command{tar} that it should use @var{cmd} instead of 3363the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}). 3364 3365@opsummary{rsh-command} 3366@item --rsh-command=@var{cmd} 3367 3368Notifies @command{tar} that is should use @var{cmd} to communicate with remote 3369devices. @xref{Device}. 3370 3371@opsummary{same-order} 3372@item --same-order 3373@itemx --preserve-order 3374@itemx -s 3375 3376This option is an optimization for @command{tar} when running on machines with 3377small amounts of memory. It informs @command{tar} that the list of file 3378arguments has already been sorted to match the order of files in the 3379archive. @xref{Reading}. 3380 3381@opsummary{same-owner} 3382@item --same-owner 3383 3384When extracting an archive, @command{tar} will attempt to preserve the owner 3385specified in the @command{tar} archive with this option present. 3386This is the default behavior for the superuser; this option has an 3387effect only for ordinary users. @xref{Attributes}. 3388 3389@opsummary{same-permissions} 3390@item --same-permissions 3391 3392(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.) 3393 3394@opsummary{seek} 3395@item --seek 3396@itemx -n 3397 3398Assume that the archive media supports seeks to arbitrary 3399locations. Usually @command{tar} determines automatically whether 3400the archive can be seeked or not. This option is intended for use 3401in cases when such recognition fails. It takes effect only if the 3402archive is open for reading (e.g. with @option{--list} or 3403@option{--extract} options). 3404 3405@opsummary{selinux} 3406@item --selinux 3407Enable the SELinux context support. 3408@xref{Extended File Attributes, selinux}. 3409 3410@opsummary{show-defaults} 3411@item --show-defaults 3412 3413Displays the default options used by @command{tar} and exits 3414successfully. This option is intended for use in shell scripts. 3415Here is an example of what you can see using this option: 3416 3417@smallexample 3418$ @kbd{tar --show-defaults} 3419--format=gnu -f- -b20 --quoting-style=escape 3420--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh 3421@end smallexample 3422 3423@noindent 3424Notice, that this option outputs only one line. The example output 3425above has been split to fit page boundaries. @xref{defaults}. 3426 3427@opsummary{show-omitted-dirs} 3428@item --show-omitted-dirs 3429 3430Instructs @command{tar} to mention the directories it is skipping when 3431operating on a @command{tar} archive. @xref{show-omitted-dirs}. 3432 3433@opsummary{show-snapshot-field-ranges} 3434@item --show-snapshot-field-ranges 3435 3436Displays the range of values allowed by this version of @command{tar} 3437for each field in the snapshot file, then exits successfully. 3438@xref{Snapshot Files}. 3439 3440@opsummary{show-transformed-names} 3441@opsummary{show-stored-names} 3442@item --show-transformed-names 3443@itemx --show-stored-names 3444 3445Display file or member names after applying any transformations 3446(@pxref{transform}). In particular, when used in conjunction with one of 3447the archive creation operations it instructs @command{tar} to list the 3448member names stored in the archive, as opposed to the actual file 3449names. @xref{listing member and file names}. 3450 3451@opsummary{skip-old-files} 3452@item --skip-old-files 3453 3454Do not overwrite existing files when extracting files from an 3455archive. @xref{Keep Old Files}. 3456 3457This option differs from @option{--keep-old-files} in that it does not 3458treat such files as an error, instead it just silently avoids 3459overwriting them. 3460 3461The @option{--warning=existing-file} option can be used together with 3462this option to produce warning messages about existing old files 3463(@pxref{warnings}). 3464 3465@opsummary{sort} 3466@item --sort=@var{order} 3467Specify the directory sorting order when reading directories. 3468@var{Order} may be one of the following: 3469 3470@table @samp 3471@item none 3472No directory sorting is performed. This is the default. 3473 3474@item name 3475Sort the directory entries on name. The operating system may deliver 3476directory entries in a more or less random order, and sorting them 3477makes archive creation reproducible. 3478 3479@item inode 3480Sort the directory entries on inode number. Sorting directories on 3481inode number may reduce the amount of disk seek operations when 3482creating an archive for some file systems. 3483 3484@end table 3485 3486@opsummary{sparse} 3487@item --sparse 3488@itemx -S 3489 3490Invokes a @acronym{GNU} extension when adding files to an archive that handles 3491sparse files efficiently. @xref{sparse}. 3492 3493@opsummary{sparse-version} 3494@item --sparse-version=@var{version} 3495 3496Specifies the @dfn{format version} to use when archiving sparse 3497files. Implies @option{--sparse}. @xref{sparse}. For the description 3498of the supported sparse formats, @xref{Sparse Formats}. 3499 3500@opsummary{starting-file} 3501@item --starting-file=@var{name} 3502@itemx -K @var{name} 3503 3504This option affects extraction only; @command{tar} will skip extracting 3505files in the archive until it finds one that matches @var{name}. 3506@xref{Scarce}. 3507 3508@opsummary{strip-components} 3509@item --strip-components=@var{number} 3510Strip given @var{number} of leading components from file names before 3511extraction. For example, if archive @file{archive.tar} contained 3512@file{/some/file/name}, then running 3513 3514@smallexample 3515tar --extract --file archive.tar --strip-components=2 3516@end smallexample 3517 3518@noindent 3519would extract this file to file @file{name}. 3520 3521@xref{transform}. 3522 3523@opsummary{suffix} 3524@item --suffix=@var{suffix} 3525 3526Alters the suffix @command{tar} uses when backing up files from the default 3527@samp{~}. @xref{backup}. 3528 3529@opsummary{tape-length} 3530@item --tape-length=@var{num}[@var{suf}] 3531@itemx -L @var{num}[@var{suf}] 3532 3533Specifies the length of tapes that @command{tar} is writing as being 3534@w{@var{num} x 1024} bytes long. If optional @var{suf} is given, it 3535specifies a multiplicative factor to be used instead of 1024. For 3536example, @samp{-L2M} means 2 megabytes. @xref{size-suffixes}, for a 3537list of allowed suffixes. @xref{Using Multiple Tapes}, for a detailed 3538discussion of this option. 3539 3540@opsummary{test-label} 3541@item --test-label 3542 3543Reads the volume label. If an argument is specified, test whether it 3544matches the volume label. @xref{--test-label option}. 3545 3546@opsummary{to-command} 3547@item --to-command=@var{command} 3548 3549During extraction @command{tar} will pipe extracted files to the 3550standard input of @var{command}. @xref{Writing to an External Program}. 3551 3552@opsummary{to-stdout} 3553@item --to-stdout 3554@itemx -O 3555 3556During extraction, @command{tar} will extract files to stdout rather 3557than to the file system. @xref{Writing to Standard Output}. 3558 3559@opsummary{totals} 3560@item --totals[=@var{signo}] 3561 3562Displays the total number of bytes transferred when processing an 3563archive. If an argument is given, these data are displayed on 3564request, when signal @var{signo} is delivered to @command{tar}. 3565@xref{totals}. 3566 3567@opsummary{touch} 3568@item --touch 3569@itemx -m 3570 3571Sets the data modification time of extracted files to the extraction time, 3572rather than the data modification time stored in the archive. 3573@xref{Data Modification Times}. 3574 3575@opsummary{transform} 3576@opsummary{xform} 3577@item --transform=@var{sed-expr} 3578@itemx --xform=@var{sed-expr} 3579Transform file or member names using @command{sed} replacement expression 3580@var{sed-expr}. For example, 3581 3582@smallexample 3583$ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .} 3584@end smallexample 3585 3586@noindent 3587will add to @file{archive} files from the current working directory, 3588replacing initial @samp{./} prefix with @samp{usr/}. For the detailed 3589discussion, @xref{transform}. 3590 3591To see transformed member names in verbose listings, use 3592@option{--show-transformed-names} option 3593(@pxref{show-transformed-names}). 3594 3595@opsummary{uncompress} 3596@item --uncompress 3597 3598(See @option{--compress}, @pxref{gzip}) 3599 3600@opsummary{ungzip} 3601@item --ungzip 3602 3603(See @option{--gzip}, @pxref{gzip}) 3604 3605@opsummary{unlink-first} 3606@item --unlink-first 3607@itemx -U 3608 3609Directs @command{tar} to remove the corresponding file from the file 3610system before extracting it from the archive. @xref{Unlink First}. 3611 3612@opsummary{unquote} 3613@item --unquote 3614Enable unquoting input file or member names (default). @xref{input 3615name quoting}. 3616 3617@opsummary{use-compress-program} 3618@item --use-compress-program=@var{prog} 3619@itemx -I=@var{prog} 3620 3621Instructs @command{tar} to access the archive through @var{prog}, which is 3622presumed to be a compression program of some sort. @xref{gzip}. 3623 3624@opsummary{utc} 3625@item --utc 3626 3627Display file modification dates in @acronym{UTC}. This option implies 3628@option{--verbose}. 3629 3630@opsummary{verbatim-files-from} 3631@item --verbatim-files-from 3632 3633Instructs @GNUTAR{} to treat each line read from a file list as a file 3634name, even if it starts with a dash. 3635 3636File lists are supplied with the @option{--files-from} (@option{-T}) 3637option. By default, each line read from a file list is first trimmed 3638off the leading and trailing whitespace and, if the result begins with 3639a dash, it is treated as a @GNUTAR{} command line option. 3640 3641Use the @option{--verbatim-files-from} option to disable this special 3642handling. This facilitates the use of @command{tar} with file lists 3643created by @command{file} command. 3644 3645This option affects all @option{--files-from} options that occur after 3646it in the command line. Its effect is reverted by the 3647@option{--no-verbatim-files-from} option. 3648 3649This option is implied by the @option{--null} option. 3650 3651@xref{verbatim-files-from}. 3652 3653@opsummary{verbose} 3654@item --verbose 3655@itemx -v 3656 3657Specifies that @command{tar} should be more verbose about the 3658operations it is performing. This option can be specified multiple 3659times for some operations to increase the amount of information displayed. 3660@xref{verbose}. 3661 3662@opsummary{verify} 3663@item --verify 3664@itemx -W 3665 3666Verifies that the archive was correctly written when creating an 3667archive. @xref{verify}. 3668 3669@opsummary{version} 3670@item --version 3671 3672Print information about the program's name, version, origin and legal 3673status, all on standard output, and then exit successfully. 3674@xref{help}. 3675 3676@opsummary{volno-file} 3677@item --volno-file=@var{file} 3678 3679Used in conjunction with @option{--multi-volume}. @command{tar} will 3680keep track of which volume of a multi-volume archive it is working in 3681@var{file}. @xref{volno-file}. 3682 3683@opsummary{warning} 3684@item --warning=@var{keyword} 3685 3686Enable or disable warning messages identified by @var{keyword}. The 3687messages are suppressed if @var{keyword} is prefixed with @samp{no-}. 3688@xref{warnings}. 3689 3690@opsummary{wildcards} 3691@item --wildcards 3692Use wildcards when matching member names with patterns. 3693@xref{controlling pattern-matching}. 3694 3695@opsummary{wildcards-match-slash} 3696@item --wildcards-match-slash 3697Wildcards match @samp{/}. 3698@xref{controlling pattern-matching}. 3699 3700@opsummary{xattrs} 3701@item --xattrs 3702Enable extended attributes support. @xref{Extended File Attributes, xattrs}. 3703 3704@opsummary{xattrs-exclude} 3705@item --xattrs-exclude=@var{pattern} 3706Specify exclude pattern for xattr keys. 3707@xref{Extended File Attributes, xattrs-exclude}. 3708 3709@opsummary{xattrs-include} 3710@item --xattrs-include=@var{pattern}. 3711Specify include pattern for xattr keys. @var{pattern} is a globbing 3712pattern, e.g. @samp{--xattrs-include='user.*'} to include 3713only attributes from the user namespace. 3714@xref{Extended File Attributes, xattrs-include}. 3715 3716@opsummary{xz} 3717@item --xz 3718@itemx -J 3719Use @command{xz} for compressing or decompressing the archives. @xref{gzip}. 3720 3721@item --zstd 3722Use @command{zstd} for compressing or decompressing the archives. @xref{gzip}. 3723 3724@end table 3725 3726@node Short Option Summary 3727@subsection Short Options Cross Reference 3728 3729Here is an alphabetized list of all of the short option forms, matching 3730them with the equivalent long option. 3731 3732@multitable @columnfractions 0.20 0.80 3733@headitem Short Option @tab Reference 3734 3735@item -A @tab @ref{--concatenate}. 3736 3737@item -B @tab @ref{--read-full-records}. 3738 3739@item -C @tab @ref{--directory}. 3740 3741@item -F @tab @ref{--info-script}. 3742 3743@item -G @tab @ref{--incremental}. 3744 3745@item -J @tab @ref{--xz}. 3746 3747@item -K @tab @ref{--starting-file}. 3748 3749@item -L @tab @ref{--tape-length}. 3750 3751@item -M @tab @ref{--multi-volume}. 3752 3753@item -N @tab @ref{--newer}. 3754 3755@item -O @tab @ref{--to-stdout}. 3756 3757@item -P @tab @ref{--absolute-names}. 3758 3759@item -R @tab @ref{--block-number}. 3760 3761@item -S @tab @ref{--sparse}. 3762 3763@item -T @tab @ref{--files-from}. 3764 3765@item -U @tab @ref{--unlink-first}. 3766 3767@item -V @tab @ref{--label}. 3768 3769@item -W @tab @ref{--verify}. 3770 3771@item -X @tab @ref{--exclude-from}. 3772 3773@item -Z @tab @ref{--compress}. 3774 3775@item -b @tab @ref{--blocking-factor}. 3776 3777@item -c @tab @ref{--create}. 3778 3779@item -d @tab @ref{--compare}. 3780 3781@item -f @tab @ref{--file}. 3782 3783@item -g @tab @ref{--listed-incremental}. 3784 3785@item -h @tab @ref{--dereference}. 3786 3787@item -i @tab @ref{--ignore-zeros}. 3788 3789@item -j @tab @ref{--bzip2}. 3790 3791@item -k @tab @ref{--keep-old-files}. 3792 3793@item -l @tab @ref{--check-links}. 3794 3795@item -m @tab @ref{--touch}. 3796 3797@item -o @tab When extracting, same as @ref{--no-same-owner}. When creating, 3798-- @ref{--old-archive}. 3799 3800The latter usage is deprecated. It is retained for compatibility with 3801the earlier versions of @GNUTAR{}. In future releases 3802@option{-o} will be equivalent to @option{--no-same-owner} only. 3803 3804@item -p @tab @ref{--preserve-permissions}. 3805 3806@item -r @tab @ref{--append}. 3807 3808@item -s @tab @ref{--same-order}. 3809 3810@item -t @tab @ref{--list}. 3811 3812@item -u @tab @ref{--update}. 3813 3814@item -v @tab @ref{--verbose}. 3815 3816@item -w @tab @ref{--interactive}. 3817 3818@item -x @tab @ref{--extract}. 3819 3820@item -z @tab @ref{--gzip}. 3821 3822@end multitable 3823 3824@node Position-Sensitive Options 3825@subsection Position-Sensitive Options 3826 3827Some @GNUTAR{} options can be used multiple times in the same 3828invocation and affect all arguments that appear after them. These are 3829options that control how file names are selected and what kind of 3830pattern matching is used. 3831 3832The most obvious example is the @option{-C} option. It instructs @command{tar} 3833to change to the directory given as its argument prior to processing 3834the rest of command line (@pxref{directory}). Thus, in the following 3835command: 3836 3837@example 3838@kbd{tar -c -f a.tar -C /etc passwd -C /var log spool} 3839@end example 3840 3841@noindent 3842the file @file{passwd} will be searched in the directory @file{/etc}, 3843and files @file{log} and @file{spool} -- in @file{/var}. 3844 3845These options can also be used in a file list supplied with the 3846@option{--files-from} (@option{-T}) option (@pxref{files}). In that 3847case they affect all files (patterns) appearing in that file after 3848them and remain in effect for any arguments processed after that file. 3849For example, if the file @file{list.txt} contained: 3850 3851@example 3852README 3853-C src 3854main.c 3855@end example 3856 3857@noindent 3858and @command{tar} were invoked as follows: 3859 3860@example 3861@kbd{tar -c -f a.tar -T list.txt Makefile} 3862@end example 3863 3864@noindent 3865then the file @file{README} would be looked up in the current working 3866directory, and files @file{main.c} and @file{Makefile} would be looked 3867up in the directory @file{src}. 3868 3869Many options can be prefixed with @option{--no-} to cancel the effect 3870of the original option. 3871 3872For example, the @option{--recursion} option controls whether to 3873recurse in the subdirectories. It's counterpart 3874@option{--no-recursion} disables this. Consider the command below. It will 3875store in the archive the directory @file{/usr} with all files and 3876directories that are located in it as well as any files and 3877directories in @file{/var}, without recursing into them@footnote{The @option{--recursion} 3878option is the default and is used here for clarity. The same example 3879can be written as: 3880 3881@example 3882tar -cf a.tar /usr --no-recursion /var/* 3883@end example 3884}: 3885 3886@example 3887tar -cf a.tar --recursion /usr --no-recursion /var/* 3888@end example 3889 3890During archive creation, @GNUTAR{} keeps track of positional options 3891used and arguments affected by them. If it finds out that any such 3892options are used in an obviously erroneous way, the fact is reported 3893and exit code is set to 2. E.g.: 3894 3895@example 3896@group 3897$ @kbd{tar -cf a.tar . --exclude '*.o'} 3898tar: The following options were used after any non-optional 3899arguments in archive create or update mode. These options are 3900positional and affect only arguments that follow them. Please, 3901rearrange them properly. 3902tar: --exclude '*.o' has no effect 3903tar: Exiting with failure status due to previous errors 3904@end group 3905@end example 3906 3907The following table summarizes all position-sensitive options. 3908 3909@table @option 3910@item --directory=@var{dir} 3911@itemx -C @var{dir} 3912@xref{directory}. 3913 3914@item --null 3915@itemx --no-null 3916@xref{nul}. 3917 3918@item --unquote 3919@itemx --no-unquote 3920@xref{input name quoting}. 3921 3922@item --verbatim-files-from 3923@itemx --no-verbatim-files-from 3924@xref{verbatim-files-from}. 3925 3926@item --recursion 3927@itemx --no-recursion 3928@xref{recurse}. 3929 3930@item --anchored 3931@itemx --no-anchored 3932@xref{anchored patterns}. 3933 3934@item --ignore-case 3935@itemx --no-ignore-case 3936@xref{case-insensitive matches}. 3937 3938@item --wildcards 3939@itemx --no-wildcards 3940@xref{controlling pattern-matching}. 3941 3942@item --wildcards-match-slash 3943@itemx --no-wildcards-match-slash 3944@xref{controlling pattern-matching}. 3945 3946@item --exclude 3947@xref{exclude}. 3948 3949@item --exclude-from 3950@itemx -X 3951@itemx --exclude-caches 3952@itemx --exclude-caches-under 3953@itemx --exclude-caches-all 3954@itemx --exclude-tag 3955@itemx --exclude-ignore 3956@itemx --exclude-ignore-recursive 3957@itemx --exclude-tag-under 3958@itemx --exclude-tag-all 3959@itemx --exclude-vcs 3960@itemx --exclude-vcs-ignores 3961@itemx --exclude-backups 3962@xref{exclude}. 3963@end table 3964 3965@node help 3966@section @GNUTAR{} documentation 3967 3968@cindex Getting program version number 3969@opindex version 3970@cindex Version of the @command{tar} program 3971Being careful, the first thing is really checking that you are using 3972@GNUTAR{}, indeed. The @option{--version} option 3973causes @command{tar} to print information about its name, version, 3974origin and legal status, all on standard output, and then exit 3975successfully. For example, @w{@samp{tar --version}} might print: 3976 3977@smallexample 3978tar (GNU tar) @value{VERSION} 3979Copyright (C) 2013-2020 Free Software Foundation, Inc. 3980License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. 3981This is free software: you are free to change and redistribute it. 3982There is NO WARRANTY, to the extent permitted by law. 3983 3984Written by John Gilmore and Jay Fenlason. 3985@end smallexample 3986 3987@noindent 3988The first occurrence of @samp{tar} in the result above is the program 3989name in the package (for example, @command{rmt} is another program), 3990while the second occurrence of @samp{tar} is the name of the package 3991itself, containing possibly many programs. The package is currently 3992named @samp{tar}, after the name of the main program it 3993contains@footnote{There are plans to merge the @command{cpio} and 3994@command{tar} packages into a single one which would be called 3995@code{paxutils}. So, who knows if, one of this days, the 3996@option{--version} would not output @w{@samp{tar (@acronym{GNU} 3997paxutils) 3.2}}.}. 3998 3999@cindex Obtaining help 4000@cindex Listing all @command{tar} options 4001@xopindex{help, introduction} 4002Another thing you might want to do is checking the spelling or meaning 4003of some particular @command{tar} option, without resorting to this 4004manual, for once you have carefully read it. @GNUTAR{} 4005has a short help feature, triggerable through the 4006@option{--help} option. By using this option, @command{tar} will 4007print a usage message listing all available options on standard 4008output, then exit successfully, without doing anything else and 4009ignoring all other options. Even if this is only a brief summary, it 4010may be several screens long. So, if you are not using some kind of 4011scrollable window, you might prefer to use something like: 4012 4013@smallexample 4014$ @kbd{tar --help | less} 4015@end smallexample 4016 4017@noindent 4018presuming, here, that you like using @command{less} for a pager. Other 4019popular pagers are @command{more} and @command{pg}. If you know about some 4020@var{keyword} which interests you and do not want to read all the 4021@option{--help} output, another common idiom is doing: 4022 4023@smallexample 4024tar --help | grep @var{keyword} 4025@end smallexample 4026 4027@noindent 4028for getting only the pertinent lines. Notice, however, that some 4029@command{tar} options have long description lines and the above 4030command will list only the first of them. 4031 4032The exact look of the option summary displayed by @kbd{tar --help} is 4033configurable. @xref{Configuring Help Summary}, for a detailed description. 4034 4035@opindex usage 4036If you only wish to check the spelling of an option, running @kbd{tar 4037--usage} may be a better choice. This will display a terse list of 4038@command{tar} options without accompanying explanations. 4039 4040The short help output is quite succinct, and you might have to get 4041back to the full documentation for precise points. If you are reading 4042this paragraph, you already have the @command{tar} manual in some 4043form. This manual is available in a variety of forms from 4044@url{http://www.gnu.org/software/tar/manual}. It may be printed out of the @GNUTAR{} 4045distribution, provided you have @TeX{} already installed somewhere, 4046and a laser printer around. Just configure the distribution, execute 4047the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the 4048usual way (contact your local guru to know how). If @GNUTAR{} 4049has been conveniently installed at your place, this 4050manual is also available in interactive, hypertextual form as an Info 4051file. Just call @w{@samp{info tar}} or, if you do not have the 4052@command{info} program handy, use the Info reader provided within 4053@acronym{GNU} Emacs, calling @samp{tar} from the main Info menu. 4054 4055There is currently no @code{man} page for @GNUTAR{}. 4056If you observe such a @code{man} page on the system you are running, 4057either it does not belong to @GNUTAR{}, or it has not 4058been produced by @acronym{GNU}. Some package maintainers convert 4059@kbd{tar --help} output to a man page, using @command{help2man}. In 4060any case, please bear in mind that the authoritative source of 4061information about @GNUTAR{} is this Texinfo documentation. 4062 4063@node defaults 4064@section Obtaining @GNUTAR{} default values 4065 4066@opindex show-defaults 4067@GNUTAR{} has some predefined defaults that are used when you do not 4068explicitly specify another values. To obtain a list of such 4069defaults, use @option{--show-defaults} option. This will output the 4070values in the form of @command{tar} command line options: 4071 4072@smallexample 4073@group 4074$ @kbd{tar --show-defaults} 4075--format=gnu -f- -b20 --quoting-style=escape 4076--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh 4077@end group 4078@end smallexample 4079 4080@noindent 4081Notice, that this option outputs only one line. The example output above 4082has been split to fit page boundaries. 4083 4084@noindent 4085The above output shows that this version of @GNUTAR{} defaults to 4086using @samp{gnu} archive format (@pxref{Formats}), it uses standard 4087output as the archive, if no @option{--file} option has been given 4088(@pxref{file tutorial}), the default blocking factor is 20 4089(@pxref{Blocking Factor}). It also shows the default locations where 4090@command{tar} will look for @command{rmt} and @command{rsh} binaries. 4091 4092@node verbose 4093@section Checking @command{tar} progress 4094 4095Typically, @command{tar} performs most operations without reporting any 4096information to the user except error messages. When using @command{tar} 4097with many options, particularly ones with complicated or 4098difficult-to-predict behavior, it is possible to make serious mistakes. 4099@command{tar} provides several options that make observing @command{tar} 4100easier. These options cause @command{tar} to print information as it 4101progresses in its job, and you might want to use them just for being 4102more careful about what is going on, or merely for entertaining 4103yourself. If you have encountered a problem when operating on an 4104archive, however, you may need more information than just an error 4105message in order to solve the problem. The following options can be 4106helpful diagnostic tools. 4107 4108@cindex Verbose operation 4109@opindex verbose 4110Normally, the @option{--list} (@option{-t}) command to list an archive 4111prints just the file names (one per line) and the other commands are 4112silent. When used with most operations, the @option{--verbose} 4113(@option{-v}) option causes @command{tar} to print the name of each 4114file or archive member as it is processed. This and the other options 4115which make @command{tar} print status information can be useful in 4116monitoring @command{tar}. 4117 4118With @option{--create} or @option{--extract}, @option{--verbose} used 4119once just prints the names of the files or members as they are processed. 4120Using it twice causes @command{tar} to print a longer listing 4121(@xref{verbose member listing}, for the description) for each member. 4122Since @option{--list} already prints the names of the members, 4123@option{--verbose} used once with @option{--list} causes @command{tar} 4124to print an @samp{ls -l} type listing of the files in the archive. 4125The following examples both extract members with long list output: 4126 4127@smallexample 4128$ @kbd{tar --extract --file=archive.tar --verbose --verbose} 4129$ @kbd{tar xvvf archive.tar} 4130@end smallexample 4131 4132Verbose output appears on the standard output except when an archive is 4133being written to the standard output, as with @samp{tar --create 4134--file=- --verbose} (@samp{tar cvf -}, or even @samp{tar cv}---if the 4135installer let standard output be the default archive). In that case 4136@command{tar} writes verbose output to the standard error stream. 4137 4138If @option{--index-file=@var{file}} is specified, @command{tar} sends 4139verbose output to @var{file} rather than to standard output or standard 4140error. 4141 4142@anchor{totals} 4143@cindex Obtaining total status information 4144@opindex totals 4145The @option{--totals} option causes @command{tar} to print on the 4146standard error the total amount of bytes transferred when processing 4147an archive. When creating or appending to an archive, this option 4148prints the number of bytes written to the archive and the average 4149speed at which they have been written, e.g.: 4150 4151@smallexample 4152@group 4153$ @kbd{tar -c -f archive.tar --totals /home} 4154Total bytes written: 7924664320 (7.4GiB, 85MiB/s) 4155@end group 4156@end smallexample 4157 4158When reading an archive, this option displays the number of bytes 4159read: 4160 4161@smallexample 4162@group 4163$ @kbd{tar -x -f archive.tar --totals} 4164Total bytes read: 7924664320 (7.4GiB, 95MiB/s) 4165@end group 4166@end smallexample 4167 4168Finally, when deleting from an archive, the @option{--totals} option 4169displays both numbers plus number of bytes removed from the archive: 4170 4171@smallexample 4172@group 4173$ @kbd{tar --delete -f foo.tar --totals --wildcards '*~'} 4174Total bytes read: 9543680 (9.2MiB, 201MiB/s) 4175Total bytes written: 3829760 (3.7MiB, 81MiB/s) 4176Total bytes deleted: 1474048 4177@end group 4178@end smallexample 4179 4180You can also obtain this information on request. When 4181@option{--totals} is used with an argument, this argument is 4182interpreted as a symbolic name of a signal, upon delivery of which the 4183statistics is to be printed: 4184 4185@table @option 4186@item --totals=@var{signo} 4187Print statistics upon delivery of signal @var{signo}. Valid arguments 4188are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and 4189@code{SIGUSR2}. Shortened names without @samp{SIG} prefix are also 4190accepted. 4191@end table 4192 4193Both forms of @option{--totals} option can be used simultaneously. 4194Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to 4195extract all members from its default archive and print statistics 4196after finishing the extraction, as well as when receiving signal 4197@code{SIGUSR1}. 4198 4199@anchor{Progress information} 4200@cindex Progress information 4201The @option{--checkpoint} option prints an occasional message 4202as @command{tar} reads or writes the archive. It is designed for 4203those who don't need the more detailed (and voluminous) output of 4204@option{--block-number} (@option{-R}), but do want visual confirmation 4205that @command{tar} is actually making forward progress. By default it 4206prints a message each 10 records read or written. This can be changed 4207by giving it a numeric argument after an equal sign: 4208 4209@smallexample 4210$ @kbd{tar -c --checkpoint=1000} /var 4211tar: Write checkpoint 1000 4212tar: Write checkpoint 2000 4213tar: Write checkpoint 3000 4214@end smallexample 4215 4216This example shows the default checkpoint message used by 4217@command{tar}. If you place a dot immediately after the equal 4218sign, it will print a @samp{.} at each checkpoint@footnote{This is 4219actually a shortcut for @option{--checkpoint=@var{n} 4220--checkpoint-action=dot}. @xref{checkpoints, dot}.}. For example: 4221 4222@smallexample 4223$ @kbd{tar -c --checkpoint=.1000} /var 4224... 4225@end smallexample 4226 4227The @option{--checkpoint} option provides a flexible mechanism for 4228executing arbitrary actions upon hitting checkpoints, see the next 4229section (@pxref{checkpoints}), for more information on it. 4230 4231@opindex show-omitted-dirs 4232@anchor{show-omitted-dirs} 4233The @option{--show-omitted-dirs} option, when reading an archive---with 4234@option{--list} or @option{--extract}, for example---causes a message 4235to be printed for each directory in the archive which is skipped. 4236This happens regardless of the reason for skipping: the directory might 4237not have been named on the command line (implicitly or explicitly), 4238it might be excluded by the use of the 4239@option{--exclude=@var{pattern}} option, or some other reason. 4240 4241@opindex block-number 4242@cindex Block number where error occurred 4243@anchor{block-number} 4244If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along with 4245every message it would normally produce, the block number within the 4246archive where the message was triggered. Also, supplementary messages 4247are triggered when reading blocks full of NULs, or when hitting end of 4248file on the archive. As of now, if the archive is properly terminated 4249with a NUL block, the reading of the file may stop before end of file 4250is met, so the position of end of file will not usually show when 4251@option{--block-number} (@option{-R}) is used. Note that @GNUTAR{} 4252drains the archive before exiting when reading the 4253archive from a pipe. 4254 4255@cindex Error message, block number of 4256This option is especially useful when reading damaged archives, since 4257it helps pinpoint the damaged sections. It can also be used with 4258@option{--list} (@option{-t}) when listing a file-system backup tape, allowing you to 4259choose among several backup tapes when retrieving a file later, in 4260favor of the tape where the file appears earliest (closest to the 4261front of the tape). @xref{backup}. 4262 4263@node checkpoints 4264@section Checkpoints 4265@cindex checkpoints, defined 4266@opindex checkpoint 4267@opindex checkpoint-action 4268 4269A @dfn{checkpoint} is a moment of time before writing @var{n}th record to 4270the archive (a @dfn{write checkpoint}), or before reading @var{n}th record 4271from the archive (a @dfn{read checkpoint}). Checkpoints allow to 4272periodically execute arbitrary actions. 4273 4274The checkpoint facility is enabled using the following option: 4275 4276@table @option 4277@xopindex{checkpoint, defined} 4278@item --checkpoint[=@var{n}] 4279Schedule checkpoints before writing or reading each @var{n}th record. 4280The default value for @var{n} is 10. 4281@end table 4282 4283A list of arbitrary @dfn{actions} can be executed at each checkpoint. 4284These actions include: pausing, displaying textual messages, and 4285executing arbitrary external programs. Actions are defined using 4286the @option{--checkpoint-action} option. 4287 4288@table @option 4289@xopindex{checkpoint-action, defined} 4290@item --checkpoint-action=@var{action} 4291Execute an @var{action} at each checkpoint. 4292@end table 4293 4294@cindex @code{echo}, checkpoint action 4295The simplest value of @var{action} is @samp{echo}. It instructs 4296@command{tar} to display the default message on the standard error 4297stream upon arriving at each checkpoint. The default message is (in 4298@acronym{POSIX} locale) @samp{Write checkpoint @var{n}}, for write 4299checkpoints, and @samp{Read checkpoint @var{n}}, for read checkpoints. 4300Here, @var{n} represents ordinal number of the checkpoint. 4301 4302In another locales, translated versions of this message are used. 4303 4304This is the default action, so running: 4305 4306@smallexample 4307$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=echo} /var 4308@end smallexample 4309 4310@noindent 4311is equivalent to: 4312 4313@smallexample 4314$ @kbd{tar -c --checkpoint=1000} /var 4315@end smallexample 4316 4317The @samp{echo} action also allows to supply a customized message. 4318You do so by placing an equals sign and the message right after it, 4319e.g.: 4320 4321@smallexample 4322--checkpoint-action="echo=Hit %s checkpoint #%u" 4323@end smallexample 4324 4325The @samp{%s} and @samp{%u} in the above example are 4326@dfn{format specifiers}. The @samp{%s} specifier is replaced with 4327the @dfn{type} of the checkpoint: @samp{write} or 4328@samp{read} (or a corresponding translated version in locales other 4329than @acronym{POSIX}). The @samp{%u} specifier is replaced with 4330the ordinal number of the checkpoint. Thus, the above example could 4331produce the following output when used with the @option{--create} 4332option: 4333 4334@smallexample 4335tar: Hit write checkpoint #10 4336tar: Hit write checkpoint #20 4337tar: Hit write checkpoint #30 4338@end smallexample 4339 4340The complete list of available format specifiers follows. Some of 4341them can take optional arguments. These arguments, if given, are 4342supplied in curly braces between the percent sign and the specifier 4343letter. 4344 4345@table @samp 4346@item %s 4347Print type of the checkpoint (@samp{write} or @samp{read}). 4348 4349@item %u 4350Print number of the checkpoint. 4351 4352@item %@{r,w,d@}T 4353Print number of bytes transferred so far and approximate transfer 4354speed. Optional arguments supply prefixes to be used before number 4355of bytes read, written and deleted, correspondingly. If absent, 4356they default to @samp{R}. @samp{W}, @samp{D}. Any or all of them can 4357be omitted, so, that e.g. @samp{%@{@}T} means to print corresponding 4358statistics without any prefixes. Any surplus arguments, if present, 4359are silently ignored. 4360 4361@example 4362$ @kbd{tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c} 4363tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0 4364tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240 4365@end example 4366 4367@noindent 4368See also the @samp{totals} action, described below. 4369 4370@item %@{@var{fmt}@}t 4371Output current local time using @var{fmt} as format for @command{strftime} 4372(@pxref{strftime, strftime,,strftime(3), strftime(3) man page}). The 4373@samp{@{@var{fmt}@}} part is optional. If not present, the default 4374format is @samp{%c}, i.e. the preferred date and time representation 4375for the current locale. 4376 4377@item %@{@var{n}@}* 4378Pad output with spaces to the @var{n}th column. If the 4379@samp{@{@var{n}@}} part is omitted, the current screen width 4380is assumed. 4381 4382@item %c 4383This is a shortcut for @samp{%@{%Y-%m-%d %H:%M:%S@}t: %ds, %@{read,wrote@}T%*\r}, 4384intended mainly for use with @samp{ttyout} action (see below). 4385@end table 4386 4387Aside from format expansion, the message string is subject to 4388@dfn{unquoting}, during which the backslash @dfn{escape sequences} are 4389replaced with their corresponding @acronym{ASCII} characters 4390(@pxref{escape sequences}). E.g. the following action will produce an 4391audible bell and the message described above at each checkpoint: 4392 4393@smallexample 4394--checkpoint-action='echo=\aHit %s checkpoint #%u' 4395@end smallexample 4396 4397@cindex @code{bell}, checkpoint action 4398There is also a special action which produces an audible signal: 4399@samp{bell}. It is not equivalent to @samp{echo='\a'}, because 4400@samp{bell} sends the bell directly to the console (@file{/dev/tty}), 4401whereas @samp{echo='\a'} sends it to the standard error. 4402 4403@cindex @code{ttyout}, checkpoint action 4404The @samp{ttyout=@var{string}} action outputs @var{string} to 4405@file{/dev/tty}, so it can be used even if the standard output is 4406redirected elsewhere. The @var{string} is subject to the same 4407modifications as with @samp{echo} action. In contrast to the latter, 4408@samp{ttyout} does not prepend @command{tar} executable name to the 4409string, nor does it output a newline after it. For example, the 4410following action will print the checkpoint message at the same screen 4411line, overwriting any previous message: 4412 4413@smallexample 4414--checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r" 4415@end smallexample 4416 4417@noindent 4418Notice the use of @samp{%*} specifier to clear out any eventual 4419remains of the prior output line. As as more complex example, 4420consider this: 4421 4422@smallexample 4423--checkpoint-action=ttyout='%@{%Y-%m-%d %H:%M:%S@}t (%d sec): #%u, %T%*\r' 4424@end smallexample 4425 4426@noindent 4427This prints the current local time, number of seconds expired since 4428tar was started, the checkpoint ordinal number, transferred bytes and 4429average computed I/O speed. 4430 4431@cindex @code{dot}, checkpoint action 4432Another available checkpoint action is @samp{dot} (or @samp{.}). It 4433instructs @command{tar} to print a single dot on the standard listing 4434stream, e.g.: 4435 4436@smallexample 4437$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=dot} /var 4438... 4439@end smallexample 4440 4441For compatibility with previous @GNUTAR{} versions, this action can 4442be abbreviated by placing a dot in front of the checkpoint frequency, 4443as shown in the previous section. 4444 4445@cindex @code{totals}, checkpoint action 4446The @samp{totals} action prints the total number of bytes transferred 4447so far. The format of the data is the same as for the 4448@option{--totals} option (@pxref{totals}). See also @samp{%T} format 4449specifier of the @samp{echo} or @samp{ttyout} action. 4450 4451@cindex @code{sleep}, checkpoint action 4452Yet another action, @samp{sleep}, pauses @command{tar} for a specified 4453amount of seconds. The following example will stop for 30 seconds at each 4454checkpoint: 4455 4456@smallexample 4457$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=sleep=30} 4458@end smallexample 4459 4460@anchor{checkpoint wait} 4461@cindex @code{wait}, checkpoint action 4462The @code{wait=@var{signo}} action stops further execution until the 4463signal @var{signo} is delivered. Valid values for @var{signo} are: 4464@code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and 4465@code{SIGUSR2}. The @samp{SIG} prefix is optional. For example: 4466 4467@example 4468$ @kbd{tar -c -f arc --checkpoint=1000 --checkpoint-action wait=USR1 .} 4469@end example 4470 4471In this example, @GNUTAR{} will stop archivation at each 1000th 4472checkpoint. wait until the @samp{SIGUSR1} signal is delivered, 4473and resume processing. 4474 4475This action is used by the @command{genfile} utility to perform 4476modifications on the input files upon hitting certain checkpoints 4477(@pxref{Exec Mode, genfile}). 4478 4479@anchor{checkpoint exec} 4480@cindex @code{exec}, checkpoint action 4481Finally, the @code{exec} action executes a given external command. 4482For example: 4483 4484@smallexample 4485$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint} 4486@end smallexample 4487 4488The supplied command can be any valid command invocation, with or 4489without additional command line arguments. If it does contain 4490arguments, don't forget to quote it to prevent it from being split by 4491the shell. @xref{external, Running External Commands}, for more detail. 4492 4493The command gets a copy of @command{tar}'s environment plus the 4494following variables: 4495 4496@table @env 4497@vrindex TAR_VERSION, checkpoint script environment 4498@item TAR_VERSION 4499@GNUTAR{} version number. 4500 4501@vrindex TAR_ARCHIVE, checkpoint script environment 4502@item TAR_ARCHIVE 4503The name of the archive @command{tar} is processing. 4504 4505@vrindex TAR_BLOCKING_FACTOR, checkpoint script environment 4506@item TAR_BLOCKING_FACTOR 4507Current blocking factor (@pxref{Blocking}). 4508 4509@vrindex TAR_CHECKPOINT, checkpoint script environment 4510@item TAR_CHECKPOINT 4511Number of the checkpoint. 4512 4513@vrindex TAR_SUBCOMMAND, checkpoint script environment 4514@item TAR_SUBCOMMAND 4515A short option describing the operation @command{tar} is executing. 4516@xref{Operations}, for a complete list of subcommand options. 4517 4518@vrindex TAR_FORMAT, checkpoint script environment 4519@item TAR_FORMAT 4520Format of the archive being processed. @xref{Formats}, for a complete 4521list of archive format names. 4522@end table 4523 4524These environment variables can also be passed as arguments to the 4525command, provided that they are properly escaped, for example: 4526 4527@smallexample 4528@kbd{tar -c -f arc.tar \ 4529 --checkpoint-action='exec=/sbin/cpoint $TAR_CHECKPOINT'} 4530@end smallexample 4531 4532@noindent 4533Notice single quotes to prevent variable names from being expanded by 4534the shell when invoking @command{tar}. 4535 4536Any number of actions can be defined, by supplying several 4537@option{--checkpoint-action} options in the command line. For 4538example, the command below displays two messages, pauses 4539execution for 30 seconds and executes the @file{/sbin/cpoint} script: 4540 4541@example 4542@group 4543$ @kbd{tar -c -f arc.tar \ 4544 --checkpoint-action='\aecho=Hit %s checkpoint #%u' \ 4545 --checkpoint-action='echo=Sleeping for 30 seconds' \ 4546 --checkpoint-action='sleep=30' \ 4547 --checkpoint-action='exec=/sbin/cpoint'} 4548@end group 4549@end example 4550 4551This example also illustrates the fact that 4552@option{--checkpoint-action} can be used without 4553@option{--checkpoint}. In this case, the default checkpoint frequency 4554(at each 10th record) is assumed. 4555 4556@node warnings 4557@section Controlling Warning Messages 4558 4559Sometimes, while performing the requested task, @GNUTAR{} notices 4560some conditions that are not exactly errors, but which the user 4561should be aware of. When this happens, @command{tar} issues a 4562@dfn{warning message} describing the condition. Warning messages 4563are output to the standard error and they do not affect the exit 4564code of @command{tar} command. 4565 4566@xopindex{warning, explained} 4567@GNUTAR{} allows the user to suppress some or all of its warning 4568messages: 4569 4570@table @option 4571@item --warning=@var{keyword} 4572Control display of the warning messages identified by @var{keyword}. 4573If @var{keyword} starts with the prefix @samp{no-}, such messages are 4574suppressed. Otherwise, they are enabled. 4575 4576Multiple @option{--warning} messages accumulate. 4577 4578The tables below list allowed values for @var{keyword} along with the 4579warning messages they control. 4580@end table 4581 4582@subheading Keywords controlling @command{tar} operation 4583@table @asis 4584@kwindex all 4585@item all 4586Enable all warning messages. This is the default. 4587@kwindex none 4588@item none 4589Disable all warning messages. 4590@kwindex filename-with-nuls 4591@cindex @samp{file name read contains nul character}, warning message 4592@item filename-with-nuls 4593@samp{%s: file name read contains nul character} 4594@kwindex alone-zero-block 4595@cindex @samp{A lone zero block at}, warning message 4596@item alone-zero-block 4597@samp{A lone zero block at %s} 4598@end table 4599 4600@subheading Keywords applicable for @command{tar --create} 4601@table @asis 4602@kwindex cachedir 4603@cindex @samp{contains a cache directory tag}, warning message 4604@item cachedir 4605@samp{%s: contains a cache directory tag %s; %s} 4606@kwindex file-shrank 4607@cindex @samp{File shrank by %s bytes}, warning message 4608@item file-shrank 4609@samp{%s: File shrank by %s bytes; padding with zeros} 4610@kwindex xdev 4611@cindex @samp{file is on a different filesystem}, warning message 4612@item xdev 4613@samp{%s: file is on a different filesystem; not dumped} 4614@kwindex file-ignored 4615@cindex @samp{Unknown file type; file ignored}, warning message 4616@cindex @samp{socket ignored}, warning message 4617@cindex @samp{door ignored}, warning message 4618@item file-ignored 4619@samp{%s: Unknown file type; file ignored} 4620@*@samp{%s: socket ignored} 4621@*@samp{%s: door ignored} 4622@kwindex file-unchanged 4623@cindex @samp{file is unchanged; not dumped}, warning message 4624@item file-unchanged 4625@samp{%s: file is unchanged; not dumped} 4626@kwindex ignore-archive 4627@cindex @samp{file is the archive; not dumped}, warning message 4628@kwindex ignore-archive 4629@cindex @samp{file is the archive; not dumped}, warning message 4630@item ignore-archive 4631@samp{%s: file is the archive; not dumped} 4632@kwindex file-removed 4633@cindex @samp{File removed before we read it}, warning message 4634@item file-removed 4635@samp{%s: File removed before we read it} 4636@kwindex file-changed 4637@cindex @samp{file changed as we read it}, warning message 4638@item file-changed 4639@samp{%s: file changed as we read it} 4640@item failed-read 4641Suppresses warnings about unreadable files or directories. This 4642keyword applies only if used together with the @option{--ignore-failed-read} 4643option. @xref{Ignore Failed Read}. 4644@end table 4645 4646@subheading Keywords applicable for @command{tar --extract} 4647@table @asis 4648@kwindex existing-file 4649@cindex @samp{%s: skipping existing file}, warning message 4650@item existing-file 4651@samp{%s: skipping existing file} 4652@kwindex timestamp 4653@cindex @samp{implausibly old time stamp %s}, warning message 4654@cindex @samp{time stamp %s is %s s in the future}, warning message 4655@item timestamp 4656@samp{%s: implausibly old time stamp %s} 4657@*@samp{%s: time stamp %s is %s s in the future} 4658@kwindex contiguous-cast 4659@cindex @samp{Extracting contiguous files as regular files}, warning message 4660@item contiguous-cast 4661@samp{Extracting contiguous files as regular files} 4662@kwindex symlink-cast 4663@cindex @samp{Attempting extraction of symbolic links as hard links}, warning message 4664@item symlink-cast 4665@samp{Attempting extraction of symbolic links as hard links} 4666@kwindex unknown-cast 4667@cindex @samp{Unknown file type '%c', extracted as normal file}, warning message 4668@item unknown-cast 4669@samp{%s: Unknown file type '%c', extracted as normal file} 4670@kwindex ignore-newer 4671@cindex @samp{Current %s is newer or same age}, warning message 4672@item ignore-newer 4673@samp{Current %s is newer or same age} 4674@kwindex unknown-keyword 4675@cindex @samp{Ignoring unknown extended header keyword '%s'}, warning message 4676@item unknown-keyword 4677@samp{Ignoring unknown extended header keyword '%s'} 4678@kwindex decompress-program 4679@item decompress-program 4680Controls verbose description of failures occurring when trying to run 4681alternative decompressor programs (@pxref{alternative decompression 4682programs}). This warning is disabled by default (unless 4683@option{--verbose} is used). A common example of what you can get 4684when using this warning is: 4685 4686@smallexample 4687$ @kbd{tar --warning=decompress-program -x -f archive.Z} 4688tar (child): cannot run compress: No such file or directory 4689tar (child): trying gzip 4690@end smallexample 4691 4692This means that @command{tar} first tried to decompress 4693@file{archive.Z} using @command{compress}, and, when that 4694failed, switched to @command{gzip}. 4695@kwindex record-size 4696@cindex @samp{Record size = %lu blocks}, warning message 4697@item record-size 4698@samp{Record size = %lu blocks} 4699@end table 4700 4701@subheading Keywords controlling incremental extraction: 4702@table @asis 4703@kwindex rename-directory 4704@cindex @samp{%s: Directory has been renamed from %s}, warning message 4705@cindex @samp{%s: Directory has been renamed}, warning message 4706@item rename-directory 4707@samp{%s: Directory has been renamed from %s} 4708@*@samp{%s: Directory has been renamed} 4709@kwindex new-directory 4710@cindex @samp{%s: Directory is new}, warning message 4711@item new-directory 4712@samp{%s: Directory is new} 4713@kwindex xdev 4714@cindex @samp{%s: directory is on a different device: not purging}, warning message 4715@item xdev 4716@samp{%s: directory is on a different device: not purging} 4717@kwindex bad-dumpdir 4718@cindex @samp{Malformed dumpdir: 'X' never used}, warning message 4719@item bad-dumpdir 4720@samp{Malformed dumpdir: 'X' never used} 4721@end table 4722 4723@node interactive 4724@section Asking for Confirmation During Operations 4725@cindex Interactive operation 4726 4727Typically, @command{tar} carries out a command without stopping for 4728further instructions. In some situations however, you may want to 4729exclude some files and archive members from the operation (for instance 4730if disk or storage space is tight). You can do this by excluding 4731certain files automatically (@pxref{Choosing}), or by performing 4732an operation interactively, using the @option{--interactive} (@option{-w}) option. 4733@command{tar} also accepts @option{--confirmation} for this option. 4734 4735@opindex interactive 4736When the @option{--interactive} (@option{-w}) option is specified, before 4737reading, writing, or deleting files, @command{tar} first prints a message 4738for each such file, telling what operation it intends to take, then asks 4739for confirmation on the terminal. The actions which require 4740confirmation include adding a file to the archive, extracting a file 4741from the archive, deleting a file from the archive, and deleting a file 4742from disk. To confirm the action, you must type a line of input 4743beginning with @samp{y}. If your input line begins with anything other 4744than @samp{y}, @command{tar} skips that file. 4745 4746If @command{tar} is reading the archive from the standard input, 4747@command{tar} opens the file @file{/dev/tty} to support the interactive 4748communications. 4749 4750Verbose output is normally sent to standard output, separate from 4751other error messages. However, if the archive is produced directly 4752on standard output, then verbose output is mixed with errors on 4753@code{stderr}. Producing the archive on standard output may be used 4754as a way to avoid using disk space, when the archive is soon to be 4755consumed by another process reading it, say. Some people felt the need 4756of producing an archive on stdout, still willing to segregate between 4757verbose output and error output. A possible approach would be using a 4758named pipe to receive the archive, and having the consumer process to 4759read from that named pipe. This has the advantage of letting standard 4760output free to receive verbose output, all separate from errors. 4761 4762@node external 4763@section Running External Commands 4764 4765Certain @GNUTAR{} operations imply running external commands that you 4766supply on the command line. One of such operations is checkpointing, 4767described above (@pxref{checkpoint exec}). Another example of this 4768feature is the @option{-I} option, which allows you to supply the 4769program to use for compressing or decompressing the archive 4770(@pxref{use-compress-program}). 4771 4772Whenever such operation is requested, @command{tar} first splits the 4773supplied command into words much like the shell does. It then treats 4774the first word as the name of the program or the shell script to execute 4775and the rest of words as its command line arguments. The program, 4776unless given as an absolute file name, is searched in the shell's 4777@env{PATH}. 4778 4779Any additional information is normally supplied to external commands 4780in environment variables, specific to each particular operation. For 4781example, the @option{--checkpoint-action=exec} option, defines the 4782@env{TAR_ARCHIVE} variable to the name of the archive being worked 4783upon. You can, should the need be, use these variables in the 4784command line of the external command. For example: 4785 4786@smallexample 4787$ @kbd{tar -x -f archive.tar \ 4788 --checkpoint-action=exec='printf "%04d in %32s\r" $TAR_CHECKPOINT $TAR_ARCHIVE'} 4789@end smallexample 4790 4791@noindent 4792This command prints for each checkpoint its number and the name of the 4793archive, using the same output line on the screen. 4794 4795Notice the use of single quotes to prevent variable names from being 4796expanded by the shell when invoking @command{tar}. 4797 4798@node operations 4799@chapter @GNUTAR{} Operations 4800 4801@menu 4802* Basic tar:: 4803* Advanced tar:: 4804* create options:: 4805* extract options:: 4806* backup:: 4807* looking ahead:: 4808@end menu 4809 4810@node Basic tar 4811@section Basic @GNUTAR{} Operations 4812 4813The basic @command{tar} operations, @option{--create} (@option{-c}), 4814@option{--list} (@option{-t}) and @option{--extract} (@option{--get}, 4815@option{-x}), are currently presented and described in the tutorial 4816chapter of this manual. This section provides some complementary notes 4817for these operations. 4818 4819@table @option 4820@xopindex{create, complementary notes} 4821@item --create 4822@itemx -c 4823 4824Creating an empty archive would have some kind of elegance. One can 4825initialize an empty archive and later use @option{--append} 4826(@option{-r}) for adding all members. Some applications would not 4827welcome making an exception in the way of adding the first archive 4828member. On the other hand, many people reported that it is 4829dangerously too easy for @command{tar} to destroy a magnetic tape with 4830an empty archive@footnote{This is well described in @cite{Unix-haters 4831Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG 4832Books, ISBN 1-56884-203-1.}. The two most common errors are: 4833 4834@enumerate 4835@item 4836Mistakingly using @code{create} instead of @code{extract}, when the 4837intent was to extract the full contents of an archive. This error 4838is likely: keys @kbd{c} and @kbd{x} are right next to each other on 4839the QWERTY keyboard. Instead of being unpacked, the archive then 4840gets wholly destroyed. When users speak about @dfn{exploding} an 4841archive, they usually mean something else :-). 4842 4843@item 4844Forgetting the argument to @code{file}, when the intent was to create 4845an archive with a single file in it. This error is likely because a 4846tired user can easily add the @kbd{f} key to the cluster of option 4847letters, by the mere force of habit, without realizing the full 4848consequence of doing so. The usual consequence is that the single 4849file, which was meant to be saved, is rather destroyed. 4850@end enumerate 4851 4852So, recognizing the likelihood and the catastrophic nature of these 4853errors, @GNUTAR{} now takes some distance from elegance, and 4854cowardly refuses to create an archive when @option{--create} option is 4855given, there are no arguments besides options, and 4856@option{--files-from} (@option{-T}) option is @emph{not} used. To get 4857around the cautiousness of @GNUTAR{} and nevertheless create an 4858archive with nothing in it, one may still use, as the value for the 4859@option{--files-from} option, a file with no names in it, as shown in 4860the following commands: 4861 4862@smallexample 4863@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null} 4864@kbd{tar -cf empty-archive.tar -T /dev/null} 4865@end smallexample 4866 4867@xopindex{extract, complementary notes} 4868@item --extract 4869@itemx --get 4870@itemx -x 4871 4872A socket is stored, within a @GNUTAR{} archive, as a pipe. 4873 4874@item @option{--list} (@option{-t}) 4875 4876@GNUTAR{} now shows dates as @samp{1996-08-30}, 4877while it used to show them as @samp{Aug 30 1996}. Preferably, 4878people should get used to ISO 8601 dates. Local American dates should 4879be made available again with full date localization support, once 4880ready. In the meantime, programs not being localizable for dates 4881should prefer international dates, that's really the way to go. 4882 4883Look up @url{http://www.cl.cam.ac.uk/@/~mgk25/@/iso-time.html} if you 4884are curious, it contains a detailed explanation of the ISO 8601 standard. 4885 4886@end table 4887 4888@node Advanced tar 4889@section Advanced @GNUTAR{} Operations 4890 4891Now that you have learned the basics of using @GNUTAR{}, you may want 4892to learn about further ways in which @command{tar} can help you. 4893 4894This chapter presents five, more advanced operations which you probably 4895won't use on a daily basis, but which serve more specialized functions. 4896We also explain the different styles of options and why you might want 4897to use one or another, or a combination of them in your @command{tar} 4898commands. Additionally, this chapter includes options which allow you to 4899define the output from @command{tar} more carefully, and provide help and 4900error correction in special circumstances. 4901 4902@FIXME{check this after the chapter is actually revised to make sure 4903it still introduces the info in the chapter correctly : ).} 4904 4905@menu 4906* Operations:: 4907* append:: 4908* update:: 4909* concatenate:: 4910* delete:: 4911* compare:: 4912@end menu 4913 4914@node Operations 4915@subsection The Five Advanced @command{tar} Operations 4916 4917@cindex basic operations 4918In the last chapter, you learned about the first three operations to 4919@command{tar}. This chapter presents the remaining five operations to 4920@command{tar}: @option{--append}, @option{--update}, @option{--concatenate}, 4921@option{--delete}, and @option{--compare}. 4922 4923You are not likely to use these operations as frequently as those 4924covered in the last chapter; however, since they perform specialized 4925functions, they are quite useful when you do need to use them. We 4926will give examples using the same directory and files that you created 4927in the last chapter. As you may recall, the directory is called 4928@file{practice}, the files are @samp{jazz}, @samp{blues}, @samp{folk}, 4929and the two archive files you created are 4930@samp{collection.tar} and @samp{music.tar}. 4931 4932We will also use the archive files @samp{afiles.tar} and 4933@samp{bfiles.tar}. The archive @samp{afiles.tar} contains the members @samp{apple}, 4934@samp{angst}, and @samp{aspic}; @samp{bfiles.tar} contains the members 4935@samp{./birds}, @samp{baboon}, and @samp{./box}. 4936 4937Unless we state otherwise, all practicing you do and examples you follow 4938in this chapter will take place in the @file{practice} directory that 4939you created in the previous chapter; see @ref{prepare for examples}. 4940(Below in this section, we will remind you of the state of the examples 4941where the last chapter left them.) 4942 4943The five operations that we will cover in this chapter are: 4944 4945@table @option 4946@item --append 4947@itemx -r 4948Add new entries to an archive that already exists. 4949@item --update 4950@itemx -u 4951Add more recent copies of archive members to the end of an archive, if 4952they exist. 4953@item --concatenate 4954@itemx --catenate 4955@itemx -A 4956Add one or more pre-existing archives to the end of another archive. 4957@item --delete 4958Delete items from an archive (does not work on tapes). 4959@item --compare 4960@itemx --diff 4961@itemx -d 4962Compare archive members to their counterparts in the file system. 4963@end table 4964 4965@node append 4966@subsection How to Add Files to Existing Archives: @option{--append} 4967 4968@cindex appending files to existing archive 4969@opindex append 4970If you want to add files to an existing archive, you don't need to 4971create a new archive; you can use @option{--append} (@option{-r}). 4972The archive must already exist in order to use @option{--append}. (A 4973related operation is the @option{--update} operation; you can use this 4974to add newer versions of archive members to an existing archive. To learn how to 4975do this with @option{--update}, @pxref{update}.) 4976 4977If you use @option{--append} to add a file that has the same name as an 4978archive member to an archive containing that archive member, then the 4979old member is not deleted. What does happen, however, is somewhat 4980complex. @command{tar} @emph{allows} you to have infinite number of files 4981with the same name. Some operations treat these same-named members no 4982differently than any other set of archive members: for example, if you 4983view an archive with @option{--list} (@option{-t}), you will see all 4984of those members listed, with their data modification times, owners, etc. 4985 4986Other operations don't deal with these members as perfectly as you might 4987prefer; if you were to use @option{--extract} to extract the archive, 4988only the most recently added copy of a member with the same name as 4989other members would end up in the working directory. This is because 4990@option{--extract} extracts an archive in the order the members appeared 4991in the archive; the most recently archived members will be extracted 4992last. Additionally, an extracted member will @emph{replace} a file of 4993the same name which existed in the directory already, and @command{tar} 4994will not prompt you about this@footnote{Unless you give it 4995@option{--keep-old-files} (or @option{--skip-old-files}) option, or 4996the disk copy is newer than the one in the archive and you invoke 4997@command{tar} with @option{--keep-newer-files} option.}. Thus, only 4998the most recently archived member will end up being extracted, as it 4999will replace the one extracted before it, and so on. 5000 5001@cindex extracting @var{n}th copy of the file 5002@xopindex{occurrence, described} 5003There exists a special option that allows you to get around this 5004behavior and extract (or list) only a particular copy of the file. 5005This is @option{--occurrence} option. If you run @command{tar} with 5006this option, it will extract only the first copy of the file. You 5007may also give this option an argument specifying the number of 5008copy to be extracted. Thus, for example if the archive 5009@file{archive.tar} contained three copies of file @file{myfile}, then 5010the command 5011 5012@smallexample 5013tar --extract --file archive.tar --occurrence=2 myfile 5014@end smallexample 5015 5016@noindent 5017would extract only the second copy. @xref{Option 5018Summary,---occurrence}, for the description of @option{--occurrence} 5019option. 5020 5021@FIXME{ hag -- you might want to incorporate some of the above into the 5022MMwtSN node; not sure. i didn't know how to make it simpler... 5023 5024There are a few ways to get around this. Xref to Multiple Members 5025with the Same Name, maybe.} 5026 5027@cindex Members, replacing with other members 5028@cindex Replacing members with other members 5029@xopindex{delete, using before --append} 5030If you want to replace an archive member, use @option{--delete} to 5031delete the member you want to remove from the archive, and then use 5032@option{--append} to add the member you want to be in the archive. Note 5033that you can not change the order of the archive; the most recently 5034added member will still appear last. In this sense, you cannot truly 5035``replace'' one member with another. (Replacing one member with another 5036will not work on certain types of media, such as tapes; see @ref{delete} 5037and @ref{Media}, for more information.) 5038 5039@menu 5040* appending files:: Appending Files to an Archive 5041* multiple:: 5042@end menu 5043 5044@node appending files 5045@subsubsection Appending Files to an Archive 5046@cindex Adding files to an Archive 5047@cindex Appending files to an Archive 5048@cindex Archives, Appending files to 5049@opindex append 5050 5051The simplest way to add a file to an already existing archive is the 5052@option{--append} (@option{-r}) operation, which writes specified 5053files into the archive whether or not they are already among the 5054archived files. 5055 5056When you use @option{--append}, you @emph{must} specify file name 5057arguments, as there is no default. If you specify a file that already 5058exists in the archive, another copy of the file will be added to the 5059end of the archive. As with other operations, the member names of the 5060newly added files will be exactly the same as their names given on the 5061command line. The @option{--verbose} (@option{-v}) option will print 5062out the names of the files as they are written into the archive. 5063 5064@option{--append} cannot be performed on some tape drives, unfortunately, 5065due to deficiencies in the formats those tape drives use. The archive 5066must be a valid @command{tar} archive, or else the results of using this 5067operation will be unpredictable. @xref{Media}. 5068 5069To demonstrate using @option{--append} to add a file to an archive, 5070create a file called @file{rock} in the @file{practice} directory. 5071Make sure you are in the @file{practice} directory. Then, run the 5072following @command{tar} command to add @file{rock} to 5073@file{collection.tar}: 5074 5075@smallexample 5076$ @kbd{tar --append --file=collection.tar rock} 5077@end smallexample 5078 5079@noindent 5080If you now use the @option{--list} (@option{-t}) operation, you will see that 5081@file{rock} has been added to the archive: 5082 5083@smallexample 5084$ @kbd{tar --list --file=collection.tar} 5085-rw-r--r-- me/user 28 1996-10-18 16:31 jazz 5086-rw-r--r-- me/user 21 1996-09-23 16:44 blues 5087-rw-r--r-- me/user 20 1996-09-23 16:44 folk 5088-rw-r--r-- me/user 20 1996-09-23 16:44 rock 5089@end smallexample 5090 5091@node multiple 5092@subsubsection Multiple Members with the Same Name 5093@cindex members, multiple 5094@cindex multiple members 5095 5096You can use @option{--append} (@option{-r}) to add copies of files 5097which have been updated since the archive was created. (However, we 5098do not recommend doing this since there is another @command{tar} 5099option called @option{--update}; @xref{update}, for more information. 5100We describe this use of @option{--append} here for the sake of 5101completeness.) When you extract the archive, the older version will 5102be effectively lost. This works because files are extracted from an 5103archive in the order in which they were archived. Thus, when the 5104archive is extracted, a file archived later in time will replace a 5105file of the same name which was archived earlier, even though the 5106older version of the file will remain in the archive unless you delete 5107all versions of the file. 5108 5109Supposing you change the file @file{blues} and then append the changed 5110version to @file{collection.tar}. As you saw above, the original 5111@file{blues} is in the archive @file{collection.tar}. If you change the 5112file and append the new version of the file to the archive, there will 5113be two copies in the archive. When you extract the archive, the older 5114version of the file will be extracted first, and then replaced by the 5115newer version when it is extracted. 5116 5117You can append the new, changed copy of the file @file{blues} to the 5118archive in this way: 5119 5120@smallexample 5121$ @kbd{tar --append --verbose --file=collection.tar blues} 5122blues 5123@end smallexample 5124 5125@noindent 5126Because you specified the @option{--verbose} option, @command{tar} has 5127printed the name of the file being appended as it was acted on. Now 5128list the contents of the archive: 5129 5130@smallexample 5131$ @kbd{tar --list --verbose --file=collection.tar} 5132-rw-r--r-- me/user 28 1996-10-18 16:31 jazz 5133-rw-r--r-- me/user 21 1996-09-23 16:44 blues 5134-rw-r--r-- me/user 20 1996-09-23 16:44 folk 5135-rw-r--r-- me/user 20 1996-09-23 16:44 rock 5136-rw-r--r-- me/user 58 1996-10-24 18:30 blues 5137@end smallexample 5138 5139@noindent 5140The newest version of @file{blues} is now at the end of the archive 5141(note the different creation dates and file sizes). If you extract 5142the archive, the older version of the file @file{blues} will be 5143replaced by the newer version. You can confirm this by extracting 5144the archive and running @samp{ls} on the directory. 5145 5146If you wish to extract the first occurrence of the file @file{blues} 5147from the archive, use @option{--occurrence} option, as shown in 5148the following example: 5149 5150@smallexample 5151$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues} 5152-rw-r--r-- me/user 21 1996-09-23 16:44 blues 5153@end smallexample 5154 5155@xref{Writing}, for more information on @option{--extract} and 5156see @ref{Option Summary, --occurrence}, for a description of 5157@option{--occurrence} option. 5158 5159@node update 5160@subsection Updating an Archive 5161@cindex Updating an archive 5162@opindex update 5163 5164In the previous section, you learned how to use @option{--append} to 5165add a file to an existing archive. A related operation is 5166@option{--update} (@option{-u}). The @option{--update} operation 5167updates a @command{tar} archive by comparing the date of the specified 5168archive members against the date of the file with the same name. If 5169the file has been modified more recently than the archive member, then 5170the newer version of the file is added to the archive (as with 5171@option{--append}). 5172 5173Unfortunately, you cannot use @option{--update} with magnetic tape drives. 5174The operation will fail. 5175 5176@FIXME{other examples of media on which --update will fail? need to ask 5177charles and/or mib/thomas/dave shevett..} 5178 5179Both @option{--update} and @option{--append} work by adding to the end 5180of the archive. When you extract a file from the archive, only the 5181version stored last will wind up in the file system, unless you use 5182the @option{--backup} option. @xref{multiple}, for a detailed discussion. 5183 5184@menu 5185* how to update:: 5186@end menu 5187 5188@node how to update 5189@subsubsection How to Update an Archive Using @option{--update} 5190@opindex update 5191 5192You must use file name arguments with the @option{--update} 5193(@option{-u}) operation. If you don't specify any files, 5194@command{tar} won't act on any files and won't tell you that it didn't 5195do anything (which may end up confusing you). 5196 5197@c note: the above parenthetical added because in fact, this 5198@c behavior just confused the author. :-) 5199 5200To see the @option{--update} option at work, create a new file, 5201@file{classical}, in your practice directory, and some extra text to the 5202file @file{blues}, using any text editor. Then invoke @command{tar} with 5203the @samp{update} operation and the @option{--verbose} (@option{-v}) 5204option specified, using the names of all the files in the @file{practice} 5205directory as file name arguments: 5206 5207@smallexample 5208$ @kbd{tar --update -v -f collection.tar blues folk rock classical} 5209blues 5210classical 5211$ 5212@end smallexample 5213 5214@noindent 5215Because we have specified verbose mode, @command{tar} prints out the names 5216of the files it is working on, which in this case are the names of the 5217files that needed to be updated. If you run @samp{tar --list} and look 5218at the archive, you will see @file{blues} and @file{classical} at its 5219end. There will be a total of two versions of the member @samp{blues}; 5220the one at the end will be newer and larger, since you added text before 5221updating it. 5222 5223The reason @command{tar} does not overwrite the older file when updating 5224it is that writing to the middle of a section of tape is a difficult 5225process. Tapes are not designed to go backward. @xref{Media}, for more 5226information about tapes. 5227 5228@option{--update} (@option{-u}) is not suitable for performing backups for two 5229reasons: it does not change directory content entries, and it 5230lengthens the archive every time it is used. The @GNUTAR{} 5231options intended specifically for backups are more 5232efficient. If you need to run backups, please consult @ref{Backups}. 5233 5234@node concatenate 5235@subsection Combining Archives with @option{--concatenate} 5236 5237@cindex Adding archives to an archive 5238@cindex Concatenating Archives 5239@opindex concatenate 5240@opindex catenate 5241@c @cindex @option{-A} described 5242Sometimes it may be convenient to add a second archive onto the end of 5243an archive rather than adding individual files to the archive. To add 5244one or more archives to the end of another archive, you should use the 5245@option{--concatenate} (@option{--catenate}, @option{-A}) operation. 5246 5247To use @option{--concatenate}, give the first archive with 5248@option{--file} option and name the rest of archives to be 5249concatenated on the command line. The members, and their member 5250names, will be copied verbatim from those archives to the first 5251one@footnote{This can cause multiple members to have the same name. For 5252information on how this affects reading the archive, see @ref{multiple}.}. 5253The new, concatenated archive will be called by the same name as the 5254one given with the @option{--file} option. As usual, if you omit 5255@option{--file}, @command{tar} will use the value of the environment 5256variable @env{TAPE}, or, if this has not been set, the default archive name. 5257 5258@FIXME{There is no way to specify a new name...} 5259 5260To demonstrate how @option{--concatenate} works, create two small archives 5261called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant 5262files from @file{practice}: 5263 5264@smallexample 5265$ @kbd{tar -cvf bluesrock.tar blues rock} 5266blues 5267rock 5268$ @kbd{tar -cvf folkjazz.tar folk jazz} 5269folk 5270jazz 5271@end smallexample 5272 5273@noindent 5274If you like, You can run @samp{tar --list} to make sure the archives 5275contain what they are supposed to: 5276 5277@smallexample 5278$ @kbd{tar -tvf bluesrock.tar} 5279-rw-r--r-- melissa/user 105 1997-01-21 19:42 blues 5280-rw-r--r-- melissa/user 33 1997-01-20 15:34 rock 5281$ @kbd{tar -tvf jazzfolk.tar} 5282-rw-r--r-- melissa/user 20 1996-09-23 16:44 folk 5283-rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz 5284@end smallexample 5285 5286We can concatenate these two archives with @command{tar}: 5287 5288@smallexample 5289$ @kbd{cd ..} 5290$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar} 5291@end smallexample 5292 5293If you now list the contents of the @file{bluesrock.tar}, you will see 5294that now it also contains the archive members of @file{jazzfolk.tar}: 5295 5296@smallexample 5297$ @kbd{tar --list --file=bluesrock.tar} 5298blues 5299rock 5300folk 5301jazz 5302@end smallexample 5303 5304When you use @option{--concatenate}, the source and target archives must 5305already exist and must have been created using compatible format 5306parameters. Notice, that @command{tar} does not check whether the 5307archives it concatenates have compatible formats, it does not 5308even check if the files are really tar archives. 5309 5310Like @option{--append} (@option{-r}), this operation cannot be performed on some 5311tape drives, due to deficiencies in the formats those tape drives use. 5312 5313@cindex @code{concatenate} vs @command{cat} 5314@cindex @command{cat} vs @code{concatenate} 5315It may seem more intuitive to you to want or try to use @command{cat} to 5316concatenate two archives instead of using the @option{--concatenate} 5317operation; after all, @command{cat} is the utility for combining files. 5318 5319However, @command{tar} archives incorporate an end-of-file marker which 5320must be removed if the concatenated archives are to be read properly as 5321one archive. @option{--concatenate} removes the end-of-archive marker 5322from the target archive before each new archive is appended. If you use 5323@command{cat} to combine the archives, the result will not be a valid 5324@command{tar} format archive. If you need to retrieve files from an 5325archive that was added to using the @command{cat} utility, use the 5326@option{--ignore-zeros} (@option{-i}) option. @xref{Ignore Zeros}, for further 5327information on dealing with archives improperly combined using the 5328@command{cat} shell utility. 5329 5330@node delete 5331@subsection Removing Archive Members Using @option{--delete} 5332@cindex Deleting files from an archive 5333@cindex Removing files from an archive 5334 5335@opindex delete 5336You can remove members from an archive by using the @option{--delete} 5337option. Specify the name of the archive with @option{--file} 5338(@option{-f}) and then specify the names of the members to be deleted; 5339if you list no member names, nothing will be deleted. The 5340@option{--verbose} option will cause @command{tar} to print the names 5341of the members as they are deleted. As with @option{--extract}, you 5342must give the exact member names when using @samp{tar --delete}. 5343@option{--delete} will remove all versions of the named file from the 5344archive. The @option{--delete} operation can run very slowly. 5345 5346Unlike other operations, @option{--delete} has no short form. 5347 5348@cindex Tapes, using @option{--delete} and 5349@cindex Deleting from tape archives 5350This operation will rewrite the archive. You can only use 5351@option{--delete} on an archive if the archive device allows you to 5352write to any point on the media, such as a disk; because of this, it 5353does not work on magnetic tapes. Do not try to delete an archive member 5354from a magnetic tape; the action will not succeed, and you will be 5355likely to scramble the archive and damage your tape. There is no safe 5356way (except by completely re-writing the archive) to delete files from 5357most kinds of magnetic tape. @xref{Media}. 5358 5359To delete all versions of the file @file{blues} from the archive 5360@file{collection.tar} in the @file{practice} directory, make sure you 5361are in that directory, and then, 5362 5363@smallexample 5364$ @kbd{tar --list --file=collection.tar} 5365blues 5366folk 5367jazz 5368rock 5369$ @kbd{tar --delete --file=collection.tar blues} 5370$ @kbd{tar --list --file=collection.tar} 5371folk 5372jazz 5373rock 5374@end smallexample 5375 5376@FIXME{Check if the above listing is actually produced after running 5377all the examples on collection.tar.} 5378 5379The @option{--delete} option has been reported to work properly when 5380@command{tar} acts as a filter from @code{stdin} to @code{stdout}. 5381 5382@node compare 5383@subsection Comparing Archive Members with the File System 5384@cindex Verifying the currency of an archive 5385 5386@opindex compare 5387The @option{--compare} (@option{-d}), or @option{--diff} operation compares 5388specified archive members against files with the same names, and then 5389reports differences in file size, mode, owner, modification date and 5390contents. You should @emph{only} specify archive member names, not file 5391names. If you do not name any members, then @command{tar} will compare the 5392entire archive. If a file is represented in the archive but does not 5393exist in the file system, @command{tar} reports a difference. 5394 5395You have to specify the record size of the archive when modifying an 5396archive with a non-default record size. 5397 5398@command{tar} ignores files in the file system that do not have 5399corresponding members in the archive. 5400 5401The following example compares the archive members @file{rock}, 5402@file{blues} and @file{funk} in the archive @file{bluesrock.tar} with 5403files of the same name in the file system. (Note that there is no file, 5404@file{funk}; @command{tar} will report an error message.) 5405 5406@smallexample 5407$ @kbd{tar --compare --file=bluesrock.tar rock blues funk} 5408rock 5409blues 5410tar: funk not found in archive 5411@end smallexample 5412 5413The spirit behind the @option{--compare} (@option{--diff}, 5414@option{-d}) option is to check whether the archive represents the 5415current state of files on disk, more than validating the integrity of 5416the archive media. For this latter goal, see @ref{verify}. 5417 5418@node create options 5419@section Options Used by @option{--create} 5420 5421@xopindex{create, additional options} 5422The previous chapter described the basics of how to use 5423@option{--create} (@option{-c}) to create an archive from a set of files. 5424@xref{create}. This section described advanced options to be used with 5425@option{--create}. 5426 5427@menu 5428* override:: Overriding File Metadata. 5429* Extended File Attributes:: 5430* Ignore Failed Read:: 5431@end menu 5432 5433@node override 5434@subsection Overriding File Metadata 5435 5436As described above, a @command{tar} archive keeps, for each member it contains, 5437its @dfn{metadata}, such as modification time, mode and ownership of 5438the file. @GNUTAR{} allows to replace these data with other values 5439when adding files to the archive. The options described in this 5440section affect creation of archives of any type. For POSIX archives, 5441see also @ref{PAX keywords}, for additional ways of controlling 5442metadata, stored in the archive. 5443 5444@table @option 5445@opindex mode 5446@item --mode=@var{permissions} 5447 5448When adding files to an archive, @command{tar} will use 5449@var{permissions} for the archive members, rather than the permissions 5450from the files. @var{permissions} can be specified either as an octal 5451number or as symbolic permissions, like with 5452@command{chmod} (@xref{File permissions, Permissions, File 5453permissions, fileutils, @acronym{GNU} file utilities}. This reference 5454also has useful information for those not being overly familiar with 5455the UNIX permission system). Using latter syntax allows for 5456more flexibility. For example, the value @samp{a+rw} adds read and write 5457permissions for everybody, while retaining executable bits on directories 5458or on any other file already marked as executable: 5459 5460@smallexample 5461$ @kbd{tar -c -f archive.tar --mode='a+rw' .} 5462@end smallexample 5463 5464@item --mtime=@var{date} 5465@opindex mtime 5466 5467When adding files to an archive, @command{tar} will use @var{date} as 5468the modification time of members when creating archives, instead of 5469their actual modification times. The argument @var{date} can be 5470either a textual date representation in almost arbitrary format 5471(@pxref{Date input formats}) or a name of an existing file, starting 5472with @samp{/} or @samp{.}. In the latter case, the modification time 5473of that file will be used. 5474 5475The following example will set the modification date to 00:00:00, 5476January 1, 1970: 5477 5478@smallexample 5479$ @kbd{tar -c -f archive.tar --mtime='1970-01-01' .} 5480@end smallexample 5481 5482@noindent 5483When used with @option{--verbose} (@pxref{verbose tutorial}) @GNUTAR{} 5484will try to convert the specified date back to its textual 5485representation and compare it with the one given with 5486@option{--mtime} options. If the two dates differ, @command{tar} will 5487print a warning saying what date it will use. This is to help user 5488ensure he is using the right date. 5489 5490For example: 5491 5492@smallexample 5493$ @kbd{tar -c -f archive.tar -v --mtime=yesterday .} 5494tar: Option --mtime: Treating date 'yesterday' as 2006-06-20 549513:06:29.152478 5496@dots{} 5497@end smallexample 5498 5499@noindent 5500When used with @option{--clamp-mtime} @GNUTAR{} will only set the 5501modification date to @var{date} on files whose actual modification 5502date is later than @var{date}. This is to make it easy to build 5503reproducible archives given a common timestamp for generated files 5504while still retaining the original timestamps of untouched files. 5505 5506@smallexample 5507$ @kbd{tar -c -f archive.tar --clamp-mtime --mtime=@@$SOURCE_DATE_EPOCH .} 5508@end smallexample 5509 5510@item --owner=@var{user} 5511@opindex owner 5512 5513Specifies that @command{tar} should use @var{user} as the owner of members 5514when creating archives, instead of the user associated with the source 5515file. 5516 5517If @var{user} contains a colon, it is taken to be of the form 5518@var{name}:@var{id} where a nonempty @var{name} specifies the user 5519name and a nonempty @var{id} specifies the decimal numeric user 5520@acronym{ID}. If @var{user} does not contain a colon, it is taken to 5521be a user number if it is one or more decimal digits; otherwise it is 5522taken to be a user name. 5523 5524If a name is given but no number, the number is inferred from the 5525current host's user database if possible, and the file's user number 5526is used otherwise. If a number is given but no name, the name is 5527inferred from the number if possible, and an empty name is used 5528otherwise. If both name and number are given, the user database is 5529not consulted, and the name and number need not be valid on the 5530current host. 5531 5532There is no value indicating a missing number, and @samp{0} usually means 5533@code{root}. Some people like to force @samp{0} as the value to offer in 5534their distributions for the owner of files, because the @code{root} user is 5535anonymous anyway, so that might as well be the owner of anonymous 5536archives. For example: 5537 5538@smallexample 5539$ @kbd{tar -c -f archive.tar --owner=0 .} 5540@end smallexample 5541 5542@noindent 5543or: 5544 5545@smallexample 5546$ @kbd{tar -c -f archive.tar --owner=root .} 5547@end smallexample 5548 5549@item --group=@var{group} 5550@opindex group 5551 5552Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group}, 5553rather than the group from the source file. As with @option{--owner}, 5554the argument @var{group} can be an existing group symbolic name, or a 5555decimal numeric group @acronym{ID}, or @var{name}:@var{id}. 5556@end table 5557 5558The @option{--owner} and @option{--group} options affect all files 5559added to the archive. @GNUTAR{} provides also two options that allow 5560for more detailed control over owner translation: 5561 5562@table @option 5563@item --owner-map=@var{file} 5564Read UID translation map from @var{file}. 5565 5566When reading, empty lines are ignored. The @samp{#} sign, unless 5567quoted, introduces a comment, which extends to the end of the line. 5568Each nonempty line defines mapping for a single UID. It must consist 5569of two fields separated by any amount of whitespace. The first field 5570defines original username and UID. It can be a valid user name or 5571a valid UID prefixed with a plus sign. In both cases the 5572corresponding UID or user name is inferred from the current host's 5573user database. 5574 5575The second field defines the UID and username to map the original one 5576to. Its format can be the same as described above. Otherwise, it can 5577have the form @var{newname}:@var{newuid}, in which case neither 5578@var{newname} nor @var{newuid} are required to be valid as per the 5579user database. 5580 5581For example, consider the following file: 5582 5583@example 5584+10 bin 5585smith root:0 5586@end example 5587 5588@noindent 5589Given this file, each input file that is owner by UID 10 will be 5590stored in archive with owner name @samp{bin} and owner UID 5591corresponding to @samp{bin}. Each file owned by user @samp{smith} 5592will be stored with owner name @samp{root} and owner ID 0. Other 5593files will remain unchanged. 5594 5595When used together with @option{--owner-map}, the @option{--owner} 5596option affects only files whose owner is not listed in the map file. 5597 5598@item --group-map=@var{file} 5599Read GID translation map from @var{file}. 5600 5601The format of @var{file} is the same as for @option{--owner-map} 5602option: 5603 5604Each nonempty line defines mapping for a single GID. It must consist 5605of two fields separated by any amount of whitespace. The first field 5606defines original group name and GID. It can be a valid group name or 5607a valid GID prefixed with a plus sign. In both cases the 5608corresponding GID or user name is inferred from the current host's 5609group database. 5610 5611The second field defines the GID and group name to map the original one 5612to. Its format can be the same as described above. Otherwise, it can 5613have the form @var{newname}:@var{newgid}, in which case neither 5614@var{newname} nor @var{newgid} are required to be valid as per the 5615group database. 5616 5617When used together with @option{--group-map}, the @option{--group} 5618option affects only files whose owner group is not rewritten using the 5619map file. 5620@end table 5621 5622@node Extended File Attributes 5623@subsection Extended File Attributes 5624 5625Extended file attributes are name-value pairs that can be 5626associated with each node in a file system. Despite the fact that 5627POSIX.1e draft which proposed them has been withdrawn, the extended 5628file attributes are supported by many file systems. @GNUTAR{} can 5629store extended file attributes along with the files. This feature is 5630controlled by the following command line arguments: 5631 5632@table @option 5633@item --xattrs 5634Enable extended attributes support. When used with @option{--create}, 5635this option instructs @GNUTAR to store extended file attribute in the 5636created archive. This implies POSIX.1-2001 archive format 5637(@option{--format=pax}). 5638 5639When used with @option{--extract}, this option tells @command{tar}, 5640for each file extracted, to read stored attributes from the archive 5641and to apply them to the file. 5642 5643@item --no-xattrs 5644Disable extended attributes support. This is the default. 5645@end table 5646 5647Attribute names are strings prefixed by a @dfn{namespace} name and a dot. 5648Currently, four namespaces exist: @samp{user}, @samp{trusted}, 5649@samp{security} and @samp{system}. By default, when @option{--xattr} 5650is used, all names are stored in the archive (or extracted, if using 5651@option{--extract}). This can be controlled using the following 5652options: 5653 5654@table @option 5655@item --xattrs-exclude=@var{pattern} 5656Specify exclude pattern for extended attributes. 5657 5658@item --xattrs-include=@var{pattern} 5659Specify include pattern for extended attributes. 5660@end table 5661 5662Here, the @var{pattern} is a globbing pattern. For example, the 5663following command: 5664 5665@example 5666$ @kbd{tar --xattrs --xattrs-exclude='user.*' -c a.tar .} 5667@end example 5668 5669will include in the archive @file{a.tar} all attributes, except those 5670from the @samp{user} namespace. 5671 5672Any number of these options can be given, thereby creating lists of 5673include and exclude patterns. 5674 5675When both options are used, first @option{--xattrs-include} is applied 5676to select the set of attribute names to keep, and then 5677@option{--xattrs-exclude} is applied to the resulting set. In other 5678words, only those attributes will be stored, whose names match one 5679of the regexps in @option{--xattrs-include} and don't match any of 5680the regexps from @option{--xattrs-exclude}. 5681 5682When listing the archive, if both @option{--xattrs} and 5683@option{--verbose} options are given, files that have extended 5684attributes are marked with an asterisk following their permission 5685mask. For example: 5686 5687@example 5688-rw-r--r--* smith/users 110 2016-03-16 16:07 file 5689@end example 5690 5691When two or more @option{--verbose} options are given, a detailed 5692listing of extended attributes is printed after each file entry. Each 5693attribute is listed on a separate line, which begins with two spaces 5694and the letter @samp{x} indicating extended attribute. It is followed 5695by a colon, length of the attribute and its name, e.g.: 5696 5697@example 5698-rw-r--r--* smith/users 110 2016-03-16 16:07 file 5699 x: 7 user.mime_type 5700 x: 32 trusted.md5sum 5701@end example 5702 5703File access control lists (@dfn{ACL}) are another actively used feature 5704proposed by the POSIX.1e standard. Each ACL consists of a set of ACL 5705entries, each of which describes the access permissions on the file for 5706an individual user or a group of users as a combination of read, write 5707and search/execute permissions. 5708 5709Whether or not to use ACLs is controlled by the following two options: 5710 5711@table @option 5712@item --acls 5713Enable POSIX ACLs support. When used with @option{--create}, 5714this option instructs @GNUTAR{} to store ACLs in the 5715created archive. This implies POSIX.1-2001 archive format 5716(@option{--format=pax}). 5717 5718When used with @option{--extract}, this option tells @command{tar}, 5719to restore ACLs for each file extracted (provided they are present 5720in the archive). 5721 5722@item --no-acls 5723Disable POSIX ACLs support. This is the default. 5724@end table 5725 5726When listing the archive, if both @option{--acls} and 5727@option{--verbose} options are given, files that have ACLs are marked 5728with a plus sign following their permission mask. For example: 5729 5730@example 5731-rw-r--r--+ smith/users 110 2016-03-16 16:07 file 5732@end example 5733 5734When two or more @option{--verbose} options are given, a detailed 5735listing of ACL is printed after each file entry: 5736 5737@example 5738@group 5739-rw-r--r--+ smith/users 110 2016-03-16 16:07 file 5740 a: user::rw-,user:gray:-w-,group::r--,mask::rw-,other::r-- 5741@end group 5742@end example 5743 5744@dfn{Security-Enhanced Linux} (@dfn{SELinux} for short) is a Linux 5745kernel security module that provides a mechanism for supporting access 5746control security policies, including so-called mandatory access 5747controls (@dfn{MAC}). Support for SELinux attributes is controlled by 5748the following command line options: 5749 5750@table @option 5751@item --selinux 5752Enable the SELinux context support. 5753 5754@item --no-selinux 5755Disable SELinux context support. 5756@end table 5757 5758@node Ignore Failed Read 5759@subsection Ignore Failed Read 5760 5761@table @option 5762@item --ignore-failed-read 5763@opindex ignore-failed-read 5764Do not exit with nonzero on unreadable files or directories. 5765@end table 5766 5767This option has effect only during creation. It instructs tar to 5768treat as mild conditions any missing or unreadable files (directories). 5769Such failures don't affect the program exit code, and the 5770corresponding diagnostic messages are marked as warnings, not errors. 5771These warnings can be suppressed using the 5772@option{--warning=failed-read} option (@pxref{warnings}). 5773 5774@node extract options 5775@section Options Used by @option{--extract} 5776@cindex options for use with @option{--extract} 5777 5778@xopindex{extract, additional options} 5779The previous chapter showed how to use @option{--extract} to extract 5780an archive into the file system. Various options cause @command{tar} to 5781extract more information than just file contents, such as the owner, 5782the permissions, the modification date, and so forth. This section 5783presents options to be used with @option{--extract} when certain special 5784considerations arise. You may review the information presented in 5785@ref{extract} for more basic information about the 5786@option{--extract} operation. 5787 5788@menu 5789* Reading:: Options to Help Read Archives 5790* Writing:: Changing How @command{tar} Writes Files 5791* Scarce:: Coping with Scarce Resources 5792@end menu 5793 5794@node Reading 5795@subsection Options to Help Read Archives 5796@cindex Options when reading archives 5797 5798@cindex Reading incomplete records 5799@cindex Records, incomplete 5800@opindex read-full-records 5801Normally, @command{tar} will request data in full record increments from 5802an archive storage device. If the device cannot return a full record, 5803@command{tar} will report an error. However, some devices do not always 5804return full records, or do not require the last record of an archive to 5805be padded out to the next record boundary. To keep reading until you 5806obtain a full record, or to accept an incomplete record if it contains 5807an end-of-archive marker, specify the @option{--read-full-records} (@option{-B}) option 5808in conjunction with the @option{--extract} or @option{--list} operations. 5809@xref{Blocking}. 5810 5811The @option{--read-full-records} (@option{-B}) option is turned on by default when 5812@command{tar} reads an archive from standard input, or from a remote 5813machine. This is because on @acronym{BSD} Unix systems, attempting to read a 5814pipe returns however much happens to be in the pipe, even if it is 5815less than was requested. If this option were not enabled, @command{tar} 5816would fail as soon as it read an incomplete record from the pipe. 5817 5818If you're not sure of the blocking factor of an archive, you can 5819read the archive by specifying @option{--read-full-records} (@option{-B}) and 5820@option{--blocking-factor=@var{512-size}} (@option{-b 5821@var{512-size}}), using a blocking factor larger than what the archive 5822uses. This lets you avoid having to determine the blocking factor 5823of an archive. @xref{Blocking Factor}. 5824 5825@menu 5826* read full records:: 5827* Ignore Zeros:: 5828@end menu 5829 5830@node read full records 5831@unnumberedsubsubsec Reading Full Records 5832 5833@FIXME{need sentence or so of intro here} 5834 5835@table @option 5836@opindex read-full-records 5837@item --read-full-records 5838@item -B 5839Use in conjunction with @option{--extract} (@option{--get}, 5840@option{-x}) to read an archive which contains incomplete records, or 5841one which has a blocking factor less than the one specified. 5842@end table 5843 5844@node Ignore Zeros 5845@unnumberedsubsubsec Ignoring Blocks of Zeros 5846 5847@cindex End-of-archive blocks, ignoring 5848@cindex Ignoring end-of-archive blocks 5849@opindex ignore-zeros 5850Normally, @command{tar} stops reading when it encounters a block of zeros 5851between file entries (which usually indicates the end of the archive). 5852@option{--ignore-zeros} (@option{-i}) allows @command{tar} to 5853completely read an archive which contains a block of zeros before the 5854end (i.e., a damaged archive, or one that was created by concatenating 5855several archives together). 5856 5857The @option{--ignore-zeros} (@option{-i}) option is turned off by default because many 5858versions of @command{tar} write garbage after the end-of-archive entry, 5859since that part of the media is never supposed to be read. @GNUTAR{} 5860does not write after the end of an archive, but seeks to 5861maintain compatibility among archiving utilities. 5862 5863@table @option 5864@item --ignore-zeros 5865@itemx -i 5866To ignore blocks of zeros (i.e., end-of-archive entries) which may be 5867encountered while reading an archive. Use in conjunction with 5868@option{--extract} or @option{--list}. 5869@end table 5870 5871@node Writing 5872@subsection Changing How @command{tar} Writes Files 5873@UNREVISED 5874 5875@FIXME{Introductory paragraph} 5876 5877@menu 5878* Dealing with Old Files:: 5879* Overwrite Old Files:: 5880* Keep Old Files:: 5881* Keep Newer Files:: 5882* Unlink First:: 5883* Recursive Unlink:: 5884* Data Modification Times:: 5885* Setting Access Permissions:: 5886* Directory Modification Times and Permissions:: 5887* Writing to Standard Output:: 5888* Writing to an External Program:: 5889* remove files:: 5890@end menu 5891 5892@node Dealing with Old Files 5893@unnumberedsubsubsec Options Controlling the Overwriting of Existing Files 5894 5895@xopindex{overwrite-dir, introduced} 5896When extracting files, if @command{tar} discovers that the extracted 5897file already exists, it normally replaces the file by removing it before 5898extracting it, to prevent confusion in the presence of hard or symbolic 5899links. (If the existing file is a symbolic link, it is removed, not 5900followed.) However, if a directory cannot be removed because it is 5901nonempty, @command{tar} normally overwrites its metadata (ownership, 5902permission, etc.). The @option{--overwrite-dir} option enables this 5903default behavior. To be more cautious and preserve the metadata of 5904such a directory, use the @option{--no-overwrite-dir} option. 5905 5906@cindex Overwriting old files, prevention 5907@xopindex{keep-old-files, introduced} 5908To be even more cautious and prevent existing files from being replaced, use 5909the @option{--keep-old-files} (@option{-k}) option. It causes 5910@command{tar} to refuse to replace or update a file that already 5911exists, i.e., a file with the same name as an archive member prevents 5912extraction of that archive member. Instead, it reports an error. For 5913example: 5914 5915@example 5916$ @kbd{ls} 5917blues 5918$ @kbd{tar -x -k -f archive.tar} 5919tar: blues: Cannot open: File exists 5920tar: Exiting with failure status due to previous errors 5921@end example 5922 5923@xopindex{skip-old-files, introduced} 5924If you wish to preserve old files untouched, but don't want 5925@command{tar} to treat them as errors, use the 5926@option{--skip-old-files} option. This option causes @command{tar} to 5927silently skip extracting over existing files. 5928 5929@xopindex{overwrite, introduced} 5930To be more aggressive about altering existing files, use the 5931@option{--overwrite} option. It causes @command{tar} to overwrite 5932existing files and to follow existing symbolic links when extracting. 5933 5934@cindex Protecting old files 5935Some people argue that @GNUTAR{} should not hesitate 5936to overwrite files with other files when extracting. When extracting 5937a @command{tar} archive, they expect to see a faithful copy of the 5938state of the file system when the archive was created. It is debatable 5939that this would always be a proper behavior. For example, suppose one 5940has an archive in which @file{usr/local} is a link to 5941@file{usr/local2}. Since then, maybe the site removed the link and 5942renamed the whole hierarchy from @file{/usr/local2} to 5943@file{/usr/local}. Such things happen all the time. I guess it would 5944not be welcome at all that @GNUTAR{} removes the 5945whole hierarchy just to make room for the link to be reinstated 5946(unless it @emph{also} simultaneously restores the full 5947@file{/usr/local2}, of course!) @GNUTAR{} is indeed 5948able to remove a whole hierarchy to reestablish a symbolic link, for 5949example, but @emph{only if} @option{--recursive-unlink} is specified 5950to allow this behavior. In any case, single files are silently 5951removed. 5952 5953@xopindex{unlink-first, introduced} 5954Finally, the @option{--unlink-first} (@option{-U}) option can improve performance in 5955some cases by causing @command{tar} to remove files unconditionally 5956before extracting them. 5957 5958@node Overwrite Old Files 5959@unnumberedsubsubsec Overwrite Old Files 5960 5961@table @option 5962@opindex overwrite 5963@item --overwrite 5964Overwrite existing files and directory metadata when extracting files 5965from an archive. 5966 5967This causes @command{tar} to write extracted files into the file system without 5968regard to the files already on the system; i.e., files with the same 5969names as archive members are overwritten when the archive is extracted. 5970It also causes @command{tar} to extract the ownership, permissions, 5971and time stamps onto any preexisting files or directories. 5972If the name of a corresponding file name is a symbolic link, the file 5973pointed to by the symbolic link will be overwritten instead of the 5974symbolic link itself (if this is possible). Moreover, special devices, 5975empty directories and even symbolic links are automatically removed if 5976they are in the way of extraction. 5977 5978Be careful when using the @option{--overwrite} option, particularly when 5979combined with the @option{--absolute-names} (@option{-P}) option, as this combination 5980can change the contents, ownership or permissions of any file on your 5981system. Also, many systems do not take kindly to overwriting files that 5982are currently being executed. 5983 5984@opindex overwrite-dir 5985@item --overwrite-dir 5986Overwrite the metadata of directories when extracting files from an 5987archive, but remove other files before extracting. 5988@end table 5989 5990@node Keep Old Files 5991@unnumberedsubsubsec Keep Old Files 5992 5993@GNUTAR{} provides two options to control its actions in a situation 5994when it is about to extract a file which already exists on disk. 5995 5996@table @option 5997@opindex keep-old-files 5998@item --keep-old-files 5999@itemx -k 6000Do not replace existing files from archive. When such a file is 6001encountered, @command{tar} issues an error message. Upon end of 6002extraction, @command{tar} exits with code 2 (@pxref{exit status}). 6003 6004@item --skip-old-files 6005Do not replace existing files from archive, but do not treat that 6006as error. Such files are silently skipped and do not affect 6007@command{tar} exit status. 6008 6009Additional verbosity can be obtained using @option{--warning=existing-file} 6010together with that option (@pxref{warnings}). 6011@end table 6012 6013@node Keep Newer Files 6014@unnumberedsubsubsec Keep Newer Files 6015 6016@table @option 6017@opindex keep-newer-files 6018@item --keep-newer-files 6019Do not replace existing files that are newer than their archive 6020copies. This option is meaningless with @option{--list} (@option{-t}). 6021@end table 6022 6023@node Unlink First 6024@unnumberedsubsubsec Unlink First 6025 6026@table @option 6027@opindex unlink-first 6028@item --unlink-first 6029@itemx -U 6030Remove files before extracting over them. 6031This can make @command{tar} run a bit faster if you know in advance 6032that the extracted files all need to be removed. Normally this option 6033slows @command{tar} down slightly, so it is disabled by default. 6034@end table 6035 6036@node Recursive Unlink 6037@unnumberedsubsubsec Recursive Unlink 6038 6039@table @option 6040@opindex recursive-unlink 6041@item --recursive-unlink 6042When this option is specified, try removing files and directory hierarchies 6043before extracting over them. @emph{This is a dangerous option!} 6044@end table 6045 6046If you specify the @option{--recursive-unlink} option, 6047@command{tar} removes @emph{anything} that keeps you from extracting a file 6048as far as current permissions will allow it. This could include removal 6049of the contents of a full directory hierarchy. 6050 6051@node Data Modification Times 6052@unnumberedsubsubsec Setting Data Modification Times 6053 6054@cindex Data modification times of extracted files 6055@cindex Modification times of extracted files 6056Normally, @command{tar} sets the data modification times of extracted 6057files to the corresponding times recorded for the files in the archive, but 6058limits the permissions of extracted files by the current @code{umask} 6059setting. 6060 6061To set the data modification times of extracted files to the time when 6062the files were extracted, use the @option{--touch} (@option{-m}) option in 6063conjunction with @option{--extract} (@option{--get}, @option{-x}). 6064 6065@table @option 6066@opindex touch 6067@item --touch 6068@itemx -m 6069Sets the data modification time of extracted archive members to the time 6070they were extracted, not the time recorded for them in the archive. 6071Use in conjunction with @option{--extract} (@option{--get}, @option{-x}). 6072@end table 6073 6074@node Setting Access Permissions 6075@unnumberedsubsubsec Setting Access Permissions 6076 6077@cindex Permissions of extracted files 6078@cindex Modes of extracted files 6079To set the modes (access permissions) of extracted files to those 6080recorded for those files in the archive, use @option{--same-permissions} 6081in conjunction with the @option{--extract} (@option{--get}, 6082@option{-x}) operation. 6083 6084@table @option 6085@opindex preserve-permissions 6086@opindex same-permissions 6087@item --preserve-permissions 6088@itemx --same-permissions 6089@c @itemx --ignore-umask 6090@itemx -p 6091Set modes of extracted archive members to those recorded in the 6092archive, instead of current umask settings. Use in conjunction with 6093@option{--extract} (@option{--get}, @option{-x}). 6094@end table 6095 6096@node Directory Modification Times and Permissions 6097@unnumberedsubsubsec Directory Modification Times and Permissions 6098 6099After successfully extracting a file member, @GNUTAR{} normally 6100restores its permissions and modification times, as described in the 6101previous sections. This cannot be done for directories, because 6102after extracting a directory @command{tar} will almost certainly 6103extract files into that directory and this will cause the directory 6104modification time to be updated. Moreover, restoring that directory 6105permissions may not permit file creation within it. Thus, restoring 6106directory permissions and modification times must be delayed at least 6107until all files have been extracted into that directory. @GNUTAR{} 6108restores directories using the following approach. 6109 6110The extracted directories are created with the mode specified in the 6111archive, as modified by the umask of the user, which gives sufficient 6112permissions to allow file creation. The meta-information about the 6113directory is recorded in the temporary list of directories. When 6114preparing to extract next archive member, @GNUTAR{} checks if the 6115directory prefix of this file contains the remembered directory. If 6116it does not, the program assumes that all files have been extracted 6117into that directory, restores its modification time and permissions 6118and removes its entry from the internal list. This approach allows 6119to correctly restore directory meta-information in the majority of 6120cases, while keeping memory requirements sufficiently small. It is 6121based on the fact, that most @command{tar} archives use the predefined 6122order of members: first the directory, then all the files and 6123subdirectories in that directory. 6124 6125However, this is not always true. The most important exception are 6126incremental archives (@pxref{Incremental Dumps}). The member order in 6127an incremental archive is reversed: first all directory members are 6128stored, followed by other (non-directory) members. So, when extracting 6129from incremental archives, @GNUTAR{} alters the above procedure. It 6130remembers all restored directories, and restores their meta-data 6131only after the entire archive has been processed. Notice, that you do 6132not need to specify any special options for that, as @GNUTAR{} 6133automatically detects archives in incremental format. 6134 6135There may be cases, when such processing is required for normal archives 6136too. Consider the following example: 6137 6138@smallexample 6139@group 6140$ @kbd{tar --no-recursion -cvf archive \ 6141 foo foo/file1 bar bar/file foo/file2} 6142foo/ 6143foo/file1 6144bar/ 6145bar/file 6146foo/file2 6147@end group 6148@end smallexample 6149 6150During the normal operation, after encountering @file{bar} 6151@GNUTAR{} will assume that all files from the directory @file{foo} 6152were already extracted and will therefore restore its timestamp and 6153permission bits. However, after extracting @file{foo/file2} the 6154directory timestamp will be offset again. 6155 6156To correctly restore directory meta-information in such cases, use 6157the @option{--delay-directory-restore} command line option: 6158 6159@table @option 6160@opindex delay-directory-restore 6161@item --delay-directory-restore 6162Delays restoring of the modification times and permissions of extracted 6163directories until the end of extraction. This way, correct 6164meta-information is restored even if the archive has unusual member 6165ordering. 6166 6167@opindex no-delay-directory-restore 6168@item --no-delay-directory-restore 6169Cancel the effect of the previous @option{--delay-directory-restore}. 6170Use this option if you have used @option{--delay-directory-restore} in 6171@env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to 6172temporarily disable it. 6173@end table 6174 6175@node Writing to Standard Output 6176@unnumberedsubsubsec Writing to Standard Output 6177 6178@cindex Writing extracted files to standard output 6179@cindex Standard output, writing extracted files to 6180To write the extracted files to the standard output, instead of 6181creating the files on the file system, use @option{--to-stdout} (@option{-O}) in 6182conjunction with @option{--extract} (@option{--get}, @option{-x}). This option is useful if you are 6183extracting files to send them through a pipe, and do not need to 6184preserve them in the file system. If you extract multiple members, 6185they appear on standard output concatenated, in the order they are 6186found in the archive. 6187 6188@table @option 6189@opindex to-stdout 6190@item --to-stdout 6191@itemx -O 6192Writes files to the standard output. Use only in conjunction with 6193@option{--extract} (@option{--get}, @option{-x}). When this option is 6194used, instead of creating the files specified, @command{tar} writes 6195the contents of the files extracted to its standard output. This may 6196be useful if you are only extracting the files in order to send them 6197through a pipe. This option is meaningless with @option{--list} 6198(@option{-t}). 6199@end table 6200 6201This can be useful, for example, if you have a tar archive containing 6202a big file and don't want to store the file on disk before processing 6203it. You can use a command like this: 6204 6205@smallexample 6206tar -xOzf foo.tgz bigfile | process 6207@end smallexample 6208 6209or even like this if you want to process the concatenation of the files: 6210 6211@smallexample 6212tar -xOzf foo.tgz bigfile1 bigfile2 | process 6213@end smallexample 6214 6215However, @option{--to-command} may be more convenient for use with 6216multiple files. See the next section. 6217 6218@node Writing to an External Program 6219@unnumberedsubsubsec Writing to an External Program 6220 6221You can instruct @command{tar} to send the contents of each extracted 6222file to the standard input of an external program: 6223 6224@table @option 6225@opindex to-command 6226@item --to-command=@var{command} 6227Extract files and pipe their contents to the standard input of 6228@var{command}. When this option is used, instead of creating the 6229files specified, @command{tar} invokes @var{command} and pipes the 6230contents of the files to its standard output. The @var{command} may 6231contain command line arguments (see @ref{external, Running External Commands}, 6232for more detail). 6233 6234Notice, that @var{command} is executed once for each regular file 6235extracted. Non-regular files (directories, etc.)@: are ignored when this 6236option is used. 6237@end table 6238 6239The command can obtain the information about the file it processes 6240from the following environment variables: 6241 6242@table @env 6243@vrindex TAR_FILETYPE, to-command environment 6244@item TAR_FILETYPE 6245Type of the file. It is a single letter with the following meaning: 6246 6247@multitable @columnfractions 0.10 0.90 6248@item f @tab Regular file 6249@item d @tab Directory 6250@item l @tab Symbolic link 6251@item h @tab Hard link 6252@item b @tab Block device 6253@item c @tab Character device 6254@end multitable 6255 6256Currently only regular files are supported. 6257 6258@vrindex TAR_MODE, to-command environment 6259@item TAR_MODE 6260File mode, an octal number. 6261 6262@vrindex TAR_FILENAME, to-command environment 6263@item TAR_FILENAME 6264The name of the file. 6265 6266@vrindex TAR_REALNAME, to-command environment 6267@item TAR_REALNAME 6268Name of the file as stored in the archive. 6269 6270@vrindex TAR_UNAME, to-command environment 6271@item TAR_UNAME 6272Name of the file owner. 6273 6274@vrindex TAR_GNAME, to-command environment 6275@item TAR_GNAME 6276Name of the file owner group. 6277 6278@vrindex TAR_ATIME, to-command environment 6279@item TAR_ATIME 6280Time of last access. It is a decimal number, representing seconds 6281since the Epoch. If the archive provides times with nanosecond 6282precision, the nanoseconds are appended to the timestamp after a 6283decimal point. 6284 6285@vrindex TAR_MTIME, to-command environment 6286@item TAR_MTIME 6287Time of last modification. 6288 6289@vrindex TAR_CTIME, to-command environment 6290@item TAR_CTIME 6291Time of last status change. 6292 6293@vrindex TAR_SIZE, to-command environment 6294@item TAR_SIZE 6295Size of the file. 6296 6297@vrindex TAR_UID, to-command environment 6298@item TAR_UID 6299UID of the file owner. 6300 6301@vrindex TAR_GID, to-command environment 6302@item TAR_GID 6303GID of the file owner. 6304@end table 6305 6306Additionally, the following variables contain information about 6307tar mode and the archive being processed: 6308 6309@table @env 6310@vrindex TAR_VERSION, to-command environment 6311@item TAR_VERSION 6312@GNUTAR{} version number. 6313 6314@vrindex TAR_ARCHIVE, to-command environment 6315@item TAR_ARCHIVE 6316The name of the archive @command{tar} is processing. 6317 6318@vrindex TAR_BLOCKING_FACTOR, to-command environment 6319@item TAR_BLOCKING_FACTOR 6320Current blocking factor (@pxref{Blocking}). 6321 6322@vrindex TAR_VOLUME, to-command environment 6323@item TAR_VOLUME 6324Ordinal number of the volume @command{tar} is processing. 6325 6326@vrindex TAR_FORMAT, to-command environment 6327@item TAR_FORMAT 6328Format of the archive being processed. @xref{Formats}, for a complete 6329list of archive format names. 6330@end table 6331 6332These variables are defined prior to executing the command, so you can 6333pass them as arguments, if you prefer. For example, if the command 6334@var{proc} takes the member name and size as its arguments, then you 6335could do: 6336 6337@smallexample 6338$ @kbd{tar -x -f archive.tar \ 6339 --to-command='proc $TAR_FILENAME $TAR_SIZE'} 6340@end smallexample 6341 6342@noindent 6343Notice single quotes to prevent variable names from being expanded by 6344the shell when invoking @command{tar}. 6345 6346If @var{command} exits with a non-0 status, @command{tar} will print 6347an error message similar to the following: 6348 6349@smallexample 6350tar: 2345: Child returned status 1 6351@end smallexample 6352 6353Here, @samp{2345} is the PID of the finished process. 6354 6355If this behavior is not wanted, use @option{--ignore-command-error}: 6356 6357@table @option 6358@opindex ignore-command-error 6359@item --ignore-command-error 6360Ignore exit codes of subprocesses. Notice that if the program 6361exits on signal or otherwise terminates abnormally, the error message 6362will be printed even if this option is used. 6363 6364@opindex no-ignore-command-error 6365@item --no-ignore-command-error 6366Cancel the effect of any previous @option{--ignore-command-error} 6367option. This option is useful if you have set 6368@option{--ignore-command-error} in @env{TAR_OPTIONS} 6369(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it. 6370@end table 6371 6372@node remove files 6373@unnumberedsubsubsec Removing Files 6374 6375@FIXME{The section is too terse. Something more to add? An example, 6376maybe?} 6377 6378@table @option 6379@opindex remove-files 6380@item --remove-files 6381Remove files after adding them to the archive. 6382@end table 6383 6384@node Scarce 6385@subsection Coping with Scarce Resources 6386@UNREVISED 6387 6388@cindex Small memory 6389@cindex Running out of space 6390 6391@menu 6392* Starting File:: 6393* Same Order:: 6394@end menu 6395 6396@node Starting File 6397@unnumberedsubsubsec Starting File 6398 6399@table @option 6400@opindex starting-file 6401@item --starting-file=@var{name} 6402@itemx -K @var{name} 6403Starts an operation in the middle of an archive. Use in conjunction 6404with @option{--extract} (@option{--get}, @option{-x}) or @option{--list} (@option{-t}). 6405@end table 6406 6407@cindex Middle of the archive, starting in the 6408If a previous attempt to extract files failed due to lack of disk 6409space, you can use @option{--starting-file=@var{name}} (@option{-K 6410@var{name}}) to start extracting only after member @var{name} of the 6411archive. This assumes, of course, that there is now free space, or 6412that you are now extracting into a different file system. (You could 6413also choose to suspend @command{tar}, remove unnecessary files from 6414the file system, and then resume the same @command{tar} operation. 6415In this case, @option{--starting-file} is not necessary.) See also 6416@ref{interactive}, and @ref{exclude}. 6417 6418@node Same Order 6419@unnumberedsubsubsec Same Order 6420 6421@table @option 6422@cindex Large lists of file names on small machines 6423@opindex same-order 6424@opindex preserve-order 6425@item --same-order 6426@itemx --preserve-order 6427@itemx -s 6428To process large lists of file names on machines with small amounts of 6429memory. Use in conjunction with @option{--compare} (@option{--diff}, 6430@option{-d}), @option{--list} (@option{-t}) or @option{--extract} 6431(@option{--get}, @option{-x}). 6432@end table 6433 6434The @option{--same-order} (@option{--preserve-order}, @option{-s}) option tells @command{tar} that the list of file 6435names to be listed or extracted is sorted in the same order as the 6436files in the archive. This allows a large list of names to be used, 6437even on a small machine that would not otherwise be able to hold all 6438the names in memory at the same time. Such a sorted list can easily be 6439created by running @samp{tar -t} on the archive and editing its output. 6440 6441This option is probably never needed on modern computer systems. 6442 6443@node backup 6444@section Backup options 6445 6446@cindex backup options 6447 6448@GNUTAR{} offers options for making backups of files 6449before writing new versions. These options control the details of 6450these backups. They may apply to the archive itself before it is 6451created or rewritten, as well as individual extracted members. Other 6452@acronym{GNU} programs (@command{cp}, @command{install}, @command{ln}, 6453and @command{mv}, for example) offer similar options. 6454 6455Backup options may prove unexpectedly useful when extracting archives 6456containing many members having identical name, or when extracting archives 6457on systems having file name limitations, making different members appear 6458as having similar names through the side-effect of name truncation. 6459@FIXME{This is true only if we have a good scheme for truncated backup names, 6460which I'm not sure at all: I suspect work is needed in this area.} 6461When any existing file is backed up before being overwritten by extraction, 6462then clashing files are automatically be renamed to be unique, and the 6463true name is kept for only the last file of a series of clashing files. 6464By using verbose mode, users may track exactly what happens. 6465 6466At the detail level, some decisions are still experimental, and may 6467change in the future, we are waiting comments from our users. So, please 6468do not learn to depend blindly on the details of the backup features. 6469For example, currently, directories themselves are never renamed through 6470using these options, so, extracting a file over a directory still has 6471good chances to fail. Also, backup options apply to created archives, 6472not only to extracted members. For created archives, backups will not 6473be attempted when the archive is a block or character device, or when it 6474refers to a remote file. 6475 6476For the sake of simplicity and efficiency, backups are made by renaming old 6477files prior to creation or extraction, and not by copying. The original 6478name is restored if the file creation fails. If a failure occurs after a 6479partial extraction of a file, both the backup and the partially extracted 6480file are kept. 6481 6482@table @samp 6483@item --backup[=@var{method}] 6484@opindex backup 6485@vindex VERSION_CONTROL 6486@cindex backups 6487Back up files that are about to be overwritten or removed. 6488Without this option, the original versions are destroyed. 6489 6490Use @var{method} to determine the type of backups made. 6491If @var{method} is not specified, use the value of the @env{VERSION_CONTROL} 6492environment variable. And if @env{VERSION_CONTROL} is not set, 6493use the @samp{existing} method. 6494 6495@vindex version-control @r{Emacs variable} 6496This option corresponds to the Emacs variable @samp{version-control}; 6497the same values for @var{method} are accepted as in Emacs. This option 6498also allows more descriptive names. The valid @var{method}s are: 6499 6500@table @samp 6501@item t 6502@itemx numbered 6503@cindex numbered @r{backup method} 6504Always make numbered backups. 6505 6506@item nil 6507@itemx existing 6508@cindex existing @r{backup method} 6509Make numbered backups of files that already have them, simple backups 6510of the others. 6511 6512@item never 6513@itemx simple 6514@cindex simple @r{backup method} 6515Always make simple backups. 6516 6517@end table 6518 6519@item --suffix=@var{suffix} 6520@opindex suffix 6521@cindex backup suffix 6522@vindex SIMPLE_BACKUP_SUFFIX 6523Append @var{suffix} to each backup file made with @option{--backup}. If this 6524option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX} 6525environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not 6526set, the default is @samp{~}, just as in Emacs. 6527 6528@end table 6529 6530@node looking ahead 6531@section Looking Ahead: The Rest of this Manual 6532 6533You have now seen how to use all eight of the operations available to 6534@command{tar}, and a number of the possible options. The next chapter 6535explains how to choose and change file and archive names, how to use 6536files to store names of other files which you can then call as 6537arguments to @command{tar} (this can help you save time if you expect to 6538archive the same list of files a number of times), and so forth. 6539@FIXME{in case it's not obvious, i'm making this up in some sense 6540based on my limited memory of what the next chapter *really* does. i 6541just wanted to flesh out this final section a little bit so i'd 6542remember to stick it in here. :-)} 6543 6544If there are too many files to conveniently list on the command line, 6545you can list the names in a file, and @command{tar} will read that file. 6546@xref{files}. 6547 6548There are various ways of causing @command{tar} to skip over some files, 6549and not archive them. @xref{Choosing}. 6550 6551@node Backups 6552@chapter Performing Backups and Restoring Files 6553@cindex backups 6554 6555@GNUTAR{} is distributed along with the scripts for performing backups 6556and restores. Even if there is a good chance those scripts may be 6557satisfying to you, they are not the only scripts or methods available for doing 6558backups and restore. You may well create your own, or use more 6559sophisticated packages dedicated to that purpose. 6560 6561Some users are enthusiastic about @code{Amanda} (The Advanced Maryland 6562Automatic Network Disk Archiver), a backup system developed by James 6563da Silva @file{jds@@cs.umd.edu} and available on many Unix systems. 6564This is free software, and it is available from @uref{http://www.amanda.org}. 6565 6566@FIXME{ 6567 6568Here is a possible plan for a future documentation about the backuping 6569scripts which are provided within the @GNUTAR{} 6570distribution. 6571 6572@itemize @bullet 6573@item dumps 6574 @itemize @minus 6575 @item what are dumps 6576 @item different levels of dumps 6577 @itemize + 6578 @item full dump = dump everything 6579 @item level 1, level 2 dumps etc 6580 A level @var{n} dump dumps everything changed since the last level 6581 @var{n}-1 dump (?) 6582 @end itemize 6583 @item how to use scripts for dumps (ie, the concept) 6584 @itemize + 6585 @item scripts to run after editing backup specs (details) 6586 @end itemize 6587 @item Backup Specs, what is it. 6588 @itemize + 6589 @item how to customize 6590 @item actual text of script [/sp/dump/backup-specs] 6591 @end itemize 6592 @item Problems 6593 @itemize + 6594 @item rsh doesn't work 6595 @item rtape isn't installed 6596 @item (others?) 6597 @end itemize 6598 @item the @option{--incremental} option of tar 6599 @item tapes 6600 @itemize + 6601 @item write protection 6602 @item types of media, different sizes and types, useful for different things 6603 @item files and tape marks 6604 one tape mark between files, two at end. 6605 @item positioning the tape 6606 MT writes two at end of write, 6607 backspaces over one when writing again. 6608 @end itemize 6609 @end itemize 6610@end itemize 6611} 6612 6613This chapter documents both the provided shell scripts and @command{tar} 6614options which are more specific to usage as a backup tool. 6615 6616To @dfn{back up} a file system means to create archives that contain 6617all the files in that file system. Those archives can then be used to 6618restore any or all of those files (for instance if a disk crashes or a 6619file is accidentally deleted). File system @dfn{backups} are also 6620called @dfn{dumps}. 6621 6622@menu 6623* Full Dumps:: Using @command{tar} to Perform Full Dumps 6624* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps 6625* Backup Levels:: Levels of Backups 6626* Backup Parameters:: Setting Parameters for Backups and Restoration 6627* Scripted Backups:: Using the Backup Scripts 6628* Scripted Restoration:: Using the Restore Script 6629@end menu 6630 6631@node Full Dumps 6632@section Using @command{tar} to Perform Full Dumps 6633@UNREVISED 6634 6635@cindex full dumps 6636@cindex dumps, full 6637 6638@cindex corrupted archives 6639Full dumps should only be made when no other people or programs 6640are modifying files in the file system. If files are modified while 6641@command{tar} is making the backup, they may not be stored properly in 6642the archive, in which case you won't be able to restore them if you 6643have to. (Files not being modified are written with no trouble, and do 6644not corrupt the entire archive.) 6645 6646You will want to use the @option{--label=@var{archive-label}} 6647(@option{-V @var{archive-label}}) option to give the archive a 6648volume label, so you can tell what this archive is even if the label 6649falls off the tape, or anything like that. 6650 6651Unless the file system you are dumping is guaranteed to fit on 6652one volume, you will need to use the @option{--multi-volume} (@option{-M}) option. 6653Make sure you have enough tapes on hand to complete the backup. 6654 6655If you want to dump each file system separately you will need to use 6656the @option{--one-file-system} option to prevent 6657@command{tar} from crossing file system boundaries when storing 6658(sub)directories. 6659 6660The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps}) 6661option is not needed, since this is a complete copy of everything in 6662the file system, and a full restore from this backup would only be 6663done onto a completely 6664empty disk. 6665 6666Unless you are in a hurry, and trust the @command{tar} program (and your 6667tapes), it is a good idea to use the @option{--verify} (@option{-W}) 6668option, to make sure your files really made it onto the dump properly. 6669This will also detect cases where the file was modified while (or just 6670after) it was being archived. Not all media (notably cartridge tapes) 6671are capable of being verified, unfortunately. 6672 6673@node Incremental Dumps 6674@section Using @command{tar} to Perform Incremental Dumps 6675 6676@dfn{Incremental backup} is a special form of @GNUTAR{} archive that 6677stores additional metadata so that exact state of the file system 6678can be restored when extracting the archive. 6679 6680@GNUTAR{} currently offers two options for handling incremental 6681backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g 6682@var{snapshot-file}}) and @option{--incremental} (@option{-G}). 6683 6684@xopindex{listed-incremental, described} 6685The option @option{--listed-incremental} instructs tar to operate on 6686an incremental archive with additional metadata stored in a standalone 6687file, called a @dfn{snapshot file}. The purpose of this file is to help 6688determine which files have been changed, added or deleted since the 6689last backup, so that the next incremental backup will contain only 6690modified files. The name of the snapshot file is given as an argument 6691to the option: 6692 6693@table @option 6694@item --listed-incremental=@var{file} 6695@itemx -g @var{file} 6696 Handle incremental backups with snapshot data in @var{file}. 6697@end table 6698 6699To create an incremental backup, you would use 6700@option{--listed-incremental} together with @option{--create} 6701(@pxref{create}). For example: 6702 6703@smallexample 6704$ @kbd{tar --create \ 6705 --file=archive.1.tar \ 6706 --listed-incremental=/var/log/usr.snar \ 6707 /usr} 6708@end smallexample 6709 6710This will create in @file{archive.1.tar} an incremental backup of 6711the @file{/usr} file system, storing additional metadata in the file 6712@file{/var/log/usr.snar}. If this file does not exist, it will be 6713created. The created archive will then be a @dfn{level 0 backup}; 6714please see the next section for more on backup levels. 6715 6716Otherwise, if the file @file{/var/log/usr.snar} exists, it 6717determines which files are modified. In this case only these files will be 6718stored in the archive. Suppose, for example, that after running the 6719above command, you delete file @file{/usr/doc/old} and create 6720directory @file{/usr/local/db} with the following contents: 6721 6722@smallexample 6723$ @kbd{ls /usr/local/db} 6724/usr/local/db/data 6725/usr/local/db/index 6726@end smallexample 6727 6728Some time later you create another incremental backup. You will 6729then see: 6730 6731@smallexample 6732$ @kbd{tar --create \ 6733 --file=archive.2.tar \ 6734 --listed-incremental=/var/log/usr.snar \ 6735 /usr} 6736tar: usr/local/db: Directory is new 6737usr/local/db/ 6738usr/local/db/data 6739usr/local/db/index 6740@end smallexample 6741 6742@noindent 6743The created archive @file{archive.2.tar} will contain only these 6744three members. This archive is called a @dfn{level 1 backup}. Notice 6745that @file{/var/log/usr.snar} will be updated with the new data, so if 6746you plan to create more @samp{level 1} backups, it is necessary to 6747create a working copy of the snapshot file before running 6748@command{tar}. The above example will then be modified as follows: 6749 6750@smallexample 6751$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1} 6752$ @kbd{tar --create \ 6753 --file=archive.2.tar \ 6754 --listed-incremental=/var/log/usr.snar-1 \ 6755 /usr} 6756@end smallexample 6757 6758@anchor{--level=0} 6759@xopindex{level, described} 6760You can force @samp{level 0} backups either by removing the snapshot 6761file before running @command{tar}, or by supplying the 6762@option{--level=0} option, e.g.: 6763 6764@smallexample 6765$ @kbd{tar --create \ 6766 --file=archive.2.tar \ 6767 --listed-incremental=/var/log/usr.snar-0 \ 6768 --level=0 \ 6769 /usr} 6770@end smallexample 6771 6772Incremental dumps depend crucially on time stamps, so the results are 6773unreliable if you modify a file's time stamps during dumping (e.g., 6774with the @option{--atime-preserve=replace} option), or if you set the clock 6775backwards. 6776 6777@anchor{device numbers} 6778@cindex Device numbers, using in incremental backups 6779Metadata stored in snapshot files include device numbers, which, 6780obviously are supposed to be non-volatile values. However, it turns 6781out that @acronym{NFS} devices have undependable values when an automounter 6782gets in the picture. This can lead to a great deal of spurious 6783redumping in incremental dumps, so it is somewhat useless to compare 6784two @acronym{NFS} devices numbers over time. The solution implemented 6785currently is to consider all @acronym{NFS} devices as being equal 6786when it comes to comparing directories; this is fairly gross, but 6787there does not seem to be a better way to go. 6788 6789Apart from using @acronym{NFS}, there are a number of cases where 6790relying on device numbers can cause spurious redumping of unmodified 6791files. For example, this occurs when archiving @acronym{LVM} snapshot 6792volumes. To avoid this, use @option{--no-check-device} option: 6793 6794@table @option 6795@xopindex{no-check-device, described} 6796@item --no-check-device 6797Do not rely on device numbers when preparing a list of changed files 6798for an incremental dump. 6799 6800@xopindex{check-device, described} 6801@item --check-device 6802Use device numbers when preparing a list of changed files 6803for an incremental dump. This is the default behavior. The purpose 6804of this option is to undo the effect of the @option{--no-check-device} 6805if it was given in @env{TAR_OPTIONS} environment variable 6806(@pxref{TAR_OPTIONS}). 6807@end table 6808 6809There is also another way to cope with changing device numbers. It is 6810described in detail in @ref{Fixing Snapshot Files}. 6811 6812Note that incremental archives use @command{tar} extensions and may 6813not be readable by non-@acronym{GNU} versions of the @command{tar} program. 6814 6815@xopindex{listed-incremental, using with @option{--extract}} 6816@xopindex{extract, using with @option{--listed-incremental}} 6817To extract from the incremental dumps, use 6818@option{--listed-incremental} together with @option{--extract} 6819option (@pxref{extracting files}). In this case, @command{tar} does 6820not need to access snapshot file, since all the data necessary for 6821extraction are stored in the archive itself. So, when extracting, you 6822can give whatever argument to @option{--listed-incremental}, the usual 6823practice is to use @option{--listed-incremental=/dev/null}. 6824Alternatively, you can use @option{--incremental}, which needs no 6825arguments. In general, @option{--incremental} (@option{-G}) can be 6826used as a shortcut for @option{--listed-incremental} when listing or 6827extracting incremental backups (for more information regarding this 6828option, @pxref{incremental-op}). 6829 6830When extracting from the incremental backup @GNUTAR{} attempts to 6831restore the exact state the file system had when the archive was 6832created. In particular, it will @emph{delete} those files in the file 6833system that did not exist in their directories when the archive was 6834created. If you have created several levels of incremental files, 6835then in order to restore the exact contents the file system had when 6836the last level was created, you will need to restore from all backups 6837in turn. Continuing our example, to restore the state of @file{/usr} 6838file system, one would do@footnote{Notice, that since both archives 6839were created without @option{-P} option (@pxref{absolute}), these 6840commands should be run from the root file system.}: 6841 6842@smallexample 6843$ @kbd{tar --extract \ 6844 --listed-incremental=/dev/null \ 6845 --file archive.1.tar} 6846$ @kbd{tar --extract \ 6847 --listed-incremental=/dev/null \ 6848 --file archive.2.tar} 6849@end smallexample 6850 6851To list the contents of an incremental archive, use @option{--list} 6852(@pxref{list}), as usual. To obtain more information about the 6853archive, use @option{--listed-incremental} or @option{--incremental} 6854combined with two @option{--verbose} options@footnote{Two 6855@option{--verbose} options were selected to avoid breaking usual 6856verbose listing output (@option{--list --verbose}) when using in 6857scripts. 6858 6859@xopindex{incremental, using with @option{--list}} 6860@xopindex{listed-incremental, using with @option{--list}} 6861@xopindex{list, using with @option{--incremental}} 6862@xopindex{list, using with @option{--listed-incremental}} 6863Versions of @GNUTAR{} up to 1.15.1 used to dump verbatim binary 6864contents of the DUMPDIR header (with terminating nulls) when 6865@option{--incremental} or @option{--listed-incremental} option was 6866given, no matter what the verbosity level. This behavior, and, 6867especially, the binary output it produced were considered inconvenient 6868and were changed in version 1.16.}: 6869 6870@smallexample 6871@kbd{tar --list --incremental --verbose --verbose --file archive.tar} 6872@end smallexample 6873 6874This command will print, for each directory in the archive, the list 6875of files in that directory at the time the archive was created. This 6876information is put out in a format which is both human-readable and 6877unambiguous for a program: each file name is printed as 6878 6879@smallexample 6880@var{x} @var{file} 6881@end smallexample 6882 6883@noindent 6884where @var{x} is a letter describing the status of the file: @samp{Y} 6885if the file is present in the archive, @samp{N} if the file is not 6886included in the archive, or a @samp{D} if the file is a directory (and 6887is included in the archive). @xref{Dumpdir}, for the detailed 6888description of dumpdirs and status codes. Each such 6889line is terminated by a newline character. The last line is followed 6890by an additional newline to indicate the end of the data. 6891 6892@anchor{incremental-op}The option @option{--incremental} (@option{-G}) 6893gives the same behavior as @option{--listed-incremental} when used 6894with @option{--list} and @option{--extract} options. When used with 6895@option{--create} option, it creates an incremental archive without 6896creating snapshot file. Thus, it is impossible to create several 6897levels of incremental backups with @option{--incremental} option. 6898 6899@node Backup Levels 6900@section Levels of Backups 6901 6902An archive containing all the files in the file system is called a 6903@dfn{full backup} or @dfn{full dump}. You could insure your data by 6904creating a full dump every day. This strategy, however, would waste a 6905substantial amount of archive media and user time, as unchanged files 6906are daily re-archived. 6907 6908It is more efficient to do a full dump only occasionally. To back up 6909files between full dumps, you can use @dfn{incremental dumps}. A @dfn{level 6910one} dump archives all the files that have changed since the last full 6911dump. 6912 6913A typical dump strategy would be to perform a full dump once a week, 6914and a level one dump once a day. This means some versions of files 6915will in fact be archived more than once, but this dump strategy makes 6916it possible to restore a file system to within one day of accuracy by 6917only extracting two archives---the last weekly (full) dump and the 6918last daily (level one) dump. The only information lost would be in 6919files changed or created since the last daily backup. (Doing dumps 6920more than once a day is usually not worth the trouble.) 6921 6922@GNUTAR{} comes with scripts you can use to do full 6923and level-one (actually, even level-two and so on) dumps. Using 6924scripts (shell programs) to perform backups and restoration is a 6925convenient and reliable alternative to typing out file name lists 6926and @command{tar} commands by hand. 6927 6928Before you use these scripts, you need to edit the file 6929@file{backup-specs}, which specifies parameters used by the backup 6930scripts and by the restore script. This file is usually located 6931in @file{/etc/backup} directory. @xref{Backup Parameters}, for its 6932detailed description. Once the backup parameters are set, you can 6933perform backups or restoration by running the appropriate script. 6934 6935The name of the backup script is @code{backup}. The name of the 6936restore script is @code{restore}. The following sections describe 6937their use in detail. 6938 6939@emph{Please Note:} The backup and restoration scripts are 6940designed to be used together. While it is possible to restore files by 6941hand from an archive which was created using a backup script, and to create 6942an archive by hand which could then be extracted using the restore script, 6943it is easier to use the scripts. @xref{Incremental Dumps}, before 6944making such an attempt. 6945 6946@node Backup Parameters 6947@section Setting Parameters for Backups and Restoration 6948 6949The file @file{backup-specs} specifies backup parameters for the 6950backup and restoration scripts provided with @command{tar}. You must 6951edit @file{backup-specs} to fit your system configuration and schedule 6952before using these scripts. 6953 6954Syntactically, @file{backup-specs} is a shell script, containing 6955mainly variable assignments. However, any valid shell construct 6956is allowed in this file. Particularly, you may wish to define 6957functions within that script (e.g., see @code{RESTORE_BEGIN} below). 6958For more information about shell script syntax, please refer to 6959@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta 6960g_02, the definition of the Shell Command Language}. See also 6961@ref{Top,,Bash Features,bashref,Bash Reference Manual}. 6962 6963The shell variables controlling behavior of @code{backup} and 6964@code{restore} are described in the following subsections. 6965 6966@menu 6967* General-Purpose Variables:: 6968* Magnetic Tape Control:: 6969* User Hooks:: 6970* backup-specs example:: An Example Text of @file{Backup-specs} 6971@end menu 6972 6973@node General-Purpose Variables 6974@subsection General-Purpose Variables 6975 6976@defvr {Backup variable} ADMINISTRATOR 6977The user name of the backup administrator. @code{Backup} scripts 6978sends a backup report to this address. 6979@end defvr 6980 6981@defvr {Backup variable} BACKUP_HOUR 6982The hour at which the backups are done. This can be a number from 0 6983to 23, or the time specification in form @var{hours}:@var{minutes}, 6984or the string @samp{now}. 6985 6986This variable is used by @code{backup}. Its value may be overridden 6987using @option{--time} option (@pxref{Scripted Backups}). 6988@end defvr 6989 6990@defvr {Backup variable} TAPE_FILE 6991 6992The device @command{tar} writes the archive to. If @var{TAPE_FILE} 6993is a remote archive (@pxref{remote-dev}), backup script will suppose 6994that your @command{mt} is able to access remote devices. If @var{RSH} 6995(@pxref{RSH}) is set, @option{--rsh-command} option will be added to 6996invocations of @command{mt}. 6997@end defvr 6998 6999@defvr {Backup variable} BLOCKING 7000 7001The blocking factor @command{tar} will use when writing the dump archive. 7002@xref{Blocking Factor}. 7003@end defvr 7004 7005@defvr {Backup variable} BACKUP_DIRS 7006 7007A list of file systems to be dumped (for @code{backup}), or restored 7008(for @code{restore}). You can include any directory 7009name in the list --- subdirectories on that file system will be 7010included, regardless of how they may look to other networked machines. 7011Subdirectories on other file systems will be ignored. 7012 7013The host name specifies which host to run @command{tar} on, and should 7014normally be the host that actually contains the file system. However, 7015the host machine must have @GNUTAR{} installed, and 7016must be able to access the directory containing the backup scripts and 7017their support files using the same file name that is used on the 7018machine where the scripts are run (i.e., what @command{pwd} will print 7019when in that directory on that machine). If the host that contains 7020the file system does not have this capability, you can specify another 7021host as long as it can access the file system through @acronym{NFS}. 7022 7023If the list of file systems is very long you may wish to put it 7024in a separate file. This file is usually named 7025@file{/etc/backup/dirs}, but this name may be overridden in 7026@file{backup-specs} using @code{DIRLIST} variable. 7027@end defvr 7028 7029@defvr {Backup variable} DIRLIST 7030 7031The name of the file that contains a list of file systems to backup 7032or restore. By default it is @file{/etc/backup/dirs}. 7033@end defvr 7034 7035@defvr {Backup variable} BACKUP_FILES 7036 7037A list of individual files to be dumped (for @code{backup}), or restored 7038(for @code{restore}). These should be accessible from the machine on 7039which the backup script is run. 7040 7041If the list of individual files is very long you may wish to store it 7042in a separate file. This file is usually named 7043@file{/etc/backup/files}, but this name may be overridden in 7044@file{backup-specs} using @code{FILELIST} variable. 7045@end defvr 7046 7047@defvr {Backup variable} FILELIST 7048 7049The name of the file that contains a list of individual files to backup 7050or restore. By default it is @file{/etc/backup/files}. 7051@end defvr 7052 7053@defvr {Backup variable} MT 7054 7055Full file name of @command{mt} binary. 7056@end defvr 7057 7058@defvr {Backup variable} RSH 7059@anchor{RSH} 7060Full file name of @command{rsh} binary or its equivalent. You may wish to 7061set it to @code{ssh}, to improve security. In this case you will have 7062to use public key authentication. 7063@end defvr 7064 7065@defvr {Backup variable} RSH_COMMAND 7066 7067Full file name of @command{rsh} binary on remote machines. This will 7068be passed via @option{--rsh-command} option to the remote invocation 7069of @GNUTAR{}. 7070@end defvr 7071 7072@defvr {Backup variable} VOLNO_FILE 7073 7074Name of temporary file to hold volume numbers. This needs to be accessible 7075by all the machines which have file systems to be dumped. 7076@end defvr 7077 7078@defvr {Backup variable} XLIST 7079 7080Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file 7081located on the remote machine and containing the list of files to 7082be excluded from the backup. Exclude file lists are searched in 7083/etc/tar-backup directory. A common use for exclude file lists 7084is to exclude files containing security-sensitive information 7085(e.g., @file{/etc/shadow} from backups). 7086 7087This variable affects only @code{backup}. 7088@end defvr 7089 7090@defvr {Backup variable} SLEEP_TIME 7091 7092Time to sleep between dumps of any two successive file systems 7093 7094This variable affects only @code{backup}. 7095@end defvr 7096 7097@defvr {Backup variable} DUMP_REMIND_SCRIPT 7098 7099Script to be run when it's time to insert a new tape in for the next 7100volume. Administrators may want to tailor this script for their site. 7101If this variable isn't set, @GNUTAR{} will display its built-in 7102prompt, and will expect confirmation from the console. For the 7103description of the default prompt, see @ref{change volume prompt}. 7104 7105@end defvr 7106 7107@defvr {Backup variable} SLEEP_MESSAGE 7108 7109Message to display on the terminal while waiting for dump time. Usually 7110this will just be some literal text. 7111@end defvr 7112 7113@defvr {Backup variable} TAR 7114 7115Full file name of the @GNUTAR{} executable. If this is not set, backup 7116scripts will search @command{tar} in the current shell path. 7117@end defvr 7118 7119@node Magnetic Tape Control 7120@subsection Magnetic Tape Control 7121 7122Backup scripts access tape device using special @dfn{hook functions}. 7123These functions take a single argument --- the name of the tape 7124device. Their names are kept in the following variables: 7125 7126@defvr {Backup variable} MT_BEGIN 7127The name of @dfn{begin} function. This function is called before 7128accessing the drive. By default it retensions the tape: 7129 7130@smallexample 7131MT_BEGIN=mt_begin 7132 7133mt_begin() @{ 7134 mt -f "$1" retension 7135@} 7136@end smallexample 7137@end defvr 7138 7139@defvr {Backup variable} MT_REWIND 7140The name of @dfn{rewind} function. The default definition is as 7141follows: 7142 7143@smallexample 7144MT_REWIND=mt_rewind 7145 7146mt_rewind() @{ 7147 mt -f "$1" rewind 7148@} 7149@end smallexample 7150 7151@end defvr 7152 7153@defvr {Backup variable} MT_OFFLINE 7154The name of the function switching the tape off line. By default 7155it is defined as follows: 7156 7157@smallexample 7158MT_OFFLINE=mt_offline 7159 7160mt_offline() @{ 7161 mt -f "$1" offl 7162@} 7163@end smallexample 7164@end defvr 7165 7166@defvr {Backup variable} MT_STATUS 7167The name of the function used to obtain the status of the archive device, 7168including error count. Default definition: 7169 7170@smallexample 7171MT_STATUS=mt_status 7172 7173mt_status() @{ 7174 mt -f "$1" status 7175@} 7176@end smallexample 7177@end defvr 7178 7179@node User Hooks 7180@subsection User Hooks 7181 7182@dfn{User hooks} are shell functions executed before and after 7183each @command{tar} invocation. Thus, there are @dfn{backup 7184hooks}, which are executed before and after dumping each file 7185system, and @dfn{restore hooks}, executed before and 7186after restoring a file system. Each user hook is a shell function 7187taking four arguments: 7188 7189@deffn {User Hook Function} hook @var{level} @var{host} @var{fs} @var{fsname} 7190Its arguments are: 7191 7192@table @var 7193@item level 7194Current backup or restore level. 7195 7196@item host 7197Name or IP address of the host machine being dumped or restored. 7198 7199@item fs 7200Full file name of the file system being dumped or restored. 7201 7202@item fsname 7203File system name with directory separators replaced with colons. This 7204is useful, e.g., for creating unique files. 7205@end table 7206@end deffn 7207 7208Following variables keep the names of user hook functions: 7209 7210@defvr {Backup variable} DUMP_BEGIN 7211Dump begin function. It is executed before dumping the file system. 7212@end defvr 7213 7214@defvr {Backup variable} DUMP_END 7215Executed after dumping the file system. 7216@end defvr 7217 7218@defvr {Backup variable} RESTORE_BEGIN 7219Executed before restoring the file system. 7220@end defvr 7221 7222@defvr {Backup variable} RESTORE_END 7223Executed after restoring the file system. 7224@end defvr 7225 7226@node backup-specs example 7227@subsection An Example Text of @file{Backup-specs} 7228 7229The following is an example of @file{backup-specs}: 7230 7231@smallexample 7232# site-specific parameters for file system backup. 7233 7234ADMINISTRATOR=friedman 7235BACKUP_HOUR=1 7236TAPE_FILE=/dev/nrsmt0 7237 7238# Use @code{ssh} instead of the less secure @code{rsh} 7239RSH=/usr/bin/ssh 7240RSH_COMMAND=/usr/bin/ssh 7241 7242# Override MT_STATUS function: 7243my_status() @{ 7244 mts -t $TAPE_FILE 7245@} 7246MT_STATUS=my_status 7247 7248# Disable MT_OFFLINE function 7249MT_OFFLINE=: 7250 7251BLOCKING=124 7252BACKUP_DIRS=" 7253 albert:/fs/fsf 7254 apple-gunkies:/gd 7255 albert:/fs/gd2 7256 albert:/fs/gp 7257 geech:/usr/jla 7258 churchy:/usr/roland 7259 albert:/ 7260 albert:/usr 7261 apple-gunkies:/ 7262 apple-gunkies:/usr 7263 gnu:/hack 7264 gnu:/u 7265 apple-gunkies:/com/mailer/gnu 7266 apple-gunkies:/com/archive/gnu" 7267 7268BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]" 7269 7270@end smallexample 7271 7272@node Scripted Backups 7273@section Using the Backup Scripts 7274 7275The syntax for running a backup script is: 7276 7277@smallexample 7278backup --level=@var{level} --time=@var{time} 7279@end smallexample 7280 7281The @option{--level} option requests the dump level. Thus, to produce 7282a full dump, specify @code{--level=0} (this is the default, so 7283@option{--level} may be omitted if its value is 7284@code{0})@footnote{For backward compatibility, the @code{backup} will also 7285try to deduce the requested dump level from the name of the 7286script itself. If the name consists of a string @samp{level-} 7287followed by a single decimal digit, that digit is taken as 7288the dump level number. Thus, you may create a link from @code{backup} 7289to @code{level-1} and then run @code{level-1} whenever you need to 7290create a level one dump.}. 7291 7292The @option{--time} option determines when should the backup be 7293run. @var{Time} may take three forms: 7294 7295@table @asis 7296@item @var{hh}:@var{mm} 7297 7298The dump must be run at @var{hh} hours @var{mm} minutes. 7299 7300@item @var{hh} 7301 7302The dump must be run at @var{hh} hours. 7303 7304@item now 7305 7306The dump must be run immediately. 7307@end table 7308 7309You should start a script with a tape or disk mounted. Once you 7310start a script, it prompts you for new tapes or disks as it 7311needs them. Media volumes don't have to correspond to archive 7312files --- a multi-volume archive can be started in the middle of a 7313tape that already contains the end of another multi-volume archive. 7314The @code{restore} script prompts for media by its archive volume, 7315so to avoid an error message you should keep track of which tape 7316(or disk) contains which volume of the archive (@pxref{Scripted 7317Restoration}). 7318 7319The backup scripts write two files on the file system. The first is a 7320record file in @file{/etc/tar-backup/}, which is used by the scripts 7321to store and retrieve information about which files were dumped. This 7322file is not meant to be read by humans, and should not be deleted by 7323them. @xref{Snapshot Files}, for a more detailed explanation of this 7324file. 7325 7326The second file is a log file containing the names of the file systems 7327and files dumped, what time the backup was made, and any error 7328messages that were generated, as well as how much space was left in 7329the media volume after the last volume of the archive was written. 7330You should check this log file after every backup. The file name is 7331@file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy} 7332represents current date, and @var{n} represents current dump level number. 7333 7334The script also prints the name of each system being dumped to the 7335standard output. 7336 7337Following is the full list of options accepted by @code{backup} 7338script: 7339 7340@table @option 7341@item -l @var{level} 7342@itemx --level=@var{level} 7343Do backup level @var{level} (default 0). 7344 7345@item -f 7346@itemx --force 7347Force backup even if today's log file already exists. 7348 7349@item -v[@var{level}] 7350@itemx --verbose[=@var{level}] 7351Set verbosity level. The higher the level is, the more debugging 7352information will be output during execution. Default @var{level} 7353is 100, which means the highest debugging level. 7354 7355@item -t @var{start-time} 7356@itemx --time=@var{start-time} 7357Wait till @var{time}, then do backup. 7358 7359@item -h 7360@itemx --help 7361Display short help message and exit. 7362 7363@item -V 7364@itemx --version 7365Display information about the program's name, version, origin and legal 7366status, all on standard output, and then exit successfully. 7367@end table 7368 7369 7370@node Scripted Restoration 7371@section Using the Restore Script 7372 7373To restore files that were archived using a scripted backup, use the 7374@code{restore} script. Its usage is quite straightforward. In the 7375simplest form, invoke @code{restore --all}, it will 7376then restore all the file systems and files specified in 7377@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}). 7378 7379You may select the file systems (and/or files) to restore by 7380giving @code{restore} a list of @dfn{patterns} in its command 7381line. For example, running 7382 7383@smallexample 7384restore 'albert:*' 7385@end smallexample 7386 7387@noindent 7388will restore all file systems on the machine @samp{albert}. A more 7389complicated example: 7390 7391@smallexample 7392restore 'albert:*' '*:/var' 7393@end smallexample 7394 7395@noindent 7396This command will restore all file systems on the machine @samp{albert} 7397as well as @file{/var} file system on all machines. 7398 7399By default @code{restore} will start restoring files from the lowest 7400available dump level (usually zero) and will continue through 7401all available dump levels. There may be situations where such a 7402thorough restore is not necessary. For example, you may wish to 7403restore only files from the recent level one backup. To do so, 7404use @option{--level} option, as shown in the example below: 7405 7406@smallexample 7407restore --level=1 7408@end smallexample 7409 7410The full list of options accepted by @code{restore} follows: 7411 7412@table @option 7413@item -a 7414@itemx --all 7415Restore all file systems and files specified in @file{backup-specs}. 7416 7417@item -l @var{level} 7418@itemx --level=@var{level} 7419Start restoring from the given backup level, instead of the default 0. 7420 7421@item -v[@var{level}] 7422@itemx --verbose[=@var{level}] 7423Set verbosity level. The higher the level is, the more debugging 7424information will be output during execution. Default @var{level} 7425is 100, which means the highest debugging level. 7426 7427@item -h 7428@itemx --help 7429Display short help message and exit. 7430 7431@item -V 7432@itemx --version 7433Display information about the program's name, version, origin and legal 7434status, all on standard output, and then exit successfully. 7435@end table 7436 7437You should start the restore script with the media containing the 7438first volume of the archive mounted. The script will prompt for other 7439volumes as they are needed. If the archive is on tape, you don't need 7440to rewind the tape to to its beginning---if the tape head is 7441positioned past the beginning of the archive, the script will rewind 7442the tape as needed. @xref{Tape Positioning}, for a discussion of tape 7443positioning. 7444 7445@quotation 7446@strong{Warning:} The script will delete files from the active file 7447system if they were not in the file system when the archive was made. 7448@end quotation 7449 7450@xref{Incremental Dumps}, for an explanation of how the script makes 7451that determination. 7452 7453@node Choosing 7454@chapter Choosing Files and Names for @command{tar} 7455 7456Certain options to @command{tar} enable you to specify a name for your 7457archive. Other options let you decide which files to include or exclude 7458from the archive, based on when or whether files were modified, whether 7459the file names do or don't match specified patterns, or whether files 7460are in specified directories. 7461 7462This chapter discusses these options in detail. 7463 7464@menu 7465* file:: Choosing the Archive's Name 7466* Selecting Archive Members:: 7467* files:: Reading Names from a File 7468* exclude:: Excluding Some Files 7469* wildcards:: Wildcards Patterns and Matching 7470* quoting styles:: Ways of Quoting Special Characters in Names 7471* transform:: Modifying File and Member Names 7472* after:: Operating Only on New Files 7473* recurse:: Descending into Directories 7474* one:: Crossing File System Boundaries 7475@end menu 7476 7477@node file 7478@section Choosing and Naming Archive Files 7479 7480@cindex Naming an archive 7481@cindex Archive Name 7482@cindex Choosing an archive file 7483@cindex Where is the archive? 7484@opindex file 7485By default, @command{tar} uses an archive file name that was compiled when 7486it was built on the system; usually this name refers to some physical 7487tape drive on the machine. However, the person who installed @command{tar} 7488on the system may not have set the default to a meaningful value as far as 7489most users are concerned. As a result, you will usually want to tell 7490@command{tar} where to find (or create) the archive. The 7491@option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) 7492option allows you to either specify or name a file to use as the archive 7493instead of the default archive file location. 7494 7495@table @option 7496@xopindex{file, short description} 7497@item --file=@var{archive-name} 7498@itemx -f @var{archive-name} 7499Name the archive to create or operate on. Use in conjunction with 7500any operation. 7501@end table 7502 7503For example, in this @command{tar} command, 7504 7505@smallexample 7506$ @kbd{tar -cvf collection.tar blues folk jazz} 7507@end smallexample 7508 7509@noindent 7510@file{collection.tar} is the name of the archive. It must directly 7511follow the @option{-f} option, since whatever directly follows @option{-f} 7512@emph{will} end up naming the archive. If you neglect to specify an 7513archive name, you may end up overwriting a file in the working directory 7514with the archive you create since @command{tar} will use this file's name 7515for the archive name. 7516 7517An archive can be saved as a file in the file system, sent through a 7518pipe or over a network, or written to an I/O device such as a tape, 7519floppy disk, or CD write drive. 7520 7521@cindex Writing new archives 7522@cindex Archive creation 7523If you do not name the archive, @command{tar} uses the value of the 7524environment variable @env{TAPE} as the file name for the archive. If 7525that is not available, @command{tar} uses a default, compiled-in archive 7526name, usually that for tape unit zero (i.e., @file{/dev/tu00}). 7527 7528@cindex Standard input and output 7529@cindex tar to standard input and output 7530If you use @file{-} as an @var{archive-name}, @command{tar} reads the 7531archive from standard input (when listing or extracting files), or 7532writes it to standard output (when creating an archive). If you use 7533@file{-} as an @var{archive-name} when modifying an archive, 7534@command{tar} reads the original archive from its standard input and 7535writes the entire new archive to its standard output. 7536 7537The following example is a convenient way of copying directory 7538hierarchy from @file{sourcedir} to @file{targetdir}. 7539 7540@smallexample 7541$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)} 7542@end smallexample 7543 7544The @option{-C} option allows to avoid using subshells: 7545 7546@smallexample 7547$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -} 7548@end smallexample 7549 7550In both examples above, the leftmost @command{tar} invocation archives 7551the contents of @file{sourcedir} to the standard output, while the 7552rightmost one reads this archive from its standard input and 7553extracts it. The @option{-p} option tells it to restore permissions 7554of the extracted files. 7555 7556@cindex Remote devices 7557@cindex tar to a remote device 7558@anchor{remote-dev} 7559To specify an archive file on a device attached to a remote machine, 7560use the following: 7561 7562@smallexample 7563@kbd{--file=@var{hostname}:/@var{dev}/@var{file-name}} 7564@end smallexample 7565 7566@noindent 7567@command{tar} will set up the remote connection, if possible, and 7568prompt you for a username and password. If you use 7569@option{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar} 7570will attempt to set up the remote connection using your username 7571as the username on the remote machine. 7572 7573@cindex Local and remote archives 7574@anchor{local and remote archives} 7575If the archive file name includes a colon (@samp{:}), then it is assumed 7576to be a file on another machine. If the archive file is 7577@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the 7578host @var{host}. The remote host is accessed using the @command{rsh} 7579program, with a username of @var{user}. If the username is omitted 7580(along with the @samp{@@} sign), then your user name will be used. 7581(This is the normal @command{rsh} behavior.) It is necessary for the 7582remote machine, in addition to permitting your @command{rsh} access, to 7583have the @file{rmt} program installed (this command is included in 7584the @GNUTAR{} distribution and by default is installed under 7585@file{@var{prefix}/libexec/rmt}, where @var{prefix} means your 7586installation prefix). If you need to use a file whose name includes a 7587colon, then the remote tape drive behavior 7588can be inhibited by using the @option{--force-local} option. 7589 7590When the archive is being created to @file{/dev/null}, @GNUTAR{} 7591tries to minimize input and output operations. The Amanda backup 7592system, when used with @GNUTAR{}, has an initial sizing pass which 7593uses this feature. 7594 7595@node Selecting Archive Members 7596@section Selecting Archive Members 7597@cindex Specifying files to act on 7598@cindex Specifying archive members 7599 7600@dfn{File Name arguments} specify which files in the file system 7601@command{tar} operates on, when creating or adding to an archive, or which 7602archive members @command{tar} operates on, when reading or deleting from 7603an archive. @xref{Operations}. 7604 7605To specify file names, you can include them as the last arguments on 7606the command line, as follows: 7607@smallexample 7608@kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}] 7609@end smallexample 7610 7611If a file name begins with dash (@samp{-}), precede it with 7612@option{--add-file} option to prevent it from being treated as an 7613option. 7614 7615@anchor{input name quoting} 7616By default @GNUTAR{} attempts to @dfn{unquote} each file or member 7617name, replacing @dfn{escape sequences} according to the following 7618table: 7619 7620@multitable @columnfractions 0.20 0.60 7621@headitem Escape @tab Replaced with 7622@item \a @tab Audible bell (@acronym{ASCII} 7) 7623@item \b @tab Backspace (@acronym{ASCII} 8) 7624@item \f @tab Form feed (@acronym{ASCII} 12) 7625@item \n @tab New line (@acronym{ASCII} 10) 7626@item \r @tab Carriage return (@acronym{ASCII} 13) 7627@item \t @tab Horizontal tabulation (@acronym{ASCII} 9) 7628@item \v @tab Vertical tabulation (@acronym{ASCII} 11) 7629@item \? @tab @acronym{ASCII} 127 7630@item \@var{n} @tab @acronym{ASCII} @var{n} (@var{n} should be an octal number 7631 of up to 3 digits) 7632@end multitable 7633 7634A backslash followed by any other symbol is retained. 7635 7636This default behavior is controlled by the following command line 7637option: 7638 7639@table @option 7640@opindex unquote 7641@item --unquote 7642Enable unquoting input file or member names (default). 7643 7644@opindex no-unquote 7645@item --no-unquote 7646Disable unquoting input file or member names. 7647@end table 7648 7649If you specify a directory name as a file name argument, all the files 7650in that directory are operated on by @command{tar}. 7651 7652If you do not specify files, @command{tar} behavior differs depending 7653on the operation mode as described below: 7654 7655When @command{tar} is invoked with @option{--create} (@option{-c}), 7656@command{tar} will stop immediately, reporting the following: 7657 7658@smallexample 7659@group 7660$ @kbd{tar cf a.tar} 7661tar: Cowardly refusing to create an empty archive 7662Try 'tar --help' or 'tar --usage' for more information. 7663@end group 7664@end smallexample 7665 7666If you specify either @option{--list} (@option{-t}) or 7667@option{--extract} (@option{--get}, @option{-x}), @command{tar} 7668operates on all the archive members in the archive. 7669 7670If run with @option{--diff} option, tar will compare the archive with 7671the contents of the current working directory. 7672 7673If you specify any other operation, @command{tar} does nothing. 7674 7675By default, @command{tar} takes file names from the command line. However, 7676there are other ways to specify file or member names, or to modify the 7677manner in which @command{tar} selects the files or members upon which to 7678operate. In general, these methods work both for specifying the names 7679of files and archive members. 7680 7681@node files 7682@section Reading Names from a File 7683 7684@cindex Reading file names from a file 7685@cindex Lists of file names 7686@cindex File Name arguments, alternatives 7687@cindex @command{find}, using with @command{tar} 7688Instead of giving the names of files or archive members on the command 7689line, you can put the names into a file, and then use the 7690@option{--files-from=@var{file-of-names}} (@option{-T 7691@var{file-of-names}}) option to @command{tar}. Give the name of the 7692file which contains the list of files to include as the argument to 7693@option{--files-from}. In the list, the file names should be separated by 7694newlines. You will frequently use this option when you have generated 7695the list of files to archive with the @command{find} utility. 7696 7697@table @option 7698@opindex files-from 7699@item --files-from=@var{file-name} 7700@itemx -T @var{file-name} 7701Get names to extract or create from file @var{file-name}. 7702@end table 7703 7704If you give a single dash as a file name for @option{--files-from}, (i.e., 7705you specify either @code{--files-from=-} or @code{-T -}), then the file 7706names are read from standard input. 7707 7708Unless you are running @command{tar} with @option{--create}, you cannot use 7709both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same 7710command. 7711 7712Any number of @option{-T} options can be given in the command line. 7713 7714The following example shows how to use @command{find} to generate a list of 7715files smaller than 400K in length and put that list into a file 7716called @file{small-files}. You can then use the @option{-T} option to 7717@command{tar} to specify the files from that file, @file{small-files}, to 7718create the archive @file{little.tgz}. (The @option{-z} option to 7719@command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for 7720more information.) 7721 7722@smallexample 7723$ @kbd{find . -size -400 -print > small-files} 7724$ @kbd{tar -c -v -z -T small-files -f little.tgz} 7725@end smallexample 7726 7727@noindent 7728By default, each line read from the file list is first stripped off 7729any leading and trailing whitespace. If the resulting string begins 7730with @samp{-} character, it is considered a @command{tar} option and is 7731processed accordingly@footnote{Versions of @GNUTAR{} up to 1.15.1 7732recognized only @option{-C} option in file lists, and only if the 7733option and its argument occupied two consecutive lines.}. Only a 7734subset of @GNUTAR{} options is allowed for use in file lists. For 7735a list of such options, @ref{Position-Sensitive Options}. 7736 7737For example, the common use of this feature is to change to another 7738directory by specifying @option{-C} option: 7739 7740@smallexample 7741@group 7742$ @kbd{cat list} 7743-C/etc 7744passwd 7745hosts 7746-C/lib 7747libc.a 7748$ @kbd{tar -c -f foo.tar --files-from list} 7749@end group 7750@end smallexample 7751 7752@noindent 7753In this example, @command{tar} will first switch to @file{/etc} 7754directory and add files @file{passwd} and @file{hosts} to the 7755archive. Then it will change to @file{/lib} directory and will archive 7756the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will 7757contain: 7758 7759@smallexample 7760@group 7761$ @kbd{tar tf foo.tar} 7762passwd 7763hosts 7764libc.a 7765@end group 7766@end smallexample 7767 7768Note, that any options used in the file list remain in effect for the 7769rest of the command line. For example, using the same @file{list} 7770file as above, the following command 7771 7772@smallexample 7773$ @kbd{tar -c -f foo.tar --files-from list libcurses.a} 7774@end smallexample 7775 7776@noindent 7777will look for file @file{libcurses.a} in the directory @file{/lib}, 7778because it was used with the last @option{-C} option 7779(@pxref{Position-Sensitive Options}). 7780 7781@anchor{verbatim-files-from} 7782@opindex verbatim-files-from 7783If such option handling is undesirable, use the 7784@option{--verbatim-files-from} option. When this option is in effect, 7785each line read from the file list is treated as a file name. Notice, 7786that this means, in particular, that no whitespace trimming is 7787performed. 7788 7789@anchor{no-verbatim-files-from} 7790@opindex no-verbatim-files-from 7791The @option{--verbatim-files-from} affects all @option{-T} options 7792that follow it in the command line. The default behavior can be 7793restored using @option{--no-verbatim-files-from} option. 7794 7795@opindex add-file 7796To disable option handling for a single file name, use the 7797@option{--add-file} option, e.g.: @code{--add-file=--my-file}. 7798 7799You can use any @GNUTAR{} command line options in the file list file, 7800including @option{--files-from} option itself. This allows for 7801including contents of a file list into another file list file. 7802Note however, that options that control file list processing, such as 7803@option{--verbatim-files-from} or @option{--null} won't affect the 7804file they appear in. They will affect next @option{--files-from} 7805option, if there is any. 7806 7807@menu 7808* nul:: 7809@end menu 7810 7811@node nul 7812@subsection @code{NUL}-Terminated File Names 7813 7814@cindex File names, terminated by @code{NUL} 7815@cindex @code{NUL}-terminated file names 7816The @option{--null} option causes 7817@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) 7818to read file names terminated by a @code{NUL} instead of a newline, so 7819files whose names contain newlines can be archived using 7820@option{--files-from}. 7821 7822@table @option 7823@xopindex{null, described} 7824@item --null 7825Only consider @code{NUL}-terminated file names, instead of files that 7826terminate in a newline. 7827 7828@xopindex{no-null, described} 7829@item --no-null 7830Undo the effect of any previous @option{--null} option. 7831@end table 7832 7833The @option{--null} option is just like the one in @acronym{GNU} 7834@command{xargs} and @command{cpio}, and is useful with the 7835@option{-print0} predicate of @acronym{GNU} @command{find}. In 7836@command{tar}, @option{--null} also disables special handling for 7837file names that begin with dash (similar to 7838@option{--verbatim-files-from} option). 7839 7840This example shows how to use @command{find} to generate a list of files 7841larger than 800K in length and put that list into a file called 7842@file{long-files}. The @option{-print0} option to @command{find} is just 7843like @option{-print}, except that it separates files with a @code{NUL} 7844rather than with a newline. You can then run @command{tar} with both the 7845@option{--null} and @option{-T} options to specify that @command{tar} gets the 7846files from that file, @file{long-files}, to create the archive 7847@file{big.tgz}. The @option{--null} option to @command{tar} will cause 7848@command{tar} to recognize the @code{NUL} separator between files. 7849 7850@smallexample 7851$ @kbd{find . -size +800 -print0 > long-files} 7852$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar} 7853@end smallexample 7854 7855The @option{--no-null} option can be used if you need to read both 7856@code{NUL}-terminated and newline-terminated files on the same command line. 7857For example, if @file{flist} is a newline-terminated file, then the 7858following command can be used to combine it with the above command: 7859 7860@smallexample 7861@group 7862$ @kbd{find . -size +800 -print0 | 7863 tar -c -f big.tar --null -T - --no-null -T flist} 7864@end group 7865@end smallexample 7866 7867This example uses short options for typographic reasons, to avoid 7868very long lines. 7869 7870@GNUTAR is tries to automatically detect @code{NUL}-terminated file 7871lists, so in many cases it is safe to use them even without the 7872@option{--null} option. In this case @command{tar} will print a 7873warning and continue reading such a file as if @option{--null} were 7874actually given: 7875 7876@smallexample 7877@group 7878$ @kbd{find . -size +800 -print0 | tar -c -f big.tar -T -} 7879tar: -: file name read contains nul character 7880@end group 7881@end smallexample 7882 7883The null terminator, however, remains in effect only for this 7884particular file, any following @option{-T} options will assume 7885newline termination. Of course, the null autodetection applies 7886to these eventual surplus @option{-T} options as well. 7887 7888@node exclude 7889@section Excluding Some Files 7890 7891@cindex File names, excluding files by 7892@cindex Excluding files by name and pattern 7893@cindex Excluding files by file system 7894@opindex exclude 7895@opindex exclude-from 7896To avoid operating on files whose names match a particular pattern, 7897use the @option{--exclude} or @option{--exclude-from} options. 7898 7899@table @option 7900@opindex exclude 7901@item --exclude=@var{pattern} 7902Causes @command{tar} to ignore files that match the @var{pattern}. 7903@end table 7904 7905@findex exclude 7906The @option{--exclude=@var{pattern}} option prevents any file or 7907member whose name matches the shell wildcard (@var{pattern}) from 7908being operated on. 7909For example, to create an archive with all the contents of the directory 7910@file{src} except for files whose names end in @file{.o}, use the 7911command @samp{tar -cf src.tar --exclude='*.o' src}. 7912 7913You may give multiple @option{--exclude} options. 7914 7915@table @option 7916@opindex exclude-from 7917@item --exclude-from=@var{file} 7918@itemx -X @var{file} 7919Causes @command{tar} to ignore files that match the patterns listed in 7920@var{file}. 7921@end table 7922 7923@findex exclude-from 7924Use the @option{--exclude-from} option to read a 7925list of patterns, one per line, from @var{file}; @command{tar} will 7926ignore files matching those patterns. Thus if @command{tar} is 7927called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a 7928single line @file{*.o}, no files whose names end in @file{.o} will be 7929added to the archive. 7930 7931Notice, that lines from @var{file} are read verbatim. One of the 7932frequent errors is leaving some extra whitespace after a file name, 7933which is difficult to catch using text editors. 7934 7935However, empty lines are OK. 7936 7937@cindex VCS, excluding patterns from ignore files 7938@cindex VCS, ignore files 7939@cindex CVS, ignore files 7940@cindex Git, ignore files 7941@cindex Bazaar, ignore files 7942@cindex Mercurial, ignore files 7943When archiving directories that are under some version control system (VCS), 7944it is often convenient to read exclusion patterns from this VCS' 7945ignore files (e.g. @file{.cvsignore}, @file{.gitignore}, etc.) The 7946following options provide such possibility: 7947 7948@table @option 7949@anchor{exclude-vcs-ignores} 7950@opindex exclude-vcs-ignores 7951@item --exclude-vcs-ignores 7952Before archiving a directory, see if it contains any of the following 7953files: @file{cvsignore}, @file{.gitignore}, @file{.bzrignore}, or 7954@file{.hgignore}. If so, read ignore patterns from these files. 7955 7956The patterns are treated much as the corresponding VCS would treat 7957them, i.e.: 7958 7959@table @file 7960@findex .cvsignore 7961@item .cvsignore 7962Contains shell-style globbing patterns that apply only to the 7963directory where this file resides. No comments are allowed in the 7964file. Empty lines are ignored. 7965 7966@findex .gitignore 7967@item .gitignore 7968Contains shell-style globbing patterns. Applies to the directory 7969where @file{.gitfile} is located and all its subdirectories. 7970 7971Any line beginning with a @samp{#} is a comment. Backslash escapes 7972the comment character. 7973 7974@findex .bzrignore 7975@item .bzrignore 7976Contains shell globbing-patterns and regular expressions (if prefixed 7977with @samp{RE:}@footnote{According to the Bazaar docs, 7978globbing-patterns are Korn-shell style and regular expressions are 7979perl-style. As of @GNUTAR{} version @value{VERSION}, these are 7980treated as shell-style globs and posix extended regexps. This will be 7981fixed in future releases.}. Patterns affect the directory and all its 7982subdirectories. 7983 7984Any line beginning with a @samp{#} is a comment. 7985 7986@findex .hgignore 7987@item .hgignore 7988Contains posix regular expressions@footnote{Support for perl-style 7989regexps will appear in future releases.}. The line @samp{syntax: 7990glob} switches to shell globbing patterns. The line @samp{syntax: 7991regexp} switches back. Comments begin with a @samp{#}. Patterns 7992affect the directory and all its subdirectories. 7993@end table 7994 7995@opindex exclude-ignore 7996@item --exclude-ignore=@var{file} 7997Before dumping a directory, @command{tar} checks if it contains 7998@var{file}. If so, exclusion patterns are read from this file. 7999The patterns affect only the directory itself. 8000 8001@opindex exclude-ignore-recursive 8002@item --exclude-ignore-recursive=@var{file} 8003Same as @option{--exclude-ignore}, except that the patterns read 8004affect both the directory where @var{file} resides and all its 8005subdirectories. 8006@end table 8007 8008@table @option 8009@cindex version control system, excluding files 8010@cindex VCS, excluding files 8011@cindex SCCS, excluding files 8012@cindex RCS, excluding files 8013@cindex CVS, excluding files 8014@cindex SVN, excluding files 8015@cindex git, excluding files 8016@cindex Bazaar, excluding files 8017@cindex Arch, excluding files 8018@cindex Mercurial, excluding files 8019@cindex Darcs, excluding files 8020@anchor{exclude-vcs} 8021@opindex exclude-vcs 8022@item --exclude-vcs 8023Exclude files and directories used by following version control 8024systems: @samp{CVS}, @samp{RCS}, @samp{SCCS}, @samp{SVN}, @samp{Arch}, 8025@samp{Bazaar}, @samp{Mercurial}, and @samp{Darcs}. 8026 8027As of version @value{VERSION}, the following files are excluded: 8028 8029@itemize @bullet 8030@item @file{CVS/}, and everything under it 8031@item @file{RCS/}, and everything under it 8032@item @file{SCCS/}, and everything under it 8033@item @file{.git/}, and everything under it 8034@item @file{.gitignore} 8035@item @file{.gitmodules} 8036@item @file{.gitattributes} 8037@item @file{.cvsignore} 8038@item @file{.svn/}, and everything under it 8039@item @file{.arch-ids/}, and everything under it 8040@item @file{@{arch@}/}, and everything under it 8041@item @file{=RELEASE-ID} 8042@item @file{=meta-update} 8043@item @file{=update} 8044@item @file{.bzr} 8045@item @file{.bzrignore} 8046@item @file{.bzrtags} 8047@item @file{.hg} 8048@item @file{.hgignore} 8049@item @file{.hgrags} 8050@item @file{_darcs} 8051@end itemize 8052 8053@opindex exclude-backups 8054@item --exclude-backups 8055Exclude backup and lock files. This option causes exclusion of files 8056that match the following shell globbing patterns: 8057 8058@table @asis 8059@item .#* 8060@item *~ 8061@item #*# 8062@end table 8063 8064@end table 8065 8066@findex exclude-caches 8067When creating an archive, the @option{--exclude-caches} option family 8068causes @command{tar} to exclude all directories that contain a @dfn{cache 8069directory tag}. A cache directory tag is a short file with the 8070well-known name @file{CACHEDIR.TAG} and having a standard header 8071specified in @url{http://www.brynosaurus.com/cachedir/spec.html}. 8072Various applications write cache directory tags into directories they 8073use to hold regenerable, non-precious data, so that such data can be 8074more easily excluded from backups. 8075 8076There are three @samp{exclude-caches} options, each providing a different 8077exclusion semantics: 8078 8079@table @option 8080@opindex exclude-caches 8081@item --exclude-caches 8082Do not archive the contents of the directory, but archive the 8083directory itself and the @file{CACHEDIR.TAG} file. 8084 8085@opindex exclude-caches-under 8086@item --exclude-caches-under 8087Do not archive the contents of the directory, nor the 8088@file{CACHEDIR.TAG} file, archive only the directory itself. 8089 8090@opindex exclude-caches-all 8091@item --exclude-caches-all 8092Omit directories containing @file{CACHEDIR.TAG} file entirely. 8093@end table 8094 8095@findex exclude-tag 8096Another option family, @option{--exclude-tag}, provides a generalization of 8097this concept. It takes a single argument, a file name to look for. 8098Any directory that contains this file will be excluded from the dump. 8099Similarly to @samp{exclude-caches}, there are three options in this 8100option family: 8101 8102@table @option 8103@opindex exclude-tag 8104@item --exclude-tag=@var{file} 8105Do not dump the contents of the directory, but dump the 8106directory itself and the @var{file}. 8107 8108@opindex exclude-tag-under 8109@item --exclude-tag-under=@var{file} 8110Do not dump the contents of the directory, nor the 8111@var{file}, archive only the directory itself. 8112 8113@opindex exclude-tag-all 8114@item --exclude-tag-all=@var{file} 8115Omit directories containing @var{file} file entirely. 8116@end table 8117 8118Multiple @option{--exclude-tag*} options can be given. 8119 8120For example, given this directory: 8121 8122@smallexample 8123@group 8124$ @kbd{find dir} 8125dir 8126dir/blues 8127dir/jazz 8128dir/folk 8129dir/folk/tagfile 8130dir/folk/sanjuan 8131dir/folk/trote 8132@end group 8133@end smallexample 8134 8135The @option{--exclude-tag} will produce the following: 8136 8137@smallexample 8138$ @kbd{tar -cf archive.tar --exclude-tag=tagfile -v dir} 8139dir/ 8140dir/blues 8141dir/jazz 8142dir/folk/ 8143tar: dir/folk/: contains a cache directory tag tagfile; 8144 contents not dumped 8145dir/folk/tagfile 8146@end smallexample 8147 8148Both the @file{dir/folk} directory and its tagfile are preserved in 8149the archive, however the rest of files in this directory are not. 8150 8151Now, using the @option{--exclude-tag-under} option will exclude 8152@file{tagfile} from the dump, while still preserving the directory 8153itself, as shown in this example: 8154 8155@smallexample 8156$ @kbd{tar -cf archive.tar --exclude-tag-under=tagfile -v dir} 8157dir/ 8158dir/blues 8159dir/jazz 8160dir/folk/ 8161./tar: dir/folk/: contains a cache directory tag tagfile; 8162 contents not dumped 8163@end smallexample 8164 8165Finally, using @option{--exclude-tag-all} omits the @file{dir/folk} 8166directory entirely: 8167 8168@smallexample 8169$ @kbd{tar -cf archive.tar --exclude-tag-all=tagfile -v dir} 8170dir/ 8171dir/blues 8172dir/jazz 8173./tar: dir/folk/: contains a cache directory tag tagfile; 8174 directory not dumped 8175@end smallexample 8176 8177@menu 8178* problems with exclude:: 8179@end menu 8180 8181@node problems with exclude 8182@unnumberedsubsec Problems with Using the @code{exclude} Options 8183 8184@xopindex{exclude, potential problems with} 8185Some users find @samp{exclude} options confusing. Here are some common 8186pitfalls: 8187 8188@itemize @bullet 8189@item 8190The main operating mode of @command{tar} does not act on a file name 8191explicitly listed on the command line, if one of its file name 8192components is excluded. In the example above, if 8193you create an archive and exclude files that end with @samp{*.o}, but 8194explicitly name the file @samp{dir.o/foo} after all the options have been 8195listed, @samp{dir.o/foo} will be excluded from the archive. 8196 8197@item 8198You can sometimes confuse the meanings of @option{--exclude} and 8199@option{--exclude-from}. Be careful: use @option{--exclude} when files 8200to be excluded are given as a pattern on the command line. Use 8201@option{--exclude-from} to introduce the name of a file which contains 8202a list of patterns, one per line; each of these patterns can exclude 8203zero, one, or many files. 8204 8205@item 8206When you use @option{--exclude=@var{pattern}}, be sure to quote the 8207@var{pattern} parameter, so @GNUTAR{} sees wildcard characters 8208like @samp{*}. If you do not do this, the shell might expand the 8209@samp{*} itself using files at hand, so @command{tar} might receive a 8210list of files instead of one pattern, or none at all, making the 8211command somewhat illegal. This might not correspond to what you want. 8212 8213For example, write: 8214 8215@smallexample 8216$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}} 8217@end smallexample 8218 8219@noindent 8220rather than: 8221 8222@smallexample 8223# @emph{Wrong!} 8224$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}} 8225@end smallexample 8226 8227@item 8228You must use use shell syntax, or globbing, rather than @code{regexp} 8229syntax, when using exclude options in @command{tar}. If you try to use 8230@code{regexp} syntax to describe files to be excluded, your command 8231might fail. 8232 8233@item 8234@FIXME{The change in semantics must have occurred before 1.11, 8235so I doubt if it is worth mentioning at all. Anyway, should at 8236least specify in which version the semantics changed.} 8237In earlier versions of @command{tar}, what is now the 8238@option{--exclude-from} option was called @option{--exclude} instead. 8239Now, @option{--exclude} applies to patterns listed on the command 8240line and @option{--exclude-from} applies to patterns listed in a 8241file. 8242 8243@end itemize 8244 8245@node wildcards 8246@section Wildcards Patterns and Matching 8247 8248@dfn{Globbing} is the operation by which @dfn{wildcard} characters, 8249@samp{*} or @samp{?} for example, are replaced and expanded into all 8250existing files matching the given pattern. @GNUTAR{} can use wildcard 8251patterns for matching (or globbing) archive members when extracting 8252from or listing an archive. Wildcard patterns are also used for 8253verifying volume labels of @command{tar} archives. This section has the 8254purpose of explaining wildcard syntax for @command{tar}. 8255 8256@FIXME{the next few paragraphs need work.} 8257 8258A @var{pattern} should be written according to shell syntax, using wildcard 8259characters to effect globbing. Most characters in the pattern stand 8260for themselves in the matched string, and case is significant: @samp{a} 8261will match only @samp{a}, and not @samp{A}. The character @samp{?} in the 8262pattern matches any single character in the matched string. The character 8263@samp{*} in the pattern matches zero, one, or more single characters in 8264the matched string. The character @samp{\} says to take the following 8265character of the pattern @emph{literally}; it is useful when one needs to 8266match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves. 8267 8268The character @samp{[}, up to the matching @samp{]}, introduces a character 8269class. A @dfn{character class} is a list of acceptable characters 8270for the next single character of the matched string. For example, 8271@samp{[abcde]} would match any of the first five letters of the alphabet. 8272Note that within a character class, all of the ``special characters'' 8273listed above other than @samp{\} lose their special meaning; for example, 8274@samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\}, 8275@samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints, 8276the characters @samp{-} and @samp{]} must either come @emph{first} or 8277@emph{last} in a character class.) 8278 8279@cindex Excluding characters from a character class 8280@cindex Character class, excluding characters from 8281If the first character of the class after the opening @samp{[} 8282is @samp{!} or @samp{^}, then the meaning of the class is reversed. 8283Rather than listing character to match, it lists those characters which 8284are @emph{forbidden} as the next single character of the matched string. 8285 8286Other characters of the class stand for themselves. The special 8287construction @samp{[@var{a}-@var{e}]}, using an hyphen between two 8288letters, is meant to represent all characters between @var{a} and 8289@var{e}, inclusive. 8290 8291@FIXME{need to add a sentence or so here to make this clear for those 8292who don't have dan around.} 8293 8294Periods (@samp{.}) or forward slashes (@samp{/}) are not considered 8295special for wildcard matches. However, if a pattern completely matches 8296a directory prefix of a matched string, then it matches the full matched 8297string: thus, excluding a directory also excludes all the files beneath it. 8298 8299@menu 8300* controlling pattern-matching:: 8301@end menu 8302 8303@node controlling pattern-matching 8304@unnumberedsubsec Controlling Pattern-Matching 8305 8306For the purposes of this section, we call @dfn{exclusion members} all 8307member names obtained while processing @option{--exclude} and 8308@option{--exclude-from} options, and @dfn{inclusion members} those 8309member names that were given in the command line or read from the file 8310specified with @option{--files-from} option. 8311 8312These two pairs of member lists are used in the following operations: 8313@option{--diff}, @option{--extract}, @option{--list}, 8314@option{--update}. 8315 8316There are no inclusion members in create mode (@option{--create} and 8317@option{--append}), since in this mode the names obtained from the 8318command line refer to @emph{files}, not archive members. 8319 8320By default, inclusion members are compared with archive members 8321literally @footnote{Notice that earlier @GNUTAR{} versions used 8322globbing for inclusion members, which contradicted to UNIX98 8323specification and was not documented. @xref{Changes}, for more 8324information on this and other changes.} and exclusion members are 8325treated as globbing patterns. For example: 8326 8327@smallexample 8328@group 8329$ @kbd{tar tf foo.tar} 8330a.c 8331b.c 8332a.txt 8333[remarks] 8334# @i{Member names are used verbatim:} 8335$ @kbd{tar -xf foo.tar -v '[remarks]'} 8336[remarks] 8337# @i{Exclude member names are globbed:} 8338$ @kbd{tar -xf foo.tar -v --exclude '*.c'} 8339a.txt 8340[remarks] 8341@end group 8342@end smallexample 8343 8344This behavior can be altered by using the following options: 8345 8346@table @option 8347@opindex wildcards 8348@item --wildcards 8349Treat all member names as wildcards. 8350 8351@opindex no-wildcards 8352@item --no-wildcards 8353Treat all member names as literal strings. 8354@end table 8355 8356Thus, to extract files whose names end in @samp{.c}, you can use: 8357 8358@smallexample 8359$ @kbd{tar -xf foo.tar -v --wildcards '*.c'} 8360a.c 8361b.c 8362@end smallexample 8363 8364@noindent 8365Notice quoting of the pattern to prevent the shell from interpreting 8366it. 8367 8368The effect of @option{--wildcards} option is canceled by 8369@option{--no-wildcards}. This can be used to pass part of 8370the command line arguments verbatim and other part as globbing 8371patterns. For example, the following invocation: 8372 8373@smallexample 8374$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'} 8375@end smallexample 8376 8377@noindent 8378instructs @command{tar} to extract from @file{foo.tar} all files whose 8379names end in @samp{.txt} and the file named @file{[remarks]}. 8380 8381Normally, a pattern matches a name if an initial subsequence of the 8382name's components matches the pattern, where @samp{*}, @samp{?}, and 8383@samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards, 8384and wildcards can match @samp{/}. 8385 8386Other than optionally stripping leading @samp{/} from names 8387(@pxref{absolute}), patterns and names are used as-is. For 8388example, trailing @samp{/} is not trimmed from a user-specified name 8389before deciding whether to exclude it. 8390 8391However, this matching procedure can be altered by the options listed 8392below. These options accumulate. For example: 8393 8394@smallexample 8395--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme' 8396@end smallexample 8397 8398@noindent 8399ignores case when excluding @samp{makefile}, but not when excluding 8400@samp{readme}. 8401 8402@table @option 8403@anchor{anchored patterns} 8404@opindex anchored 8405@opindex no-anchored 8406@item --anchored 8407@itemx --no-anchored 8408If anchored, a pattern must match an initial subsequence 8409of the name's components. Otherwise, the pattern can match any 8410subsequence. Default is @option{--no-anchored} for exclusion members 8411and @option{--anchored} inclusion members. 8412 8413@anchor{case-insensitive matches} 8414@opindex ignore-case 8415@opindex no-ignore-case 8416@item --ignore-case 8417@itemx --no-ignore-case 8418When ignoring case, upper-case patterns match lower-case names and vice versa. 8419When not ignoring case (the default), matching is case-sensitive. 8420 8421@opindex wildcards-match-slash 8422@opindex no-wildcards-match-slash 8423@item --wildcards-match-slash 8424@itemx --no-wildcards-match-slash 8425When wildcards match slash (the default for exclusion members), a 8426wildcard like @samp{*} in the pattern can match a @samp{/} in the 8427name. Otherwise, @samp{/} is matched only by @samp{/}. 8428 8429@end table 8430 8431The @option{--recursion} and @option{--no-recursion} options 8432(@pxref{recurse}) also affect how member patterns are interpreted. If 8433recursion is in effect, a pattern matches a name if it matches any of 8434the name's parent directories. 8435 8436The following table summarizes pattern-matching default values: 8437 8438@multitable @columnfractions .3 .7 8439@headitem Members @tab Default settings 8440@item Inclusion @tab @option{--no-wildcards --anchored --no-wildcards-match-slash} 8441@item Exclusion @tab @option{--wildcards --no-anchored --wildcards-match-slash} 8442@end multitable 8443 8444@node quoting styles 8445@section Quoting Member Names 8446 8447When displaying member names, @command{tar} takes care to avoid 8448ambiguities caused by certain characters. This is called @dfn{name 8449quoting}. The characters in question are: 8450 8451@itemize @bullet 8452@item Non-printable control characters: 8453@anchor{escape sequences} 8454@multitable @columnfractions 0.20 0.10 0.60 8455@headitem Character @tab @acronym{ASCII} @tab Character name 8456@item \a @tab 7 @tab Audible bell 8457@item \b @tab 8 @tab Backspace 8458@item \f @tab 12 @tab Form feed 8459@item \n @tab 10 @tab New line 8460@item \r @tab 13 @tab Carriage return 8461@item \t @tab 9 @tab Horizontal tabulation 8462@item \v @tab 11 @tab Vertical tabulation 8463@end multitable 8464 8465@item Space (@acronym{ASCII} 32) 8466 8467@item Single and double quotes (@samp{'} and @samp{"}) 8468 8469@item Backslash (@samp{\}) 8470@end itemize 8471 8472The exact way @command{tar} uses to quote these characters depends on 8473the @dfn{quoting style}. The default quoting style, called 8474@dfn{escape} (see below), uses backslash notation to represent control 8475characters and backslash. 8476 8477@GNUTAR{} offers seven distinct quoting styles, which can be selected 8478using @option{--quoting-style} option: 8479 8480@table @option 8481@item --quoting-style=@var{style} 8482@opindex quoting-style 8483 8484Sets quoting style. Valid values for @var{style} argument are: 8485literal, shell, shell-always, c, escape, locale, clocale. 8486@end table 8487 8488These styles are described in detail below. To illustrate their 8489effect, we will use an imaginary tar archive @file{arch.tar} 8490containing the following members: 8491 8492@smallexample 8493@group 8494# 1. Contains horizontal tabulation character. 8495a tab 8496# 2. Contains newline character 8497a 8498newline 8499# 3. Contains a space 8500a space 8501# 4. Contains double quotes 8502a"double"quote 8503# 5. Contains single quotes 8504a'single'quote 8505# 6. Contains a backslash character: 8506a\backslash 8507@end group 8508@end smallexample 8509 8510Here is how usual @command{ls} command would have listed them, if they 8511had existed in the current working directory: 8512 8513@smallexample 8514@group 8515$ @kbd{ls} 8516a\ttab 8517a\nnewline 8518a\ space 8519a"double"quote 8520a'single'quote 8521a\\backslash 8522@end group 8523@end smallexample 8524 8525Quoting styles: 8526 8527@table @samp 8528@item literal 8529No quoting, display each character as is: 8530 8531@smallexample 8532@group 8533$ @kbd{tar tf arch.tar --quoting-style=literal} 8534./ 8535./a space 8536./a'single'quote 8537./a"double"quote 8538./a\backslash 8539./a tab 8540./a 8541newline 8542@end group 8543@end smallexample 8544 8545@item shell 8546Display characters the same way Bourne shell does: 8547control characters, except @samp{\t} and @samp{\n}, are printed using 8548backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a 8549single quote is printed as @samp{\'}. If a name contains any quoted 8550characters, it is enclosed in single quotes. In particular, if a name 8551contains single quotes, it is printed as several single-quoted strings: 8552 8553@smallexample 8554@group 8555$ @kbd{tar tf arch.tar --quoting-style=shell} 8556./ 8557'./a space' 8558'./a'\''single'\''quote' 8559'./a"double"quote' 8560'./a\backslash' 8561'./a tab' 8562'./a 8563newline' 8564@end group 8565@end smallexample 8566 8567@item shell-always 8568Same as @samp{shell}, but the names are always enclosed in single 8569quotes: 8570 8571@smallexample 8572@group 8573$ @kbd{tar tf arch.tar --quoting-style=shell-always} 8574'./' 8575'./a space' 8576'./a'\''single'\''quote' 8577'./a"double"quote' 8578'./a\backslash' 8579'./a tab' 8580'./a 8581newline' 8582@end group 8583@end smallexample 8584 8585@item c 8586Use the notation of the C programming language. All names are 8587enclosed in double quotes. Control characters are quoted using 8588backslash notations, double quotes are represented as @samp{\"}, 8589backslash characters are represented as @samp{\\}. Single quotes and 8590spaces are not quoted: 8591 8592@smallexample 8593@group 8594$ @kbd{tar tf arch.tar --quoting-style=c} 8595"./" 8596"./a space" 8597"./a'single'quote" 8598"./a\"double\"quote" 8599"./a\\backslash" 8600"./a\ttab" 8601"./a\nnewline" 8602@end group 8603@end smallexample 8604 8605@item escape 8606Control characters are printed using backslash notation, and a 8607backslash as @samp{\\}. This is the default quoting style, unless it 8608was changed when configured the package. 8609 8610@smallexample 8611@group 8612$ @kbd{tar tf arch.tar --quoting-style=escape} 8613./ 8614./a space 8615./a'single'quote 8616./a"double"quote 8617./a\\backslash 8618./a\ttab 8619./a\nnewline 8620@end group 8621@end smallexample 8622 8623@item locale 8624Control characters, single quote and backslash are printed using 8625backslash notation. All names are quoted using left and right 8626quotation marks, appropriate to the current locale. If it does not 8627define quotation marks, use @samp{'} as left and as right 8628quotation marks. Any occurrences of the right quotation mark in a 8629name are escaped with @samp{\}, for example: 8630 8631For example: 8632 8633@smallexample 8634@group 8635$ @kbd{tar tf arch.tar --quoting-style=locale} 8636'./' 8637'./a space' 8638'./a\'single\'quote' 8639'./a"double"quote' 8640'./a\\backslash' 8641'./a\ttab' 8642'./a\nnewline' 8643@end group 8644@end smallexample 8645 8646@item clocale 8647Same as @samp{locale}, but @samp{"} is used for both left and right 8648quotation marks, if not provided by the currently selected locale: 8649 8650@smallexample 8651@group 8652$ @kbd{tar tf arch.tar --quoting-style=clocale} 8653"./" 8654"./a space" 8655"./a'single'quote" 8656"./a\"double\"quote" 8657"./a\\backslash" 8658"./a\ttab" 8659"./a\nnewline" 8660@end group 8661@end smallexample 8662@end table 8663 8664You can specify which characters should be quoted in addition to those 8665implied by the current quoting style: 8666 8667@table @option 8668@item --quote-chars=@var{string} 8669Always quote characters from @var{string}, even if the selected 8670quoting style would not quote them. 8671@end table 8672 8673For example, using @samp{escape} quoting (compare with the usual 8674escape listing above): 8675 8676@smallexample 8677@group 8678$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'} 8679./ 8680./a\ space 8681./a'single'quote 8682./a\"double\"quote 8683./a\\backslash 8684./a\ttab 8685./a\nnewline 8686@end group 8687@end smallexample 8688 8689To disable quoting of such additional characters, use the following 8690option: 8691 8692@table @option 8693@item --no-quote-chars=@var{string} 8694Remove characters listed in @var{string} from the list of quoted 8695characters set by the previous @option{--quote-chars} option. 8696@end table 8697 8698This option is particularly useful if you have added 8699@option{--quote-chars} to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS}) 8700and wish to disable it for the current invocation. 8701 8702Note, that @option{--no-quote-chars} does @emph{not} disable those 8703characters that are quoted by default in the selected quoting style. 8704 8705@node transform 8706@section Modifying File and Member Names 8707 8708@command{Tar} archives contain detailed information about files stored 8709in them and full file names are part of that information. When 8710storing a file to an archive, its file name is recorded in it, 8711along with the actual file contents. When restoring from an archive, 8712a file is created on disk with exactly the same name as that stored 8713in the archive. In the majority of cases this is the desired behavior 8714of a file archiver. However, there are some cases when it is not. 8715 8716First of all, it is often unsafe to extract archive members with 8717absolute file names or those that begin with a @file{../}. @GNUTAR{} 8718takes special precautions when extracting such names and provides a 8719special option for handling them, which is described in 8720@ref{absolute}. 8721 8722Secondly, you may wish to extract file names without some leading 8723directory components, or with otherwise modified names. In other 8724cases it is desirable to store files under differing names in the 8725archive. 8726 8727@GNUTAR{} provides several options for these needs. 8728 8729@table @option 8730@opindex strip-components 8731@item --strip-components=@var{number} 8732Strip given @var{number} of leading components from file names before 8733extraction. 8734@end table 8735 8736For example, suppose you have archived whole @file{/usr} hierarchy to 8737a tar archive named @file{usr.tar}. Among other files, this archive 8738contains @file{usr/include/stdlib.h}, which you wish to extract to 8739the current working directory. To do so, you type: 8740 8741@smallexample 8742$ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h} 8743@end smallexample 8744 8745The option @option{--strip=2} instructs @command{tar} to strip the 8746two leading components (@file{usr/} and @file{include/}) off the file 8747name. 8748 8749If you add the @option{--verbose} (@option{-v}) option to the invocation 8750above, you will note that the verbose listing still contains the 8751full file name, with the two removed components still in place. This 8752can be inconvenient, so @command{tar} provides a special option for 8753altering this behavior: 8754 8755@anchor{show-transformed-names} 8756@table @option 8757@opindex show-transformed-names 8758@item --show-transformed-names 8759Display file or member names with all requested transformations 8760applied. 8761@end table 8762 8763@noindent 8764For example: 8765 8766@smallexample 8767@group 8768$ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h} 8769usr/include/stdlib.h 8770$ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h} 8771stdlib.h 8772@end group 8773@end smallexample 8774 8775Notice that in both cases the file @file{stdlib.h} is extracted to the 8776current working directory, @option{--show-transformed-names} affects 8777only the way its name is displayed. 8778 8779This option is especially useful for verifying whether the invocation 8780will have the desired effect. Thus, before running 8781 8782@smallexample 8783$ @kbd{tar -x --strip=@var{n}} 8784@end smallexample 8785 8786@noindent 8787it is often advisable to run 8788 8789@smallexample 8790$ @kbd{tar -t -v --show-transformed --strip=@var{n}} 8791@end smallexample 8792 8793@noindent 8794to make sure the command will produce the intended results. 8795 8796In case you need to apply more complex modifications to the file name, 8797@GNUTAR{} provides a general-purpose transformation option: 8798 8799@table @option 8800@opindex transform 8801@opindex xform 8802@item --transform=@var{expression} 8803@itemx --xform=@var{expression} 8804Modify file names using supplied @var{expression}. 8805@end table 8806 8807@noindent 8808The @var{expression} is a @command{sed}-like replace expression of the 8809form: 8810 8811@smallexample 8812s/@var{regexp}/@var{replace}/[@var{flags}] 8813@end smallexample 8814 8815@noindent 8816where @var{regexp} is a @dfn{regular expression}, @var{replace} is a 8817replacement for each file name part that matches @var{regexp}. Both 8818@var{regexp} and @var{replace} are described in detail in 8819@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}. 8820 8821Any delimiter can be used in lieu of @samp{/}, the only requirement being 8822that it be used consistently throughout the expression. For example, 8823the following two expressions are equivalent: 8824 8825@smallexample 8826@group 8827s/one/two/ 8828s,one,two, 8829@end group 8830@end smallexample 8831 8832Changing delimiters is often useful when the @var{regex} contains 8833slashes. For example, it is more convenient to write @code{s,/,-,} than 8834@code{s/\//-/}. 8835 8836As in @command{sed}, you can give several replace expressions, 8837separated by a semicolon. 8838 8839Supported @var{flags} are: 8840 8841@table @samp 8842@item g 8843Apply the replacement to @emph{all} matches to the @var{regexp}, not 8844just the first. 8845 8846@item i 8847Use case-insensitive matching. 8848 8849@item x 8850@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended 8851regexps, Extended regular expressions, Extended regular expressions, 8852sed, GNU sed}). 8853 8854@item @var{number} 8855Only replace the @var{number}th match of the @var{regexp}. 8856 8857Note: the @acronym{POSIX} standard does not specify what should happen 8858when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{} 8859follows the GNU @command{sed} implementation in this regard, so 8860the interaction is defined to be: ignore matches before the 8861@var{number}th, and then match and replace all matches from the 8862@var{number}th on. 8863 8864@end table 8865 8866In addition, several @dfn{transformation scope} flags are supported, 8867that control to what files transformations apply. These are: 8868 8869@table @samp 8870@item r 8871Apply transformation to regular archive members. 8872 8873@item R 8874Do not apply transformation to regular archive members. 8875 8876@item s 8877Apply transformation to symbolic link targets. 8878 8879@item S 8880Do not apply transformation to symbolic link targets. 8881 8882@item h 8883Apply transformation to hard link targets. 8884 8885@item H 8886Do not apply transformation to hard link targets. 8887@end table 8888 8889Default is @samp{rsh}, which means to apply transformations to both archive 8890members and targets of symbolic and hard links. 8891 8892Default scope flags can also be changed using @samp{flags=} statement 8893in the transform expression. The flags set this way remain in force 8894until next @samp{flags=} statement or end of expression, whichever 8895occurs first. For example: 8896 8897@smallexample 8898 --transform 'flags=S;s|^|/usr/local/|' 8899@end smallexample 8900 8901Here are several examples of @option{--transform} usage: 8902 8903@enumerate 8904@item Extract @file{usr/} hierarchy into @file{usr/local/}: 8905 8906@smallexample 8907$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar} 8908@end smallexample 8909 8910@item Strip two leading directory components (equivalent to 8911@option{--strip-components=2}): 8912 8913@smallexample 8914$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar} 8915@end smallexample 8916 8917@item Convert each file name to lower case: 8918 8919@smallexample 8920$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar} 8921@end smallexample 8922 8923@item Prepend @file{/prefix/} to each file name: 8924 8925@smallexample 8926$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar} 8927@end smallexample 8928 8929@item Archive the @file{/lib} directory, prepending @samp{/usr/local} 8930to each archive member: 8931 8932@smallexample 8933$ @kbd{tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib} 8934@end smallexample 8935@end enumerate 8936 8937Notice the use of flags in the last example. The @file{/lib} 8938directory often contains many symbolic links to files within it. 8939It may look, for example, like this: 8940 8941@smallexample 8942$ @kbd{ls -l} 8943drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/ 8944-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so 8945lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so 8946... 8947@end smallexample 8948 8949Using the expression @samp{s,^,/usr/local/,} would mean adding 8950@samp{/usr/local} to both regular archive members and to link 8951targets. In this case, @file{/lib/libc.so.6} would become: 8952 8953@smallexample 8954 /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so 8955@end smallexample 8956 8957This is definitely not desired. To avoid this, the @samp{S} flag 8958is used, which excludes symbolic link targets from filename 8959transformations. The result is: 8960 8961@smallexample 8962$ @kbd{tar --transform 's,^,/usr/local/,S' -c -v -f arch.tar \ 8963 --show-transformed /lib} 8964drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/ 8965-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so 8966lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \ 8967 -> libc-2.3.2.so 8968@end smallexample 8969 8970Unlike @option{--strip-components}, @option{--transform} can be used 8971in any @GNUTAR{} operation mode. For example, the following command 8972adds files to the archive while replacing the leading @file{usr/} 8973component with @file{var/}: 8974 8975@smallexample 8976$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /} 8977@end smallexample 8978 8979To test @option{--transform} effect we suggest using 8980@option{--show-transformed-names} option: 8981 8982@smallexample 8983$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \ 8984 --verbose --show-transformed-names /} 8985@end smallexample 8986 8987If both @option{--strip-components} and @option{--transform} are used 8988together, then @option{--transform} is applied first, and the required 8989number of components is then stripped from its result. 8990 8991You can use as many @option{--transform} options in a single command 8992line as you want. The specified expressions will then be applied in 8993order of their appearance. For example, the following two invocations 8994are equivalent: 8995 8996@smallexample 8997$ @kbd{tar -cf arch.tar --transform='s,/usr/var,/var/' \ 8998 --transform='s,/usr/local,/usr/,'} 8999$ @kbd{tar -cf arch.tar \ 9000 --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'} 9001@end smallexample 9002 9003@node after 9004@section Operating Only on New Files 9005 9006@cindex Excluding file by age 9007@cindex Data Modification time, excluding files by 9008@cindex Modification time, excluding files by 9009@cindex Age, excluding files by 9010The @option{--after-date=@var{date}} (@option{--newer=@var{date}}, 9011@option{-N @var{date}}) option causes @command{tar} to only work on 9012files whose data modification or status change times are newer than 9013the @var{date} given. If @var{date} starts with @samp{/} or @samp{.}, 9014it is taken to be a file name; the data modification time of that file 9015is used as the date. If you use this option when creating or appending 9016to an archive, the archive will only include new files. If you use 9017@option{--after-date} when extracting an archive, @command{tar} will 9018only extract files newer than the @var{date} you specify. 9019 9020If you only want @command{tar} to make the date comparison based on 9021modification of the file's data (rather than status 9022changes), then use the @option{--newer-mtime=@var{date}} option. 9023 9024@cindex --after-date and --update compared 9025@cindex --newer-mtime and --update compared 9026You may use these options with any operation. Note that these options 9027differ from the @option{--update} (@option{-u}) operation in that they 9028allow you to specify a particular date against which @command{tar} can 9029compare when deciding whether or not to archive the files. 9030 9031@table @option 9032@opindex after-date 9033@opindex newer 9034@item --after-date=@var{date} 9035@itemx --newer=@var{date} 9036@itemx -N @var{date} 9037Only store files newer than @var{date}. 9038 9039Acts on files only if their data modification or status change times are 9040later than @var{date}. Use in conjunction with any operation. 9041 9042If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file 9043name; the data modification time of that file is used as the date. 9044 9045@opindex newer-mtime 9046@item --newer-mtime=@var{date} 9047Acts like @option{--after-date}, but only looks at data modification times. 9048@end table 9049 9050These options limit @command{tar} to operate only on files which have 9051been modified after the date specified. A file's status is considered to have 9052changed if its contents have been modified, or if its owner, 9053permissions, and so forth, have been changed. (For more information on 9054how to specify a date, see @ref{Date input formats}; remember that the 9055entire date argument must be quoted if it contains any spaces.) 9056 9057Gurus would say that @option{--after-date} tests both the data 9058modification time (@code{mtime}, the time the contents of the file 9059were last modified) and the status change time (@code{ctime}, the time 9060the file's status was last changed: owner, permissions, etc.@:) 9061fields, while @option{--newer-mtime} tests only the @code{mtime} 9062field. 9063 9064To be precise, @option{--after-date} checks @emph{both} @code{mtime} and 9065@code{ctime} and processes the file if either one is more recent than 9066@var{date}, while @option{--newer-mtime} only checks @code{mtime} and 9067disregards @code{ctime}. Neither does it use @code{atime} (the last time the 9068contents of the file were looked at). 9069 9070Date specifiers can have embedded spaces. Because of this, you may need 9071to quote date arguments to keep the shell from parsing them as separate 9072arguments. For example, the following command will add to the archive 9073all the files modified less than two days ago: 9074 9075@smallexample 9076$ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'} 9077@end smallexample 9078 9079When any of these options is used with the option @option{--verbose} 9080(@pxref{verbose tutorial}) @GNUTAR{} will try to convert the specified 9081date back to its textual representation and compare that with the 9082one given with the option. If the two dates differ, @command{tar} will 9083print a warning saying what date it will use. This is to help user 9084ensure he is using the right date. For example: 9085 9086@smallexample 9087@group 9088$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .} 9089tar: Option --after-date: Treating date '10 days ago' as 2006-06-11 909013:19:37.232434 9091@end group 9092@end smallexample 9093 9094@quotation 9095@strong{Please Note:} @option{--after-date} and @option{--newer-mtime} 9096should not be used for incremental backups. @xref{Incremental Dumps}, 9097for proper way of creating incremental backups. 9098@end quotation 9099 9100@node recurse 9101@section Descending into Directories 9102@cindex Avoiding recursion in directories 9103@cindex Descending directories, avoiding 9104@cindex Directories, avoiding recursion 9105@cindex Recursion in directories, avoiding 9106 9107Usually, @command{tar} will recursively explore all directories (either 9108those given on the command line or through the @option{--files-from} 9109option) for the various files they contain. However, you may not always 9110want @command{tar} to act this way. 9111 9112@opindex no-recursion 9113@cindex @command{find}, using with @command{tar} 9114The @option{--no-recursion} option inhibits @command{tar}'s recursive descent 9115into specified directories. If you specify @option{--no-recursion}, you can 9116use the @command{find} (@pxref{Top,, find, find, GNU Find Manual}) 9117utility for hunting through levels of directories to 9118construct a list of file names which you could then pass to @command{tar}. 9119@command{find} allows you to be more selective when choosing which files to 9120archive; see @ref{files}, for more information on using @command{find} with 9121@command{tar}. 9122 9123@table @option 9124@item --no-recursion 9125Prevents @command{tar} from recursively descending directories. 9126 9127@opindex recursion 9128@item --recursion 9129Requires @command{tar} to recursively descend directories. 9130This is the default. 9131@end table 9132 9133When you use @option{--no-recursion}, @GNUTAR{} grabs 9134directory entries themselves, but does not descend on them 9135recursively. Many people use @command{find} for locating files they 9136want to back up, and since @command{tar} @emph{usually} recursively 9137descends on directories, they have to use the @samp{@w{-not -type d}} 9138test in their @command{find} invocation (@pxref{Type, Type, Type test, 9139find, Finding Files}), as they usually do not want all the files in a 9140directory. They then use the @option{--files-from} option to archive 9141the files located via @command{find}. 9142 9143The problem when restoring files archived in this manner is that the 9144directories themselves are not in the archive; so the 9145@option{--same-permissions} (@option{--preserve-permissions}, 9146@option{-p}) option does not affect them---while users might really 9147like it to. Specifying @option{--no-recursion} is a way to tell 9148@command{tar} to grab only the directory entries given to it, adding 9149no new files on its own. To summarize, if you use @command{find} to 9150create a list of files to be stored in an archive, use it as follows: 9151 9152@smallexample 9153@group 9154$ @kbd{find @var{dir} @var{tests} | \ 9155 tar -cf @var{archive} --no-recursion -T -} 9156@end group 9157@end smallexample 9158 9159The @option{--no-recursion} option also applies when extracting: it 9160causes @command{tar} to extract only the matched directory entries, not 9161the files under those directories. 9162 9163The @option{--no-recursion} option also affects how globbing patterns 9164are interpreted (@pxref{controlling pattern-matching}). 9165 9166The @option{--no-recursion} and @option{--recursion} options apply to 9167later options and operands, and can be overridden by later occurrences 9168of @option{--no-recursion} and @option{--recursion}. For example: 9169 9170@smallexample 9171$ @kbd{tar -cf jams.tar --no-recursion grape --recursion grape/concord} 9172@end smallexample 9173 9174@noindent 9175creates an archive with one entry for @file{grape}, and the recursive 9176contents of @file{grape/concord}, but no entries under @file{grape} 9177other than @file{grape/concord}. 9178 9179@node one 9180@section Crossing File System Boundaries 9181@cindex File system boundaries, not crossing 9182 9183@command{tar} will normally automatically cross file system boundaries in 9184order to archive files which are part of a directory tree. You can 9185change this behavior by running @command{tar} and specifying 9186@option{--one-file-system}. This option only affects files that are 9187archived because they are in a directory that is being archived; 9188@command{tar} will still archive files explicitly named on the command line 9189or through @option{--files-from}, regardless of where they reside. 9190 9191@table @option 9192@opindex one-file-system 9193@item --one-file-system 9194Prevents @command{tar} from crossing file system boundaries when 9195archiving. Use in conjunction with any write operation. 9196@end table 9197 9198The @option{--one-file-system} option causes @command{tar} to modify its 9199normal behavior in archiving the contents of directories. If a file in 9200a directory is not on the same file system as the directory itself, then 9201@command{tar} will not archive that file. If the file is a directory 9202itself, @command{tar} will not archive anything beneath it; in other words, 9203@command{tar} will not cross mount points. 9204 9205This option is useful for making full or incremental archival backups of 9206a file system. If this option is used in conjunction with 9207@option{--verbose} (@option{-v}), files that are excluded are 9208mentioned by name on the standard error. 9209 9210@menu 9211* directory:: Changing Directory 9212* absolute:: Absolute File Names 9213@end menu 9214 9215@node directory 9216@subsection Changing the Working Directory 9217 9218@FIXME{need to read over this node now for continuity; i've switched 9219things around some.} 9220 9221@cindex Changing directory mid-stream 9222@cindex Directory, changing mid-stream 9223@cindex Working directory, specifying 9224To change the working directory in the middle of a list of file names, 9225either on the command line or in a file specified using 9226@option{--files-from} (@option{-T}), use @option{--directory} (@option{-C}). 9227This will change the working directory to the specified directory 9228after that point in the list. 9229 9230@table @option 9231@opindex directory 9232@item --directory=@var{directory} 9233@itemx -C @var{directory} 9234Changes the working directory in the middle of a command line. 9235@end table 9236 9237For example, 9238 9239@smallexample 9240$ @kbd{tar -c -f jams.tar grape prune -C food cherry} 9241@end smallexample 9242 9243@noindent 9244will place the files @file{grape} and @file{prune} from the current 9245directory into the archive @file{jams.tar}, followed by the file 9246@file{cherry} from the directory @file{food}. This option is especially 9247useful when you have several widely separated files that you want to 9248store in the same archive. 9249 9250Note that the file @file{cherry} is recorded in the archive under the 9251precise name @file{cherry}, @emph{not} @file{food/cherry}. Thus, the 9252archive will contain three files that all appear to have come from the 9253same directory; if the archive is extracted with plain @samp{tar 9254--extract}, all three files will be written in the current directory. 9255 9256Contrast this with the command, 9257 9258@smallexample 9259$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry} 9260@end smallexample 9261 9262@noindent 9263which records the third file in the archive under the name 9264@file{red/cherry} so that, if the archive is extracted using 9265@samp{tar --extract}, the third file will be written in a subdirectory 9266named @file{red}. 9267 9268You can use the @option{--directory} option to make the archive 9269independent of the original name of the directory holding the files. 9270The following command places the files @file{/etc/passwd}, 9271@file{/etc/hosts}, and @file{/lib/libc.a} into the archive 9272@file{foo.tar}: 9273 9274@smallexample 9275$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a} 9276@end smallexample 9277 9278@noindent 9279However, the names of the archive members will be exactly what they were 9280on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}. 9281They will not appear to be related by file name to the original 9282directories where those files were located. 9283 9284Note that @option{--directory} options are interpreted consecutively. If 9285@option{--directory} specifies a relative file name, it is interpreted 9286relative to the then current directory, which might not be the same as 9287the original current working directory of @command{tar}, due to a previous 9288@option{--directory} option. 9289 9290When using @option{--files-from} (@pxref{files}), you can put various 9291@command{tar} options (including @option{-C}) in the file list. Notice, 9292however, that in this case the option and its argument may not be 9293separated by whitespace. If you use short option, its argument must 9294either follow the option letter immediately, without any intervening 9295whitespace, or occupy the next line. Otherwise, if you use long 9296option, separate its argument by an equal sign. 9297 9298For instance, the file list for the above example will be: 9299 9300@smallexample 9301@group 9302-C/etc 9303passwd 9304hosts 9305--directory=/lib 9306libc.a 9307@end group 9308@end smallexample 9309 9310@noindent 9311To use it, you would invoke @command{tar} as follows: 9312 9313@smallexample 9314$ @kbd{tar -c -f foo.tar --files-from list} 9315@end smallexample 9316 9317The interpretation of options in file lists is disabled by 9318@option{--verbatim-files-from} and @option{--null} options. 9319 9320@node absolute 9321@subsection Absolute File Names 9322@cindex absolute file names 9323@cindex file names, absolute 9324 9325By default, @GNUTAR{} drops a leading @samp{/} on 9326input or output, and complains about file names containing a @file{..} 9327component. There is an option that turns off this behavior: 9328 9329@table @option 9330@opindex absolute-names 9331@item --absolute-names 9332@itemx -P 9333Do not strip leading slashes from file names, and permit file names 9334containing a @file{..} file name component. 9335@end table 9336 9337When @command{tar} extracts archive members from an archive, it strips any 9338leading slashes (@samp{/}) from the member name. This causes absolute 9339member names in the archive to be treated as relative file names. This 9340allows you to have such members extracted wherever you want, instead of 9341being restricted to extracting the member in the exact directory named 9342in the archive. For example, if the archive member has the name 9343@file{/etc/passwd}, @command{tar} will extract it as if the name were 9344really @file{etc/passwd}. 9345 9346File names containing @file{..} can cause problems when extracting, so 9347@command{tar} normally warns you about such files when creating an 9348archive, and rejects attempts to extracts such files. 9349 9350Other @command{tar} programs do not do this. As a result, if you 9351create an archive whose member names start with a slash, they will be 9352difficult for other people with a non-@GNUTAR{} 9353program to use. Therefore, @GNUTAR{} also strips 9354leading slashes from member names when putting members into the 9355archive. For example, if you ask @command{tar} to add the file 9356@file{/bin/ls} to an archive, it will do so, but the member name will 9357be @file{bin/ls}@footnote{A side effect of this is that when 9358@option{--create} is used with @option{--verbose} the resulting output 9359is not, generally speaking, the same as the one you'd get running 9360@kbd{tar --list} command. This may be important if you use some 9361scripts for comparing both outputs. @xref{listing member and file names}, 9362for the information on how to handle this case.}. 9363 9364Symbolic links containing @file{..} or leading @samp{/} can also cause 9365problems when extracting, so @command{tar} normally extracts them last; 9366it may create empty files as placeholders during extraction. 9367 9368If you use the @option{--absolute-names} (@option{-P}) option, 9369@command{tar} will do none of these transformations. 9370 9371To archive or extract files relative to the root directory, specify 9372the @option{--absolute-names} (@option{-P}) option. 9373 9374Normally, @command{tar} acts on files relative to the working 9375directory---ignoring superior directory names when archiving, and 9376ignoring leading slashes when extracting. 9377 9378When you specify @option{--absolute-names} (@option{-P}), 9379@command{tar} stores file names including all superior directory 9380names, and preserves leading slashes. If you only invoked 9381@command{tar} from the root directory you would never need the 9382@option{--absolute-names} option, but using this option 9383may be more convenient than switching to root. 9384 9385@FIXME{Should be an example in the tutorial/wizardry section using this 9386to transfer files between systems.} 9387 9388@table @option 9389@item --absolute-names 9390Preserves full file names (including superior directory names) when 9391archiving and extracting files. 9392 9393@end table 9394 9395@command{tar} prints out a message about removing the @samp{/} from 9396file names. This message appears once per @GNUTAR{} 9397invocation. It represents something which ought to be told; ignoring 9398what it means can cause very serious surprises, later. 9399 9400Some people, nevertheless, do not want to see this message. Wanting to 9401play really dangerously, one may of course redirect @command{tar} standard 9402error to the sink. For example, under @command{sh}: 9403 9404@smallexample 9405$ @kbd{tar -c -f archive.tar /home 2> /dev/null} 9406@end smallexample 9407 9408@noindent 9409Another solution, both nicer and simpler, would be to change to 9410the @file{/} directory first, and then avoid absolute notation. 9411For example: 9412 9413@smallexample 9414$ @kbd{tar -c -f archive.tar -C / home} 9415@end smallexample 9416 9417@xref{Integrity}, for some of the security-related implications 9418of using this option. 9419 9420@include parse-datetime.texi 9421 9422@node Formats 9423@chapter Controlling the Archive Format 9424 9425@cindex Tar archive formats 9426Due to historical reasons, there are several formats of tar archives. 9427All of them are based on the same principles, but have some subtle 9428differences that often make them incompatible with each other. 9429 9430GNU tar is able to create and handle archives in a variety of formats. 9431The most frequently used formats are (in alphabetical order): 9432 9433@table @asis 9434@item gnu 9435Format used by @GNUTAR{} versions up to 1.13.25. This format derived 9436from an early @acronym{POSIX} standard, adding some improvements such as 9437sparse file handling and incremental archives. Unfortunately these 9438features were implemented in a way incompatible with other archive 9439formats. 9440 9441Archives in @samp{gnu} format are able to hold file names of unlimited 9442length. 9443 9444@item oldgnu 9445Format used by @GNUTAR{} of versions prior to 1.12. 9446 9447@item v7 9448Archive format, compatible with the V7 implementation of tar. This 9449format imposes a number of limitations. The most important of them 9450are: 9451 9452@enumerate 9453@item The maximum length of a file name is limited to 99 characters. 9454@item The maximum length of a symbolic link is limited to 99 characters. 9455@item It is impossible to store special files (block and character 9456devices, fifos etc.) 9457@item Maximum value of user or group @acronym{ID} is limited to 2097151 (7777777 9458octal) 9459@item V7 archives do not contain symbolic ownership information (user 9460and group name of the file owner). 9461@end enumerate 9462 9463This format has traditionally been used by Automake when producing 9464Makefiles. This practice will change in the future, in the meantime, 9465however this means that projects containing file names more than 99 9466characters long will not be able to use @GNUTAR{} @value{VERSION} and 9467Automake prior to 1.9. 9468 9469@item ustar 9470Archive format defined by @acronym{POSIX.1-1988} specification. It stores 9471symbolic ownership information. It is also able to store 9472special files. However, it imposes several restrictions as well: 9473 9474@enumerate 9475@item The maximum length of a file name is limited to 256 characters, 9476provided that the file name can be split at a directory separator in 9477two parts, first of them being at most 155 bytes long. So, in most 9478cases the maximum file name length will be shorter than 256 9479characters. 9480@item The maximum length of a symbolic link name is limited to 9481100 characters. 9482@item Maximum size of a file the archive is able to accommodate 9483is 8GB 9484@item Maximum value of UID/GID is 2097151. 9485@item Maximum number of bits in device major and minor numbers is 21. 9486@end enumerate 9487 9488@item star 9489Format used by J@"org Schilling @command{star} 9490implementation. @GNUTAR{} is able to read @samp{star} archives but 9491currently does not produce them. 9492 9493@item posix 9494Archive format defined by @acronym{POSIX.1-2001} specification. This is the 9495most flexible and feature-rich format. It does not impose any 9496restrictions on file sizes or file name lengths. This format is quite 9497recent, so not all tar implementations are able to handle it properly. 9498However, this format is designed in such a way that any tar 9499implementation able to read @samp{ustar} archives will be able to read 9500most @samp{posix} archives as well, with the only exception that any 9501additional information (such as long file names etc.)@: will in such 9502case be extracted as plain text files along with the files it refers to. 9503 9504This archive format will be the default format for future versions 9505of @GNUTAR{}. 9506 9507@end table 9508 9509The following table summarizes the limitations of each of these 9510formats: 9511 9512@multitable @columnfractions .10 .20 .20 .20 .20 9513@headitem Format @tab UID @tab File Size @tab File Name @tab Devn 9514@item gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63 9515@item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63 9516@item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a 9517@item ustar @tab 2097151 @tab 8GB @tab 256 @tab 21 9518@item posix @tab Unlimited @tab Unlimited @tab Unlimited @tab Unlimited 9519@end multitable 9520 9521The default format for @GNUTAR{} is defined at compilation 9522time. You may check it by running @command{tar --help}, and examining 9523the last lines of its output. Usually, @GNUTAR{} is configured 9524to create archives in @samp{gnu} format, however, future version will 9525switch to @samp{posix}. 9526 9527@menu 9528* Compression:: Using Less Space through Compression 9529* Attributes:: Handling File Attributes 9530* Portability:: Making @command{tar} Archives More Portable 9531* cpio:: Comparison of @command{tar} and @command{cpio} 9532@end menu 9533 9534@node Compression 9535@section Using Less Space through Compression 9536 9537@menu 9538* gzip:: Creating and Reading Compressed Archives 9539* sparse:: Archiving Sparse Files 9540@end menu 9541 9542@node gzip 9543@subsection Creating and Reading Compressed Archives 9544@cindex Compressed archives 9545@cindex Storing archives in compressed format 9546 9547@cindex gzip 9548@cindex bzip2 9549@cindex lzip 9550@cindex lzma 9551@cindex lzop 9552@cindex compress 9553@cindex zstd 9554@GNUTAR{} is able to create and read compressed archives. It supports 9555a wide variety of compression programs, namely: @command{gzip}, 9556@command{bzip2}, @command{lzip}, @command{lzma}, @command{lzop}, 9557@command{zstd}, @command{xz} and traditional @command{compress}. The 9558latter is supported mostly for backward compatibility, and we recommend 9559against using it, because it is by far less effective than the other 9560compression programs@footnote{It also had patent problems in the past.}. 9561 9562Creating a compressed archive is simple: you just specify a 9563@dfn{compression option} along with the usual archive creation 9564commands. Available compression options are summarized in the 9565table below: 9566 9567@multitable @columnfractions 0.4 0.2 0.4 9568@headitem Long @tab Short @tab Archive format 9569@item @option{--gzip} @tab @option{-z} @tab @command{gzip} 9570@item @option{--bzip2} @tab @option{-j} @tab @command{bzip2} 9571@item @option{--xz} @tab @option{-J} @tab @command{xz} 9572@item @option{--lzip} @tab @tab @command{lzip} 9573@item @option{--lzma} @tab @tab @command{lzma} 9574@item @option{--lzop} @tab @tab @command{lzop} 9575@item @option{--zstd} @tab @tab @command{zstd} 9576@item @option{--compress} @tab @option{-Z} @tab @command{compress} 9577@end multitable 9578 9579For example: 9580 9581@smallexample 9582$ @kbd{tar czf archive.tar.gz .} 9583@end smallexample 9584 9585You can also let @GNUTAR{} select the compression program based on 9586the suffix of the archive file name. This is done using 9587@option{--auto-compress} (@option{-a}) command line option. For 9588example, the following invocation will use @command{bzip2} for 9589compression: 9590 9591@smallexample 9592$ @kbd{tar caf archive.tar.bz2 .} 9593@end smallexample 9594 9595@noindent 9596whereas the following one will use @command{lzma}: 9597 9598@smallexample 9599$ @kbd{tar caf archive.tar.lzma .} 9600@end smallexample 9601 9602For a complete list of file name suffixes recognized by @GNUTAR{}, 9603see @ref{auto-compress}. 9604 9605Reading compressed archive is even simpler: you don't need to specify 9606any additional options as @GNUTAR{} recognizes its format 9607automatically. Thus, the following commands will list and extract the 9608archive created in previous example: 9609 9610@smallexample 9611# List the compressed archive 9612$ @kbd{tar tf archive.tar.gz} 9613# Extract the compressed archive 9614$ @kbd{tar xf archive.tar.gz} 9615@end smallexample 9616 9617The format recognition algorithm is based on @dfn{signatures}, a 9618special byte sequences in the beginning of file, that are specific for 9619certain compression formats. If this approach fails, @command{tar} 9620falls back to using archive name suffix to determine its format 9621(@pxref{auto-compress}, for a list of recognized suffixes). 9622 9623@anchor{alternative decompression programs} 9624@cindex alternative decompression programs 9625Some compression programs are able to handle different compression 9626formats. @GNUTAR{} uses this, if the principal decompressor for the 9627given format is not available. For example, if @command{compress} is 9628not installed, @command{tar} will try to use @command{gzip}. As of 9629version @value{VERSION} the following alternatives are 9630tried@footnote{To verbosely trace the decompressor selection, use the 9631@option{--warning=decompress-program} option 9632(@pxref{warnings,decompress-program}).}: 9633 9634@multitable @columnfractions 0.3 0.3 0.3 9635@headitem Format @tab Main decompressor @tab Alternatives 9636@item compress @tab compress @tab gzip 9637@item lzma @tab lzma @tab xz 9638@item bzip2 @tab bzip2 @tab lbzip2 9639@end multitable 9640 9641The only case when you have to specify a decompression option while 9642reading the archive is when reading from a pipe or from a tape drive 9643that does not support random access. However, in this case @GNUTAR{} 9644will indicate which option you should use. For example: 9645 9646@smallexample 9647$ @kbd{cat archive.tar.gz | tar tf -} 9648tar: Archive is compressed. Use -z option 9649tar: Error is not recoverable: exiting now 9650@end smallexample 9651 9652If you see such diagnostics, just add the suggested option to the 9653invocation of @GNUTAR{}: 9654 9655@smallexample 9656$ @kbd{cat archive.tar.gz | tar tzf -} 9657@end smallexample 9658 9659Notice also, that there are several restrictions on operations on 9660compressed archives. First of all, compressed archives cannot be 9661modified, i.e., you cannot update (@option{--update}, alias @option{-u}) 9662them or delete (@option{--delete}) members from them or 9663add (@option{--append}, alias @option{-r}) members to them. Likewise, you 9664cannot append another @command{tar} archive to a compressed archive using 9665@option{--concatenate} (@option{-A}). Secondly, multi-volume 9666archives cannot be compressed. 9667 9668The following options allow to select a particular compressor program: 9669 9670@table @option 9671@opindex gzip 9672@opindex ungzip 9673@item -z 9674@itemx --gzip 9675@itemx --ungzip 9676Filter the archive through @command{gzip}. 9677 9678@opindex xz 9679@item -J 9680@itemx --xz 9681Filter the archive through @code{xz}. 9682 9683@item -j 9684@itemx --bzip2 9685Filter the archive through @code{bzip2}. 9686 9687@opindex lzip 9688@item --lzip 9689Filter the archive through @command{lzip}. 9690 9691@opindex lzma 9692@item --lzma 9693Filter the archive through @command{lzma}. 9694 9695@opindex lzop 9696@item --lzop 9697Filter the archive through @command{lzop}. 9698 9699@opindex zstd 9700@item --zstd 9701Filter the archive through @command{zstd}. 9702 9703@opindex compress 9704@opindex uncompress 9705@item -Z 9706@itemx --compress 9707@itemx --uncompress 9708Filter the archive through @command{compress}. 9709@end table 9710 9711When any of these options is given, @GNUTAR{} searches the compressor 9712binary in the current path and invokes it. The name of the compressor 9713program is specified at compilation time using a corresponding 9714@option{--with-@var{compname}} option to @command{configure}, e.g. 9715@option{--with-bzip2} to select a specific @command{bzip2} binary. 9716@xref{lbzip2}, for a detailed discussion. 9717 9718The output produced by @command{tar --help} shows the actual 9719compressor names along with each of these options. 9720 9721You can use any of these options on physical devices (tape drives, 9722etc.)@: and remote files as well as on normal files; data to or from 9723such devices or remote files is reblocked by another copy of the 9724@command{tar} program to enforce the specified (or default) record 9725size. The default compression parameters are used. 9726You can override them by using the @option{-I} option (see 9727below), e.g.: 9728 9729@smallexample 9730$ @kbd{tar -cf archive.tar.gz -I 'gzip -9 -n' subdir} 9731@end smallexample 9732 9733@noindent 9734A more traditional way to do this is to use a pipe: 9735 9736@smallexample 9737$ @kbd{tar cf - subdir | gzip -9 -n > archive.tar.gz} 9738@end smallexample 9739 9740@cindex corrupted archives 9741Compressed archives are easily corrupted, because compressed files 9742have little redundancy. The adaptive nature of the 9743compression scheme means that the compression tables are implicitly 9744spread all over the archive. If you lose a few blocks, the dynamic 9745construction of the compression tables becomes unsynchronized, and there 9746is little chance that you could recover later in the archive. 9747 9748Other compression options provide better control over creating 9749compressed archives. These are: 9750 9751@table @option 9752@anchor{auto-compress} 9753@opindex auto-compress 9754@item --auto-compress 9755@itemx -a 9756Select a compression program to use by the archive file name 9757suffix. The following suffixes are recognized: 9758 9759@multitable @columnfractions 0.3 0.6 9760@headitem Suffix @tab Compression program 9761@item @samp{.gz} @tab @command{gzip} 9762@item @samp{.tgz} @tab @command{gzip} 9763@item @samp{.taz} @tab @command{gzip} 9764@item @samp{.Z} @tab @command{compress} 9765@item @samp{.taZ} @tab @command{compress} 9766@item @samp{.bz2} @tab @command{bzip2} 9767@item @samp{.tz2} @tab @command{bzip2} 9768@item @samp{.tbz2} @tab @command{bzip2} 9769@item @samp{.tbz} @tab @command{bzip2} 9770@item @samp{.lz} @tab @command{lzip} 9771@item @samp{.lzma} @tab @command{lzma} 9772@item @samp{.tlz} @tab @command{lzma} 9773@item @samp{.lzo} @tab @command{lzop} 9774@item @samp{.xz} @tab @command{xz} 9775@item @samp{.zst} @tab @command{zstd} 9776@item @samp{.tzst} @tab @command{zstd} 9777@end multitable 9778 9779@anchor{use-compress-program} 9780@opindex use-compress-program 9781@item --use-compress-program=@var{command} 9782@itemx -I=@var{command} 9783Use external compression program @var{command}. Use this option if you 9784want to specify options for the compression program, or if you 9785are not happy with the compression program associated with the suffix 9786at compile time, or if you have a compression program that @GNUTAR{} 9787does not support. The @var{command} argument is a valid command 9788invocation, as you would type it at the command line prompt, with any 9789additional options as needed. Enclose it in quotes if it contains 9790white space (@pxref{external, Running External Commands}). 9791 9792The @var{command} should follow two conventions: 9793 9794First, when invoked without additional options, it should read data 9795from standard input, compress it and output it on standard output. 9796 9797Secondly, if invoked with the additional @option{-d} option, it should 9798do exactly the opposite, i.e., read the compressed data from the 9799standard input and produce uncompressed data on the standard output. 9800 9801The latter requirement means that you must not use the @option{-d} 9802option as a part of the @var{command} itself. 9803@end table 9804 9805@cindex gpg, using with tar 9806@cindex gnupg, using with tar 9807@cindex Using encrypted archives 9808The @option{--use-compress-program} option, in particular, lets you 9809implement your own filters, not necessarily dealing with 9810compression/decompression. For example, suppose you wish to implement 9811PGP encryption on top of compression, using @command{gpg} (@pxref{Top, 9812gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard 9813Manual}). The following script does that: 9814 9815@smallexample 9816@group 9817#! /bin/sh 9818case $1 in 9819-d) gpg --decrypt - | gzip -d -c;; 9820'') gzip -c | gpg -s;; 9821*) echo "Unknown option $1">&2; exit 1;; 9822esac 9823@end group 9824@end smallexample 9825 9826Suppose you name it @file{gpgz} and save it somewhere in your 9827@env{PATH}. Then the following command will create a compressed 9828archive signed with your private key: 9829 9830@smallexample 9831$ @kbd{tar -cf foo.tar.gpgz -Igpgz .} 9832@end smallexample 9833 9834@noindent 9835Likewise, the command below will list its contents: 9836 9837@smallexample 9838$ @kbd{tar -tf foo.tar.gpgz -Igpgz .} 9839@end smallexample 9840 9841@ignore 9842The above is based on the following discussion: 9843 9844 I have one question, or maybe it's a suggestion if there isn't a way 9845 to do it now. I would like to use @option{--gzip}, but I'd also like 9846 the output to be fed through a program like @acronym{GNU} 9847 @command{ecc} (actually, right now that's @samp{exactly} what I'd like 9848 to use :-)), basically adding ECC protection on top of compression. 9849 It seems as if this should be quite easy to do, but I can't work out 9850 exactly how to go about it. Of course, I can pipe the standard output 9851 of @command{tar} through @command{ecc}, but then I lose (though I 9852 haven't started using it yet, I confess) the ability to have 9853 @command{tar} use @command{rmt} for it's I/O (I think). 9854 9855 I think the most straightforward thing would be to let me specify a 9856 general set of filters outboard of compression (preferably ordered, 9857 so the order can be automatically reversed on input operations, and 9858 with the options they require specifiable), but beggars shouldn't be 9859 choosers and anything you decide on would be fine with me. 9860 9861 By the way, I like @command{ecc} but if (as the comments say) it can't 9862 deal with loss of block sync, I'm tempted to throw some time at adding 9863 that capability. Supposing I were to actually do such a thing and 9864 get it (apparently) working, do you accept contributed changes to 9865 utilities like that? (Leigh Clayton @file{loc@@soliton.com}, May 1995). 9866 9867 Isn't that exactly the role of the 9868 @option{--use-compress-prog=@var{program}} option? 9869 I never tried it myself, but I suspect you may want to write a 9870 @var{prog} script or program able to filter stdin to stdout to 9871 way you want. It should recognize the @option{-d} option, for when 9872 extraction is needed rather than creation. 9873 9874 It has been reported that if one writes compressed data (through the 9875 @option{--gzip} or @option{--compress} options) to a DLT and tries to use 9876 the DLT compression mode, the data will actually get bigger and one will 9877 end up with less space on the tape. 9878@end ignore 9879 9880@menu 9881* lbzip2:: Using lbzip2 with @GNUTAR{}. 9882@end menu 9883 9884@node lbzip2 9885@subsubsection Using lbzip2 with @GNUTAR{}. 9886@cindex lbzip2 9887@cindex Laszlo Ersek 9888 @command{Lbzip2} is a multithreaded utility for handling 9889@samp{bzip2} compression, written by Laszlo Ersek. It makes use of 9890multiple processors to speed up its operation and in general works 9891considerably faster than @command{bzip2}. For a detailed description 9892of @command{lbzip2} see @uref{http://freshmeat.net/@/projects/@/lbzip2} and 9893@uref{http://www.linuxinsight.com/@/lbzip2-parallel-bzip2-utility.html, 9894lbzip2: parallel bzip2 utility}. 9895 9896 Recent versions of @command{lbzip2} are mostly command line compatible 9897with @command{bzip2}, which makes it possible to automatically invoke 9898it via the @option{--bzip2} @GNUTAR{} command line option. To do so, 9899@GNUTAR{} must be configured with the @option{--with-bzip2} command 9900line option, like this: 9901 9902@smallexample 9903$ @kbd{./configure --with-bzip2=lbzip2 [@var{other-options}]} 9904@end smallexample 9905 9906 Once configured and compiled this way, @command{tar --help} will show the 9907following: 9908 9909@smallexample 9910@group 9911$ @kbd{tar --help | grep -- --bzip2} 9912 -j, --bzip2 filter the archive through lbzip2 9913@end group 9914@end smallexample 9915 9916@noindent 9917which means that running @command{tar --bzip2} will invoke @command{lbzip2}. 9918 9919@node sparse 9920@subsection Archiving Sparse Files 9921@cindex Sparse Files 9922 9923Files in the file system occasionally have @dfn{holes}. A @dfn{hole} 9924in a file is a section of the file's contents which was never written. 9925The contents of a hole reads as all zeros. On many operating systems, 9926actual disk storage is not allocated for holes, but they are counted 9927in the length of the file. If you archive such a file, @command{tar} 9928could create an archive longer than the original. To have @command{tar} 9929attempt to recognize the holes in a file, use @option{--sparse} 9930(@option{-S}). When you use this option, then, for any file using 9931less disk space than would be expected from its length, @command{tar} 9932searches the file for holes. It then records in the archive for the file where 9933the holes (consecutive stretches of zeros) are, and only archives the 9934``real contents'' of the file. On extraction (using @option{--sparse} is not 9935needed on extraction) any such files have also holes created wherever the holes 9936were found. Thus, if you use @option{--sparse}, @command{tar} archives won't 9937take more space than the original. 9938 9939@GNUTAR{} uses two methods for detecting holes in sparse files. These 9940methods are described later in this subsection. 9941 9942@table @option 9943@opindex sparse 9944@item -S 9945@itemx --sparse 9946This option instructs @command{tar} to test each file for sparseness 9947before attempting to archive it. If the file is found to be sparse it 9948is treated specially, thus allowing to decrease the amount of space 9949used by its image in the archive. 9950 9951This option is meaningful only when creating or updating archives. It 9952has no effect on extraction. 9953@end table 9954 9955Consider using @option{--sparse} when performing file system backups, 9956to avoid archiving the expanded forms of files stored sparsely in the 9957system. 9958 9959Even if your system has no sparse files currently, some may be 9960created in the future. If you use @option{--sparse} while making file 9961system backups as a matter of course, you can be assured the archive 9962will never take more space on the media than the files take on disk 9963(otherwise, archiving a disk filled with sparse files might take 9964hundreds of tapes). @xref{Incremental Dumps}. 9965 9966However, be aware that @option{--sparse} option may present a serious 9967drawback. Namely, in order to determine the positions of holes in a file 9968@command{tar} may have to read it before trying to archive it, so in total 9969the file may be read @strong{twice}. This may happen when your OS or your FS 9970does not support @dfn{SEEK_HOLE/SEEK_DATA} feature in @dfn{lseek} (See 9971@option{--hole-detection}, below). 9972 9973@cindex sparse formats, defined 9974When using @samp{POSIX} archive format, @GNUTAR{} is able to store 9975sparse files using in three distinct ways, called @dfn{sparse 9976formats}. A sparse format is identified by its @dfn{number}, 9977consisting, as usual of two decimal numbers, delimited by a dot. By 9978default, format @samp{1.0} is used. If, for some reason, you wish to 9979use an earlier format, you can select it using 9980@option{--sparse-version} option. 9981 9982@table @option 9983@opindex sparse-version 9984@item --sparse-version=@var{version} 9985Select the format to store sparse files in. Valid @var{version} values 9986are: @samp{0.0}, @samp{0.1} and @samp{1.0}. @xref{Sparse Formats}, 9987for a detailed description of each format. 9988@end table 9989 9990Using @option{--sparse-format} option implies @option{--sparse}. 9991 9992@table @option 9993@opindex hole-detection 9994@cindex hole detection 9995@item --hole-detection=@var{method} 9996Enforce concrete hole detection method. Before the real contents of sparse 9997file are stored, @command{tar} needs to gather knowledge about file 9998sparseness. This is because it needs to have the file's map of holes 9999stored into tar header before it starts archiving the file contents. 10000Currently, two methods of hole detection are implemented: 10001 10002@itemize @bullet 10003@item @option{--hole-detection=seek} 10004Seeking the file for data and holes. It uses enhancement of the @code{lseek} 10005system call (@code{SEEK_HOLE} and @code{SEEK_DATA}) which is able to 10006reuse file system knowledge about sparse file contents - so the 10007detection is usually very fast. To use this feature, your file system 10008and operating system must support it. At the time of this writing 10009(2015) this feature, in spite of not being accepted by POSIX, is 10010fairly widely supported by different operating systems. 10011 10012@item @option{--hole-detection=raw} 10013Reading byte-by-byte the whole sparse file before the archiving. This 10014method detects holes like consecutive stretches of zeroes. Comparing to 10015the previous method, it is usually much slower, although more 10016portable. 10017@end itemize 10018@end table 10019 10020When no @option{--hole-detection} option is given, @command{tar} uses 10021the @samp{seek}, if supported by the operating system. 10022 10023Using @option{--hole-detection} option implies @option{--sparse}. 10024 10025@node Attributes 10026@section Handling File Attributes 10027@cindex attributes, files 10028@cindex file attributes 10029 10030When @command{tar} reads files, it updates their access times. To 10031avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either 10032reset the access time retroactively or avoid changing it in the first 10033place. 10034 10035@table @option 10036@opindex atime-preserve 10037@item --atime-preserve 10038@itemx --atime-preserve=replace 10039@itemx --atime-preserve=system 10040Preserve the access times of files that are read. This works only for 10041files that you own, unless you have superuser privileges. 10042 10043@option{--atime-preserve=replace} works on most systems, but it also 10044restores the data modification time and updates the status change 10045time. Hence it doesn't interact with incremental dumps nicely 10046(@pxref{Incremental Dumps}), and it can set access or data modification times 10047incorrectly if other programs access the file while @command{tar} is 10048running. 10049 10050@option{--atime-preserve=system} avoids changing the access time in 10051the first place, if the operating system supports this. 10052Unfortunately, this may or may not work on any given operating system 10053or file system. If @command{tar} knows for sure it won't work, it 10054complains right away. 10055 10056Currently @option{--atime-preserve} with no operand defaults to 10057@option{--atime-preserve=replace}, but this is intended to change to 10058@option{--atime-preserve=system} when the latter is better-supported. 10059 10060@opindex touch 10061@item -m 10062@itemx --touch 10063Do not extract data modification time. 10064 10065When this option is used, @command{tar} leaves the data modification times 10066of the files it extracts as the times when the files were extracted, 10067instead of setting it to the times recorded in the archive. 10068 10069This option is meaningless with @option{--list} (@option{-t}). 10070 10071@opindex same-owner 10072@item --same-owner 10073Create extracted files with the same ownership they have in the 10074archive. 10075 10076This is the default behavior for the superuser, 10077so this option is meaningful only for non-root users, when @command{tar} 10078is executed on those systems able to give files away. This is 10079considered as a security flaw by many people, at least because it 10080makes quite difficult to correctly account users for the disk space 10081they occupy. Also, the @code{suid} or @code{sgid} attributes of 10082files are easily and silently lost when files are given away. 10083 10084When writing an archive, @command{tar} writes the user @acronym{ID} and user name 10085separately. If it can't find a user name (because the user @acronym{ID} is not 10086in @file{/etc/passwd}), then it does not write one. When restoring, 10087it tries to look the name (if one was written) up in 10088@file{/etc/passwd}. If it fails, then it uses the user @acronym{ID} stored in 10089the archive instead. 10090 10091@opindex no-same-owner 10092@item --no-same-owner 10093@itemx -o 10094Do not attempt to restore ownership when extracting. This is the 10095default behavior for ordinary users, so this option has an effect 10096only for the superuser. 10097 10098@opindex numeric-owner 10099@item --numeric-owner 10100The @option{--numeric-owner} option allows (ANSI) archives to be written 10101without user/group name information or such information to be ignored 10102when extracting. It effectively disables the generation and/or use 10103of user/group name information. This option forces extraction using 10104the numeric ids from the archive, ignoring the names. 10105 10106This is useful in certain circumstances, when restoring a backup from 10107an emergency floppy with different passwd/group files for example. 10108It is otherwise impossible to extract files with the right ownerships 10109if the password file in use during the extraction does not match the 10110one belonging to the file system(s) being extracted. This occurs, 10111for example, if you are restoring your files after a major crash and 10112had booted from an emergency floppy with no password file or put your 10113disk into another machine to do the restore. 10114 10115The numeric ids are @emph{always} saved into @command{tar} archives. 10116The identifying names are added at create time when provided by the 10117system, unless @option{--format=oldgnu} is used. Numeric ids could be 10118used when moving archives between a collection of machines using 10119a centralized management for attribution of numeric ids to users 10120and groups. This is often made through using the NIS capabilities. 10121 10122When making a @command{tar} file for distribution to other sites, it 10123is sometimes cleaner to use a single owner for all files in the 10124distribution, and nicer to specify the write permission bits of the 10125files as stored in the archive independently of their actual value on 10126the file system. The way to prepare a clean distribution is usually 10127to have some Makefile rule creating a directory, copying all needed 10128files in that directory, then setting ownership and permissions as 10129wanted (there are a lot of possible schemes), and only then making a 10130@command{tar} archive out of this directory, before cleaning 10131everything out. Of course, we could add a lot of options to 10132@GNUTAR{} for fine tuning permissions and ownership. 10133This is not the good way, I think. @GNUTAR{} is 10134already crowded with options and moreover, the approach just explained 10135gives you a great deal of control already. 10136 10137@xopindex{same-permissions, short description} 10138@xopindex{preserve-permissions, short description} 10139@item -p 10140@itemx --same-permissions 10141@itemx --preserve-permissions 10142Extract all protection information. 10143 10144This option causes @command{tar} to set the modes (access permissions) of 10145extracted files exactly as recorded in the archive. If this option 10146is not used, the current @code{umask} setting limits the permissions 10147on extracted files. This option is by default enabled when 10148@command{tar} is executed by a superuser. 10149 10150 10151This option is meaningless with @option{--list} (@option{-t}). 10152@end table 10153 10154@node Portability 10155@section Making @command{tar} Archives More Portable 10156 10157Creating a @command{tar} archive on a particular system that is meant to be 10158useful later on many other machines and with other versions of @command{tar} 10159is more challenging than you might think. @command{tar} archive formats 10160have been evolving since the first versions of Unix. Many such formats 10161are around, and are not always compatible with each other. This section 10162discusses a few problems, and gives some advice about making @command{tar} 10163archives more portable. 10164 10165One golden rule is simplicity. For example, limit your @command{tar} 10166archives to contain only regular files and directories, avoiding 10167other kind of special files. Do not attempt to save sparse files or 10168contiguous files as such. Let's discuss a few more problems, in turn. 10169 10170@FIXME{Discuss GNU extensions (incremental backups, multi-volume 10171archives and archive labels) in GNU and PAX formats.} 10172 10173@menu 10174* Portable Names:: Portable Names 10175* dereference:: Symbolic Links 10176* hard links:: Hard Links 10177* old:: Old V7 Archives 10178* ustar:: Ustar Archives 10179* gnu:: GNU and old GNU format archives. 10180* posix:: @acronym{POSIX} archives 10181* Checksumming:: Checksumming Problems 10182* Large or Negative Values:: Large files, negative time stamps, etc. 10183* Other Tars:: How to Extract GNU-Specific Data Using 10184 Other @command{tar} Implementations 10185@end menu 10186 10187@node Portable Names 10188@subsection Portable Names 10189 10190Use portable file and member names. A name is portable if it contains 10191only @acronym{ASCII} letters and digits, @samp{/}, @samp{.}, @samp{_}, and 10192@samp{-}; it cannot be empty, start with @samp{-} or @samp{//}, or 10193contain @samp{/-}. Avoid deep directory nesting. For portability to 10194old Unix hosts, limit your file name components to 14 characters or 10195less. 10196 10197If you intend to have your @command{tar} archives to be read under 10198MSDOS, you should not rely on case distinction for file names, and you 10199might use the @acronym{GNU} @command{doschk} program for helping you 10200further diagnosing illegal MSDOS names, which are even more limited 10201than System V's. 10202 10203@node dereference 10204@subsection Symbolic Links 10205@cindex File names, using symbolic links 10206@cindex Symbolic link as file name 10207 10208@opindex dereference 10209Normally, when @command{tar} archives a symbolic link, it writes a 10210block to the archive naming the target of the link. In that way, the 10211@command{tar} archive is a faithful record of the file system contents. 10212When @option{--dereference} (@option{-h}) is used with 10213@option{--create} (@option{-c}), @command{tar} archives the files 10214symbolic links point to, instead of 10215the links themselves. 10216 10217When creating portable archives, use @option{--dereference} 10218(@option{-h}): some systems do not support 10219symbolic links, and moreover, your distribution might be unusable if 10220it contains unresolved symbolic links. 10221 10222When reading from an archive, the @option{--dereference} (@option{-h}) 10223option causes @command{tar} to follow an already-existing symbolic 10224link when @command{tar} writes or reads a file named in the archive. 10225Ordinarily, @command{tar} does not follow such a link, though it may 10226remove the link before writing a new file. @xref{Dealing with Old 10227Files}. 10228 10229The @option{--dereference} option is unsafe if an untrusted user can 10230modify directories while @command{tar} is running. @xref{Security}. 10231 10232@node hard links 10233@subsection Hard Links 10234@cindex File names, using hard links 10235@cindex hard links, dereferencing 10236@cindex dereferencing hard links 10237 10238Normally, when @command{tar} archives a hard link, it writes a 10239block to the archive naming the target of the link (a @samp{1} type 10240block). In that way, the actual file contents is stored in file only 10241once. For example, consider the following two files: 10242 10243@smallexample 10244@group 10245$ ls -l 10246-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one 10247-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden 10248@end group 10249@end smallexample 10250 10251Here, @file{jeden} is a link to @file{one}. When archiving this 10252directory with a verbose level 2, you will get an output similar to 10253the following: 10254 10255@smallexample 10256$ tar cvvf ../archive.tar . 10257drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./ 10258-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden 10259hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden 10260@end smallexample 10261 10262The last line shows that, instead of storing two copies of the file, 10263@command{tar} stored it only once, under the name @file{jeden}, and 10264stored file @file{one} as a hard link to this file. 10265 10266It may be important to know that all hard links to the given file are 10267stored in the archive. For example, this may be necessary for exact 10268reproduction of the file system. The following option does that: 10269 10270@table @option 10271@xopindex{check-links, described} 10272@item --check-links 10273@itemx -l 10274Check the number of links dumped for each processed file. If this 10275number does not match the total number of hard links for the file, print 10276a warning message. 10277@end table 10278 10279For example, trying to archive only file @file{jeden} with this option 10280produces the following diagnostics: 10281 10282@smallexample 10283$ tar -c -f ../archive.tar -l jeden 10284tar: Missing links to 'jeden'. 10285@end smallexample 10286 10287Although creating special records for hard links helps keep a faithful 10288record of the file system contents and makes archives more compact, it 10289may present some difficulties when extracting individual members from 10290the archive. For example, trying to extract file @file{one} from the 10291archive created in previous examples produces, in the absence of file 10292@file{jeden}: 10293 10294@smallexample 10295$ tar xf archive.tar ./one 10296tar: ./one: Cannot hard link to './jeden': No such file or directory 10297tar: Error exit delayed from previous errors 10298@end smallexample 10299 10300The reason for this behavior is that @command{tar} cannot seek back in 10301the archive to the previous member (in this case, @file{one}), to 10302extract it@footnote{There are plans to fix this in future releases.}. 10303If you wish to avoid such problems at the cost of a bigger archive, 10304use the following option: 10305 10306@table @option 10307@xopindex{hard-dereference, described} 10308@item --hard-dereference 10309Dereference hard links and store the files they refer to. 10310@end table 10311 10312For example, trying this option on our two sample files, we get two 10313copies in the archive, each of which can then be extracted 10314independently of the other: 10315 10316@smallexample 10317@group 10318$ tar -c -vv -f ../archive.tar --hard-dereference . 10319drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./ 10320-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden 10321-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one 10322@end group 10323@end smallexample 10324 10325@node old 10326@subsection Old V7 Archives 10327@cindex Format, old style 10328@cindex Old style format 10329@cindex Old style archives 10330@cindex v7 archive format 10331 10332Certain old versions of @command{tar} cannot handle additional 10333information recorded by newer @command{tar} programs. To create an 10334archive in V7 format (not ANSI), which can be read by these old 10335versions, specify the @option{--format=v7} option in 10336conjunction with the @option{--create} (@option{-c}) (@command{tar} also 10337accepts @option{--portability} or @option{--old-archive} for this 10338option). When you specify it, 10339@command{tar} leaves out information about directories, pipes, fifos, 10340contiguous files, and device files, and specifies file ownership by 10341group and user IDs instead of group and user names. 10342 10343When updating an archive, do not use @option{--format=v7} 10344unless the archive was created using this option. 10345 10346In most cases, a @emph{new} format archive can be read by an @emph{old} 10347@command{tar} program without serious trouble, so this option should 10348seldom be needed. On the other hand, most modern @command{tar}s are 10349able to read old format archives, so it might be safer for you to 10350always use @option{--format=v7} for your distributions. Notice, 10351however, that @samp{ustar} format is a better alternative, as it is 10352free from many of @samp{v7}'s drawbacks. 10353 10354@node ustar 10355@subsection Ustar Archive Format 10356 10357@cindex ustar archive format 10358The archive format defined by the @acronym{POSIX}.1-1988 specification is 10359called @code{ustar}. Although it is more flexible than the V7 format, it 10360still has many restrictions (@pxref{Formats,ustar}, for the detailed 10361description of @code{ustar} format). Along with V7 format, 10362@code{ustar} format is a good choice for archives intended to be read 10363with other implementations of @command{tar}. 10364 10365To create an archive in @code{ustar} format, use the @option{--format=ustar} 10366option in conjunction with @option{--create} (@option{-c}). 10367 10368@node gnu 10369@subsection @acronym{GNU} and old @GNUTAR{} format 10370 10371@cindex GNU archive format 10372@cindex Old GNU archive format 10373@GNUTAR{} was based on an early draft of the 10374@acronym{POSIX} 1003.1 @code{ustar} standard. @acronym{GNU} extensions to 10375@command{tar}, such as the support for file names longer than 100 10376characters, use portions of the @command{tar} header record which were 10377specified in that @acronym{POSIX} draft as unused. Subsequent changes in 10378@acronym{POSIX} have allocated the same parts of the header record for 10379other purposes. As a result, @GNUTAR{} format is 10380incompatible with the current @acronym{POSIX} specification, and with 10381@command{tar} programs that follow it. 10382 10383In the majority of cases, @command{tar} will be configured to create 10384this format by default. This will change in future releases, since 10385we plan to make @samp{POSIX} format the default. 10386 10387To force creation a @GNUTAR{} archive, use option 10388@option{--format=gnu}. 10389 10390@node posix 10391@subsection @GNUTAR{} and @acronym{POSIX} @command{tar} 10392 10393@cindex POSIX archive format 10394@cindex PAX archive format 10395Starting from version 1.14 @GNUTAR{} features full support for 10396@acronym{POSIX.1-2001} archives. 10397 10398A @acronym{POSIX} conformant archive will be created if @command{tar} 10399was given @option{--format=posix} (@option{--format=pax}) option. No 10400special option is required to read and extract from a @acronym{POSIX} 10401archive. 10402 10403@menu 10404* PAX keywords:: Controlling Extended Header Keywords. 10405@end menu 10406 10407@node PAX keywords 10408@subsubsection Controlling Extended Header Keywords 10409 10410@table @option 10411@opindex pax-option 10412@item --pax-option=@var{keyword-list} 10413Handle keywords in @acronym{PAX} extended headers. This option is 10414equivalent to @option{-o} option of the @command{pax} utility. 10415@end table 10416 10417@var{Keyword-list} is a comma-separated 10418list of keyword options, each keyword option taking one of 10419the following forms: 10420 10421@table @code 10422@item delete=@var{pattern} 10423When used with one of archive-creation commands, 10424this option instructs @command{tar} to omit from extended header records 10425that it produces any keywords matching the string @var{pattern}. 10426 10427When used in extract or list mode, this option instructs tar 10428to ignore any keywords matching the given @var{pattern} in the extended 10429header records. In both cases, matching is performed using the pattern 10430matching notation described in @acronym{POSIX 1003.2}, 3.13 10431(@pxref{wildcards}). For example: 10432 10433@smallexample 10434--pax-option delete=security.* 10435@end smallexample 10436 10437would suppress security-related information. 10438 10439@item exthdr.name=@var{string} 10440 10441This keyword allows user control over the name that is written into the 10442ustar header blocks for the extended headers. The name is obtained 10443from @var{string} after making the following substitutions: 10444 10445@multitable @columnfractions .25 .55 10446@headitem Meta-character @tab Replaced By 10447@item %d @tab The directory name of the file, equivalent to the 10448result of the @command{dirname} utility on the translated file name. 10449@item %f @tab The name of the file with the directory information 10450stripped, equivalent to the result of the @command{basename} utility 10451on the translated file name. 10452@item %p @tab The process @acronym{ID} of the @command{tar} process. 10453@item %% @tab A @samp{%} character. 10454@end multitable 10455 10456Any other @samp{%} characters in @var{string} produce undefined 10457results. 10458 10459If no option @samp{exthdr.name=string} is specified, @command{tar} 10460will use the following default value: 10461 10462@smallexample 10463%d/PaxHeaders/%f 10464@end smallexample 10465 10466This default is selected to ensure the reproducibility of the 10467archive. @acronym{POSIX} standard recommends to use 10468@samp{%d/PaxHeaders.%p/%f} instead, which means the two archives 10469created with the same set of options and containing the same set 10470of files will be byte-to-byte different. This default will be used 10471if the environment variable @env{POSIXLY_CORRECT} is set. 10472 10473@item exthdr.mtime=@var{value} 10474 10475This keyword defines the value of the @samp{mtime} field that 10476is written into the ustar header blocks for the extended headers. 10477By default, the @samp{mtime} field is set to the modification time 10478of the archive member described by that extended header (or to the 10479value of the @option{--mtime} option, if supplied). 10480 10481@item globexthdr.name=@var{string} 10482This keyword allows user control over the name that is written into 10483the ustar header blocks for global extended header records. The name 10484is obtained from the contents of @var{string}, after making 10485the following substitutions: 10486 10487@multitable @columnfractions .25 .55 10488@headitem Meta-character @tab Replaced By 10489@item %n @tab An integer that represents the 10490sequence number of the global extended header record in the archive, 10491starting at 1. 10492@item %p @tab The process @acronym{ID} of the @command{tar} process. 10493@item %% @tab A @samp{%} character. 10494@end multitable 10495 10496Any other @samp{%} characters in @var{string} produce undefined results. 10497 10498If no option @samp{globexthdr.name=string} is specified, @command{tar} 10499will use the following default value: 10500 10501@smallexample 10502$TMPDIR/GlobalHead.%n 10503@end smallexample 10504 10505If the environment variable @env{POSIXLY_CORRECT} is set, the 10506following value is used instead: 10507 10508@smallexample 10509$TMPDIR/GlobalHead.%p.%n 10510@end smallexample 10511 10512In both cases, @samp{$TMPDIR} stands for the value of the @var{TMPDIR} 10513environment variable. If @var{TMPDIR} is not set, @command{tar} 10514uses @samp{/tmp}. 10515 10516@item globexthdr.mtime=@var{value} 10517 10518This keyword defines the value of the @samp{mtime} field that 10519is written into the ustar header blocks for the global extended headers. 10520By default, the @samp{mtime} field is set to the time when 10521@command{tar} was invoked. 10522 10523@item @var{keyword}=@var{value} 10524When used with one of archive-creation commands, these keyword/value pairs 10525will be included at the beginning of the archive in a global extended 10526header record. When used with one of archive-reading commands, 10527@command{tar} will behave as if it has encountered these keyword/value 10528pairs at the beginning of the archive in a global extended header 10529record. 10530 10531@item @var{keyword}:=@var{value} 10532When used with one of archive-creation commands, these keyword/value pairs 10533will be included as records at the beginning of an extended header for 10534each file. This is effectively equivalent to @var{keyword}=@var{value} 10535form except that it creates no global extended header records. 10536 10537When used with one of archive-reading commands, @command{tar} will 10538behave as if these keyword/value pairs were included as records at the 10539end of each extended header; thus, they will override any global or 10540file-specific extended header record keywords of the same names. 10541For example, in the command: 10542 10543@smallexample 10544tar --format=posix --create \ 10545 --file archive --pax-option gname:=user . 10546@end smallexample 10547 10548the group name will be forced to a new value for all files 10549stored in the archive. 10550@end table 10551 10552In any of the forms described above, the @var{value} may be 10553a string enclosed in curly braces. In that case, the string 10554between the braces is understood either as a textual time 10555representation, as described in @ref{Date input formats}, or a name of 10556the existing file, starting with @samp{/} or @samp{.}. In the latter 10557case, the modification time of that file is used. 10558 10559For example, to set all modification times to the current date, you 10560use the following option: 10561 10562@smallexample 10563--pax-option='mtime:=@{now@}' 10564@end smallexample 10565 10566Note quoting of the option's argument. 10567 10568@cindex archives, binary equivalent 10569@cindex binary equivalent archives, creating 10570As another example, here is the option that ensures that any two 10571archives created using it, will be binary equivalent if they have the 10572same contents: 10573 10574@smallexample 10575--pax-option=atime:=0 10576@end smallexample 10577 10578@noindent 10579If you extract files from such an archive and recreate the archive 10580from them, you will also need to eliminate changes due to ctime, as 10581shown in examples below: 10582 10583@smallexample 10584--pax-option=atime:=0,ctime:=0 10585@end smallexample 10586 10587@noindent 10588or 10589 10590@smallexample 10591--pax-option=atime:=0,delete=ctime 10592@end smallexample 10593 10594Notice, that if you create an archive in POSIX format (@pxref{posix}) 10595and the environment variable @env{POSIXLY_CORRECT} is set, then the 10596two archives created using the same options on the same set of files 10597will not be byte-to-byte equivalent even with the above option. This 10598is because the posix default for extended header names includes the 10599PID of the tar process, which is different at each run. To produce 10600byte-to-byte equivalent archives in this case, either unset 10601@env{POSIXLY_CORRECT}, or use the following option: 10602 10603@smallexample 10604---pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,ctime:=0 10605@end smallexample 10606 10607@node Checksumming 10608@subsection Checksumming Problems 10609 10610SunOS and HP-UX @command{tar} fail to accept archives created using 10611@GNUTAR{} and containing non-@acronym{ASCII} file names, that 10612is, file names having characters with the eighth bit set, because they 10613use signed checksums, while @GNUTAR{} uses unsigned 10614checksums while creating archives, as per @acronym{POSIX} standards. On 10615reading, @GNUTAR{} computes both checksums and accepts either of them. 10616It is somewhat worrying that a lot of people may go 10617around doing backup of their files using faulty (or at least 10618non-standard) software, not learning about it until it's time to 10619restore their missing files with an incompatible file extractor, or 10620vice versa. 10621 10622@GNUTAR{} computes checksums both ways, and accepts either of them 10623on read, so @acronym{GNU} tar can read Sun tapes even with their 10624wrong checksums. @GNUTAR{} produces the standard 10625checksum, however, raising incompatibilities with Sun. That is to 10626say, @GNUTAR{} has not been modified to 10627@emph{produce} incorrect archives to be read by buggy @command{tar}'s. 10628I've been told that more recent Sun @command{tar} now read standard 10629archives, so maybe Sun did a similar patch, after all? 10630 10631The story seems to be that when Sun first imported @command{tar} 10632sources on their system, they recompiled it without realizing that 10633the checksums were computed differently, because of a change in 10634the default signing of @code{char}'s in their compiler. So they 10635started computing checksums wrongly. When they later realized their 10636mistake, they merely decided to stay compatible with it, and with 10637themselves afterwards. Presumably, but I do not really know, HP-UX 10638has chosen their @command{tar} archives to be compatible with Sun's. 10639The current standards do not favor Sun @command{tar} format. In any 10640case, it now falls on the shoulders of SunOS and HP-UX users to get 10641a @command{tar} able to read the good archives they receive. 10642 10643@node Large or Negative Values 10644@subsection Large or Negative Values 10645@cindex large values 10646@cindex future time stamps 10647@cindex negative time stamps 10648@UNREVISED 10649 10650The above sections suggest to use @samp{oldest possible} archive 10651format if in doubt. However, sometimes it is not possible. If you 10652attempt to archive a file whose metadata cannot be represented using 10653required format, @GNUTAR{} will print error message and ignore such a 10654file. You will than have to switch to a format that is able to 10655handle such values. The format summary table (@pxref{Formats}) will 10656help you to do so. 10657 10658In particular, when trying to archive files larger than 8GB or with 10659timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16 1066012:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and 10661@acronym{POSIX} archive formats. When considering which format to 10662choose, bear in mind that the @acronym{GNU} format uses 10663two's-complement base-256 notation to store values that do not fit 10664into standard @acronym{ustar} range. Such archives can generally be 10665read only by a @GNUTAR{} implementation. Moreover, they sometimes 10666cannot be correctly restored on another hosts even by @GNUTAR{}. For 10667example, using two's complement representation for negative time 10668stamps that assumes a signed 32-bit @code{time_t} generates archives 10669that are not portable to hosts with differing @code{time_t} 10670representations. 10671 10672On the other hand, @acronym{POSIX} archives, generally speaking, can 10673be extracted by any tar implementation that understands older 10674@acronym{ustar} format. The only exception are files larger than 8GB. 10675 10676@FIXME{Describe how @acronym{POSIX} archives are extracted by non 10677POSIX-aware tars.} 10678 10679@node Other Tars 10680@subsection How to Extract GNU-Specific Data Using Other @command{tar} Implementations 10681 10682In previous sections you became acquainted with various quirks 10683necessary to make your archives portable. Sometimes you may need to 10684extract archives containing GNU-specific members using some 10685third-party @command{tar} implementation or an older version of 10686@GNUTAR{}. Of course your best bet is to have @GNUTAR{} installed, 10687but if it is for some reason impossible, this section will explain 10688how to cope without it. 10689 10690When we speak about @dfn{GNU-specific} members we mean two classes of 10691them: members split between the volumes of a multi-volume archive and 10692sparse members. You will be able to always recover such members if 10693the archive is in PAX format. In addition split members can be 10694recovered from archives in old GNU format. The following subsections 10695describe the required procedures in detail. 10696 10697@menu 10698* Split Recovery:: Members Split Between Volumes 10699* Sparse Recovery:: Sparse Members 10700@end menu 10701 10702@node Split Recovery 10703@subsubsection Extracting Members Split Between Volumes 10704 10705@cindex Multi-volume archives, extracting using non-GNU tars 10706If a member is split between several volumes of an old GNU format archive 10707most third party @command{tar} implementation will fail to extract 10708it. To extract it, use @command{tarcat} program (@pxref{Tarcat}). 10709This program is available from 10710@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html, @GNUTAR{} 10711home page}. It concatenates several archive volumes into a single 10712valid archive. For example, if you have three volumes named from 10713@file{vol-1.tar} to @file{vol-3.tar}, you can do the following to 10714extract them using a third-party @command{tar}: 10715 10716@smallexample 10717$ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -} 10718@end smallexample 10719 10720@cindex Multi-volume archives in PAX format, extracting using non-GNU tars 10721You could use this approach for most (although not all) PAX 10722format archives as well. However, extracting split members from a PAX 10723archive is a much easier task, because PAX volumes are constructed in 10724such a way that each part of a split member is extracted to a 10725different file by @command{tar} implementations that are not aware of 10726GNU extensions. More specifically, the very first part retains its 10727original name, and all subsequent parts are named using the pattern: 10728 10729@smallexample 10730%d/GNUFileParts/%f.%n 10731@end smallexample 10732 10733@noindent 10734where symbols preceded by @samp{%} are @dfn{macro characters} that 10735have the following meaning: 10736 10737@multitable @columnfractions .25 .55 10738@headitem Meta-character @tab Replaced By 10739@item %d @tab The directory name of the file, equivalent to the 10740result of the @command{dirname} utility on its full name. 10741@item %f @tab The file name of the file, equivalent to the result 10742of the @command{basename} utility on its full name. 10743@item %p @tab The process @acronym{ID} of the @command{tar} process that 10744created the archive. 10745@item %n @tab Ordinal number of this particular part. 10746@end multitable 10747 10748For example, if the file @file{var/longfile} was split during archive 10749creation between three volumes, then the member names will be: 10750 10751@smallexample 10752var/longfile 10753var/GNUFileParts/longfile.1 10754var/GNUFileParts/longfile.2 10755@end smallexample 10756 10757When you extract your archive using a third-party @command{tar}, these 10758files will be created on your disk, and the only thing you will need 10759to do to restore your file in its original form is concatenate them in 10760the proper order, for example: 10761 10762@smallexample 10763@group 10764$ @kbd{cd var} 10765$ @kbd{cat GNUFileParts/longfile.1 \ 10766 GNUFileParts/longfile.2 >> longfile} 10767$ rm -f GNUFileParts 10768@end group 10769@end smallexample 10770 10771Notice, that if the @command{tar} implementation you use supports PAX 10772format archives, it will probably emit warnings about unknown keywords 10773during extraction. They will look like this: 10774 10775@smallexample 10776@group 10777Tar file too small 10778Unknown extended header keyword 'GNU.volume.filename' ignored. 10779Unknown extended header keyword 'GNU.volume.size' ignored. 10780Unknown extended header keyword 'GNU.volume.offset' ignored. 10781@end group 10782@end smallexample 10783 10784@noindent 10785You can safely ignore these warnings. 10786 10787If your @command{tar} implementation is not PAX-aware, you will get 10788more warnings and more files generated on your disk, e.g.: 10789 10790@smallexample 10791@group 10792$ @kbd{tar xf vol-1.tar} 10793var/PaxHeaders/longfile: Unknown file type 'x', extracted as 10794normal file 10795Unexpected EOF in archive 10796$ @kbd{tar xf vol-2.tar} 10797tmp/GlobalHead.1: Unknown file type 'g', extracted as normal file 10798GNUFileParts/PaxHeaders/sparsefile.1: Unknown file type 10799'x', extracted as normal file 10800@end group 10801@end smallexample 10802 10803Ignore these warnings. The @file{PaxHeaders.*} directories created 10804will contain files with @dfn{extended header keywords} describing the 10805extracted files. You can delete them, unless they describe sparse 10806members. Read further to learn more about them. 10807 10808@node Sparse Recovery 10809@subsubsection Extracting Sparse Members 10810 10811@cindex sparse files, extracting with non-GNU tars 10812Any @command{tar} implementation will be able to extract sparse members from a 10813PAX archive. However, the extracted files will be @dfn{condensed}, 10814i.e., any zero blocks will be removed from them. When we restore such 10815a condensed file to its original form, by adding zero blocks (or 10816@dfn{holes}) back to their original locations, we call this process 10817@dfn{expanding} a compressed sparse file. 10818 10819@pindex xsparse 10820To expand a file, you will need a simple auxiliary program called 10821@command{xsparse}. It is available in source form from 10822@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html, @GNUTAR{} 10823home page}. 10824 10825@cindex sparse files v.1.0, extracting with non-GNU tars 10826Let's begin with archive members in @dfn{sparse format 10827version 1.0}@footnote{@xref{PAX 1}.}, which are the easiest to expand. 10828The condensed file will contain both file map and file data, so no 10829additional data will be needed to restore it. If the original file 10830name was @file{@var{dir}/@var{name}}, then the condensed file will be 10831named @file{@var{dir}/@/GNUSparseFile.@var{n}/@/@var{name}}, where 10832@var{n} is a decimal number@footnote{Technically speaking, @var{n} is a 10833@dfn{process @acronym{ID}} of the @command{tar} process which created the 10834archive (@pxref{PAX keywords}).}. 10835 10836To expand a version 1.0 file, run @command{xsparse} as follows: 10837 10838@smallexample 10839$ @kbd{xsparse @file{cond-file}} 10840@end smallexample 10841 10842@noindent 10843where @file{cond-file} is the name of the condensed file. The utility 10844will deduce the name for the resulting expanded file using the 10845following algorithm: 10846 10847@enumerate 1 10848@item If @file{cond-file} does not contain any directories, 10849@file{../cond-file} will be used; 10850 10851@item If @file{cond-file} has the form 10852@file{@var{dir}/@var{t}/@var{name}}, where both @var{t} and @var{name} 10853are simple names, with no @samp{/} characters in them, the output file 10854name will be @file{@var{dir}/@var{name}}. 10855 10856@item Otherwise, if @file{cond-file} has the form 10857@file{@var{dir}/@var{name}}, the output file name will be 10858@file{@var{name}}. 10859@end enumerate 10860 10861In the unlikely case when this algorithm does not suit your needs, 10862you can explicitly specify output file name as a second argument to 10863the command: 10864 10865@smallexample 10866$ @kbd{xsparse @file{cond-file} @file{out-file}} 10867@end smallexample 10868 10869It is often a good idea to run @command{xsparse} in @dfn{dry run} mode 10870first. In this mode, the command does not actually expand the file, 10871but verbosely lists all actions it would be taking to do so. The dry 10872run mode is enabled by @option{-n} command line argument: 10873 10874@smallexample 10875@group 10876$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile} 10877Reading v.1.0 sparse map 10878Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to 10879'/home/gray/sparsefile' 10880Finished dry run 10881@end group 10882@end smallexample 10883 10884To actually expand the file, you would run: 10885 10886@smallexample 10887$ @kbd{xsparse /home/gray/GNUSparseFile.6058/sparsefile} 10888@end smallexample 10889 10890@noindent 10891The program behaves the same way all UNIX utilities do: it will keep 10892quiet unless it has something important to tell you (e.g. an error 10893condition or something). If you wish it to produce verbose output, 10894similar to that from the dry run mode, use @option{-v} option: 10895 10896@smallexample 10897@group 10898$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile} 10899Reading v.1.0 sparse map 10900Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to 10901'/home/gray/sparsefile' 10902Done 10903@end group 10904@end smallexample 10905 10906Additionally, if your @command{tar} implementation has extracted the 10907@dfn{extended headers} for this file, you can instruct @command{xstar} 10908to use them in order to verify the integrity of the expanded file. 10909The option @option{-x} sets the name of the extended header file to 10910use. Continuing our example: 10911 10912@smallexample 10913@group 10914$ @kbd{xsparse -v -x /home/gray/PaxHeaders/sparsefile \ 10915 /home/gray/GNUSparseFile/sparsefile} 10916Reading extended header file 10917Found variable GNU.sparse.major = 1 10918Found variable GNU.sparse.minor = 0 10919Found variable GNU.sparse.name = sparsefile 10920Found variable GNU.sparse.realsize = 217481216 10921Reading v.1.0 sparse map 10922Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to 10923'/home/gray/sparsefile' 10924Done 10925@end group 10926@end smallexample 10927 10928@anchor{extracting sparse v0x} 10929@cindex sparse files v.0.1, extracting with non-GNU tars 10930@cindex sparse files v.0.0, extracting with non-GNU tars 10931An @dfn{extended header} is a special @command{tar} archive header 10932that precedes an archive member and contains a set of 10933@dfn{variables}, describing the member properties that cannot be 10934stored in the standard @code{ustar} header. While optional for 10935expanding sparse version 1.0 members, the use of extended headers is 10936mandatory when expanding sparse members in older sparse formats: v.0.0 10937and v.0.1 (The sparse formats are described in detail in @ref{Sparse 10938Formats}.) So, for these formats, the question is: how to obtain 10939extended headers from the archive? 10940 10941If you use a @command{tar} implementation that does not support PAX 10942format, extended headers for each member will be extracted as a 10943separate file. If we represent the member name as 10944@file{@var{dir}/@var{name}}, then the extended header file will be 10945named @file{@var{dir}/@/PaxHeaders/@/@var{name}}. 10946 10947Things become more difficult if your @command{tar} implementation 10948does support PAX headers, because in this case you will have to 10949manually extract the headers. We recommend the following algorithm: 10950 10951@enumerate 1 10952@item 10953Consult the documentation of your @command{tar} implementation for an 10954option that prints @dfn{block numbers} along with the archive 10955listing (analogous to @GNUTAR{}'s @option{-R} option). For example, 10956@command{star} has @option{-block-number}. 10957 10958@item 10959Obtain verbose listing using the @samp{block number} option, and 10960find block numbers of the sparse member in question and the member 10961immediately following it. For example, running @command{star} on our 10962archive we obtain: 10963 10964@smallexample 10965@group 10966$ @kbd{star -t -v -block-number -f arc.tar} 10967@dots{} 10968star: Unknown extended header keyword 'GNU.sparse.size' ignored. 10969star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored. 10970star: Unknown extended header keyword 'GNU.sparse.name' ignored. 10971star: Unknown extended header keyword 'GNU.sparse.map' ignored. 10972block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile 10973block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README 10974@dots{} 10975@end group 10976@end smallexample 10977 10978@noindent 10979(as usual, ignore the warnings about unknown keywords.) 10980 10981@item 10982Let @var{size} be the size of the sparse member, @var{Bs} be its block number 10983and @var{Bn} be the block number of the next member. 10984Compute: 10985 10986@smallexample 10987@var{N} = @var{Bs} - @var{Bn} - @var{size}/512 - 2 10988@end smallexample 10989 10990@noindent 10991This number gives the size of the extended header part in tar @dfn{blocks}. 10992In our example, this formula gives: @code{897 - 56 - 425984 / 512 - 2 10993= 7}. 10994 10995@item 10996Use @command{dd} to extract the headers: 10997 10998@smallexample 10999@kbd{dd if=@var{archive} of=@var{hname} bs=512 skip=@var{Bs} count=@var{N}} 11000@end smallexample 11001 11002@noindent 11003where @var{archive} is the archive name, @var{hname} is a name of the 11004file to store the extended header in, @var{Bs} and @var{N} are 11005computed in previous steps. 11006 11007In our example, this command will be 11008 11009@smallexample 11010$ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56 count=7} 11011@end smallexample 11012@end enumerate 11013 11014Finally, you can expand the condensed file, using the obtained header: 11015 11016@smallexample 11017@group 11018$ @kbd{xsparse -v -x xhdr GNUSparseFile.6058/sparsefile} 11019Reading extended header file 11020Found variable GNU.sparse.size = 217481216 11021Found variable GNU.sparse.numblocks = 208 11022Found variable GNU.sparse.name = sparsefile 11023Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{} 11024Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile' 11025Done 11026@end group 11027@end smallexample 11028 11029@node cpio 11030@section Comparison of @command{tar} and @command{cpio} 11031@UNREVISED 11032 11033@FIXME{Reorganize the following material} 11034 11035The @command{cpio} archive formats, like @command{tar}, do have maximum 11036file name lengths. The binary and old @acronym{ASCII} formats have a maximum file 11037length of 256, and the new @acronym{ASCII} and @acronym{CRC ASCII} formats have a max 11038file length of 1024. @acronym{GNU} @command{cpio} can read and write archives 11039with arbitrary file name lengths, but other @command{cpio} implementations 11040may crash unexplainedly trying to read them. 11041 11042@command{tar} handles symbolic links in the form in which it comes in @acronym{BSD}; 11043@command{cpio} doesn't handle symbolic links in the form in which it comes 11044in System V prior to SVR4, and some vendors may have added symlinks 11045to their system without enhancing @command{cpio} to know about them. 11046Others may have enhanced it in a way other than the way I did it 11047at Sun, and which was adopted by AT&T (and which is, I think, also 11048present in the @command{cpio} that Berkeley picked up from AT&T and put 11049into a later @acronym{BSD} release---I think I gave them my changes). 11050 11051(SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio} 11052can handle @command{tar} format input, and write it on output, and it 11053probably handles symbolic links. They may not have bothered doing 11054anything to enhance @command{tar} as a result.) 11055 11056@command{cpio} handles special files; traditional @command{tar} doesn't. 11057 11058@command{tar} comes with V7, System III, System V, and @acronym{BSD} source; 11059@command{cpio} comes only with System III, System V, and later @acronym{BSD} 11060(4.3-tahoe and later). 11061 11062@command{tar}'s way of handling multiple hard links to a file can handle 11063file systems that support 32-bit i-numbers (e.g., the @acronym{BSD} file system); 11064@command{cpio}s way requires you to play some games (in its ``binary'' 11065format, i-numbers are only 16 bits, and in its ``portable @acronym{ASCII}'' format, 11066they're 18 bits---it would have to play games with the "file system @acronym{ID}" 11067field of the header to make sure that the file system @acronym{ID}/i-number pairs 11068of different files were always different), and I don't know which 11069@command{cpio}s, if any, play those games. Those that don't might get 11070confused and think two files are the same file when they're not, and 11071make hard links between them. 11072 11073@command{tar}s way of handling multiple hard links to a file places only 11074one copy of the link on the tape, but the name attached to that copy 11075is the @emph{only} one you can use to retrieve the file; @command{cpio}s 11076way puts one copy for every link, but you can retrieve it using any 11077of the names. 11078 11079@quotation 11080What type of check sum (if any) is used, and how is this calculated. 11081@end quotation 11082 11083See the attached manual pages for @command{tar} and @command{cpio} format. 11084@command{tar} uses a checksum which is the sum of all the bytes in the 11085@command{tar} header for a file; @command{cpio} uses no checksum. 11086 11087@quotation 11088If anyone knows why @command{cpio} was made when @command{tar} was present 11089at the unix scene, 11090@end quotation 11091 11092It wasn't. @command{cpio} first showed up in PWB/UNIX 1.0; no 11093generally-available version of UNIX had @command{tar} at the time. I don't 11094know whether any version that was generally available @emph{within AT&T} 11095had @command{tar}, or, if so, whether the people within AT&T who did 11096@command{cpio} knew about it. 11097 11098On restore, if there is a corruption on a tape @command{tar} will stop at 11099that point, while @command{cpio} will skip over it and try to restore the 11100rest of the files. 11101 11102The main difference is just in the command syntax and header format. 11103 11104@command{tar} is a little more tape-oriented in that everything is blocked 11105to start on a record boundary. 11106 11107@quotation 11108Is there any differences between the ability to recover crashed 11109archives between the two of them. (Is there any chance of recovering 11110crashed archives at all.) 11111@end quotation 11112 11113Theoretically it should be easier under @command{tar} since the blocking 11114lets you find a header with some variation of @samp{dd skip=@var{nn}}. 11115However, modern @command{cpio}'s and variations have an option to just 11116search for the next file header after an error with a reasonable chance 11117of resyncing. However, lots of tape driver software won't allow you to 11118continue past a media error which should be the only reason for getting 11119out of sync unless a file changed sizes while you were writing the 11120archive. 11121 11122@quotation 11123If anyone knows why @command{cpio} was made when @command{tar} was present 11124at the unix scene, please tell me about this too. 11125@end quotation 11126 11127Probably because it is more media efficient (by not blocking everything 11128and using only the space needed for the headers where @command{tar} 11129always uses 512 bytes per file header) and it knows how to archive 11130special files. 11131 11132You might want to look at the freely available alternatives. The 11133major ones are @command{afio}, @GNUTAR{}, and 11134@command{pax}, each of which have their own extensions with some 11135backwards compatibility. 11136 11137Sparse files were @command{tar}red as sparse files (which you can 11138easily test, because the resulting archive gets smaller, and 11139@acronym{GNU} @command{cpio} can no longer read it). 11140 11141@node Media 11142@chapter Tapes and Other Archive Media 11143@UNREVISED 11144 11145A few special cases about tape handling warrant more detailed 11146description. These special cases are discussed below. 11147 11148Many complexities surround the use of @command{tar} on tape drives. Since 11149the creation and manipulation of archives located on magnetic tape was 11150the original purpose of @command{tar}, it contains many features making 11151such manipulation easier. 11152 11153Archives are usually written on dismountable media---tape cartridges, 11154mag tapes, or floppy disks. 11155 11156The amount of data a tape or disk holds depends not only on its size, 11157but also on how it is formatted. A 2400 foot long reel of mag tape 11158holds 40 megabytes of data when formatted at 1600 bits per inch. The 11159physically smaller EXABYTE tape cartridge holds 2.3 gigabytes. 11160 11161Magnetic media are re-usable---once the archive on a tape is no longer 11162needed, the archive can be erased and the tape or disk used over. 11163Media quality does deteriorate with use, however. Most tapes or disks 11164should be discarded when they begin to produce data errors. EXABYTE 11165tape cartridges should be discarded when they generate an @dfn{error 11166count} (number of non-usable bits) of more than 10k. 11167 11168Magnetic media are written and erased using magnetic fields, and 11169should be protected from such fields to avoid damage to stored data. 11170Sticking a floppy disk to a filing cabinet using a magnet is probably 11171not a good idea. 11172 11173@menu 11174* Device:: Device selection and switching 11175* Remote Tape Server:: 11176* Common Problems and Solutions:: 11177* Blocking:: Blocking 11178* Many:: Many archives on one tape 11179* Using Multiple Tapes:: Using Multiple Tapes 11180* label:: Including a Label in the Archive 11181* verify:: 11182* Write Protection:: 11183@end menu 11184 11185@node Device 11186@section Device Selection and Switching 11187@UNREVISED 11188 11189@table @option 11190@item -f [@var{hostname}:]@var{file} 11191@itemx --file=[@var{hostname}:]@var{file} 11192Use archive file or device @var{file} on @var{hostname}. 11193@end table 11194 11195This option is used to specify the file name of the archive @command{tar} 11196works on. 11197 11198If the file name is @samp{-}, @command{tar} reads the archive from standard 11199input (when listing or extracting), or writes it to standard output 11200(when creating). If the @samp{-} file name is given when updating an 11201archive, @command{tar} will read the original archive from its standard 11202input, and will write the entire new archive to its standard output. 11203 11204If the file name contains a @samp{:}, it is interpreted as 11205@samp{hostname:file name}. If the @var{hostname} contains an @dfn{at} 11206sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}. In 11207either case, @command{tar} will invoke the command @command{rsh} (or 11208@command{remsh}) to start up an @command{/usr/libexec/rmt} on the remote 11209machine. If you give an alternate login name, it will be given to the 11210@command{rsh}. 11211Naturally, the remote machine must have an executable 11212@command{/usr/libexec/rmt}. This program is free software from the 11213University of California, and a copy of the source code can be found 11214with the sources for @command{tar}; it's compiled and installed by default. 11215The exact path to this utility is determined when configuring the package. 11216It is @file{@var{prefix}/libexec/rmt}, where @var{prefix} stands for 11217your installation prefix. This location may also be overridden at 11218runtime by using the @option{--rmt-command=@var{command}} option (@xref{Option Summary, 11219---rmt-command}, for detailed description of this option. @xref{Remote 11220Tape Server}, for the description of @command{rmt} command). 11221 11222If this option is not given, but the environment variable @env{TAPE} 11223is set, its value is used; otherwise, old versions of @command{tar} 11224used a default archive name (which was picked when @command{tar} was 11225compiled). The default is normally set up to be the @dfn{first} tape 11226drive or other transportable I/O medium on the system. 11227 11228Starting with version 1.11.5, @GNUTAR{} uses 11229standard input and standard output as the default device, and I will 11230not try anymore supporting automatic device detection at installation 11231time. This was failing really in too many cases, it was hopeless. 11232This is now completely left to the installer to override standard 11233input and standard output for default device, if this seems 11234preferable. Further, I think @emph{most} actual usages of 11235@command{tar} are done with pipes or disks, not really tapes, 11236cartridges or diskettes. 11237 11238Some users think that using standard input and output is running 11239after trouble. This could lead to a nasty surprise on your screen if 11240you forget to specify an output file name---especially if you are going 11241through a network or terminal server capable of buffering large amounts 11242of output. We had so many bug reports in that area of configuring 11243default tapes automatically, and so many contradicting requests, that 11244we finally consider the problem to be portably intractable. We could 11245of course use something like @samp{/dev/tape} as a default, but this 11246is @emph{also} running after various kind of trouble, going from hung 11247processes to accidental destruction of real tapes. After having seen 11248all this mess, using standard input and output as a default really 11249sounds like the only clean choice left, and a very useful one too. 11250 11251@GNUTAR{} reads and writes archive in records, I 11252suspect this is the main reason why block devices are preferred over 11253character devices. Most probably, block devices are more efficient 11254too. The installer could also check for @samp{DEFTAPE} in 11255@file{<sys/mtio.h>}. 11256 11257@table @option 11258@xopindex{force-local, short description} 11259@item --force-local 11260Archive file is local even if it contains a colon. 11261 11262@opindex rsh-command 11263@item --rsh-command=@var{command} 11264Use remote @var{command} instead of @command{rsh}. This option exists 11265so that people who use something other than the standard @command{rsh} 11266(e.g., a Kerberized @command{rsh}) can access a remote device. 11267 11268When this command is not used, the shell command found when 11269the @command{tar} program was installed is used instead. This is 11270the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh}, 11271@file{/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}. 11272The installer may have overridden this by defining the environment 11273variable @env{RSH} @emph{at installation time}. 11274 11275@item -[0-7][lmh] 11276Specify drive and density. 11277 11278@xopindex{multi-volume, short description} 11279@item -M 11280@itemx --multi-volume 11281Create/list/extract multi-volume archive. 11282 11283This option causes @command{tar} to write a @dfn{multi-volume} archive---one 11284that may be larger than will fit on the medium used to hold it. 11285@xref{Multi-Volume Archives}. 11286 11287@xopindex{tape-length, short description} 11288@item -L @var{num} 11289@itemx --tape-length=@var{size}[@var{suf}] 11290Change tape after writing @var{size} units of data. Unless @var{suf} is 11291given, @var{size} is treated as kilobytes, i.e. @samp{@var{size} x 112921024} bytes. The following suffixes alter this behavior: 11293 11294@float Table, size-suffixes 11295@caption{Size Suffixes} 11296@multitable @columnfractions 0.2 0.3 0.3 11297@headitem Suffix @tab Units @tab Byte Equivalent 11298@item b @tab Blocks @tab @var{size} x 512 11299@item B @tab Kilobytes @tab @var{size} x 1024 11300@item c @tab Bytes @tab @var{size} 11301@item G @tab Gigabytes @tab @var{size} x 1024^3 11302@item K @tab Kilobytes @tab @var{size} x 1024 11303@item k @tab Kilobytes @tab @var{size} x 1024 11304@item M @tab Megabytes @tab @var{size} x 1024^2 11305@item P @tab Petabytes @tab @var{size} x 1024^5 11306@item T @tab Terabytes @tab @var{size} x 1024^4 11307@item w @tab Words @tab @var{size} x 2 11308@end multitable 11309@end float 11310 11311This option might be useful when your tape drivers do not properly 11312detect end of physical tapes. By being slightly conservative on the 11313maximum tape length, you might avoid the problem entirely. 11314 11315@xopindex{info-script, short description} 11316@xopindex{new-volume-script, short description} 11317@item -F @var{command} 11318@itemx --info-script=@var{command} 11319@itemx --new-volume-script=@var{command} 11320Execute @var{command} at end of each tape. This implies 11321@option{--multi-volume} (@option{-M}). @xref{info-script}, for a detailed 11322description of this option. 11323@end table 11324 11325@node Remote Tape Server 11326@section Remote Tape Server 11327 11328@cindex remote tape drive 11329@pindex rmt 11330In order to access the tape drive on a remote machine, @command{tar} 11331uses the remote tape server written at the University of California at 11332Berkeley. The remote tape server must be installed as 11333@file{@var{prefix}/libexec/rmt} on any machine whose tape drive you 11334want to use. @command{tar} calls @command{rmt} by running an 11335@command{rsh} or @command{remsh} to the remote machine, optionally 11336using a different login name if one is supplied. 11337 11338A copy of the source for the remote tape server is provided. Its 11339source code can be freely distributed. It is compiled and 11340installed by default. 11341 11342@cindex absolute file names 11343Unless you use the @option{--absolute-names} (@option{-P}) option, 11344@GNUTAR{} will not allow you to create an archive that contains 11345absolute file names (a file name beginning with @samp{/}). If you try, 11346@command{tar} will automatically remove the leading @samp{/} from the 11347file names it stores in the archive. It will also type a warning 11348message telling you what it is doing. 11349 11350When reading an archive that was created with a different 11351@command{tar} program, @GNUTAR{} automatically 11352extracts entries in the archive which have absolute file names as if 11353the file names were not absolute. This is an important feature. A 11354visitor here once gave a @command{tar} tape to an operator to restore; 11355the operator used Sun @command{tar} instead of @GNUTAR{}, 11356and the result was that it replaced large portions of 11357our @file{/bin} and friends with versions from the tape; needless to 11358say, we were unhappy about having to recover the file system from 11359backup tapes. 11360 11361For example, if the archive contained a file @file{/usr/bin/computoy}, 11362@GNUTAR{} would extract the file to @file{usr/bin/computoy}, 11363relative to the current directory. If you want to extract the files in 11364an archive to the same absolute names that they had when the archive 11365was created, you should do a @samp{cd /} before extracting the files 11366from the archive, or you should either use the @option{--absolute-names} 11367option, or use the command @samp{tar -C / @dots{}}. 11368 11369@cindex Ultrix 3.1 and write failure 11370Some versions of Unix (Ultrix 3.1 is known to have this problem), 11371can claim that a short write near the end of a tape succeeded, 11372when it actually failed. This will result in the -M option not 11373working correctly. The best workaround at the moment is to use a 11374significantly larger blocking factor than the default 20. 11375 11376In order to update an archive, @command{tar} must be able to backspace the 11377archive in order to reread or rewrite a record that was just read (or 11378written). This is currently possible only on two kinds of files: normal 11379disk files (or any other file that can be backspaced with @samp{lseek}), 11380and industry-standard 9-track magnetic tape (or any other kind of tape 11381that can be backspaced with the @code{MTIOCTOP} @code{ioctl}). 11382 11383This means that the @option{--append}, @option{--concatenate}, and 11384@option{--delete} commands will not work on any other kind of file. 11385Some media simply cannot be backspaced, which means these commands and 11386options will never be able to work on them. These non-backspacing 11387media include pipes and cartridge tape drives. 11388 11389Some other media can be backspaced, and @command{tar} will work on them 11390once @command{tar} is modified to do so. 11391 11392Archives created with the @option{--multi-volume}, @option{--label}, and 11393@option{--incremental} (@option{-G}) options may not be readable by other version 11394of @command{tar}. In particular, restoring a file that was split over 11395a volume boundary will require some careful work with @command{dd}, if 11396it can be done at all. Other versions of @command{tar} may also create 11397an empty file whose name is that of the volume header. Some versions 11398of @command{tar} may create normal files instead of directories archived 11399with the @option{--incremental} (@option{-G}) option. 11400 11401@node Common Problems and Solutions 11402@section Some Common Problems and their Solutions 11403 11404@ifclear PUBLISH 11405 11406@format 11407errors from system: 11408permission denied 11409no such file or directory 11410not owner 11411 11412errors from @command{tar}: 11413directory checksum error 11414header format error 11415 11416errors from media/system: 11417i/o error 11418device busy 11419@end format 11420 11421@end ifclear 11422 11423@node Blocking 11424@section Blocking 11425@cindex block 11426@cindex record 11427 11428@dfn{Block} and @dfn{record} terminology is rather confused, and it 11429is also confusing to the expert reader. On the other hand, readers 11430who are new to the field have a fresh mind, and they may safely skip 11431the next two paragraphs, as the remainder of this manual uses those 11432two terms in a quite consistent way. 11433 11434John Gilmore, the writer of the public domain @command{tar} from which 11435@GNUTAR{} was originally derived, wrote (June 1995): 11436 11437@quotation 11438The nomenclature of tape drives comes from IBM, where I believe 11439they were invented for the IBM 650 or so. On IBM mainframes, what 11440is recorded on tape are tape blocks. The logical organization of 11441data is into records. There are various ways of putting records into 11442blocks, including @code{F} (fixed sized records), @code{V} (variable 11443sized records), @code{FB} (fixed blocked: fixed size records, @var{n} 11444to a block), @code{VB} (variable size records, @var{n} to a block), 11445@code{VSB} (variable spanned blocked: variable sized records that can 11446occupy more than one block), etc. The @code{JCL} @samp{DD RECFORM=} 11447parameter specified this to the operating system. 11448 11449The Unix man page on @command{tar} was totally confused about this. 11450When I wrote @code{PD TAR}, I used the historically correct terminology 11451(@command{tar} writes data records, which are grouped into blocks). 11452It appears that the bogus terminology made it into @acronym{POSIX} (no surprise 11453here), and now Fran@,{c}ois has migrated that terminology back 11454into the source code too. 11455@end quotation 11456 11457The term @dfn{physical block} means the basic transfer chunk from or 11458to a device, after which reading or writing may stop without anything 11459being lost. In this manual, the term @dfn{block} usually refers to 11460a disk physical block, @emph{assuming} that each disk block is 512 11461bytes in length. It is true that some disk devices have different 11462physical blocks, but @command{tar} ignore these differences in its own 11463format, which is meant to be portable, so a @command{tar} block is always 11464512 bytes in length, and @dfn{block} always mean a @command{tar} block. 11465The term @dfn{logical block} often represents the basic chunk of 11466allocation of many disk blocks as a single entity, which the operating 11467system treats somewhat atomically; this concept is only barely used 11468in @GNUTAR{}. 11469 11470The term @dfn{physical record} is another way to speak of a physical 11471block, those two terms are somewhat interchangeable. In this manual, 11472the term @dfn{record} usually refers to a tape physical block, 11473@emph{assuming} that the @command{tar} archive is kept on magnetic tape. 11474It is true that archives may be put on disk or used with pipes, 11475but nevertheless, @command{tar} tries to read and write the archive one 11476@dfn{record} at a time, whatever the medium in use. One record is made 11477up of an integral number of blocks, and this operation of putting many 11478disk blocks into a single tape block is called @dfn{reblocking}, or 11479more simply, @dfn{blocking}. The term @dfn{logical record} refers to 11480the logical organization of many characters into something meaningful 11481to the application. The term @dfn{unit record} describes a small set 11482of characters which are transmitted whole to or by the application, 11483and often refers to a line of text. Those two last terms are unrelated 11484to what we call a @dfn{record} in @GNUTAR{}. 11485 11486When writing to tapes, @command{tar} writes the contents of the archive 11487in chunks known as @dfn{records}. To change the default blocking 11488factor, use the @option{--blocking-factor=@var{512-size}} (@option{-b 11489@var{512-size}}) option. Each record will then be composed of 11490@var{512-size} blocks. (Each @command{tar} block is 512 bytes. 11491@xref{Standard}.) Each file written to the archive uses at least one 11492full record. As a result, using a larger record size can result in 11493more wasted space for small files. On the other hand, a larger record 11494size can often be read and written much more efficiently. 11495 11496Further complicating the problem is that some tape drives ignore the 11497blocking entirely. For these, a larger record size can still improve 11498performance (because the software layers above the tape drive still 11499honor the blocking), but not as dramatically as on tape drives that 11500honor blocking. 11501 11502When reading an archive, @command{tar} can usually figure out the 11503record size on itself. When this is the case, and a non-standard 11504record size was used when the archive was created, @command{tar} will 11505print a message about a non-standard blocking factor, and then operate 11506normally@footnote{If this message is not needed, you can turn it off 11507using the @option{--warning=no-record-size} option.}. On some tape 11508devices, however, @command{tar} cannot figure out the record size 11509itself. On most of those, you can specify a blocking factor (with 11510@option{--blocking-factor}) larger than the actual blocking factor, 11511and then use the @option{--read-full-records} (@option{-B}) option. 11512(If you specify a blocking factor with @option{--blocking-factor} and 11513don't use the @option{--read-full-records} option, then @command{tar} 11514will not attempt to figure out the recording size itself.) On some 11515devices, you must always specify the record size exactly with 11516@option{--blocking-factor} when reading, because @command{tar} cannot 11517figure it out. In any case, use @option{--list} (@option{-t}) before 11518doing any extractions to see whether @command{tar} is reading the archive 11519correctly. 11520 11521@command{tar} blocks are all fixed size (512 bytes), and its scheme for 11522putting them into records is to put a whole number of them (one or 11523more) into each record. @command{tar} records are all the same size; 11524at the end of the file there's a block containing all zeros, which 11525is how you tell that the remainder of the last record(s) are garbage. 11526 11527In a standard @command{tar} file (no options), the block size is 512 11528and the record size is 10240, for a blocking factor of 20. What the 11529@option{--blocking-factor} option does is sets the blocking factor, 11530changing the record size while leaving the block size at 512 bytes. 1153120 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives; 11532most tape drives these days prefer much bigger records in order to 11533stream and not waste tape. When writing tapes for myself, some tend 11534to use a factor of the order of 2048, say, giving a record size of 11535around one megabyte. 11536 11537If you use a blocking factor larger than 20, older @command{tar} 11538programs might not be able to read the archive, so we recommend this 11539as a limit to use in practice. @GNUTAR{}, however, 11540will support arbitrarily large record sizes, limited only by the 11541amount of virtual memory or the physical characteristics of the tape 11542device. 11543 11544@menu 11545* Format Variations:: Format Variations 11546* Blocking Factor:: The Blocking Factor of an Archive 11547@end menu 11548 11549@node Format Variations 11550@subsection Format Variations 11551@cindex Format Parameters 11552@cindex Format Options 11553@cindex Options, archive format specifying 11554@cindex Options, format specifying 11555@UNREVISED 11556 11557Format parameters specify how an archive is written on the archive 11558media. The best choice of format parameters will vary depending on 11559the type and number of files being archived, and on the media used to 11560store the archive. 11561 11562To specify format parameters when accessing or creating an archive, 11563you can use the options described in the following sections. 11564If you do not specify any format parameters, @command{tar} uses 11565default parameters. You cannot modify a compressed archive. 11566If you create an archive with the @option{--blocking-factor} option 11567specified (@pxref{Blocking Factor}), you must specify that 11568blocking-factor when operating on the archive. @xref{Formats}, for other 11569examples of format parameter considerations. 11570 11571@node Blocking Factor 11572@subsection The Blocking Factor of an Archive 11573@cindex Blocking Factor 11574@cindex Record Size 11575@cindex Number of blocks per record 11576@cindex Number of bytes per record 11577@cindex Bytes per record 11578@cindex Blocks per record 11579@UNREVISED 11580 11581@opindex blocking-factor 11582The data in an archive is grouped into blocks, which are 512 bytes. 11583Blocks are read and written in whole number multiples called 11584@dfn{records}. The number of blocks in a record (i.e., the size of a 11585record in units of 512 bytes) is called the @dfn{blocking factor}. 11586The @option{--blocking-factor=@var{512-size}} (@option{-b 11587@var{512-size}}) option specifies the blocking factor of an archive. 11588The default blocking factor is typically 20 (i.e., 10240 bytes), but 11589can be specified at installation. To find out the blocking factor of 11590an existing archive, use @samp{tar --list --file=@var{archive-name}}. 11591This may not work on some devices. 11592 11593Records are separated by gaps, which waste space on the archive media. 11594If you are archiving on magnetic tape, using a larger blocking factor 11595(and therefore larger records) provides faster throughput and allows you 11596to fit more data on a tape (because there are fewer gaps). If you are 11597archiving on cartridge, a very large blocking factor (say 126 or more) 11598greatly increases performance. A smaller blocking factor, on the other 11599hand, may be useful when archiving small files, to avoid archiving lots 11600of nulls as @command{tar} fills out the archive to the end of the record. 11601In general, the ideal record size depends on the size of the 11602inter-record gaps on the tape you are using, and the average size of the 11603files you are archiving. @xref{create}, for information on 11604writing archives. 11605 11606@FIXME{Need example of using a cartridge with blocking factor=126 or more.} 11607 11608Archives with blocking factors larger than 20 cannot be read 11609by very old versions of @command{tar}, or by some newer versions 11610of @command{tar} running on old machines with small address spaces. 11611With @GNUTAR{}, the blocking factor of an archive is limited 11612only by the maximum record size of the device containing the archive, 11613or by the amount of available virtual memory. 11614 11615Also, on some systems, not using adequate blocking factors, as sometimes 11616imposed by the device drivers, may yield unexpected diagnostics. For 11617example, this has been reported: 11618 11619@smallexample 11620Cannot write to /dev/dlt: Invalid argument 11621@end smallexample 11622 11623@noindent 11624In such cases, it sometimes happen that the @command{tar} bundled by 11625the system is aware of block size idiosyncrasies, while @GNUTAR{} 11626requires an explicit specification for the block size, 11627which it cannot guess. This yields some people to consider 11628@GNUTAR{} is misbehaving, because by comparison, 11629@cite{the bundle @command{tar} works OK}. Adding @w{@kbd{-b 256}}, 11630for example, might resolve the problem. 11631 11632If you use a non-default blocking factor when you create an archive, you 11633must specify the same blocking factor when you modify that archive. Some 11634archive devices will also require you to specify the blocking factor when 11635reading that archive, however this is not typically the case. Usually, you 11636can use @option{--list} (@option{-t}) without specifying a blocking factor---@command{tar} 11637reports a non-default record size and then lists the archive members as 11638it would normally. To extract files from an archive with a non-standard 11639blocking factor (particularly if you're not sure what the blocking factor 11640is), you can usually use the @option{--read-full-records} (@option{-B}) option while 11641specifying a blocking factor larger then the blocking factor of the archive 11642(i.e., @samp{tar --extract --read-full-records --blocking-factor=300}). 11643@xref{list}, for more information on the @option{--list} (@option{-t}) 11644operation. @xref{Reading}, for a more detailed explanation of that option. 11645 11646@table @option 11647@item --blocking-factor=@var{number} 11648@itemx -b @var{number} 11649Specifies the blocking factor of an archive. Can be used with any 11650operation, but is usually not necessary with @option{--list} (@option{-t}). 11651@end table 11652 11653Device blocking 11654 11655@table @option 11656@item -b @var{blocks} 11657@itemx --blocking-factor=@var{blocks} 11658Set record size to @math{@var{blocks}*512} bytes. 11659 11660This option is used to specify a @dfn{blocking factor} for the archive. 11661When reading or writing the archive, @command{tar}, will do reads and writes 11662of the archive in records of @math{@var{block}*512} bytes. This is true 11663even when the archive is compressed. Some devices requires that all 11664write operations be a multiple of a certain size, and so, @command{tar} 11665pads the archive out to the next record boundary. 11666 11667The default blocking factor is set when @command{tar} is compiled, and is 11668typically 20. Blocking factors larger than 20 cannot be read by very 11669old versions of @command{tar}, or by some newer versions of @command{tar} 11670running on old machines with small address spaces. 11671 11672With a magnetic tape, larger records give faster throughput and fit 11673more data on a tape (because there are fewer inter-record gaps). 11674If the archive is in a disk file or a pipe, you may want to specify 11675a smaller blocking factor, since a large one will result in a large 11676number of null bytes at the end of the archive. 11677 11678When writing cartridge or other streaming tapes, a much larger 11679blocking factor (say 126 or more) will greatly increase performance. 11680However, you must specify the same blocking factor when reading or 11681updating the archive. 11682 11683Apparently, Exabyte drives have a physical block size of 8K bytes. 11684If we choose our blocksize as a multiple of 8k bytes, then the problem 11685seems to disappear. Id est, we are using block size of 112 right 11686now, and we haven't had the problem since we switched@dots{} 11687 11688With @GNUTAR{} the blocking factor is limited only 11689by the maximum record size of the device containing the archive, or by 11690the amount of available virtual memory. 11691 11692However, deblocking or reblocking is virtually avoided in a special 11693case which often occurs in practice, but which requires all the 11694following conditions to be simultaneously true: 11695@itemize @bullet 11696@item 11697the archive is subject to a compression option, 11698@item 11699the archive is not handled through standard input or output, nor 11700redirected nor piped, 11701@item 11702the archive is directly handled to a local disk, instead of any special 11703device, 11704@item 11705@option{--blocking-factor} is not explicitly specified on the @command{tar} 11706invocation. 11707@end itemize 11708 11709If the output goes directly to a local disk, and not through 11710stdout, then the last write is not extended to a full record size. 11711Otherwise, reblocking occurs. Here are a few other remarks on this 11712topic: 11713 11714@itemize @bullet 11715 11716@item 11717@command{gzip} will complain about trailing garbage if asked to 11718uncompress a compressed archive on tape, there is an option to turn 11719the message off, but it breaks the regularity of simply having to use 11720@samp{@var{prog} -d} for decompression. It would be nice if gzip was 11721silently ignoring any number of trailing zeros. I'll ask Jean-loup 11722Gailly, by sending a copy of this message to him. 11723 11724@item 11725@command{compress} does not show this problem, but as Jean-loup pointed 11726out to Michael, @samp{compress -d} silently adds garbage after 11727the result of decompression, which tar ignores because it already 11728recognized its end-of-file indicator. So this bug may be safely 11729ignored. 11730 11731@item 11732@samp{gzip -d -q} will be silent about the trailing zeros indeed, 11733but will still return an exit status of 2 which tar reports in turn. 11734@command{tar} might ignore the exit status returned, but I hate doing 11735that, as it weakens the protection @command{tar} offers users against 11736other possible problems at decompression time. If @command{gzip} was 11737silently skipping trailing zeros @emph{and} also avoiding setting the 11738exit status in this innocuous case, that would solve this situation. 11739 11740@item 11741@command{tar} should become more solid at not stopping to read a pipe at 11742the first null block encountered. This inelegantly breaks the pipe. 11743@command{tar} should rather drain the pipe out before exiting itself. 11744@end itemize 11745 11746@xopindex{ignore-zeros, short description} 11747@item -i 11748@itemx --ignore-zeros 11749Ignore blocks of zeros in archive (means EOF). 11750 11751The @option{--ignore-zeros} (@option{-i}) option causes @command{tar} to ignore blocks 11752of zeros in the archive. Normally a block of zeros indicates the 11753end of the archive, but when reading a damaged archive, or one which 11754was created by concatenating several archives together, this option 11755allows @command{tar} to read the entire archive. This option is not on 11756by default because many versions of @command{tar} write garbage after 11757the zeroed blocks. 11758 11759Note that this option causes @command{tar} to read to the end of the 11760archive file, which may sometimes avoid problems when multiple files 11761are stored on a single physical tape. 11762 11763@xopindex{read-full-records, short description} 11764@item -B 11765@itemx --read-full-records 11766Reblock as we read (for reading 4.2@acronym{BSD} pipes). 11767 11768If @option{--read-full-records} is used, @command{tar} 11769will not panic if an attempt to read a record from the archive does 11770not return a full record. Instead, @command{tar} will keep reading 11771until it has obtained a full 11772record. 11773 11774This option is turned on by default when @command{tar} is reading 11775an archive from standard input, or from a remote machine. This is 11776because on @acronym{BSD} Unix systems, a read of a pipe will return however 11777much happens to be in the pipe, even if it is less than @command{tar} 11778requested. If this option was not used, @command{tar} would fail as 11779soon as it read an incomplete record from the pipe. 11780 11781This option is also useful with the commands for updating an archive. 11782 11783@end table 11784 11785Tape blocking 11786 11787@FIXME{Appropriate options should be moved here from elsewhere.} 11788 11789@cindex blocking factor 11790@cindex tape blocking 11791 11792When handling various tapes or cartridges, you have to take care of 11793selecting a proper blocking, that is, the number of disk blocks you 11794put together as a single tape block on the tape, without intervening 11795tape gaps. A @dfn{tape gap} is a small landing area on the tape 11796with no information on it, used for decelerating the tape to a 11797full stop, and for later regaining the reading or writing speed. 11798When the tape driver starts reading a record, the record has to 11799be read whole without stopping, as a tape gap is needed to stop the 11800tape motion without losing information. 11801 11802@cindex Exabyte blocking 11803@cindex DAT blocking 11804Using higher blocking (putting more disk blocks per tape block) will use 11805the tape more efficiently as there will be less tape gaps. But reading 11806such tapes may be more difficult for the system, as more memory will be 11807required to receive at once the whole record. Further, if there is a 11808reading error on a huge record, this is less likely that the system will 11809succeed in recovering the information. So, blocking should not be too 11810low, nor it should be too high. @command{tar} uses by default a blocking of 1181120 for historical reasons, and it does not really matter when reading or 11812writing to disk. Current tape technology would easily accommodate higher 11813blockings. Sun recommends a blocking of 126 for Exabytes and 96 for DATs. 11814We were told that for some DLT drives, the blocking should be a multiple 11815of 4Kb, preferably 64Kb (@w{@kbd{-b 128}}) or 256 for decent performance. 11816Other manufacturers may use different recommendations for the same tapes. 11817This might also depends of the buffering techniques used inside modern 11818tape controllers. Some imposes a minimum blocking, or a maximum blocking. 11819Others request blocking to be some exponent of two. 11820 11821So, there is no fixed rule for blocking. But blocking at read time 11822should ideally be the same as blocking used at write time. At one place 11823I know, with a wide variety of equipment, they found it best to use a 11824blocking of 32 to guarantee that their tapes are fully interchangeable. 11825 11826I was also told that, for recycled tapes, prior erasure (by the same 11827drive unit that will be used to create the archives) sometimes lowers 11828the error rates observed at rewriting time. 11829 11830I might also use @option{--number-blocks} instead of 11831@option{--block-number}, so @option{--block} will then expand to 11832@option{--blocking-factor} unambiguously. 11833 11834@node Many 11835@section Many Archives on One Tape 11836 11837@FIXME{Appropriate options should be moved here from elsewhere.} 11838 11839@findex ntape @r{device} 11840Most tape devices have two entries in the @file{/dev} directory, or 11841entries that come in pairs, which differ only in the minor number for 11842this device. Let's take for example @file{/dev/tape}, which often 11843points to the only or usual tape device of a given system. There might 11844be a corresponding @file{/dev/nrtape} or @file{/dev/ntape}. The simpler 11845name is the @emph{rewinding} version of the device, while the name 11846having @samp{nr} in it is the @emph{no rewinding} version of the same 11847device. 11848 11849A rewinding tape device will bring back the tape to its beginning point 11850automatically when this device is opened or closed. Since @command{tar} 11851opens the archive file before using it and closes it afterwards, this 11852means that a simple: 11853 11854@smallexample 11855$ @kbd{tar cf /dev/tape @var{directory}} 11856@end smallexample 11857 11858@noindent 11859will reposition the tape to its beginning both prior and after saving 11860@var{directory} contents to it, thus erasing prior tape contents and 11861making it so that any subsequent write operation will destroy what has 11862just been saved. 11863 11864@cindex tape positioning 11865So, a rewinding device is normally meant to hold one and only one file. 11866If you want to put more than one @command{tar} archive on a given tape, you 11867will need to avoid using the rewinding version of the tape device. You 11868will also have to pay special attention to tape positioning. Errors in 11869positioning may overwrite the valuable data already on your tape. Many 11870people, burnt by past experiences, will only use rewinding devices and 11871limit themselves to one file per tape, precisely to avoid the risk of 11872such errors. Be fully aware that writing at the wrong position on a 11873tape loses all information past this point and most probably until the 11874end of the tape, and this destroyed information @emph{cannot} be 11875recovered. 11876 11877To save @var{directory-1} as a first archive at the beginning of a 11878tape, and leave that tape ready for a second archive, you should use: 11879 11880@smallexample 11881$ @kbd{mt -f /dev/nrtape rewind} 11882$ @kbd{tar cf /dev/nrtape @var{directory-1}} 11883@end smallexample 11884 11885@cindex tape marks 11886@dfn{Tape marks} are special magnetic patterns written on the tape 11887media, which are later recognizable by the reading hardware. These 11888marks are used after each file, when there are many on a single tape. 11889An empty file (that is to say, two tape marks in a row) signal the 11890logical end of the tape, after which no file exist. Usually, 11891non-rewinding tape device drivers will react to the close request issued 11892by @command{tar} by first writing two tape marks after your archive, and by 11893backspacing over one of these. So, if you remove the tape at that time 11894from the tape drive, it is properly terminated. But if you write 11895another file at the current position, the second tape mark will be 11896erased by the new information, leaving only one tape mark between files. 11897 11898So, you may now save @var{directory-2} as a second archive after the 11899first on the same tape by issuing the command: 11900 11901@smallexample 11902$ @kbd{tar cf /dev/nrtape @var{directory-2}} 11903@end smallexample 11904 11905@noindent 11906and so on for all the archives you want to put on the same tape. 11907 11908Another usual case is that you do not write all the archives the same 11909day, and you need to remove and store the tape between two archive 11910sessions. In general, you must remember how many files are already 11911saved on your tape. Suppose your tape already has 16 files on it, and 11912that you are ready to write the 17th. You have to take care of skipping 11913the first 16 tape marks before saving @var{directory-17}, say, by using 11914these commands: 11915 11916@smallexample 11917$ @kbd{mt -f /dev/nrtape rewind} 11918$ @kbd{mt -f /dev/nrtape fsf 16} 11919$ @kbd{tar cf /dev/nrtape @var{directory-17}} 11920@end smallexample 11921 11922In all the previous examples, we put aside blocking considerations, but 11923you should do the proper things for that as well. @xref{Blocking}. 11924 11925@menu 11926* Tape Positioning:: Tape Positions and Tape Marks 11927* mt:: The @command{mt} Utility 11928@end menu 11929 11930@node Tape Positioning 11931@subsection Tape Positions and Tape Marks 11932@UNREVISED 11933 11934Just as archives can store more than one file from the file system, 11935tapes can store more than one archive file. To keep track of where 11936archive files (or any other type of file stored on tape) begin and 11937end, tape archive devices write magnetic @dfn{tape marks} on the 11938archive media. Tape drives write one tape mark between files, 11939two at the end of all the file entries. 11940 11941If you think of data as a series of records "rrrr"'s, and tape marks as 11942"*"'s, a tape might look like the following: 11943 11944@smallexample 11945rrrr*rrrrrr*rrrrr*rr*rrrrr**------------------------- 11946@end smallexample 11947 11948Tape devices read and write tapes using a read/write @dfn{tape 11949head}---a physical part of the device which can only access one 11950point on the tape at a time. When you use @command{tar} to read or 11951write archive data from a tape device, the device will begin reading 11952or writing from wherever on the tape the tape head happens to be, 11953regardless of which archive or what part of the archive the tape 11954head is on. Before writing an archive, you should make sure that no 11955data on the tape will be overwritten (unless it is no longer needed). 11956Before reading an archive, you should make sure the tape head is at 11957the beginning of the archive you want to read. You can do it manually 11958via @code{mt} utility (@pxref{mt}). The @code{restore} script does 11959that automatically (@pxref{Scripted Restoration}). 11960 11961If you want to add new archive file entries to a tape, you should 11962advance the tape to the end of the existing file entries, backspace 11963over the last tape mark, and write the new archive file. If you were 11964to add two archives to the example above, the tape might look like the 11965following: 11966 11967@smallexample 11968rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- 11969@end smallexample 11970 11971@node mt 11972@subsection The @command{mt} Utility 11973@UNREVISED 11974 11975@FIXME{Is it true that this only works on non-block devices? 11976should explain the difference, (fixed or variable).} 11977@xref{Blocking Factor}. 11978 11979You can use the @command{mt} utility to advance or rewind a tape past a 11980specified number of archive files on the tape. This will allow you 11981to move to the beginning of an archive before extracting or reading 11982it, or to the end of all the archives before writing a new one. 11983@FIXME{Why isn't there an "advance 'til you find two tape marks 11984together"?} 11985 11986The syntax of the @command{mt} command is: 11987 11988@smallexample 11989@kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]} 11990@end smallexample 11991 11992where @var{tapename} is the name of the tape device, @var{number} is 11993the number of times an operation is performed (with a default of one), 11994and @var{operation} is one of the following: 11995 11996@FIXME{is there any use for record operations?} 11997 11998@table @option 11999@item eof 12000@itemx weof 12001Writes @var{number} tape marks at the current position on the tape. 12002 12003@item fsf 12004Moves tape position forward @var{number} files. 12005 12006@item bsf 12007Moves tape position back @var{number} files. 12008 12009@item rewind 12010Rewinds the tape. (Ignores @var{number}.) 12011 12012@item offline 12013@itemx rewoff1 12014Rewinds the tape and takes the tape device off-line. (Ignores @var{number}.) 12015 12016@item status 12017Prints status information about the tape unit. 12018 12019@end table 12020 12021If you don't specify a @var{tapename}, @command{mt} uses the environment 12022variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use 12023the default device specified in your @file{sys/mtio.h} file 12024(@code{DEFTAPE} variable). If this is not defined, the program will 12025display a descriptive error message and exit with code 1. 12026 12027@command{mt} returns a 0 exit status when the operation(s) were 12028successful, 1 if the command was unrecognized, and 2 if an operation 12029failed. 12030 12031@node Using Multiple Tapes 12032@section Using Multiple Tapes 12033 12034Often you might want to write a large archive, one larger than will fit 12035on the actual tape you are using. In such a case, you can run multiple 12036@command{tar} commands, but this can be inconvenient, particularly if you 12037are using options like @option{--exclude=@var{pattern}} or dumping entire file systems. 12038Therefore, @command{tar} provides a special mode for creating 12039multi-volume archives. 12040 12041@dfn{Multi-volume} archive is a single @command{tar} archive, stored 12042on several media volumes of fixed size. Although in this section we will 12043often call @samp{volume} a @dfn{tape}, there is absolutely no 12044requirement for multi-volume archives to be stored on tapes. Instead, 12045they can use whatever media type the user finds convenient, they can 12046even be located on files. 12047 12048When creating a multi-volume archive, @GNUTAR{} continues to fill 12049current volume until it runs out of space, then it switches to 12050next volume (usually the operator is queried to replace the tape on 12051this point), and continues working on the new volume. This operation 12052continues until all requested files are dumped. If @GNUTAR{} detects 12053end of media while dumping a file, such a file is archived in split 12054form. Some very big files can even be split across several volumes. 12055 12056Each volume is itself a valid @GNUTAR{} archive, so it can be read 12057without any special options. Consequently any file member residing 12058entirely on one volume can be extracted or otherwise operated upon 12059without needing the other volume. Sure enough, to extract a split 12060member you would need all volumes its parts reside on. 12061 12062Multi-volume archives suffer from several limitations. In particular, 12063they cannot be compressed. 12064 12065@GNUTAR{} is able to create multi-volume archives of two formats 12066(@pxref{Formats}): @samp{GNU} and @samp{POSIX}. 12067 12068@menu 12069* Multi-Volume Archives:: Archives Longer than One Tape or Disk 12070* Tape Files:: Tape Files 12071* Tarcat:: Concatenate Volumes into a Single Archive 12072 12073@end menu 12074 12075@node Multi-Volume Archives 12076@subsection Archives Longer than One Tape or Disk 12077@cindex Multi-volume archives 12078 12079@opindex multi-volume 12080To create an archive that is larger than will fit on a single unit of 12081the media, use the @option{--multi-volume} (@option{-M}) option in conjunction with 12082the @option{--create} option (@pxref{create}). A @dfn{multi-volume} 12083archive can be manipulated like any other archive (provided the 12084@option{--multi-volume} option is specified), but is stored on more 12085than one tape or file. 12086 12087When you specify @option{--multi-volume}, @command{tar} does not report an 12088error when it comes to the end of an archive volume (when reading), or 12089the end of the media (when writing). Instead, it prompts you to load 12090a new storage volume. If the archive is on a magnetic tape, you 12091should change tapes when you see the prompt; if the archive is on a 12092floppy disk, you should change disks; etc. 12093 12094@table @option 12095@item --multi-volume 12096@itemx -M 12097Creates a multi-volume archive, when used in conjunction with 12098@option{--create} (@option{-c}). To perform any other operation on a multi-volume 12099archive, specify @option{--multi-volume} in conjunction with that 12100operation. 12101For example: 12102 12103@smallexample 12104$ @kbd{tar --create --multi-volume --file=/dev/tape @var{files}} 12105@end smallexample 12106@end table 12107 12108The method @command{tar} uses to detect end of tape is not perfect, and 12109fails on some operating systems or on some devices. If @command{tar} 12110cannot detect the end of the tape itself, you can use 12111@option{--tape-length} option to inform it about the capacity of the 12112tape: 12113 12114@anchor{tape-length} 12115@table @option 12116@opindex tape-length 12117@item --tape-length=@var{size}[@var{suf}] 12118@itemx -L @var{size}[@var{suf}] 12119Set maximum length of a volume. The @var{suf}, if given, specifies 12120units in which @var{size} is expressed, e.g. @samp{2M} mean 2 12121megabytes (@pxref{size-suffixes}, for a list of allowed size 12122suffixes). Without @var{suf}, units of 1024 bytes (kilobyte) are 12123assumed. 12124 12125This option selects @option{--multi-volume} automatically. For example: 12126 12127@smallexample 12128$ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}} 12129@end smallexample 12130 12131@noindent 12132or, which is equivalent: 12133 12134@smallexample 12135$ @kbd{tar --create --tape-length=4G --file=/dev/tape @var{files}} 12136@end smallexample 12137@end table 12138 12139@anchor{change volume prompt} 12140When @GNUTAR{} comes to the end of a storage media, it asks you to 12141change the volume. The built-in prompt for POSIX locale 12142is@footnote{If you run @GNUTAR{} under a different locale, the 12143translation to the locale's language will be used.}: 12144 12145@smallexample 12146Prepare volume #@var{n} for '@var{archive}' and hit return: 12147@end smallexample 12148 12149@noindent 12150where @var{n} is the ordinal number of the volume to be created and 12151@var{archive} is archive file or device name. 12152 12153When prompting for a new tape, @command{tar} accepts any of the following 12154responses: 12155 12156@table @kbd 12157@item ? 12158Request @command{tar} to explain possible responses. 12159@item q 12160Request @command{tar} to exit immediately. 12161@item n @var{file-name} 12162Request @command{tar} to write the next volume on the file @var{file-name}. 12163@item ! 12164Request @command{tar} to run a subshell. This option can be disabled 12165by giving @option{--restrict} command line option to 12166@command{tar}@footnote{@xref{--restrict}, for more information about 12167this option.}. 12168@item y 12169Request @command{tar} to begin writing the next volume. 12170@end table 12171 12172(You should only type @samp{y} after you have changed the tape; 12173otherwise @command{tar} will write over the volume it just finished.) 12174 12175@cindex Volume number file 12176@cindex volno file 12177@anchor{volno-file} 12178@opindex volno-file 12179The volume number used by @command{tar} in its tape-changing prompt 12180can be changed; if you give the 12181@option{--volno-file=@var{file-of-number}} option, then 12182@var{file-of-number} should be an non-existing file to be created, or 12183else, a file already containing a decimal number. That number will be 12184used as the volume number of the first volume written. When 12185@command{tar} is finished, it will rewrite the file with the 12186now-current volume number. (This does not change the volume number 12187written on a tape label, as per @ref{label}, it @emph{only} affects 12188the number used in the prompt.) 12189 12190@cindex End-of-archive info script 12191@cindex Info script 12192@anchor{info-script} 12193@opindex info-script 12194@opindex new-volume-script 12195If you want more elaborate behavior than this, you can write a special 12196@dfn{new volume script}, that will be responsible for changing the 12197volume, and instruct @command{tar} to use it instead of its normal 12198prompting procedure: 12199 12200@table @option 12201@item --info-script=@var{command} 12202@itemx --new-volume-script=@var{command} 12203@itemx -F @var{command} 12204Specify the command to invoke when switching volumes. The @var{command} 12205can be used to eject cassettes, or to broadcast messages such as 12206@samp{Someone please come change my tape} when performing unattended 12207backups. 12208@end table 12209 12210The @var{command} can contain additional options, if such are needed. 12211@xref{external, Running External Commands}, for a detailed discussion 12212of the way @GNUTAR{} runs external commands. It inherits 12213@command{tar}'s shell environment. Additional data is passed to it 12214via the following environment variables: 12215 12216@table @env 12217@vrindex TAR_VERSION, info script environment variable 12218@item TAR_VERSION 12219@GNUTAR{} version number. 12220 12221@vrindex TAR_ARCHIVE, info script environment variable 12222@item TAR_ARCHIVE 12223The name of the archive @command{tar} is processing. 12224 12225@vrindex TAR_BLOCKING_FACTOR, info script environment variable 12226@item TAR_BLOCKING_FACTOR 12227Current blocking factor (@pxref{Blocking}). 12228 12229@vrindex TAR_VOLUME, info script environment variable 12230@item TAR_VOLUME 12231Ordinal number of the volume @command{tar} is about to start. 12232 12233@vrindex TAR_SUBCOMMAND, info script environment variable 12234@item TAR_SUBCOMMAND 12235A short option describing the operation @command{tar} is executing. 12236@xref{Operations}, for a complete list of subcommand options. 12237 12238@vrindex TAR_FORMAT, info script environment variable 12239@item TAR_FORMAT 12240Format of the archive being processed. @xref{Formats}, for a complete 12241list of archive format names. 12242 12243@vrindex TAR_FD, info script environment variable 12244@item TAR_FD 12245File descriptor which can be used to communicate the new volume 12246name to @command{tar}. 12247@end table 12248 12249These variables can be used in the @var{command} itself, provided that 12250they are properly quoted to prevent them from being expanded by the 12251shell that invokes @command{tar}. 12252 12253The volume script can instruct @command{tar} to use new archive name, 12254by writing in to file descriptor @env{$TAR_FD} (see below for an example). 12255 12256If the info script fails, @command{tar} exits; otherwise, it begins 12257writing the next volume. 12258 12259If you want @command{tar} to cycle through a series of files or tape 12260drives, there are three approaches to choose from. First of all, you 12261can give @command{tar} multiple @option{--file} options. In this case 12262the specified files will be used, in sequence, as the successive 12263volumes of the archive. Only when the first one in the sequence needs 12264to be used again will @command{tar} prompt for a tape change (or run 12265the info script). For example, suppose someone has two tape drives on 12266a system named @file{/dev/tape0} and @file{/dev/tape1}. For having 12267@GNUTAR{} to switch to the second drive when it needs to write the 12268second tape, and then back to the first tape, etc., just do either of: 12269 12270@smallexample 12271$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}} 12272$ @kbd{tar -cM -f /dev/tape0 -f /dev/tape1 @var{files}} 12273@end smallexample 12274 12275The second method is to use the @samp{n} response to the tape-change 12276prompt. 12277 12278Finally, the most flexible approach is to use a volume script, that 12279writes new archive name to the file descriptor @env{$TAR_FD}. For example, the 12280following volume script will create a series of archive files, named 12281@file{@var{archive}-@var{vol}}, where @var{archive} is the name of the 12282archive being created (as given by @option{--file} option) and 12283@var{vol} is the ordinal number of the archive being created: 12284 12285@smallexample 12286@group 12287#! /bin/bash 12288# For this script it's advisable to use a shell, such as Bash, 12289# that supports a TAR_FD value greater than 9. 12290 12291echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE. 12292 12293name=`expr $TAR_ARCHIVE : '\(.*\)-.*'` 12294case $TAR_SUBCOMMAND in 12295-c) ;; 12296-d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1 12297 ;; 12298*) exit 1 12299esac 12300 12301echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&$TAR_FD 12302@end group 12303@end smallexample 12304 12305The same script can be used while listing, comparing or extracting 12306from the created archive. For example: 12307 12308@smallexample 12309@group 12310# @r{Create a multi-volume archive:} 12311$ @kbd{tar -c -L1024 -f archive.tar -F new-volume .} 12312# @r{Extract from the created archive:} 12313$ @kbd{tar -x -f archive.tar -F new-volume .} 12314@end group 12315@end smallexample 12316 12317@noindent 12318Notice, that the first command had to use @option{-L} option, since 12319otherwise @GNUTAR{} will end up writing everything to file 12320@file{archive.tar}. 12321 12322You can read each individual volume of a multi-volume archive as if it 12323were an archive by itself. For example, to list the contents of one 12324volume, use @option{--list}, without @option{--multi-volume} specified. 12325To extract an archive member from one volume (assuming it is described 12326that volume), use @option{--extract}, again without 12327@option{--multi-volume}. 12328 12329If an archive member is split across volumes (i.e., its entry begins on 12330one volume of the media and ends on another), you need to specify 12331@option{--multi-volume} to extract it successfully. In this case, you 12332should load the volume where the archive member starts, and use 12333@samp{tar --extract --multi-volume}---@command{tar} will prompt for later 12334volumes as it needs them. @xref{extracting archives}, for more 12335information about extracting archives. 12336 12337Multi-volume archives can be modified like any other archive. To add 12338files to a multi-volume archive, you need to only mount the last 12339volume of the archive media (and new volumes, if needed). For all 12340other operations, you need to use the entire archive. 12341 12342If a multi-volume archive was labeled using 12343@option{--label=@var{archive-label}} (@pxref{label}) when it was 12344created, @command{tar} will not automatically label volumes which are 12345added later. To label subsequent volumes, specify 12346@option{--label=@var{archive-label}} again in conjunction with the 12347@option{--append}, @option{--update} or @option{--concatenate} operation. 12348 12349Notice that multi-volume support is a GNU extension and the archives 12350created in this mode should be read only using @GNUTAR{}. If you 12351absolutely have to process such archives using a third-party @command{tar} 12352implementation, read @ref{Split Recovery}. 12353 12354@node Tape Files 12355@subsection Tape Files 12356@cindex labeling archives 12357@opindex label 12358@UNREVISED 12359 12360To give the archive a name which will be recorded in it, use the 12361@option{--label=@var{volume-label}} (@option{-V @var{volume-label}}) 12362option. This will write a special block identifying 12363@var{volume-label} as the name of the archive to the front of the 12364archive which will be displayed when the archive is listed with 12365@option{--list}. If you are creating a multi-volume archive with 12366@option{--multi-volume} (@pxref{Using Multiple Tapes}), then the 12367volume label will have @samp{Volume @var{nnn}} appended to the name 12368you give, where @var{nnn} is the number of the volume of the archive. 12369If you use the @option{--label=@var{volume-label}} option when 12370reading an archive, it checks to make sure the label on the tape 12371matches the one you gave. @xref{label}. 12372 12373When @command{tar} writes an archive to tape, it creates a single 12374tape file. If multiple archives are written to the same tape, one 12375after the other, they each get written as separate tape files. When 12376extracting, it is necessary to position the tape at the right place 12377before running @command{tar}. To do this, use the @command{mt} command. 12378For more information on the @command{mt} command and on the organization 12379of tapes into a sequence of tape files, see @ref{mt}. 12380 12381People seem to often do: 12382 12383@smallexample 12384@kbd{--label="@var{some-prefix} `date +@var{some-format}`"} 12385@end smallexample 12386 12387or such, for pushing a common date in all volumes or an archive set. 12388 12389@node Tarcat 12390@subsection Concatenate Volumes into a Single Archive 12391 12392@pindex tarcat 12393 Sometimes it is necessary to convert existing @GNUTAR{} multi-volume 12394archive to a single @command{tar} archive. Simply concatenating all 12395volumes into one will not work, since each volume carries an additional 12396information at the beginning. @GNUTAR{} is shipped with the shell 12397script @command{tarcat} designed for this purpose. 12398 12399 The script takes a list of files comprising a multi-volume archive 12400and creates the resulting archive at the standard output. For example: 12401 12402@smallexample 12403@kbd{tarcat vol.1 vol.2 vol.3 | tar tf -} 12404@end smallexample 12405 12406 The script implements a simple heuristics to determine the format of 12407the first volume file and to decide how to process the rest of the 12408files. However, it makes no attempt to verify whether the files are 12409given in order or even if they are valid @command{tar} archives. 12410It uses @command{dd} and does not filter its standard error, so you 12411will usually see lots of spurious messages. 12412 12413@FIXME{The script is not installed. Should we install it?} 12414 12415@node label 12416@section Including a Label in the Archive 12417@cindex Labeling an archive 12418@cindex Labels on the archive media 12419@cindex Labeling multi-volume archives 12420 12421@opindex label 12422 To avoid problems caused by misplaced paper labels on the archive 12423media, you can include a @dfn{label} entry --- an archive member which 12424contains the name of the archive --- in the archive itself. Use the 12425@option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) 12426option@footnote{Until version 1.10, that option was called 12427@option{--volume}, but is not available under that name anymore.} in 12428conjunction with the @option{--create} operation to include a label 12429entry in the archive as it is being created. 12430 12431@table @option 12432@item --label=@var{archive-label} 12433@itemx -V @var{archive-label} 12434Includes an @dfn{archive-label} at the beginning of the archive when 12435the archive is being created, when used in conjunction with the 12436@option{--create} operation. Checks to make sure the archive label 12437matches the one specified (when used in conjunction with any other 12438operation). 12439@end table 12440 12441 If you create an archive using both 12442@option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) 12443and @option{--multi-volume} (@option{-M}), each volume of the archive 12444will have an archive label of the form @samp{@var{archive-label} 12445Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the 12446next, and so on. @xref{Using Multiple Tapes}, for information on 12447creating multiple volume archives. 12448 12449@cindex Volume label, listing 12450@cindex Listing volume label 12451 The volume label will be displayed by @option{--list} along with 12452the file contents. If verbose display is requested, it will also be 12453explicitly marked as in the example below: 12454 12455@smallexample 12456@group 12457$ @kbd{tar --verbose --list --file=iamanarchive} 12458V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header-- 12459-rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename 12460@end group 12461@end smallexample 12462 12463@opindex test-label 12464@anchor{--test-label option} 12465 However, @option{--list} option will cause listing entire 12466contents of the archive, which may be undesirable (for example, if the 12467archive is stored on a tape). You can request checking only the volume 12468label by specifying @option{--test-label} option. This option reads only the 12469first block of an archive, so it can be used with slow storage 12470devices. For example: 12471 12472@smallexample 12473@group 12474$ @kbd{tar --test-label --file=iamanarchive} 12475iamalabel 12476@end group 12477@end smallexample 12478 12479 If @option{--test-label} is used with one or more command line 12480arguments, @command{tar} compares the volume label with each 12481argument. It exits with code 0 if a match is found, and with code 1 12482otherwise@footnote{Note that @GNUTAR{} versions up to 1.23 indicated 12483mismatch with an exit code 2 and printed a spurious diagnostics on 12484stderr.}. No output is displayed, unless you also used the 12485@option{--verbose} option. For example: 12486 12487@smallexample 12488@group 12489$ @kbd{tar --test-label --file=iamanarchive 'iamalabel'} 12490@result{} 0 12491$ @kbd{tar --test-label --file=iamanarchive 'alabel'} 12492@result{} 1 12493@end group 12494@end smallexample 12495 12496 When used with the @option{--verbose} option, @command{tar} 12497prints the actual volume label (if any), and a verbose diagnostics in 12498case of a mismatch: 12499 12500@smallexample 12501@group 12502$ @kbd{tar --test-label --verbose --file=iamanarchive 'iamalabel'} 12503iamalabel 12504@result{} 0 12505$ @kbd{tar --test-label --verbose --file=iamanarchive 'alabel'} 12506iamalabel 12507tar: Archive label mismatch 12508@result{} 1 12509@end group 12510@end smallexample 12511 12512 If you request any operation, other than @option{--create}, along 12513with using @option{--label} option, @command{tar} will first check if 12514the archive label matches the one specified and will refuse to proceed 12515if it does not. Use this as a safety precaution to avoid accidentally 12516overwriting existing archives. For example, if you wish to add files 12517to @file{archive}, presumably labeled with string @samp{My volume}, 12518you will get: 12519 12520@smallexample 12521@group 12522$ @kbd{tar -rf archive --label 'My volume' .} 12523tar: Archive not labeled to match 'My volume' 12524@end group 12525@end smallexample 12526 12527@noindent 12528in case its label does not match. This will work even if 12529@file{archive} is not labeled at all. 12530 12531 Similarly, @command{tar} will refuse to list or extract the 12532archive if its label doesn't match the @var{archive-label} 12533specified. In those cases, @var{archive-label} argument is interpreted 12534as a globbing-style pattern which must match the actual magnetic 12535volume label. @xref{exclude}, for a precise description of how match 12536is attempted@footnote{Previous versions of @command{tar} used full 12537regular expression matching, or before that, only exact string 12538matching, instead of wildcard matchers. We decided for the sake of 12539simplicity to use a uniform matching device through 12540@command{tar}.}. If the switch @option{--multi-volume} (@option{-M}) is being used, 12541the volume label matcher will also suffix @var{archive-label} by 12542@w{@samp{ Volume [1-9]*}} if the initial match fails, before giving 12543up. Since the volume numbering is automatically added in labels at 12544creation time, it sounded logical to equally help the user taking care 12545of it when the archive is being read. 12546 12547 You can also use @option{--label} to get a common information on 12548all tapes of a series. For having this information different in each 12549series created through a single script used on a regular basis, just 12550manage to get some date string as part of the label. For example: 12551 12552@smallexample 12553@group 12554$ @kbd{tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"} 12555$ @kbd{tar --create --file=/dev/tape --multi-volume \ 12556 --label="Daily backup for `date +%Y-%m-%d`"} 12557@end group 12558@end smallexample 12559 12560 Some more notes about volume labels: 12561 12562@itemize @bullet 12563@item Each label has its own date and time, which corresponds 12564to the time when @GNUTAR{} initially attempted to write it, 12565often soon after the operator launches @command{tar} or types the 12566carriage return telling that the next tape is ready. 12567 12568@item Comparing date labels to get an idea of tape throughput is 12569unreliable. It gives correct results only if the delays for rewinding 12570tapes and the operator switching them were negligible, which is 12571usually not the case. 12572@end itemize 12573 12574@node verify 12575@section Verifying Data as It is Stored 12576@cindex Verifying a write operation 12577@cindex Double-checking a write operation 12578 12579@table @option 12580@item -W 12581@itemx --verify 12582@opindex verify, short description 12583Attempt to verify the archive after writing. 12584@end table 12585 12586This option causes @command{tar} to verify the archive after writing it. 12587Each volume is checked after it is written, and any discrepancies 12588are recorded on the standard error output. 12589 12590Verification requires that the archive be on a back-space-able medium. 12591This means pipes, some cartridge tape drives, and some other devices 12592cannot be verified. 12593 12594You can insure the accuracy of an archive by comparing files in the 12595system with archive members. @command{tar} can compare an archive to the 12596file system as the archive is being written, to verify a write 12597operation, or can compare a previously written archive, to insure that 12598it is up to date. 12599 12600@xopindex{verify, using with @option{--create}} 12601@xopindex{create, using with @option{--verify}} 12602To check for discrepancies in an archive immediately after it is 12603written, use the @option{--verify} (@option{-W}) option in conjunction with 12604the @option{--create} operation. When this option is 12605specified, @command{tar} checks archive members against their counterparts 12606in the file system, and reports discrepancies on the standard error. 12607 12608To verify an archive, you must be able to read it from before the end 12609of the last written entry. This option is useful for detecting data 12610errors on some tapes. Archives written to pipes, some cartridge tape 12611drives, and some other devices cannot be verified. 12612 12613One can explicitly compare an already made archive with the file 12614system by using the @option{--compare} (@option{--diff}, @option{-d}) 12615option, instead of using the more automatic @option{--verify} option. 12616@xref{compare}. 12617 12618Note that these two options have a slightly different intent. The 12619@option{--compare} option checks how identical are the logical contents of some 12620archive with what is on your disks, while the @option{--verify} option is 12621really for checking if the physical contents agree and if the recording 12622media itself is of dependable quality. So, for the @option{--verify} 12623operation, @command{tar} tries to defeat all in-memory cache pertaining to 12624the archive, while it lets the speed optimization undisturbed for the 12625@option{--compare} option. If you nevertheless use @option{--compare} for 12626media verification, you may have to defeat the in-memory cache yourself, 12627maybe by opening and reclosing the door latch of your recording unit, 12628forcing some doubt in your operating system about the fact this is really 12629the same volume as the one just written or read. 12630 12631The @option{--verify} option would not be necessary if drivers were indeed 12632able to detect dependably all write failures. This sometimes require many 12633magnetic heads, some able to read after the writes occurred. One would 12634not say that drivers unable to detect all cases are necessarily flawed, 12635as long as programming is concerned. 12636 12637The @option{--verify} (@option{-W}) option will not work in 12638conjunction with the @option{--multi-volume} (@option{-M}) option or 12639the @option{--append} (@option{-r}), @option{--update} (@option{-u}) 12640and @option{--delete} operations. @xref{Operations}, for more 12641information on these operations. 12642 12643Also, since @command{tar} normally strips leading @samp{/} from file 12644names (@pxref{absolute}), a command like @samp{tar --verify -cf 12645/tmp/foo.tar /etc} will work as desired only if the working directory is 12646@file{/}, as @command{tar} uses the archive's relative member names 12647(e.g., @file{etc/motd}) when verifying the archive. 12648 12649@node Write Protection 12650@section Write Protection 12651 12652Almost all tapes and diskettes, and in a few rare cases, even disks can 12653be @dfn{write protected}, to protect data on them from being changed. 12654Once an archive is written, you should write protect the media to prevent 12655the archive from being accidentally overwritten or deleted. (This will 12656protect the archive from being changed with a tape or floppy drive---it 12657will not protect it from magnet fields or other physical hazards.) 12658 12659The write protection device itself is usually an integral part of the 12660physical media, and can be a two position (write enabled/write 12661disabled) switch, a notch which can be popped out or covered, a ring 12662which can be removed from the center of a tape reel, or some other 12663changeable feature. 12664 12665@node Reliability and security 12666@chapter Reliability and Security 12667 12668The @command{tar} command reads and writes files as any other 12669application does, and is subject to the usual caveats about 12670reliability and security. This section contains some commonsense 12671advice on the topic. 12672 12673@menu 12674* Reliability:: 12675* Security:: 12676@end menu 12677 12678@node Reliability 12679@section Reliability 12680 12681Ideally, when @command{tar} is creating an archive, it reads from a 12682file system that is not being modified, and encounters no errors or 12683inconsistencies while reading and writing. If this is the case, the 12684archive should faithfully reflect what was read. Similarly, when 12685extracting from an archive, ideally @command{tar} ideally encounters 12686no errors and the extracted files faithfully reflect what was in the 12687archive. 12688 12689However, when reading or writing real-world file systems, several 12690things can go wrong; these include permissions problems, corruption of 12691data, and race conditions. 12692 12693@menu 12694* Permissions problems:: 12695* Data corruption and repair:: 12696* Race conditions:: 12697@end menu 12698 12699@node Permissions problems 12700@subsection Permissions Problems 12701 12702If @command{tar} encounters errors while reading or writing files, it 12703normally reports an error and exits with nonzero status. The work it 12704does may therefore be incomplete. For example, when creating an 12705archive, if @command{tar} cannot read a file then it cannot copy the 12706file into the archive. 12707 12708@node Data corruption and repair 12709@subsection Data Corruption and Repair 12710 12711If an archive becomes corrupted by an I/O error, this may corrupt the 12712data in an extracted file. Worse, it may corrupt the file's metadata, 12713which may cause later parts of the archive to become misinterpreted. 12714An tar-format archive contains a checksum that most likely will detect 12715errors in the metadata, but it will not detect errors in the data. 12716 12717If data corruption is a concern, you can compute and check your own 12718checksums of an archive by using other programs, such as 12719@command{cksum}. 12720 12721When attempting to recover from a read error or data corruption in an 12722archive, you may need to skip past the questionable data and read the 12723rest of the archive. This requires some expertise in the archive 12724format and in other software tools. 12725 12726@node Race conditions 12727@subsection Race conditions 12728 12729If some other process is modifying the file system while @command{tar} 12730is reading or writing files, the result may well be inconsistent due 12731to race conditions. For example, if another process creates some 12732files in a directory while @command{tar} is creating an archive 12733containing the directory's files, @command{tar} may see some of the 12734files but not others, or it may see a file that is in the process of 12735being created. The resulting archive may not be a snapshot of the 12736file system at any point in time. If an application such as a 12737database system depends on an accurate snapshot, restoring from the 12738@command{tar} archive of a live file system may therefore break that 12739consistency and may break the application. The simplest way to avoid 12740the consistency issues is to avoid making other changes to the file 12741system while tar is reading it or writing it. 12742 12743When creating an archive, several options are available to avoid race 12744conditions. Some hosts have a way of snapshotting a file system, or 12745of temporarily suspending all changes to a file system, by (say) 12746suspending the only virtual machine that can modify a file system; if 12747you use these facilities and have @command{tar -c} read from a 12748snapshot when creating an archive, you can avoid inconsistency 12749problems. More drastically, before starting @command{tar} you could 12750suspend or shut down all processes other than @command{tar} that have 12751access to the file system, or you could unmount the file system and 12752then mount it read-only. 12753 12754When extracting from an archive, one approach to avoid race conditions 12755is to create a directory that no other process can write to, and 12756extract into that. 12757 12758@node Security 12759@section Security 12760 12761In some cases @command{tar} may be used in an adversarial situation, 12762where an untrusted user is attempting to gain information about or 12763modify otherwise-inaccessible files. Dealing with untrusted data 12764(that is, data generated by an untrusted user) typically requires 12765extra care, because even the smallest mistake in the use of 12766@command{tar} is more likely to be exploited by an adversary than by a 12767race condition. 12768 12769@menu 12770* Privacy:: 12771* Integrity:: 12772* Live untrusted data:: 12773* Security rules of thumb:: 12774@end menu 12775 12776@node Privacy 12777@subsection Privacy 12778 12779Standard privacy concerns apply when using @command{tar}. For 12780example, suppose you are archiving your home directory into a file 12781@file{/archive/myhome.tar}. Any secret information in your home 12782directory, such as your SSH secret keys, are copied faithfully into 12783the archive. Therefore, if your home directory contains any file that 12784should not be read by some other user, the archive itself should be 12785not be readable by that user. And even if the archive's data are 12786inaccessible to untrusted users, its metadata (such as size or 12787last-modified date) may reveal some information about your home 12788directory; if the metadata are intended to be private, the archive's 12789parent directory should also be inaccessible to untrusted users. 12790 12791One precaution is to create @file{/archive} so that it is not 12792accessible to any user, unless that user also has permission to access 12793all the files in your home directory. 12794 12795Similarly, when extracting from an archive, take care that the 12796permissions of the extracted files are not more generous than what you 12797want. Even if the archive itself is readable only to you, files 12798extracted from it have their own permissions that may differ. 12799 12800@node Integrity 12801@subsection Integrity 12802 12803When creating archives, take care that they are not writable by a 12804untrusted user; otherwise, that user could modify the archive, and 12805when you later extract from the archive you will get incorrect data. 12806 12807When @command{tar} extracts from an archive, by default it writes into 12808files relative to the working directory. If the archive was generated 12809by an untrusted user, that user therefore can write into any file 12810under the working directory. If the working directory contains a 12811symbolic link to another directory, the untrusted user can also write 12812into any file under the referenced directory. When extracting from an 12813untrusted archive, it is therefore good practice to create an empty 12814directory and run @command{tar} in that directory. 12815 12816When extracting from two or more untrusted archives, each one should 12817be extracted independently, into different empty directories. 12818Otherwise, the first archive could create a symbolic link into an area 12819outside the working directory, and the second one could follow the 12820link and overwrite data that is not under the working directory. For 12821example, when restoring from a series of incremental dumps, the 12822archives should have been created by a trusted process, as otherwise 12823the incremental restores might alter data outside the working 12824directory. 12825 12826If you use the @option{--absolute-names} (@option{-P}) option when 12827extracting, @command{tar} respects any file names in the archive, even 12828file names that begin with @file{/} or contain @file{..}. As this 12829lets the archive overwrite any file in your system that you can write, 12830the @option{--absolute-names} (@option{-P}) option should be used only 12831for trusted archives. 12832 12833Conversely, with the @option{--keep-old-files} (@option{-k}) and 12834@option{--skip-old-files} options, @command{tar} refuses to replace 12835existing files when extracting. The difference between the two 12836options is that the former treats existing files as errors whereas the 12837latter just silently ignores them. 12838 12839Finally, with the @option{--no-overwrite-dir} option, @command{tar} 12840refuses to replace the permissions or ownership of already-existing 12841directories. These options may help when extracting from untrusted 12842archives. 12843 12844@node Live untrusted data 12845@subsection Dealing with Live Untrusted Data 12846 12847Extra care is required when creating from or extracting into a file 12848system that is accessible to untrusted users. For example, superusers 12849who invoke @command{tar} must be wary about its actions being hijacked 12850by an adversary who is reading or writing the file system at the same 12851time that @command{tar} is operating. 12852 12853When creating an archive from a live file system, @command{tar} is 12854vulnerable to denial-of-service attacks. For example, an adversarial 12855user could create the illusion of an indefinitely-deep directory 12856hierarchy @file{d/e/f/g/...} by creating directories one step ahead of 12857@command{tar}, or the illusion of an indefinitely-long file by 12858creating a sparse file but arranging for blocks to be allocated just 12859before @command{tar} reads them. There is no easy way for 12860@command{tar} to distinguish these scenarios from legitimate uses, so 12861you may need to monitor @command{tar}, just as you'd need to monitor 12862any other system service, to detect such attacks. 12863 12864While a superuser is extracting from an archive into a live file 12865system, an untrusted user might replace a directory with a symbolic 12866link, in hopes that @command{tar} will follow the symbolic link and 12867extract data into files that the untrusted user does not have access 12868to. Even if the archive was generated by the superuser, it may 12869contain a file such as @file{d/etc/passwd} that the untrusted user 12870earlier created in order to break in; if the untrusted user replaces 12871the directory @file{d/etc} with a symbolic link to @file{/etc} while 12872@command{tar} is running, @command{tar} will overwrite 12873@file{/etc/passwd}. This attack can be prevented by extracting into a 12874directory that is inaccessible to untrusted users. 12875 12876Similar attacks via symbolic links are also possible when creating an 12877archive, if the untrusted user can modify an ancestor of a top-level 12878argument of @command{tar}. For example, an untrusted user that can 12879modify @file{/home/eve} can hijack a running instance of @samp{tar -cf 12880- /home/eve/Documents/yesterday} by replacing 12881@file{/home/eve/Documents} with a symbolic link to some other 12882location. Attacks like these can be prevented by making sure that 12883untrusted users cannot modify any files that are top-level arguments 12884to @command{tar}, or any ancestor directories of these files. 12885 12886@node Security rules of thumb 12887@subsection Security Rules of Thumb 12888 12889This section briefly summarizes rules of thumb for avoiding security 12890pitfalls. 12891 12892@itemize @bullet 12893 12894@item 12895Protect archives at least as much as you protect any of the files 12896being archived. 12897 12898@item 12899Extract from an untrusted archive only into an otherwise-empty 12900directory. This directory and its parent should be accessible only to 12901trusted users. For example: 12902 12903@example 12904@group 12905$ @kbd{chmod go-rwx .} 12906$ @kbd{mkdir -m go-rwx dir} 12907$ @kbd{cd dir} 12908$ @kbd{tar -xvf /archives/got-it-off-the-net.tar.gz} 12909@end group 12910@end example 12911 12912As a corollary, do not do an incremental restore from an untrusted archive. 12913 12914@item 12915Do not let untrusted users access files extracted from untrusted 12916archives without checking first for problems such as setuid programs. 12917 12918@item 12919Do not let untrusted users modify directories that are ancestors of 12920top-level arguments of @command{tar}. For example, while you are 12921executing @samp{tar -cf /archive/u-home.tar /u/home}, do not let an 12922untrusted user modify @file{/}, @file{/archive}, or @file{/u}. 12923 12924@item 12925Pay attention to the diagnostics and exit status of @command{tar}. 12926 12927@item 12928When archiving live file systems, monitor running instances of 12929@command{tar} to detect denial-of-service attacks. 12930 12931@item 12932Avoid unusual options such as @option{--absolute-names} (@option{-P}), 12933@option{--dereference} (@option{-h}), @option{--overwrite}, 12934@option{--recursive-unlink}, and @option{--remove-files} unless you 12935understand their security implications. 12936 12937@end itemize 12938 12939@node Changes 12940@appendix Changes 12941 12942This appendix lists some important user-visible changes between 12943various versions of @GNUTAR{}. An up-to-date version of this document 12944is available at 12945@uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the 12946@GNUTAR{} documentation page}. 12947 12948@table @asis 12949@item Use of globbing patterns when listing and extracting. 12950 12951Previous versions of GNU tar assumed shell-style globbing when 12952extracting from or listing an archive. For example: 12953 12954@smallexample 12955$ @kbd{tar xf foo.tar '*.c'} 12956@end smallexample 12957 12958would extract all files whose names end in @samp{.c}. This behavior 12959was not documented and was incompatible with traditional tar 12960implementations. Therefore, starting from version 1.15.91, GNU tar 12961no longer uses globbing by default. For example, the above invocation 12962is now interpreted as a request to extract from the archive the file 12963named @file{*.c}. 12964 12965To facilitate transition to the new behavior for those users who got 12966used to the previous incorrect one, @command{tar} will print a warning 12967if it finds out that a requested member was not found in the archive 12968and its name looks like a globbing pattern. For example: 12969 12970@smallexample 12971$ @kbd{tar xf foo.tar '*.c'} 12972tar: Pattern matching characters used in file names. Please, 12973tar: use --wildcards to enable pattern matching, or --no-wildcards to 12974tar: suppress this warning. 12975tar: *.c: Not found in archive 12976tar: Error exit delayed from previous errors 12977@end smallexample 12978 12979To treat member names as globbing patterns, use the @option{--wildcards} option. 12980If you want to tar to mimic the behavior of versions prior to 1.15.91, 12981add this option to your @env{TAR_OPTIONS} variable. 12982 12983@xref{wildcards}, for the detailed discussion of the use of globbing 12984patterns by @GNUTAR{}. 12985 12986@item Use of short option @option{-o}. 12987 12988Earlier versions of @GNUTAR{} understood @option{-o} command line 12989option as a synonym for @option{--old-archive}. 12990 12991@GNUTAR{} starting from version 1.13.90 understands this option as 12992a synonym for @option{--no-same-owner}. This is compatible with 12993UNIX98 @command{tar} implementations. 12994 12995However, to facilitate transition, @option{-o} option retains its 12996old semantics when it is used with one of archive-creation commands. 12997Users are encouraged to use @option{--format=oldgnu} instead. 12998 12999It is especially important, since versions of @acronym{GNU} Automake 13000up to and including 1.8.4 invoke tar with this option to produce 13001distribution tarballs. @xref{Formats,v7}, for the detailed discussion 13002of this issue and its implications. 13003 13004@xref{Options, tar-formats, Changing Automake's Behavior, 13005automake, GNU Automake}, for a description on how to use various 13006archive formats with @command{automake}. 13007 13008Future versions of @GNUTAR{} will understand @option{-o} only as a 13009synonym for @option{--no-same-owner}. 13010 13011@item Use of short option @option{-l} 13012 13013Earlier versions of @GNUTAR{} understood @option{-l} option as a 13014synonym for @option{--one-file-system}. Since such usage contradicted 13015to UNIX98 specification and harmed compatibility with other 13016implementations, it was declared deprecated in version 1.14. However, 13017to facilitate transition to its new semantics, it was supported by 13018versions 1.15 and 1.15.90. The present use of @option{-l} as a short 13019variant of @option{--check-links} was introduced in version 1.15.91. 13020 13021@item Use of options @option{--portability} and @option{--old-archive} 13022 13023These options are deprecated. Please use @option{--format=v7} instead. 13024 13025@item Use of option @option{--posix} 13026 13027This option is deprecated. Please use @option{--format=posix} instead. 13028@end table 13029 13030@node Recipes 13031@appendix Recipes 13032@include recipes.texi 13033 13034@node Configuring Help Summary 13035@appendix Configuring Help Summary 13036 13037Running @kbd{tar --help} displays the short @command{tar} option 13038summary (@pxref{help}). This summary is organized by @dfn{groups} of 13039semantically close options. The options within each group are printed 13040in the following order: a short option, eventually followed by a list 13041of corresponding long option names, followed by a short description of 13042the option. For example, here is an excerpt from the actual @kbd{tar 13043--help} output: 13044 13045@verbatim 13046 Main operation mode: 13047 13048 -A, --catenate, --concatenate append tar files to an archive 13049 -c, --create create a new archive 13050 -d, --diff, --compare find differences between archive and 13051 file system 13052 --delete delete from the archive 13053@end verbatim 13054 13055@vrindex ARGP_HELP_FMT, environment variable 13056The exact visual representation of the help output is configurable via 13057@env{ARGP_HELP_FMT} environment variable. The value of this variable 13058is a comma-separated list of @dfn{format variable} assignments. There 13059are two kinds of format variables. An @dfn{offset variable} keeps the 13060offset of some part of help output text from the leftmost column on 13061the screen. A @dfn{boolean} variable is a flag that toggles some 13062output feature on or off. Depending on the type of the corresponding 13063variable, there are two kinds of assignments: 13064 13065@table @asis 13066@item Offset assignment 13067 13068The assignment to an offset variable has the following syntax: 13069 13070@smallexample 13071@var{variable}=@var{value} 13072@end smallexample 13073 13074@noindent 13075where @var{variable} is the variable name, and @var{value} is a 13076numeric value to be assigned to the variable. 13077 13078@item Boolean assignment 13079 13080To assign @code{true} value to a variable, simply put this variable name. To 13081assign @code{false} value, prefix the variable name with @samp{no-}. For 13082example: 13083 13084@smallexample 13085@group 13086# Assign @code{true} value: 13087dup-args 13088# Assign @code{false} value: 13089no-dup-args 13090@end group 13091@end smallexample 13092@end table 13093 13094Following variables are declared: 13095 13096@deftypevr {Help Output} boolean dup-args 13097If true, arguments for an option are shown with both short and long 13098options, even when a given option has both forms, for example: 13099 13100@smallexample 13101 -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE 13102@end smallexample 13103 13104If false, then if an option has both short and long forms, the 13105argument is only shown with the long one, for example: 13106 13107@smallexample 13108 -f, --file=ARCHIVE use archive file or device ARCHIVE 13109@end smallexample 13110 13111@noindent 13112and a message indicating that the argument is applicable to both 13113forms is printed below the options. This message can be disabled 13114using @code{dup-args-note} (see below). 13115 13116The default is false. 13117@end deftypevr 13118 13119@deftypevr {Help Output} boolean dup-args-note 13120If this variable is true, which is the default, the following notice 13121is displayed at the end of the help output: 13122 13123@quotation 13124Mandatory or optional arguments to long options are also mandatory or 13125optional for any corresponding short options. 13126@end quotation 13127 13128Setting @code{no-dup-args-note} inhibits this message. Normally, only one of 13129variables @code{dup-args} or @code{dup-args-note} should be set. 13130@end deftypevr 13131 13132@deftypevr {Help Output} offset short-opt-col 13133Column in which short options start. Default is 2. 13134 13135@smallexample 13136@group 13137$ @kbd{tar --help|grep ARCHIVE} 13138 -f, --file=ARCHIVE use archive file or device ARCHIVE 13139$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE} 13140 -f, --file=ARCHIVE use archive file or device ARCHIVE 13141@end group 13142@end smallexample 13143@end deftypevr 13144 13145@deftypevr {Help Output} offset long-opt-col 13146Column in which long options start. Default is 6. For example: 13147 13148@smallexample 13149@group 13150$ @kbd{tar --help|grep ARCHIVE} 13151 -f, --file=ARCHIVE use archive file or device ARCHIVE 13152$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE} 13153 -f, --file=ARCHIVE use archive file or device ARCHIVE 13154@end group 13155@end smallexample 13156@end deftypevr 13157 13158@deftypevr {Help Output} offset doc-opt-col 13159Column in which @dfn{doc options} start. A doc option isn't actually 13160an option, but rather an arbitrary piece of documentation that is 13161displayed in much the same manner as the options. For example, in 13162the description of @option{--format} option: 13163 13164@smallexample 13165@group 13166 -H, --format=FORMAT create archive of the given format. 13167 13168 FORMAT is one of the following: 13169 13170 gnu GNU tar 1.13.x format 13171 oldgnu GNU format as per tar <= 1.12 13172 pax POSIX 1003.1-2001 (pax) format 13173 posix same as pax 13174 ustar POSIX 1003.1-1988 (ustar) format 13175 v7 old V7 tar format 13176@end group 13177@end smallexample 13178 13179@noindent 13180the format names are doc options. Thus, if you set 13181@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output 13182will look as follows: 13183 13184@smallexample 13185@group 13186 -H, --format=FORMAT create archive of the given format. 13187 13188 FORMAT is one of the following: 13189 13190 gnu GNU tar 1.13.x format 13191 oldgnu GNU format as per tar <= 1.12 13192 pax POSIX 1003.1-2001 (pax) format 13193 posix same as pax 13194 ustar POSIX 1003.1-1988 (ustar) format 13195 v7 old V7 tar format 13196@end group 13197@end smallexample 13198@end deftypevr 13199 13200@deftypevr {Help Output} offset opt-doc-col 13201Column in which option description starts. Default is 29. 13202 13203@smallexample 13204@group 13205$ @kbd{tar --help|grep ARCHIVE} 13206 -f, --file=ARCHIVE use archive file or device ARCHIVE 13207$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE} 13208 -f, --file=ARCHIVE use archive file or device ARCHIVE 13209$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE} 13210 -f, --file=ARCHIVE 13211 use archive file or device ARCHIVE 13212@end group 13213@end smallexample 13214 13215@noindent 13216Notice, that the description starts on a separate line if 13217@code{opt-doc-col} value is too small. 13218@end deftypevr 13219 13220@deftypevr {Help Output} offset header-col 13221Column in which @dfn{group headers} are printed. A group header is a 13222descriptive text preceding an option group. For example, in the 13223following text: 13224 13225@verbatim 13226 Main operation mode: 13227 13228 -A, --catenate, --concatenate append tar files to 13229 an archive 13230 -c, --create create a new archive 13231@end verbatim 13232@noindent 13233@samp{Main operation mode:} is the group header. 13234 13235The default value is 1. 13236@end deftypevr 13237 13238@deftypevr {Help Output} offset usage-indent 13239Indentation of wrapped usage lines. Affects @option{--usage} 13240output. Default is 12. 13241@end deftypevr 13242 13243@deftypevr {Help Output} offset rmargin 13244Right margin of the text output. Used for wrapping. 13245@end deftypevr 13246 13247@node Fixing Snapshot Files 13248@appendix Fixing Snapshot Files 13249@include tar-snapshot-edit.texi 13250 13251@node Tar Internals 13252@appendix Tar Internals 13253@include intern.texi 13254 13255@node Genfile 13256@appendix Genfile 13257@include genfile.texi 13258 13259@node GNU Free Documentation License 13260@appendix GNU Free Documentation License 13261 13262@include fdl.texi 13263 13264@node Index of Command Line Options 13265@appendix Index of Command Line Options 13266 13267This appendix contains an index of all @GNUTAR{} long command line 13268options. The options are listed without the preceding double-dash. 13269For a cross-reference of short command line options, see 13270@ref{Short Option Summary}. 13271 13272@printindex op 13273 13274@node Index 13275@appendix Index 13276 13277@printindex cp 13278 13279@summarycontents 13280@contents 13281@bye 13282 13283@c Local variables: 13284@c texinfo-column-for-description: 32 13285@c End: 13286