X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=doc%2Ftar.info-1;fp=doc%2Ftar.info-1;h=0000000000000000000000000000000000000000;hb=5c46f61cabb7912f25347b9300d1d585d7a635cb;hp=67f9cf95981fe43fbcf3cfc607c01ba5148f417b;hpb=138fc7e67e3d9845cd7d81aad0e9c7724784f9b9;p=tar diff --git a/doc/tar.info-1 b/doc/tar.info-1 deleted file mode 100644 index 67f9cf9..0000000 --- a/doc/tar.info-1 +++ /dev/null @@ -1,7723 +0,0 @@ -This is tar.info, produced by makeinfo version 4.8.90 from tar.texi. - - This manual is for GNU `tar' (version 1.20, 14 April 2008), which -creates and extracts files from archives. - - Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003, -2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover Texts - being "A GNU Manual," and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - "GNU Free Documentation License". - - (a) The FSF's Back-Cover Text is: "You have the freedom to copy - and modify this GNU manual. Buying copies from the FSF supports - it in developing GNU and promoting software freedom." - -INFO-DIR-SECTION Archiving -START-INFO-DIR-ENTRY -* Tar: (tar). Making tape (or disk) archives. -END-INFO-DIR-ENTRY - -INFO-DIR-SECTION Individual utilities -START-INFO-DIR-ENTRY -* tar: (tar)tar invocation. Invoking GNU `tar'. -END-INFO-DIR-ENTRY - - -File: tar.info, Node: Top, Next: Introduction, Up: (dir) - -GNU tar: an archiver tool -************************* - -This manual is for GNU `tar' (version 1.20, 14 April 2008), which -creates and extracts files from archives. - - Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003, -2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover Texts - being "A GNU Manual," and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - "GNU Free Documentation License". - - (a) The FSF's Back-Cover Text is: "You have the freedom to copy - and modify this GNU manual. Buying copies from the FSF supports - it in developing GNU and promoting software freedom." - - The first part of this master menu lists the major nodes in this Info -document. The rest of the menu lists all the lower level nodes. - -* Menu: - -* Introduction:: -* Tutorial:: -* tar invocation:: -* operations:: -* Backups:: -* Choosing:: -* Date input formats:: -* Formats:: -* Media:: - -Appendices - -* Changes:: -* Configuring Help Summary:: -* Fixing Snapshot Files:: -* Tar Internals:: -* Genfile:: -* Free Software Needs Free Documentation:: -* Copying This Manual:: -* Index of Command Line Options:: -* Index:: - - --- The Detailed Node Listing --- - -Introduction - -* Book Contents:: What this Book Contains -* Definitions:: Some Definitions -* What tar Does:: What `tar' Does -* Naming tar Archives:: How `tar' Archives are Named -* Authors:: GNU `tar' Authors -* Reports:: Reporting bugs or suggestions - -Tutorial Introduction to `tar' - -* assumptions:: -* stylistic conventions:: -* basic tar options:: Basic `tar' Operations and Options -* frequent operations:: -* Two Frequent Options:: -* create:: How to Create Archives -* list:: How to List Archives -* extract:: How to Extract Members from an Archive -* going further:: - -Two Frequently Used Options - -* file tutorial:: -* verbose tutorial:: -* help tutorial:: - -How to Create Archives - -* prepare for examples:: -* Creating the archive:: -* create verbose:: -* short create:: -* create dir:: - -How to List Archives - -* list dir:: - -How to Extract Members from an Archive - -* extracting archives:: -* extracting files:: -* extract dir:: -* extracting untrusted archives:: -* failing commands:: - -Invoking GNU `tar' - -* Synopsis:: -* using tar options:: -* Styles:: -* All Options:: -* help:: -* defaults:: -* verbose:: -* checkpoints:: -* interactive:: - -The Three Option Styles - -* Long Options:: Long Option Style -* Short Options:: Short Option Style -* Old Options:: Old Option Style -* Mixing:: Mixing Option Styles - -All `tar' Options - -* Operation Summary:: -* Option Summary:: -* Short Option Summary:: - -GNU `tar' Operations - -* Basic tar:: -* Advanced tar:: -* create options:: -* extract options:: -* backup:: -* Applications:: -* looking ahead:: - -Advanced GNU `tar' Operations - -* Operations:: -* append:: -* update:: -* concatenate:: -* delete:: -* compare:: - -How to Add Files to Existing Archives: `--append' - -* appending files:: Appending Files to an Archive -* multiple:: - -Updating an Archive - -* how to update:: - -Options Used by `--create' - -* override:: Overriding File Metadata. -* Ignore Failed Read:: - -Options Used by `--extract' - -* Reading:: Options to Help Read Archives -* Writing:: Changing How `tar' Writes Files -* Scarce:: Coping with Scarce Resources - -Options to Help Read Archives - -* read full records:: -* Ignore Zeros:: - -Changing How `tar' Writes Files - -* Dealing with Old Files:: -* Overwrite Old Files:: -* Keep Old Files:: -* Keep Newer Files:: -* Unlink First:: -* Recursive Unlink:: -* Data Modification Times:: -* Setting Access Permissions:: -* Directory Modification Times and Permissions:: -* Writing to Standard Output:: -* Writing to an External Program:: -* remove files:: - -Coping with Scarce Resources - -* Starting File:: -* Same Order:: - -Performing Backups and Restoring Files - -* Full Dumps:: Using `tar' to Perform Full Dumps -* Incremental Dumps:: Using `tar' to Perform Incremental Dumps -* Backup Levels:: Levels of Backups -* Backup Parameters:: Setting Parameters for Backups and Restoration -* Scripted Backups:: Using the Backup Scripts -* Scripted Restoration:: Using the Restore Script - -Setting Parameters for Backups and Restoration - -* General-Purpose Variables:: -* Magnetic Tape Control:: -* User Hooks:: -* backup-specs example:: An Example Text of `Backup-specs' - -Choosing Files and Names for `tar' - -* file:: Choosing the Archive's Name -* Selecting Archive Members:: -* files:: Reading Names from a File -* exclude:: Excluding Some Files -* wildcards:: Wildcards Patterns and Matching -* quoting styles:: Ways of Quoting Special Characters in Names -* transform:: Modifying File and Member Names -* after:: Operating Only on New Files -* recurse:: Descending into Directories -* one:: Crossing File System Boundaries - -Reading Names from a File - -* nul:: - -Excluding Some Files - -* problems with exclude:: - -Wildcards Patterns and Matching - -* controlling pattern-matching:: - -Crossing File System Boundaries - -* directory:: Changing Directory -* absolute:: Absolute File Names - -Date input formats - -* General date syntax:: Common rules. -* Calendar date items:: 19 Dec 1994. -* Time of day items:: 9:20pm. -* Time zone items:: EST, PDT, GMT. -* Day of week items:: Monday and others. -* Relative items in date strings:: next tuesday, 2 years ago. -* Pure numbers in date strings:: 19931219, 1440. -* Seconds since the Epoch:: @1078100502. -* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". -* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al. - -Controlling the Archive Format - -* Compression:: Using Less Space through Compression -* Attributes:: Handling File Attributes -* Portability:: Making `tar' Archives More Portable -* cpio:: Comparison of `tar' and `cpio' - -Using Less Space through Compression - -* gzip:: Creating and Reading Compressed Archives -* sparse:: Archiving Sparse Files - -Making `tar' Archives More Portable - -* Portable Names:: Portable Names -* dereference:: Symbolic Links -* hard links:: Hard Links -* old:: Old V7 Archives -* ustar:: Ustar Archives -* gnu:: GNU and old GNU format archives. -* posix:: POSIX archives -* Checksumming:: Checksumming Problems -* Large or Negative Values:: Large files, negative time stamps, etc. -* Other Tars:: How to Extract GNU-Specific Data Using - Other `tar' Implementations - -GNU `tar' and POSIX `tar' - -* PAX keywords:: Controlling Extended Header Keywords. - -How to Extract GNU-Specific Data Using Other `tar' Implementations - -* Split Recovery:: Members Split Between Volumes -* Sparse Recovery:: Sparse Members - -Tapes and Other Archive Media - -* Device:: Device selection and switching -* Remote Tape Server:: -* Common Problems and Solutions:: -* Blocking:: Blocking -* Many:: Many archives on one tape -* Using Multiple Tapes:: Using Multiple Tapes -* label:: Including a Label in the Archive -* verify:: -* Write Protection:: - -Blocking - -* Format Variations:: Format Variations -* Blocking Factor:: The Blocking Factor of an Archive - -Many Archives on One Tape - -* Tape Positioning:: Tape Positions and Tape Marks -* mt:: The `mt' Utility - -Using Multiple Tapes - -* Multi-Volume Archives:: Archives Longer than One Tape or Disk -* Tape Files:: Tape Files -* Tarcat:: Concatenate Volumes into a Single Archive - - -Tar Internals - -* Standard:: Basic Tar Format -* Extensions:: GNU Extensions to the Archive Format -* Sparse Formats:: Storing Sparse Files -* Snapshot Files:: -* Dumpdir:: - -Storing Sparse Files - -* Old GNU Format:: -* PAX 0:: PAX Format, Versions 0.0 and 0.1 -* PAX 1:: PAX Format, Version 1.0 - -Genfile - -* Generate Mode:: File Generation Mode. -* Status Mode:: File Status Mode. -* Exec Mode:: Synchronous Execution mode. - -Copying This Manual - -* GNU Free Documentation License:: License for copying this manual - - -File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top - -1 Introduction -************** - -GNU `tar' creates and manipulates "archives" which are actually -collections of many other files; the program provides users with an -organized and systematic method for controlling a large amount of data. -The name "tar" originally came from the phrase "Tape ARchive", but -archives need not (and these days, typically do not) reside on tapes. - -* Menu: - -* Book Contents:: What this Book Contains -* Definitions:: Some Definitions -* What tar Does:: What `tar' Does -* Naming tar Archives:: How `tar' Archives are Named -* Authors:: GNU `tar' Authors -* Reports:: Reporting bugs or suggestions - - -File: tar.info, Node: Book Contents, Next: Definitions, Up: Introduction - -1.1 What this Book Contains -=========================== - -The first part of this chapter introduces you to various terms that will -recur throughout the book. It also tells you who has worked on GNU -`tar' and its documentation, and where you should send bug reports or -comments. - - The second chapter is a tutorial (*note Tutorial::) which provides a -gentle introduction for people who are new to using `tar'. It is meant -to be self contained, not requiring any reading from subsequent -chapters to make sense. It moves from topic to topic in a logical, -progressive order, building on information already explained. - - Although the tutorial is paced and structured to allow beginners to -learn how to use `tar', it is not intended solely for beginners. The -tutorial explains how to use the three most frequently used operations -(`create', `list', and `extract') as well as two frequently used -options (`file' and `verbose'). The other chapters do not refer to the -tutorial frequently; however, if a section discusses something which is -a complex variant of a basic concept, there may be a cross reference to -that basic concept. (The entire book, including the tutorial, assumes -that the reader understands some basic concepts of using a Unix-type -operating system; *note Tutorial::.) - - The third chapter presents the remaining five operations, and -information about using `tar' options and option syntax. - - The other chapters are meant to be used as a reference. Each chapter -presents everything that needs to be said about a specific topic. - - One of the chapters (*note Date input formats::) exists in its -entirety in other GNU manuals, and is mostly self-contained. In -addition, one section of this manual (*note Standard::) contains a big -quote which is taken directly from `tar' sources. - - In general, we give both long and short (abbreviated) option names -at least once in each section where the relevant option is covered, so -that novice readers will become familiar with both styles. (A few -options have no short versions, and the relevant sections will indicate -this.) - - -File: tar.info, Node: Definitions, Next: What tar Does, Prev: Book Contents, Up: Introduction - -1.2 Some Definitions -==================== - -The `tar' program is used to create and manipulate `tar' archives. An -"archive" is a single file which contains the contents of many files, -while still identifying the names of the files, their owner(s), and so -forth. (In addition, archives record access permissions, user and -group, size in bytes, and data modification time. Some archives also -record the file names in each archived directory, as well as other file -and directory information.) You can use `tar' to "create" a new -archive in a specified directory. - - The files inside an archive are called "members". Within this -manual, we use the term "file" to refer only to files accessible in the -normal ways (by `ls', `cat', and so forth), and the term "member" to -refer only to the members of an archive. Similarly, a "file name" is -the name of a file, as it resides in the file system, and a "member -name" is the name of an archive member within the archive. - - The term "extraction" refers to the process of copying an archive -member (or multiple members) into a file in the file system. Extracting -all the members of an archive is often called "extracting the archive". -The term "unpack" can also be used to refer to the extraction of many -or all the members of an archive. Extracting an archive does not -destroy the archive's structure, just as creating an archive does not -destroy the copies of the files that exist outside of the archive. You -may also "list" the members in a given archive (this is often thought -of as "printing" them to the standard output, or the command line), or -"append" members to a pre-existing archive. All of these operations -can be performed using `tar'. - - -File: tar.info, Node: What tar Does, Next: Naming tar Archives, Prev: Definitions, Up: Introduction - -1.3 What `tar' Does -=================== - -The `tar' program provides the ability to create `tar' archives, as -well as various other kinds of manipulation. For example, you can use -`tar' on previously created archives to extract files, to store -additional files, or to update or list files which were already stored. - - Initially, `tar' archives were used to store files conveniently on -magnetic tape. The name `tar' comes from this use; it stands for -`t'ape `ar'chiver. Despite the utility's name, `tar' can direct its -output to available devices, files, or other programs (using pipes). -`tar' may even access remote devices or files (as archives). - - You can use `tar' archives in many ways. We want to stress a few of -them: storage, backup, and transportation. - -Storage - Often, `tar' archives are used to store related files for - convenient file transfer over a network. For example, the GNU - Project distributes its software bundled into `tar' archives, so - that all the files relating to a particular program (or set of - related programs) can be transferred as a single unit. - - A magnetic tape can store several files in sequence. However, the - tape has no names for these files; it only knows their relative - position on the tape. One way to store several files on one tape - and retain their names is by creating a `tar' archive. Even when - the basic transfer mechanism can keep track of names, as FTP can, - the nuisance of handling multiple files, directories, and multiple - links makes `tar' archives useful. - - Archive files are also used for long-term storage. You can think - of this as transportation from the present into the future. (It - is a science-fiction idiom that you can move through time as well - as in space; the idea here is that `tar' can be used to move - archives in all dimensions, even time!) - -Backup - Because the archive created by `tar' is capable of preserving file - information and directory structure, `tar' is commonly used for - performing full and incremental backups of disks. A backup puts a - collection of files (possibly pertaining to many users and - projects) together on a disk or a tape. This guards against - accidental destruction of the information in those files. GNU - `tar' has special features that allow it to be used to make - incremental and full dumps of all the files in a file system. - -Transportation - You can create an archive on one system, transfer it to another - system, and extract the contents there. This allows you to - transport a group of files from one system to another. - - -File: tar.info, Node: Naming tar Archives, Next: Authors, Prev: What tar Does, Up: Introduction - -1.4 How `tar' Archives are Named -================================ - -Conventionally, `tar' archives are given names ending with `.tar'. -This is not necessary for `tar' to operate properly, but this manual -follows that convention in order to accustom readers to it and to make -examples more clear. - - Often, people refer to `tar' archives as "`tar' files," and archive -members as "files" or "entries". For people familiar with the -operation of `tar', this causes no difficulty. However, in this -manual, we consistently refer to "archives" and "archive members" to -make learning to use `tar' easier for novice users. - - -File: tar.info, Node: Authors, Next: Reports, Prev: Naming tar Archives, Up: Introduction - -1.5 GNU `tar' Authors -===================== - -GNU `tar' was originally written by John Gilmore, and modified by many -people. The GNU enhancements were written by Jay Fenlason, then Joy -Kendall, and the whole package has been further maintained by Thomas -Bushnell, n/BSG, Franc,ois Pinard, Paul Eggert, and finally Sergey -Poznyakoff with the help of numerous and kind users. - - We wish to stress that `tar' is a collective work, and owes much to -all those people who reported problems, offered solutions and other -insights, or shared their thoughts and suggestions. An impressive, yet -partial list of those contributors can be found in the `THANKS' file -from the GNU `tar' distribution. - - Jay Fenlason put together a draft of a GNU `tar' manual, borrowing -notes from the original man page from John Gilmore. This was withdrawn -in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a -tutorial and manual for GNU `tar'. Franc,ois Pinard put version 1.11.8 -of the manual together by taking information from all these sources and -merging them. Melissa Weisshaus finally edited and redesigned the book -to create version 1.12. The book for versions from 1.14 up to 1.20 -were edited by the current maintainer, Sergey Poznyakoff. - - For version 1.12, Daniel Hagerty contributed a great deal of -technical consulting. In particular, he is the primary author of *note -Backups::. - - In July, 2003 GNU `tar' was put on CVS at savannah.gnu.org (see -`http://savannah.gnu.org/projects/tar'), and active development and -maintenance work has started again. Currently GNU `tar' is being -maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey. - - Support for POSIX archives was added by Sergey Poznyakoff. - - -File: tar.info, Node: Reports, Prev: Authors, Up: Introduction - -1.6 Reporting bugs or suggestions -================================= - -If you find problems or have suggestions about this program or manual, -please report them to `bug-tar@gnu.org'. - - When reporting a bug, please be sure to include as much detail as -possible, in order to reproduce it. . - - -File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top - -2 Tutorial Introduction to `tar' -******************************** - -This chapter guides you through some basic examples of three `tar' -operations: `--create', `--list', and `--extract'. If you already know -how to use some other version of `tar', then you may not need to read -this chapter. This chapter omits most complicated details about how -`tar' works. - -* Menu: - -* assumptions:: -* stylistic conventions:: -* basic tar options:: Basic `tar' Operations and Options -* frequent operations:: -* Two Frequent Options:: -* create:: How to Create Archives -* list:: How to List Archives -* extract:: How to Extract Members from an Archive -* going further:: - - -File: tar.info, Node: assumptions, Next: stylistic conventions, Up: Tutorial - -2.1 Assumptions this Tutorial Makes -=================================== - -This chapter is paced to allow beginners to learn about `tar' slowly. -At the same time, we will try to cover all the basic aspects of these -three operations. In order to accomplish both of these tasks, we have -made certain assumptions about your knowledge before reading this -manual, and the hardware you will be using: - - * Before you start to work through this tutorial, you should - understand what the terms "archive" and "archive member" mean - (*note Definitions::). In addition, you should understand - something about how Unix-type operating systems work, and you - should know how to use some basic utilities. For example, you - should know how to create, list, copy, rename, edit, and delete - files and directories; how to change between directories; and how - to figure out where you are in the file system. You should have - some basic understanding of directory structure and how files are - named according to which directory they are in. You should - understand concepts such as standard output and standard input, - what various definitions of the term `argument' mean, and the - differences between relative and absolute file names. - - * This manual assumes that you are working from your own home - directory (unless we state otherwise). In this tutorial, you will - create a directory to practice `tar' commands in. When we show - file names, we will assume that those names are relative to your - home directory. For example, my home directory is - `/home/fsf/melissa'. All of my examples are in a subdirectory of - the directory named by that file name; the subdirectory is called - `practice'. - - * In general, we show examples of archives which exist on (or can be - written to, or worked with from) a directory on a hard disk. In - most cases, you could write those archives to, or work with them - on any other device, such as a tape drive. However, some of the - later examples in the tutorial and next chapter will not work on - tape drives. Additionally, working with tapes is much more - complicated than working with hard disks. For these reasons, the - tutorial does not cover working with tape drives. *Note Media::, - for complete information on using `tar' archives with tape drives. - - - -File: tar.info, Node: stylistic conventions, Next: basic tar options, Prev: assumptions, Up: Tutorial - -2.2 Stylistic Conventions -========================= - -In the examples, `$' represents a typical shell prompt. It precedes -lines you should type; to make this more clear, those lines are shown -in `this font', as opposed to lines which represent the computer's -response; those lines are shown in `this font', or sometimes `like -this'. - - -File: tar.info, Node: basic tar options, Next: frequent operations, Prev: stylistic conventions, Up: Tutorial - -2.3 Basic `tar' Operations and Options -====================================== - -`tar' can take a wide variety of arguments which specify and define the -actions it will have on the particular set of files or the archive. -The main types of arguments to `tar' fall into one of two classes: -operations, and options. - - Some arguments fall into a class called "operations"; exactly one of -these is both allowed and required for any instance of using `tar'; you -may _not_ specify more than one. People sometimes speak of "operating -modes". You are in a particular operating mode when you have specified -the operation which specifies it; there are eight operations in total, -and thus there are eight operating modes. - - The other arguments fall into the class known as "options". You are -not required to specify any options, and you are allowed to specify more -than one at a time (depending on the way you are using `tar' at that -time). Some options are used so frequently, and are so useful for -helping you type commands more carefully that they are effectively -"required". We will discuss them in this chapter. - - You can write most of the `tar' operations and options in any of -three forms: long (mnemonic) form, short form, and old style. Some of -the operations and options have no short or "old" forms; however, the -operations and options which we will cover in this tutorial have -corresponding abbreviations. We will indicate those abbreviations -appropriately to get you used to seeing them. (Note that the "old -style" option forms exist in GNU `tar' for compatibility with Unix -`tar'. In this book we present a full discussion of this way of -writing options and operations (*note Old Options::), and we discuss -the other two styles of writing options (*Note Long Options::, and -*note Short Options::). - - In the examples and in the text of this tutorial, we usually use the -long forms of operations and options; but the "short" forms produce the -same result and can make typing long `tar' commands easier. For -example, instead of typing - - tar --create --verbose --file=afiles.tar apple angst aspic - -you can type - tar -c -v -f afiles.tar apple angst aspic - -or even - tar -cvf afiles.tar apple angst aspic - -For more information on option syntax, see *note Advanced tar::. In -discussions in the text, when we name an option by its long form, we -also give the corresponding short option in parentheses. - - The term, "option", can be confusing at times, since "operations" -are often lumped in with the actual, _optional_ "options" in certain -general class statements. For example, we just talked about "short and -long forms of options and operations". However, experienced `tar' -users often refer to these by shorthand terms such as, "short and long -options". This term assumes that the "operations" are included, also. -Context will help you determine which definition of "options" to use. - - Similarly, the term "command" can be confusing, as it is often used -in two different ways. People sometimes refer to `tar' "commands". A -`tar' "command" is the entire command line of user input which tells -`tar' what to do -- including the operation, options, and any arguments -(file names, pipes, other commands, etc.). However, you will also -sometimes hear the term "the `tar' command". When the word "command" -is used specifically like this, a person is usually referring to the -`tar' _operation_, not the whole line. Again, use context to figure -out which of the meanings the speaker intends. - - -File: tar.info, Node: frequent operations, Next: Two Frequent Options, Prev: basic tar options, Up: Tutorial - -2.4 The Three Most Frequently Used Operations -============================================= - -Here are the three most frequently used operations (both short and long -forms), as well as a brief description of their meanings. The rest of -this chapter will cover how to use these operations in detail. We will -present the rest of the operations in the next chapter. - -`--create' -`-c' - Create a new `tar' archive. - -`--list' -`-t' - List the contents of an archive. - -`--extract' -`-x' - Extract one or more members from an archive. - - -File: tar.info, Node: Two Frequent Options, Next: create, Prev: frequent operations, Up: Tutorial - -2.5 Two Frequently Used Options -=============================== - -To understand how to run `tar' in the three operating modes listed -previously, you also need to understand how to use two of the options to -`tar': `--file' (which takes an archive file as an argument) and -`--verbose'. (You are usually not _required_ to specify either of -these options when you run `tar', but they can be very useful in making -things more clear and helping you avoid errors.) - -* Menu: - -* file tutorial:: -* verbose tutorial:: -* help tutorial:: - - -File: tar.info, Node: file tutorial, Next: verbose tutorial, Up: Two Frequent Options - -The `--file' Option -------------------- - -`--file=ARCHIVE-NAME' -`-f ARCHIVE-NAME' - Specify the name of an archive file. - - You can specify an argument for the `--file=ARCHIVE-NAME' (`-f -ARCHIVE-NAME') option whenever you use `tar'; this option determines -the name of the archive file that `tar' will work on. - - If you don't specify this argument, then `tar' will examine the -environment variable `TAPE'. If it is set, its value will be used as -the archive name. Otherwise, `tar' will use the default archive, -determined at the compile time. Usually it is standard output or some -physical tape drive attached to your machine (you can verify what the -default is by running `tar --show-defaults', *note defaults::). If -there is no tape drive attached, or the default is not meaningful, then -`tar' will print an error message. The error message might look -roughly like one of the following: - - tar: can't open /dev/rmt8 : No such device or address - tar: can't open /dev/rsmt0 : I/O error - -To avoid confusion, we recommend that you always specify an archive file -name by using `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') when writing -your `tar' commands. For more information on using the -`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option, see *note file::. - - -File: tar.info, Node: verbose tutorial, Next: help tutorial, Prev: file tutorial, Up: Two Frequent Options - -The `--verbose' Option ----------------------- - -`--verbose' -`-v' - Show the files being worked on as `tar' is running. - - `--verbose' (`-v') shows details about the results of running `tar'. -This can be especially useful when the results might not be obvious. -For example, if you want to see the progress of `tar' as it writes -files into the archive, you can use the `--verbose' option. In the -beginning, you may find it useful to use `--verbose' at all times; when -you are more accustomed to `tar', you will likely want to use it at -certain times but not at others. We will use `--verbose' at times to -help make something clear, and we will give many examples both using -and not using `--verbose' to show the differences. - - Each instance of `--verbose' on the command line increases the -verbosity level by one, so if you need more details on the output, -specify it twice. - - When reading archives (`--list', `--extract', `--diff'), `tar' by -default prints only the names of the members being extracted. Using -`--verbose' will show a full, `ls' style member listing. - - In contrast, when writing archives (`--create', `--append', -`--update'), `tar' does not print file names by default. So, a single -`--verbose' option shows the file names being added to the archive, -while two `--verbose' options enable the full listing. - - For example, to create an archive in verbose mode: - - $ tar -cvf afiles.tar apple angst aspic - apple - angst - aspic - -Creating the same archive with the verbosity level 2 could give: - - $ tar -cvvf afiles.tar apple angst aspic - -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple - -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst - -rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic - -This works equally well using short or long forms of options. Using -long forms, you would simply write out the mnemonic form of the option -twice, like this: - - $ tar --create --verbose --verbose ... - -Note that you must double the hyphens properly each time. - - Later in the tutorial, we will give examples using -`--verbose --verbose'. - - The full output consists of six fields: - - * File type and permissions in symbolic form. These are displayed - in the same format as the first column of `ls -l' output (*note - format=verbose: (fileutils)What information is listed.). - - * Owner name and group separated by a slash character. If these - data are not available (for example, when listing a `v7' format - archive), numeric ID values are printed instead. - - * Size of the file, in bytes. - - * File modification date in ISO 8601 format. - - * File modification time. - - * File name. If the name contains any special characters (white - space, newlines, etc.) these are displayed in an unambiguous form - using so called "quoting style". For the detailed discussion of - available styles and on how to use them, see *note quoting - styles::. - - Depending on the file type, the name can be followed by some - additional information, described in the following table: - - `-> LINK-NAME' - The file or archive member is a "symbolic link" and LINK-NAME - is the name of file it links to. - - `link to LINK-NAME' - The file or archive member is a "hard link" and LINK-NAME is - the name of file it links to. - - `--Long Link--' - The archive member is an old GNU format long link. You will - normally not encounter this. - - `--Long Name--' - The archive member is an old GNU format long name. You will - normally not encounter this. - - `--Volume Header--' - The archive member is a GNU "volume header" (*note Tape - Files::). - - `--Continued at byte N--' - Encountered only at the beginning of a multi-volume archive - (*note Using Multiple Tapes::). This archive member is a - continuation from the previous volume. The number N gives the - offset where the original file was split. - - `unknown file type C' - An archive member of unknown type. C is the type character - from the archive header. If you encounter such a message, it - means that either your archive contains proprietary member - types GNU `tar' is not able to handle, or the archive is - corrupted. - - - For example, here is an archive listing containing most of the -special suffixes explained above: - - V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header-- - -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at - byte 32456-- - -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple - lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple - -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues - hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues - - - -File: tar.info, Node: help tutorial, Prev: verbose tutorial, Up: Two Frequent Options - -Getting Help: Using the `--help' Option ---------------------------------------- - -`--help' - The `--help' option to `tar' prints out a very brief list of all - operations and option available for the current version of `tar' - available on your system. - - -File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial - -2.6 How to Create Archives -========================== - - _(This message will disappear, once this node revised.)_ - -One of the basic operations of `tar' is `--create' (`-c'), which you -use to create a `tar' archive. We will explain `--create' first -because, in order to learn about the other operations, you will find it -useful to have an archive available to practice on. - - To make this easier, in this section you will first create a -directory containing three files. Then, we will show you how to create -an _archive_ (inside the new directory). Both the directory, and the -archive are specifically for you to practice on. The rest of this -chapter and the next chapter will show many examples using this -directory and the files you will create: some of those files may be -other directories and other archives. - - The three files you will archive in this example are called `blues', -`folk', and `jazz'. The archive is called `collection.tar'. - - This section will proceed slowly, detailing how to use `--create' in -`verbose' mode, and showing examples using both short and long forms. -In the rest of the tutorial, and in the examples in the next chapter, -we will proceed at a slightly quicker pace. This section moves more -slowly to allow beginning users to understand how `tar' works. - -* Menu: - -* prepare for examples:: -* Creating the archive:: -* create verbose:: -* short create:: -* create dir:: - - -File: tar.info, Node: prepare for examples, Next: Creating the archive, Up: create - -2.6.1 Preparing a Practice Directory for Examples -------------------------------------------------- - -To follow along with this and future examples, create a new directory -called `practice' containing files called `blues', `folk' and `jazz'. -The files can contain any information you like: ideally, they should -contain information which relates to their names, and be of different -lengths. Our examples assume that `practice' is a subdirectory of your -home directory. - - Now `cd' to the directory named `practice'; `practice' is now your -"working directory". (_Please note_: Although the full file name of -this directory is `/HOMEDIR/practice', in our examples we will refer to -this directory as `practice'; the HOMEDIR is presumed. - - In general, you should check that the files to be archived exist -where you think they do (in the working directory) by running `ls'. -Because you just created the directory and the files and have changed to -that directory, you probably don't need to do that this time. - - It is very important to make sure there isn't already a file in the -working directory with the archive name you intend to use (in this case, -`collection.tar'), or that you don't care about its contents. Whenever -you use `create', `tar' will erase the current contents of the file -named by `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') if it exists. `tar' -will not tell you if you are about to overwrite an archive unless you -specify an option which does this (*note backup::, for the information -on how to do so). To add files to an existing archive, you need to use -a different option, such as `--append' (`-r'); see *note append:: for -information on how to do this. - - -File: tar.info, Node: Creating the archive, Next: create verbose, Prev: prepare for examples, Up: create - -2.6.2 Creating the Archive --------------------------- - -To place the files `blues', `folk', and `jazz' into an archive named -`collection.tar', use the following command: - - $ tar --create --file=collection.tar blues folk jazz - - The order of the arguments is not very important, _when using long -option forms_. You could also say: - - $ tar blues --create folk --file=collection.tar jazz - -However, you can see that this order is harder to understand; this is -why we will list the arguments in the order that makes the commands -easiest to understand (and we encourage you to do the same when you use -`tar', to avoid errors). - - Note that the sequence `--file=collection.tar' is considered to be -_one_ argument. If you substituted any other string of characters for -`collection.tar', then that string would become the name of the -archive file you create. - - The order of the options becomes more important when you begin to use -short forms. With short forms, if you type commands in the wrong order -(even if you type them correctly in all other ways), you may end up with -results you don't expect. For this reason, it is a good idea to get -into the habit of typing options in the order that makes inherent sense. -*Note short create::, for more information on this. - - In this example, you type the command as shown above: `--create' is -the operation which creates the new archive (`collection.tar'), and -`--file' is the option which lets you give it the name you chose. The -files, `blues', `folk', and `jazz', are now members of the archive, -`collection.tar' (they are "file name arguments" to the `--create' -operation. *Note Choosing::, for the detailed discussion on these.) -Now that they are in the archive, they are called _archive members_, -not files. (*note members: Definitions.). - - When you create an archive, you _must_ specify which files you want -placed in the archive. If you do not specify any archive members, GNU -`tar' will complain. - - If you now list the contents of the working directory (`ls'), you -will find the archive file listed as well as the files you saw -previously: - - blues folk jazz collection.tar - -Creating the archive `collection.tar' did not destroy the copies of the -files in the directory. - - Keep in mind that if you don't indicate an operation, `tar' will not -run and will prompt you for one. If you don't name any files, `tar' -will complain. You must have write access to the working directory, or -else you will not be able to create an archive in that directory. - - _Caution_: Do not attempt to use `--create' (`-c') to add files to -an existing archive; it will delete the archive and write a new one. -Use `--append' (`-r') instead. *Note append::. - - -File: tar.info, Node: create verbose, Next: short create, Prev: Creating the archive, Up: create - -2.6.3 Running `--create' with `--verbose' ------------------------------------------ - -If you include the `--verbose' (`-v') option on the command line, `tar' -will list the files it is acting on as it is working. In verbose mode, -the `create' example above would appear as: - - $ tar --create --verbose --file=collection.tar blues folk jazz - blues - folk - jazz - - This example is just like the example we showed which did not use -`--verbose', except that `tar' generated the remaining lines . - - In the rest of the examples in this chapter, we will frequently use -`verbose' mode so we can show actions or `tar' responses that you would -otherwise not see, and which are important for you to understand. - - -File: tar.info, Node: short create, Next: create dir, Prev: create verbose, Up: create - -2.6.4 Short Forms with `create' -------------------------------- - -As we said before, the `--create' (`-c') operation is one of the most -basic uses of `tar', and you will use it countless times. Eventually, -you will probably want to use abbreviated (or "short") forms of -options. A full discussion of the three different forms that options -can take appears in *note Styles::; for now, here is what the previous -example (including the `--verbose' (`-v') option) looks like using -short option forms: - - $ tar -cvf collection.tar blues folk jazz - blues - folk - jazz - -As you can see, the system responds the same no matter whether you use -long or short option forms. - - One difference between using short and long option forms is that, -although the exact placement of arguments following options is no more -specific when using short forms, it is easier to become confused and -make a mistake when using short forms. For example, suppose you -attempted the above example in the following way: - - $ tar -cfv collection.tar blues folk jazz - -In this case, `tar' will make an archive file called `v', containing -the files `blues', `folk', and `jazz', because the `v' is the closest -"file name" to the `-f' option, and is thus taken to be the chosen -archive file name. `tar' will try to add a file called -`collection.tar' to the `v' archive file; if the file `collection.tar' -did not already exist, `tar' will report an error indicating that this -file does not exist. If the file `collection.tar' does already exist -(e.g., from a previous command you may have run), then `tar' will add -this file to the archive. Because the `-v' option did not get -registered, `tar' will not run under `verbose' mode, and will not -report its progress. - - The end result is that you may be quite confused about what happened, -and possibly overwrite a file. To illustrate this further, we will show -you how an example we showed previously would look using short forms. - - This example, - - $ tar blues --create folk --file=collection.tar jazz - -is confusing as it is. When shown using short forms, however, it -becomes much more so: - - $ tar blues -c folk -f collection.tar jazz - -It would be very easy to put the wrong string of characters immediately -following the `-f', but doing that could sacrifice valuable data. - - For this reason, we recommend that you pay very careful attention to -the order of options and placement of file and archive names, -especially when using short option forms. Not having the option name -written out mnemonically can affect how well you remember which option -does what, and therefore where different names have to be placed. - - -File: tar.info, Node: create dir, Prev: short create, Up: create - -2.6.5 Archiving Directories ---------------------------- - -You can archive a directory by specifying its directory name as a file -name argument to `tar'. The files in the directory will be archived -relative to the working directory, and the directory will be re-created -along with its contents when the archive is extracted. - - To archive a directory, first move to its superior directory. If you -have followed the previous instructions in this tutorial, you should -type: - - $ cd .. - $ - -This will put you into the directory which contains `practice', i.e., -your home directory. Once in the superior directory, you can specify -the subdirectory, `practice', as a file name argument. To store -`practice' in the new archive file `music.tar', type: - - $ tar --create --verbose --file=music.tar practice - -`tar' should output: - - practice/ - practice/blues - practice/folk - practice/jazz - practice/collection.tar - - Note that the archive thus created is not in the subdirectory -`practice', but rather in the current working directory--the directory -from which `tar' was invoked. Before trying to archive a directory -from its superior directory, you should make sure you have write access -to the superior directory itself, not only the directory you are trying -archive with `tar'. For example, you will probably not be able to -store your home directory in an archive by invoking `tar' from the root -directory; *Note absolute::. (Note also that `collection.tar', the -original archive file, has itself been archived. `tar' will accept any -file as a file to be archived, regardless of its content. When -`music.tar' is extracted, the archive file `collection.tar' will be -re-written into the file system). - - If you give `tar' a command such as - - $ tar --create --file=foo.tar . - -`tar' will report `tar: ./foo.tar is the archive; not dumped'. This -happens because `tar' creates the archive `foo.tar' in the current -directory before putting any files into it. Then, when `tar' attempts -to add all the files in the directory `.' to the archive, it notices -that the file `./foo.tar' is the same as the archive `foo.tar', and -skips it. (It makes no sense to put an archive into itself.) GNU `tar' -will continue in this case, and create the archive normally, except for -the exclusion of that one file. (_Please note:_ Other implementations -of `tar' may not be so clever; they will enter an infinite loop when -this happens, so you should not depend on this behavior unless you are -certain you are running GNU `tar'. In general, it is wise to always -place the archive outside of the directory being dumped. - - -File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial - -2.7 How to List Archives -======================== - -Frequently, you will find yourself wanting to determine exactly what a -particular archive contains. You can use the `--list' (`-t') operation -to get the member names as they currently appear in the archive, as -well as various attributes of the files at the time they were archived. -For example, you can examine the archive `collection.tar' that you -created in the last section with the command, - - $ tar --list --file=collection.tar - -The output of `tar' would then be: - - blues - folk - jazz - -The archive `bfiles.tar' would list as follows: - - ./birds - baboon - ./box - -Be sure to use a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option just -as with `--create' (`-c') to specify the name of the archive. - - If you use the `--verbose' (`-v') option with `--list', then `tar' -will print out a listing reminiscent of `ls -l', showing owner, file -size, and so forth. This output is described in detail in *note -verbose member listing::. - - If you had used `--verbose' (`-v') mode, the example above would -look like: - - $ tar --list --verbose --file=collection.tar folk - -rw-r--r-- myself user 62 1990-05-23 10:55 folk - - It is important to notice that the output of `tar --list --verbose' -does not necessarily match that produced by `tar --create --verbose' -while creating the archive. It is because GNU `tar', unless told -explicitly not to do so, removes some directory prefixes from file -names before storing them in the archive (*Note absolute::, for more -information). In other words, in verbose mode GNU `tar' shows "file -names" when creating an archive and "member names" when listing it. -Consider this example: - - $ tar cfv archive /etc/mail - tar: Removing leading `/' from member names - /etc/mail/ - /etc/mail/sendmail.cf - /etc/mail/aliases - $ tar tf archive - etc/mail/ - etc/mail/sendmail.cf - etc/mail/aliases - - This default behavior can sometimes be inconvenient. You can force -GNU `tar' show member names when creating archive by supplying -`--show-stored-names' option. - -`--show-stored-names' - Print member (as opposed to _file_) names when creating the - archive. - - You can specify one or more individual member names as arguments when -using `list'. In this case, `tar' will only list the names of members -you identify. For example, `tar --list --file=afiles.tar apple' would -only print `apple'. - - Because `tar' preserves file names, these must be specified as they -appear in the archive (i.e., relative to the directory from which the -archive was created). Therefore, it is essential when specifying -member names to `tar' that you give the exact member names. For -example, `tar --list --file=bfiles.tar birds' would produce an error -message something like `tar: birds: Not found in archive', because -there is no member named `birds', only one named `./birds'. While the -names `birds' and `./birds' name the same file, _member_ names by -default are compared verbatim. - - However, `tar --list --file=bfiles.tar baboon' would respond with -`baboon', because this exact member name is in the archive file -`bfiles.tar'. If you are not sure of the exact file name, use -"globbing patterns", for example: - - $ tar --list --file=bfiles.tar --wildcards '*b*' - -will list all members whose name contains `b'. *Note wildcards::, for -a detailed discussion of globbing patterns and related `tar' command -line options. - -* Menu: - -* list dir:: - - -File: tar.info, Node: list dir, Up: list - -Listing the Contents of a Stored Directory ------------------------------------------- - -To get information about the contents of an archived directory, use the -directory name as a file name argument in conjunction with `--list' -(`-t'). To find out file attributes, include the `--verbose' (`-v') -option. - - For example, to find out about files in the directory `practice', in -the archive file `music.tar', type: - - $ tar --list --verbose --file=music.tar practice - - `tar' responds: - - drwxrwxrwx myself user 0 1990-05-31 21:49 practice/ - -rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues - -rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk - -rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz - -rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar - - When you use a directory name as a file name argument, `tar' acts on -all the files (including sub-directories) in that directory. - - -File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial - -2.8 How to Extract Members from an Archive -========================================== - - _(This message will disappear, once this node revised.)_ - -Creating an archive is only half the job--there is no point in storing -files in an archive if you can't retrieve them. The act of retrieving -members from an archive so they can be used and manipulated as -unarchived files again is called "extraction". To extract files from -an archive, use the `--extract' (`--get' or `-x') operation. As with -`--create', specify the name of the archive with `--file' (`-f') -option. Extracting an archive does not modify the archive in any way; -you can extract it multiple times if you want or need to. - - Using `--extract', you can extract an entire archive, or specific -files. The files can be directories containing other files, or not. As -with `--create' (`-c') and `--list' (`-t'), you may use the short or the -long form of the operation without affecting the performance. - -* Menu: - -* extracting archives:: -* extracting files:: -* extract dir:: -* extracting untrusted archives:: -* failing commands:: - - -File: tar.info, Node: extracting archives, Next: extracting files, Up: extract - -2.8.1 Extracting an Entire Archive ----------------------------------- - -To extract an entire archive, specify the archive file name only, with -no individual file names as arguments. For example, - - $ tar -xvf collection.tar - -produces this: - - -rw-r--r-- me user 28 1996-10-18 16:31 jazz - -rw-r--r-- me user 21 1996-09-23 16:44 blues - -rw-r--r-- me user 20 1996-09-23 16:44 folk - - -File: tar.info, Node: extracting files, Next: extract dir, Prev: extracting archives, Up: extract - -2.8.2 Extracting Specific Files -------------------------------- - -To extract specific archive members, give their exact member names as -arguments, as printed by `--list' (`-t'). If you had mistakenly -deleted one of the files you had placed in the archive `collection.tar' -earlier (say, `blues'), you can extract it from the archive without -changing the archive's structure. Its contents will be identical to -the original file `blues' that you deleted. - - First, make sure you are in the `practice' directory, and list the -files in the directory. Now, delete the file, `blues', and list the -files in the directory again. - - You can now extract the member `blues' from the archive file -`collection.tar' like this: - - $ tar --extract --file=collection.tar blues - -If you list the files in the directory again, you will see that the file -`blues' has been restored, with its original permissions, data -modification times, and owner.(1) (These parameters will be identical -to those which the file had when you originally placed it in the -archive; any changes you may have made before deleting the file from -the file system, however, will _not_ have been made to the archive -member.) The archive file, `collection.tar', is the same as it was -before you extracted `blues'. You can confirm this by running `tar' -with `--list' (`-t'). - - Remember that as with other operations, specifying the exact member -name is important. `tar --extract --file=bfiles.tar birds' will fail, -because there is no member named `birds'. To extract the member named -`./birds', you must specify `tar --extract --file=bfiles.tar ./birds'. -If you don't remember the exact member names, use `--list' (`-t') option -(*note list::). You can also extract those members that match a -specific "globbing pattern". For example, to extract from `bfiles.tar' -all files that begin with `b', no matter their directory prefix, you -could type: - - $ tar -x -f bfiles.tar --wildcards --no-anchored 'b*' - -Here, `--wildcards' instructs `tar' to treat command line arguments as -globbing patterns and `--no-anchored' informs it that the patterns -apply to member names after any `/' delimiter. The use of globbing -patterns is discussed in detail in *Note wildcards::. - - You can extract a file to standard output by combining the above -options with the `--to-stdout' (`-O') option (*note Writing to Standard -Output::). - - If you give the `--verbose' option, then `--extract' will print the -names of the archive members as it extracts them. - - ---------- Footnotes ---------- - - (1) This is only accidentally true, but not in general. Whereas -modification times are always restored, in most cases, one has to be -root for restoring the owner, and use a special option for restoring -permissions. Here, it just happens that the restoring user is also the -owner of the archived members, and that the current `umask' is -compatible with original permissions. - - -File: tar.info, Node: extract dir, Next: extracting untrusted archives, Prev: extracting files, Up: extract - -2.8.3 Extracting Files that are Directories -------------------------------------------- - -Extracting directories which are members of an archive is similar to -extracting other files. The main difference to be aware of is that if -the extracted directory has the same name as any directory already in -the working directory, then files in the extracted directory will be -placed into the directory of the same name. Likewise, if there are -files in the pre-existing directory with the same names as the members -which you extract, the files from the extracted archive will replace -the files already in the working directory (and possible -subdirectories). This will happen regardless of whether or not the -files in the working directory were more recent than those extracted -(there exist, however, special options that alter this behavior *note -Writing::). - - However, if a file was stored with a directory name as part of its -file name, and that directory does not exist under the working -directory when the file is extracted, `tar' will create the directory. - - We can demonstrate how to use `--extract' to extract a directory -file with an example. Change to the `practice' directory if you -weren't there, and remove the files `folk' and `jazz'. Then, go back -to the parent directory and extract the archive `music.tar'. You may -either extract the entire archive, or you may extract only the files -you just deleted. To extract the entire archive, don't give any file -names as arguments after the archive name `music.tar'. To extract only -the files you deleted, use the following command: - - $ tar -xvf music.tar practice/folk practice/jazz - practice/folk - practice/jazz - -If you were to specify two `--verbose' (`-v') options, `tar' would have -displayed more detail about the extracted files, as shown in the -example below: - - $ tar -xvvf music.tar practice/folk practice/jazz - -rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz - -rw-r--r-- me user 20 1996-09-23 16:44 practice/folk - -Because you created the directory with `practice' as part of the file -names of each of the files by archiving the `practice' directory as -`practice', you must give `practice' as part of the file names when you -extract those files from the archive. - - -File: tar.info, Node: extracting untrusted archives, Next: failing commands, Prev: extract dir, Up: extract - -2.8.4 Extracting Archives from Untrusted Sources ------------------------------------------------- - -Extracting files from archives can overwrite files that already exist. -If you receive an archive from an untrusted source, you should make a -new directory and extract into that directory, so that you don't have -to worry about the extraction overwriting one of your existing files. -For example, if `untrusted.tar' came from somewhere else on the -Internet, and you don't necessarily trust its contents, you can extract -it as follows: - - $ mkdir newdir - $ cd newdir - $ tar -xvf ../untrusted.tar - - It is also a good practice to examine contents of the archive before -extracting it, using `--list' (`-t') option, possibly combined with -`--verbose' (`-v'). - - -File: tar.info, Node: failing commands, Prev: extracting untrusted archives, Up: extract - -2.8.5 Commands That Will Fail ------------------------------ - -Here are some sample commands you might try which will not work, and why -they won't work. - - If you try to use this command, - - $ tar -xvf music.tar folk jazz - -you will get the following response: - - tar: folk: Not found in archive - tar: jazz: Not found in archive - $ - -This is because these files were not originally _in_ the parent -directory `..', where the archive is located; they were in the -`practice' directory, and their file names reflect this: - - $ tar -tvf music.tar - practice/folk - practice/jazz - practice/rock - -Likewise, if you try to use this command, - - $ tar -tvf music.tar folk jazz - -you would get a similar response. Members with those names are not in -the archive. You must use the correct member names, or wildcards, in -order to extract the files from the archive. - - If you have forgotten the correct names of the files in the archive, -use `tar --list --verbose' to list them correctly. - - -File: tar.info, Node: going further, Prev: extract, Up: Tutorial - -2.9 Going Further Ahead in this Manual -====================================== - - _(This message will disappear, once this node revised.)_ - - -File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top - -3 Invoking GNU `tar' -******************** - - _(This message will disappear, once this node revised.)_ - -This chapter is about how one invokes the GNU `tar' command, from the -command synopsis (*note Synopsis::). There are numerous options, and -many styles for writing them. One mandatory option specifies the -operation `tar' should perform (*note Operation Summary::), other -options are meant to detail how this operation should be performed -(*note Option Summary::). Non-option arguments are not always -interpreted the same way, depending on what the operation is. - - You will find in this chapter everything about option styles and -rules for writing them (*note Styles::). On the other hand, operations -and options are fully described elsewhere, in other chapters. Here, -you will find only synthetic descriptions for operations and options, -together with pointers to other parts of the `tar' manual. - - Some options are so special they are fully described right in this -chapter. They have the effect of inhibiting the normal operation of -`tar' or else, they globally alter the amount of feedback the user -receives about what is going on. These are the `--help' and -`--version' (*note help::), `--verbose' (*note verbose::) and -`--interactive' options (*note interactive::). - -* Menu: - -* Synopsis:: -* using tar options:: -* Styles:: -* All Options:: -* help:: -* defaults:: -* verbose:: -* checkpoints:: -* interactive:: - - -File: tar.info, Node: Synopsis, Next: using tar options, Up: tar invocation - -3.1 General Synopsis of `tar' -============================= - -The GNU `tar' program is invoked as either one of: - - tar OPTION... [NAME]... - tar LETTER... [ARGUMENT]... [OPTION]... [NAME]... - - The second form is for when old options are being used. - - You can use `tar' to store files in an archive, to extract them from -an archive, and to do other types of archive manipulation. The primary -argument to `tar', which is called the "operation", specifies which -action to take. The other arguments to `tar' are either "options", -which change the way `tar' performs an operation, or file names or -archive members, which specify the files or members `tar' is to act on. - - You can actually type in arguments in any order, even if in this -manual the options always precede the other arguments, to make examples -easier to understand. Further, the option stating the main operation -mode (the `tar' main command) is usually given first. - - Each NAME in the synopsis above is interpreted as an archive member -name when the main command is one of `--compare' (`--diff', `-d'), -`--delete', `--extract' (`--get', `-x'), `--list' (`-t') or `--update' -(`-u'). When naming archive members, you must give the exact name of -the member in the archive, as it is printed by `--list'. For -`--append' (`-r') and `--create' (`-c'), these NAME arguments specify -the names of either files or directory hierarchies to place in the -archive. These files or hierarchies should already exist in the file -system, prior to the execution of the `tar' command. - - `tar' interprets relative file names as being relative to the -working directory. `tar' will make all file names relative (by -removing leading slashes when archiving or restoring files), unless you -specify otherwise (using the `--absolute-names' option). *Note -absolute::, for more information about `--absolute-names'. - - If you give the name of a directory as either a file name or a member -name, then `tar' acts recursively on all the files and directories -beneath that directory. For example, the name `/' identifies all the -files in the file system to `tar'. - - The distinction between file names and archive member names is -especially important when shell globbing is used, and sometimes a -source of confusion for newcomers. *Note wildcards::, for more -information about globbing. The problem is that shells may only glob -using existing files in the file system. Only `tar' itself may glob on -archive members, so when needed, you must ensure that wildcard -characters reach `tar' without being interpreted by the shell first. -Using a backslash before `*' or `?', or putting the whole argument -between quotes, is usually sufficient for this. - - Even if NAMEs are often specified on the command line, they can also -be read from a text file in the file system, using the -`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option. - - If you don't use any file name arguments, `--append' (`-r'), -`--delete' and `--concatenate' (`--catenate', `-A') will do nothing, -while `--create' (`-c') will usually yield a diagnostic and inhibit -`tar' execution. The other operations of `tar' (`--list', `--extract', -`--compare', and `--update') will act on the entire contents of the -archive. - - Besides successful exits, GNU `tar' may fail for many reasons. Some -reasons correspond to bad usage, that is, when the `tar' command is -improperly written. Errors may be encountered later, while -encountering an error processing the archive or the files. Some errors -are recoverable, in which case the failure is delayed until `tar' has -completed all its work. Some errors are such that it would not -meaningful, or at least risky, to continue processing: `tar' then -aborts processing immediately. All abnormal exits, whether immediate -or delayed, should always be clearly diagnosed on `stderr', after a -line stating the nature of the error. - - Possible exit codes of GNU `tar' are summarized in the following -table: - -0 - `Successful termination'. - -1 - `Some files differ'. If tar was invoked with `--compare' - (`--diff', `-d') command line option, this means that some files - in the archive differ from their disk counterparts (*note - compare::). If tar was given `--create', `--append' or `--update' - option, this exit code means that some files were changed while - being archived and so the resulting archive does not contain the - exact copy of the file set. - -2 - `Fatal error'. This means that some fatal, unrecoverable error - occurred. - - If `tar' has invoked a subprocess and that subprocess exited with a -nonzero exit code, `tar' exits with that code as well. This can -happen, for example, if `tar' was given some compression option (*note -gzip::) and the external compressor program failed. Another example is -`rmt' failure during backup to the remote device (*note Remote Tape -Server::). - - -File: tar.info, Node: using tar options, Next: Styles, Prev: Synopsis, Up: tar invocation - -3.2 Using `tar' Options -======================= - -GNU `tar' has a total of eight operating modes which allow you to -perform a variety of tasks. You are required to choose one operating -mode each time you employ the `tar' program by specifying one, and only -one operation as an argument to the `tar' command (two lists of four -operations each may be found at *note frequent operations:: and *note -Operations::). Depending on circumstances, you may also wish to -customize how the chosen operating mode behaves. For example, you may -wish to change the way the output looks, or the format of the files -that you wish to archive may require you to do something special in -order to make the archive look right. - - You can customize and control `tar''s performance by running `tar' -with one or more options (such as `--verbose' (`-v'), which we used in -the tutorial). As we said in the tutorial, "options" are arguments to -`tar' which are (as their name suggests) optional. Depending on the -operating mode, you may specify one or more options. Different options -will have different effects, but in general they all change details of -the operation, such as archive format, archive name, or level of user -interaction. Some options make sense with all operating modes, while -others are meaningful only with particular modes. You will likely use -some options frequently, while you will only use others infrequently, or -not at all. (A full list of options is available in *note All -Options::.) - - The `TAR_OPTIONS' environment variable specifies default options to -be placed in front of any explicit options. For example, if -`TAR_OPTIONS' is `-v --unlink-first', `tar' behaves as if the two -options `-v' and `--unlink-first' had been specified before any -explicit options. Option specifications are separated by whitespace. -A backslash escapes the next character, so it can be used to specify an -option containing whitespace or a backslash. - - Note that `tar' options are case sensitive. For example, the -options `-T' and `-t' are different; the first requires an argument for -stating the name of a file providing a list of NAMEs, while the second -does not require an argument and is another way to write `--list' -(`-t'). - - In addition to the eight operations, there are many options to -`tar', and three different styles for writing both: long (mnemonic) -form, short form, and old style. These styles are discussed below. -Both the options and the operations can be written in any of these three -styles. - - -File: tar.info, Node: Styles, Next: All Options, Prev: using tar options, Up: tar invocation - -3.3 The Three Option Styles -=========================== - -There are three styles for writing operations and options to the command -line invoking `tar'. The different styles were developed at different -times during the history of `tar'. These styles will be presented -below, from the most recent to the oldest. - - Some options must take an argument. (For example, `--file' (`-f')) -takes the name of an archive file as an argument. If you do not supply -an archive file name, `tar' will use a default, but this can be -confusing; thus, we recommend that you always supply a specific archive -file name.) Where you _place_ the arguments generally depends on which -style of options you choose. We will detail specific information -relevant to each option style in the sections on the different option -styles, below. The differences are subtle, yet can often be very -important; incorrect option placement can cause you to overwrite a -number of important files. We urge you to note these differences, and -only use the option style(s) which makes the most sense to you until -you feel comfortable with the others. - - Some options _may_ take an argument. Such options may have at most -long and short forms, they do not have old style equivalent. The rules -for specifying an argument for such options are stricter than those for -specifying mandatory arguments. Please, pay special attention to them. - -* Menu: - -* Long Options:: Long Option Style -* Short Options:: Short Option Style -* Old Options:: Old Option Style -* Mixing:: Mixing Option Styles - - -File: tar.info, Node: Long Options, Next: Short Options, Up: Styles - -3.3.1 Long Option Style ------------------------ - -Each option has at least one "long" (or "mnemonic") name starting with -two dashes in a row, e.g., `--list'. The long names are more clear than -their corresponding short or old names. It sometimes happens that a -single long option has many different names which are synonymous, such -as `--compare' and `--diff'. In addition, long option names can be -given unique abbreviations. For example, `--cre' can be used in place -of `--create' because there is no other long option which begins with -`cre'. (One way to find this out is by trying it and seeing what -happens; if a particular abbreviation could represent more than one -option, `tar' will tell you that that abbreviation is ambiguous and -you'll know that that abbreviation won't work. You may also choose to -run `tar --help' to see a list of options. Be aware that if you run -`tar' with a unique abbreviation for the long name of an option you -didn't want to use, you are stuck; `tar' will perform the command as -ordered.) - - Long options are meant to be obvious and easy to remember, and their -meanings are generally easier to discern than those of their -corresponding short options (see below). For example: - - $ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0 - -gives a fairly good set of hints about what the command does, even for -those not fully acquainted with `tar'. - - Long options which require arguments take those arguments -immediately following the option name. There are two ways of -specifying a mandatory argument. It can be separated from the option -name either by an equal sign, or by any amount of white space -characters. For example, the `--file' option (which tells the name of -the `tar' archive) is given a file such as `archive.tar' as argument by -using any of the following notations: `--file=archive.tar' or `--file -archive.tar'. - - In contrast, optional arguments must always be introduced using an -equal sign. For example, the `--backup' option takes an optional -argument specifying backup type. It must be used as -`--backup=BACKUP-TYPE'. - - -File: tar.info, Node: Short Options, Next: Old Options, Prev: Long Options, Up: Styles - -3.3.2 Short Option Style ------------------------- - -Most options also have a "short option" name. Short options start with -a single dash, and are followed by a single character, e.g., `-t' -(which is equivalent to `--list'). The forms are absolutely identical -in function; they are interchangeable. - - The short option names are faster to type than long option names. - - Short options which require arguments take their arguments -immediately following the option, usually separated by white space. It -is also possible to stick the argument right after the short option -name, using no intervening space. For example, you might write -`-f archive.tar' or `-farchive.tar' instead of using -`--file=archive.tar'. Both `--file=ARCHIVE-NAME' and `-f ARCHIVE-NAME' -denote the option which indicates a specific archive, here named -`archive.tar'. - - Short options which take optional arguments take their arguments -immediately following the option letter, _without any intervening white -space characters_. - - Short options' letters may be clumped together, but you are not -required to do this (as compared to old options; see below). When -short options are clumped as a set, use one (single) dash for them all, -e.g., ``tar' -cvf'. Only the last option in such a set is allowed to -have an argument(1). - - When the options are separated, the argument for each option which -requires an argument directly follows that option, as is usual for Unix -programs. For example: - - $ tar -c -v -b 20 -f /dev/rmt0 - - If you reorder short options' locations, be sure to move any -arguments that belong to them. If you do not move the arguments -properly, you may end up overwriting files. - - ---------- Footnotes ---------- - - (1) Clustering many options, the last of which has an argument, is a -rather opaque way to write options. Some wonder if GNU `getopt' should -not even be made helpful enough for considering such usages as invalid. - - -File: tar.info, Node: Old Options, Next: Mixing, Prev: Short Options, Up: Styles - -3.3.3 Old Option Style ----------------------- - - _(This message will disappear, once this node revised.)_ - -Like short options, "old options" are single letters. However, old -options must be written together as a single clumped set, without -spaces separating them or dashes preceding them(1). This set of -letters must be the first to appear on the command line, after the -`tar' program name and some white space; old options cannot appear -anywhere else. The letter of an old option is exactly the same letter -as the corresponding short option. For example, the old option `t' is -the same as the short option `-t', and consequently, the same as the -long option `--list'. So for example, the command `tar cv' specifies -the option `-v' in addition to the operation `-c'. - - When options that need arguments are given together with the command, -all the associated arguments follow, in the same order as the options. -Thus, the example given previously could also be written in the old -style as follows: - - $ tar cvbf 20 /dev/rmt0 - -Here, `20' is the argument of `-b' and `/dev/rmt0' is the argument of -`-f'. - - On the other hand, this old style syntax makes it difficult to match -option letters with their corresponding arguments, and is often -confusing. In the command `tar cvbf 20 /dev/rmt0', for example, `20' -is the argument for `-b', `/dev/rmt0' is the argument for `-f', and -`-v' does not have a corresponding argument. Even using short options -like in `tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all -arguments next to the option they pertain to. - - If you want to reorder the letters in the old option argument, be -sure to reorder any corresponding argument appropriately. - - This old way of writing `tar' options can surprise even experienced -users. For example, the two commands: - - tar cfz archive.tar.gz file - tar -cfz archive.tar.gz file - -are quite different. The first example uses `archive.tar.gz' as the -value for option `f' and recognizes the option `z'. The second -example, however, uses `z' as the value for option `f' -- probably not -what was intended. - - Old options are kept for compatibility with old versions of `tar'. - - This second example could be corrected in many ways, among which the -following are equivalent: - - tar -czf archive.tar.gz file - tar -cf archive.tar.gz -z file - tar cf archive.tar.gz -z file - - As far as we know, all `tar' programs, GNU and non-GNU, support old -options. GNU `tar' supports them not only for historical reasons, but -also because many people are used to them. For compatibility with Unix -`tar', the first argument is always treated as containing command and -option letters even if it doesn't start with `-'. Thus, `tar c' is -equivalent to `tar -c': both of them specify the `--create' (`-c') -command to create an archive. - - ---------- Footnotes ---------- - - (1) Beware that if you precede options with a dash, you are -announcing the short option style instead of the old option style; -short options are decoded differently. - - -File: tar.info, Node: Mixing, Prev: Old Options, Up: Styles - -3.3.4 Mixing Option Styles --------------------------- - -All three styles may be intermixed in a single `tar' command, so long -as the rules for each style are fully respected(1). Old style options -and either of the modern styles of options may be mixed within a single -`tar' command. However, old style options must be introduced as the -first arguments only, following the rule for old options (old options -must appear directly after the `tar' command and some white space). -Modern options may be given only after all arguments to the old options -have been collected. If this rule is not respected, a modern option -might be falsely interpreted as the value of the argument to one of the -old style options. - - For example, all the following commands are wholly equivalent, and -illustrate the many combinations and orderings of option styles. - - tar --create --file=archive.tar - tar --create -f archive.tar - tar --create -farchive.tar - tar --file=archive.tar --create - tar --file=archive.tar -c - tar -c --file=archive.tar - tar -c -f archive.tar - tar -c -farchive.tar - tar -cf archive.tar - tar -cfarchive.tar - tar -f archive.tar --create - tar -f archive.tar -c - tar -farchive.tar --create - tar -farchive.tar -c - tar c --file=archive.tar - tar c -f archive.tar - tar c -farchive.tar - tar cf archive.tar - tar f archive.tar --create - tar f archive.tar -c - tar fc archive.tar - - On the other hand, the following commands are _not_ equivalent to -the previous set: - - tar -f -c archive.tar - tar -fc archive.tar - tar -fcarchive.tar - tar -farchive.tarc - tar cfarchive.tar - -These last examples mean something completely different from what the -user intended (judging based on the example in the previous set which -uses long options, whose intent is therefore very clear). The first -four specify that the `tar' archive would be a file named `-c', `c', -`carchive.tar' or `archive.tarc', respectively. The first two examples -also specify a single non-option, NAME argument having the value -`archive.tar'. The last example contains only old style option letters -(repeating option `c' twice), not all of which are meaningful (eg., `.', -`h', or `i'), with no argument value. - - ---------- Footnotes ---------- - - (1) Before GNU `tar' version 1.11.6, a bug prevented intermixing old -style options with long options in some cases. - - -File: tar.info, Node: All Options, Next: help, Prev: Styles, Up: tar invocation - -3.4 All `tar' Options -===================== - -The coming manual sections contain an alphabetical listing of all `tar' -operations and options, with brief descriptions and cross references to -more in-depth explanations in the body of the manual. They also -contain an alphabetically arranged table of the short option forms with -their corresponding long option. You can use this table as a reference -for deciphering `tar' commands in scripts. - -* Menu: - -* Operation Summary:: -* Option Summary:: -* Short Option Summary:: - - -File: tar.info, Node: Operation Summary, Next: Option Summary, Up: All Options - -3.4.1 Operations ----------------- - -`--append' -`-r' - Appends files to the end of the archive. *Note append::. - -`--catenate' -`-A' - Same as `--concatenate'. *Note concatenate::. - -`--compare' -`-d' - Compares archive members with their counterparts in the file - system, and reports differences in file size, mode, owner, - modification date and contents. *Note compare::. - -`--concatenate' -`-A' - Appends other `tar' archives to the end of the archive. *Note - concatenate::. - -`--create' -`-c' - Creates a new `tar' archive. *Note create::. - -`--delete' - Deletes members from the archive. Don't try this on a archive on a - tape! *Note delete::. - -`--diff' -`-d' - Same `--compare'. *Note compare::. - -`--extract' -`-x' - Extracts members from the archive into the file system. *Note - extract::. - -`--get' -`-x' - Same as `--extract'. *Note extract::. - -`--list' -`-t' - Lists the members in an archive. *Note list::. - -`--update' -`-u' - Adds files to the end of the archive, but only if they are newer - than their counterparts already in the archive, or if they do not - already exist in the archive. *Note update::. - - - -File: tar.info, Node: Option Summary, Next: Short Option Summary, Prev: Operation Summary, Up: All Options - -3.4.2 `tar' Options -------------------- - -`--absolute-names' -`-P' - Normally when creating an archive, `tar' strips an initial `/' - from member names. This option disables that behavior. *Note - absolute::. - -`--after-date' - (See `--newer', *note after::) - -`--anchored' - A pattern must match an initial subsequence of the name's - components. *Note controlling pattern-matching::. - -`--atime-preserve' -`--atime-preserve=replace' -`--atime-preserve=system' - Attempt to preserve the access time of files when reading them. - This option currently is effective only on files that you own, - unless you have superuser privileges. - - `--atime-preserve=replace' remembers the access time of a file - before reading it, and then restores the access time afterwards. - This may cause problems if other programs are reading the file at - the same time, as the times of their accesses will be lost. On - most platforms restoring the access time also requires `tar' to - restore the data modification time too, so this option may also - cause problems if other programs are writing the file at the same - time. (Tar attempts to detect this situation, but cannot do so - reliably due to race conditions.) Worse, on most platforms - restoring the access time also updates the status change time, - which means that this option is incompatible with incremental - backups. - - `--atime-preserve=system' avoids changing time stamps on files, - without interfering with time stamp updates caused by other - programs, so it works better with incremental backups. However, - it requires a special `O_NOATIME' option from the underlying - operating and file system implementation, and it also requires - that searching directories does not update their access times. As - of this writing (November 2005) this works only with Linux, and - only with Linux kernels 2.6.8 and later. Worse, there is - currently no reliable way to know whether this feature actually - works. Sometimes `tar' knows that it does not work, and if you use - `--atime-preserve=system' then `tar' complains and exits right - away. But other times `tar' might think that the option works - when it actually does not. - - Currently `--atime-preserve' with no operand defaults to - `--atime-preserve=replace', but this may change in the future as - support for `--atime-preserve=system' improves. - - If your operating system does not support - `--atime-preserve=system', you might be able to preserve access - times reliably by by using the `mount' command. For example, you - can mount the file system read-only, or access the file system via - a read-only loopback mount, or use the `noatime' mount option - available on some systems. However, mounting typically requires - superuser privileges and can be a pain to manage. - -`--auto-compress' -`-a' - During a `--create' operation, enables automatic compressed format - recognition based on the archive suffix. *Note gzip::. - -`--backup=BACKUP-TYPE' - Rather than deleting files from the file system, `tar' will back - them up using simple or numbered backups, depending upon - BACKUP-TYPE. *Note backup::. - -`--block-number' -`-R' - With this option present, `tar' prints error messages for read - errors with the block number in the archive file. *Note - block-number::. - -`--blocking-factor=BLOCKING' -`-b BLOCKING' - Sets the blocking factor `tar' uses to BLOCKING x 512 bytes per - record. *Note Blocking Factor::. - -`--bzip2' -`-j' - This option tells `tar' to read or write archives through `bzip2'. - *Note gzip::. - -`--check-device' - Check device numbers when creating a list of modified files for - incremental archiving. This is the default. *Note device - numbers::, for a detailed description. - -`--checkpoint[=NUMBER]' - This option directs `tar' to print periodic checkpoint messages as - it reads through the archive. It is intended for when you want a - visual indication that `tar' is still running, but don't want to - see `--verbose' output. You can also instruct `tar' to execute a - list of actions on each checkpoint, see `--checklist-action' - below. For a detailed description, see *note checkpoints::. - -`--checkpoint-action=ACTION' - Instruct `tar' to execute an action upon hitting a breakpoint. - Here we give only a brief outline. *Note checkpoints::, for a - complete description. - - The ACTION argument can be one of the following: - - bell - Produce an audible bell on the console. - - dot - . - Print a single dot on the standard listing stream. - - echo - Display a textual message on the standard error, with the - status and number of the checkpoint. This is the default. - - echo=STRING - Display STRING on the standard error. Before output, the - string is subject to meta-character expansion. - - exec=COMMAND - Execute the given COMMAND. - - sleep=TIME - Wait for TIME seconds. - - ttyout=STRING - Output STRING on the current console (`/dev/tty'). - - Several `--checkpoint-action' options can be specified. The - supplied actions will be executed in order of their appearance in - the command line. - - Using `--checkpoint-action' without `--checkpoint' assumes default - checkpoint frequency of one checkpoint per 10 records. - -`--check-links' -`-l' - If this option was given, `tar' will check the number of links - dumped for each processed file. If this number does not match the - total number of hard links for the file, a warning message will be - output (1). - - *Note hard links::. - -`--compress' -`--uncompress' -`-Z' - `tar' will use the `compress' program when reading or writing the - archive. This allows you to directly act on archives while saving - space. *Note gzip::. - -`--confirmation' - (See `--interactive'.) *Note interactive::. - -`--delay-directory-restore' - Delay setting modification times and permissions of extracted - directories until the end of extraction. *Note Directory - Modification Times and Permissions::. - -`--dereference' -`-h' - When creating a `tar' archive, `tar' will archive the file that a - symbolic link points to, rather than archiving the symlink. *Note - dereference::. - -`--directory=DIR' -`-C DIR' - When this option is specified, `tar' will change its current - directory to DIR before performing any operations. When this - option is used during archive creation, it is order sensitive. - *Note directory::. - -`--exclude=PATTERN' - When performing operations, `tar' will skip files that match - PATTERN. *Note exclude::. - -`--exclude-from=FILE' -`-X FILE' - Similar to `--exclude', except `tar' will use the list of patterns - in the file FILE. *Note exclude::. - -`--exclude-caches' - Exclude from dump any directory containing a valid cache directory - tag file, but still dump the directory node and the tag file - itself. - - *Note exclude::. - -`--exclude-caches-under' - Exclude from dump any directory containing a valid cache directory - tag file, but still dump the directory node itself. - - *Note exclude::. - -`--exclude-caches-all' - Exclude from dump any directory containing a valid cache directory - tag file. *Note exclude::. - -`--exclude-tag=FILE' - Exclude from dump any directory containing file named FILE, but - dump the directory node and FILE itself. *Note exclude::. - -`--exclude-tag-under=FILE' - Exclude from dump the contents of any directory containing file - named FILE, but dump the directory node itself. *Note exclude::. - -`--exclude-tag-all=FILE' - Exclude from dump any directory containing file named FILE. *Note - exclude::. - -`--exclude-vcs' - Exclude from dump directories and files, that are internal for some - widely used version control systems. - - *Note exclude::. - -`--file=ARCHIVE' -`-f ARCHIVE' - `tar' will use the file ARCHIVE as the `tar' archive it performs - operations on, rather than `tar''s compilation dependent default. - *Note file tutorial::. - -`--files-from=FILE' -`-T FILE' - `tar' will use the contents of FILE as a list of archive members - or files to operate on, in addition to those specified on the - command-line. *Note files::. - -`--force-local' - Forces `tar' to interpret the file name given to `--file' as a - local file, even if it looks like a remote tape drive name. *Note - local and remote archives::. - -`--format=FORMAT' -`-H FORMAT' - Selects output archive format. FORMAT may be one of the following: - - `v7' - Creates an archive that is compatible with Unix V7 `tar'. - - `oldgnu' - Creates an archive that is compatible with GNU `tar' version - 1.12 or earlier. - - `gnu' - Creates archive in GNU tar 1.13 format. Basically it is the - same as `oldgnu' with the only difference in the way it - handles long numeric fields. - - `ustar' - Creates a POSIX.1-1988 compatible archive. - - `posix' - Creates a POSIX.1-2001 archive. - - - *Note Formats::, for a detailed discussion of these formats. - -`--group=GROUP' - Files added to the `tar' archive will have a group ID of GROUP, - rather than the group from the source file. GROUP is first decoded - as a group symbolic name, but if this interpretation fails, it has - to be a decimal numeric group ID. *Note override::. - - Also see the comments for the `--owner=USER' option. - -`--gzip' -`--gunzip' -`--ungzip' -`-z' - This option tells `tar' to read or write archives through `gzip', - allowing `tar' to directly operate on several kinds of compressed - archives transparently. *Note gzip::. - -`--hard-dereference' - When creating an archive, dereference hard links and store the - files they refer to, instead of creating usual hard link members. - - *Note hard links::. - -`--help' -`-?' - `tar' will print out a short message summarizing the operations and - options to `tar' and exit. *Note help::. - -`--ignore-case' - Ignore case when matching member or file names with patterns. - *Note controlling pattern-matching::. - -`--ignore-command-error' - Ignore exit codes of subprocesses. *Note Writing to an External - Program::. - -`--ignore-failed-read' - Do not exit unsuccessfully merely because an unreadable file was - encountered. *Note Reading::. - -`--ignore-zeros' -`-i' - With this option, `tar' will ignore zeroed blocks in the archive, - which normally signals EOF. *Note Reading::. - -`--incremental' -`-G' - Informs `tar' that it is working with an old GNU-format - incremental backup archive. It is intended primarily for - backwards compatibility only. *Note Incremental Dumps::, for a - detailed discussion of incremental archives. - -`--index-file=FILE' - Send verbose output to FILE instead of to standard output. - -`--info-script=SCRIPT-FILE' -`--new-volume-script=SCRIPT-FILE' -`-F SCRIPT-FILE' - When `tar' is performing multi-tape backups, SCRIPT-FILE is run at - the end of each tape. If SCRIPT-FILE exits with nonzero status, - `tar' fails immediately. *Note info-script::, for a detailed - discussion of SCRIPT-FILE. - -`--interactive' -`--confirmation' -`-w' - Specifies that `tar' should ask the user for confirmation before - performing potentially destructive options, such as overwriting - files. *Note interactive::. - -`--keep-newer-files' - Do not replace existing files that are newer than their archive - copies when extracting files from an archive. - -`--keep-old-files' -`-k' - Do not overwrite existing files when extracting files from an - archive. *Note Keep Old Files::. - -`--label=NAME' -`-V NAME' - When creating an archive, instructs `tar' to write NAME as a name - record in the archive. When extracting or listing archives, `tar' - will only operate on archives that have a label matching the - pattern specified in NAME. *Note Tape Files::. - -`--listed-incremental=SNAPSHOT-FILE' -`-g SNAPSHOT-FILE' - During a `--create' operation, specifies that the archive that - `tar' creates is a new GNU-format incremental backup, using - SNAPSHOT-FILE to determine which files to backup. With other - operations, informs `tar' that the archive is in incremental - format. *Note Incremental Dumps::. - -`--lzma' - This option tells `tar' to read or write archives through `lzma'. - *Note gzip::. - -`--mode=PERMISSIONS' - When adding files to an archive, `tar' will use PERMISSIONS for - the archive members, rather than the permissions from the files. - PERMISSIONS can be specified either as an octal number or as - symbolic permissions, like with `chmod'. *Note override::. - -`--mtime=DATE' - When adding files to an archive, `tar' will use DATE as the - modification time of members when creating archives, instead of - their actual modification times. The value of DATE can be either - a textual date representation (*note Date input formats::) or a - name of the existing file, starting with `/' or `.'. In the - latter case, the modification time of that file is used. *Note - override::. - -`--multi-volume' -`-M' - Informs `tar' that it should create or otherwise operate on a - multi-volume `tar' archive. *Note Using Multiple Tapes::. - -`--new-volume-script' - (see -info-script) - -`--newer=DATE' -`--after-date=DATE' -`-N' - When creating an archive, `tar' will only add files that have - changed since DATE. If DATE begins with `/' or `.', it is taken - to be the name of a file whose data modification time specifies - the date. *Note after::. - -`--newer-mtime=DATE' - Like `--newer', but add only files whose contents have changed (as - opposed to just `--newer', which will also back up files for which - any status information has changed). *Note after::. - -`--no-anchored' - An exclude pattern can match any subsequence of the name's - components. *Note controlling pattern-matching::. - -`--no-check-device' - Do not check device numbers when creating a list of modified files - for incremental archiving. *Note device numbers::, for a detailed - description. - -`--no-delay-directory-restore' - Modification times and permissions of extracted directories are - set when all files from this directory have been extracted. This - is the default. *Note Directory Modification Times and - Permissions::. - -`--no-ignore-case' - Use case-sensitive matching. *Note controlling pattern-matching::. - -`--no-ignore-command-error' - Print warnings about subprocesses that terminated with a nonzero - exit code. *Note Writing to an External Program::. - -`--no-overwrite-dir' - Preserve metadata of existing directories when extracting files - from an archive. *Note Overwrite Old Files::. - -`--no-quote-chars=STRING' - Remove characters listed in STRING from the list of quoted - characters set by the previous `--quote-chars' option (*note - quoting styles::). - -`--no-recursion' - With this option, `tar' will not recurse into directories. *Note - recurse::. - -`--no-same-owner' -`-o' - When extracting an archive, do not attempt to preserve the owner - specified in the `tar' archive. This the default behavior for - ordinary users. - -`--no-same-permissions' - When extracting an archive, subtract the user's umask from files - from the permissions specified in the archive. This is the - default behavior for ordinary users. - -`--no-unquote' - Treat all input file or member names literally, do not interpret - escape sequences. *Note input name quoting::. - -`--no-wildcards' - Do not use wildcards. *Note controlling pattern-matching::. - -`--no-wildcards-match-slash' - Wildcards do not match `/'. *Note controlling pattern-matching::. - -`--null' - When `tar' is using the `--files-from' option, this option - instructs `tar' to expect file names terminated with NUL, so `tar' - can correctly work with file names that contain newlines. *Note - nul::. - -`--numeric-owner' - This option will notify `tar' that it should use numeric user and - group IDs when creating a `tar' file, rather than names. *Note - Attributes::. - -`-o' - The function of this option depends on the action `tar' is - performing. When extracting files, `-o' is a synonym for - `--no-same-owner', i.e., it prevents `tar' from restoring - ownership of files being extracted. - - When creating an archive, it is a synonym for `--old-archive'. - This behavior is for compatibility with previous versions of GNU - `tar', and will be removed in future releases. - - *Note Changes::, for more information. - -`--occurrence[=NUMBER]' - This option can be used in conjunction with one of the subcommands - `--delete', `--diff', `--extract' or `--list' when a list of files - is given either on the command line or via `-T' option. - - This option instructs `tar' to process only the NUMBERth - occurrence of each named file. NUMBER defaults to 1, so - - tar -x -f archive.tar --occurrence filename - - will extract the first occurrence of the member `filename' from - `archive.tar' and will terminate without scanning to the end of - the archive. - -`--old-archive' - Synonym for `--format=v7'. - -`--one-file-system' - Used when creating an archive. Prevents `tar' from recursing into - directories that are on different file systems from the current - directory. - -`--overwrite' - Overwrite existing files and directory metadata when extracting - files from an archive. *Note Overwrite Old Files::. - -`--overwrite-dir' - Overwrite the metadata of existing directories when extracting - files from an archive. *Note Overwrite Old Files::. - -`--owner=USER' - Specifies that `tar' should use USER as the owner of members when - creating archives, instead of the user associated with the source - file. USER is first decoded as a user symbolic name, but if this - interpretation fails, it has to be a decimal numeric user ID. - *Note override::. - - This option does not affect extraction from archives. - -`--pax-option=KEYWORD-LIST' - This option is meaningful only with POSIX.1-2001 archives (*note - posix::). It modifies the way `tar' handles the extended header - keywords. KEYWORD-LIST is a comma-separated list of keyword - options. *Note PAX keywords::, for a detailed discussion. - -`--portability' -`--old-archive' - Synonym for `--format=v7'. - -`--posix' - Same as `--format=posix'. - -`--preserve' - Synonymous with specifying both `--preserve-permissions' and - `--same-order'. *Note Setting Access Permissions::. - -`--preserve-order' - (See `--same-order'; *note Reading::.) - -`--preserve-permissions' -`--same-permissions' -`-p' - When `tar' is extracting an archive, it normally subtracts the - users' umask from the permissions specified in the archive and uses - that number as the permissions to create the destination file. - Specifying this option instructs `tar' that it should use the - permissions directly from the archive. *Note Setting Access - Permissions::. - -`--quote-chars=STRING' - Always quote characters from STRING, even if the selected quoting - style would not quote them (*note quoting styles::). - -`--quoting-style=STYLE' - Set quoting style to use when printing member and file names - (*note quoting styles::). Valid STYLE values are: `literal', - `shell', `shell-always', `c', `escape', `locale', and `clocale'. - Default quoting style is `escape', unless overridden while - configuring the package. - -`--read-full-records' -`-B' - Specifies that `tar' should reblock its input, for reading from - pipes on systems with buggy implementations. *Note Reading::. - -`--record-size=SIZE' - Instructs `tar' to use SIZE bytes per record when accessing the - archive. *Note Blocking Factor::. - -`--recursion' - With this option, `tar' recurses into directories (default). - *Note recurse::. - -`--recursive-unlink' - Remove existing directory hierarchies before extracting - directories of the same name from the archive. *Note Recursive - Unlink::. - -`--remove-files' - Directs `tar' to remove the source file from the file system after - appending it to an archive. *Note remove files::. - -`--restrict' - Disable use of some potentially harmful `tar' options. Currently - this option disables shell invocation from multi-volume menu - (*note Using Multiple Tapes::). - -`--rmt-command=CMD' - Notifies `tar' that it should use CMD instead of the default - `/usr/libexec/rmt' (*note Remote Tape Server::). - -`--rsh-command=CMD' - Notifies `tar' that is should use CMD to communicate with remote - devices. *Note Device::. - -`--same-order' -`--preserve-order' -`-s' - This option is an optimization for `tar' when running on machines - with small amounts of memory. It informs `tar' that the list of - file arguments has already been sorted to match the order of files - in the archive. *Note Reading::. - -`--same-owner' - When extracting an archive, `tar' will attempt to preserve the - owner specified in the `tar' archive with this option present. - This is the default behavior for the superuser; this option has an - effect only for ordinary users. *Note Attributes::. - -`--same-permissions' - (See `--preserve-permissions'; *note Setting Access Permissions::.) - -`--seek' -`-n' - Assume that the archive media supports seeks to arbitrary - locations. Usually `tar' determines automatically whether the - archive can be seeked or not. This option is intended for use in - cases when such recognition fails. - -`--show-defaults' - Displays the default options used by `tar' and exits successfully. - This option is intended for use in shell scripts. Here is an - example of what you can see using this option: - - $ tar --show-defaults - --format=gnu -f- -b20 --quoting-style=escape \ - --rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh - -`--show-omitted-dirs' - Instructs `tar' to mention the directories it is skipping when - operating on a `tar' archive. *Note show-omitted-dirs::. - -`--show-transformed-names' -`--show-stored-names' - Display file or member names after applying any transformations - (*note transform::). In particular, when used in conjunction with - one of the archive creation operations it instructs `tar' to list - the member names stored in the archive, as opposed to the actual - file names. *Note listing member and file names::. - -`--sparse' -`-S' - Invokes a GNU extension when adding files to an archive that - handles sparse files efficiently. *Note sparse::. - -`--sparse-version=VERSION' - Specifies the "format version" to use when archiving sparse files. - Implies `--sparse'. *Note sparse::. For the description of the - supported sparse formats, *Note Sparse Formats::. - -`--starting-file=NAME' -`-K NAME' - This option affects extraction only; `tar' will skip extracting - files in the archive until it finds one that matches NAME. *Note - Scarce::. - -`--strip-components=NUMBER' - Strip given NUMBER of leading components from file names before - extraction. For example, if archive `archive.tar' contained - `/some/file/name', then running - - tar --extract --file archive.tar --strip-components=2 - - would extract this file to file `name'. - - , summary - -`--suffix=SUFFIX' - Alters the suffix `tar' uses when backing up files from the default - `~'. *Note backup::. - -`--tape-length=NUM' -`-L NUM' - Specifies the length of tapes that `tar' is writing as being - NUM x 1024 bytes long. *Note Using Multiple Tapes::. - -`--test-label' - Reads the volume label. If an argument is specified, test whether - it matches the volume label. *Note --test-label option::. - -`--to-command=COMMAND' - During extraction `tar' will pipe extracted files to the standard - input of COMMAND. *Note Writing to an External Program::. - -`--to-stdout' -`-O' - During extraction, `tar' will extract files to stdout rather than - to the file system. *Note Writing to Standard Output::. - -`--totals[=SIGNO]' - Displays the total number of bytes transferred when processing an - archive. If an argument is given, these data are displayed on - request, when signal SIGNO is delivered to `tar'. *Note totals::. - -`--touch' -`-m' - Sets the data modification time of extracted files to the - extraction time, rather than the data modification time stored in - the archive. *Note Data Modification Times::. - -`--transform=SED-EXPR' - Transform file or member names using `sed' replacement expression - SED-EXPR. For example, - - $ tar cf archive.tar --transform 's,^\./,usr/,' . - - will add to `archive' files from the current working directory, - replacing initial `./' prefix with `usr/'. For the detailed - discussion, *Note transform::. - - To see transformed member names in verbose listings, use - `--show-transformed-names' option (*note show-transformed-names::). - -`--uncompress' - (See `--compress'. *note gzip::) - -`--ungzip' - (See `--gzip'. *note gzip::) - -`--unlink-first' -`-U' - Directs `tar' to remove the corresponding file from the file - system before extracting it from the archive. *Note Unlink - First::. - -`--unquote' - Enable unquoting input file or member names (default). *Note - input name quoting::. - -`--use-compress-program=PROG' - Instructs `tar' to access the archive through PROG, which is - presumed to be a compression program of some sort. *Note gzip::. - -`--utc' - Display file modification dates in UTC. This option implies - `--verbose'. - -`--verbose' -`-v' - Specifies that `tar' should be more verbose about the operations - it is performing. This option can be specified multiple times for - some operations to increase the amount of information displayed. - *Note verbose::. - -`--verify' -`-W' - Verifies that the archive was correctly written when creating an - archive. *Note verify::. - -`--version' - Print information about the program's name, version, origin and - legal status, all on standard output, and then exit successfully. - *Note help::. - -`--volno-file=FILE' - Used in conjunction with `--multi-volume'. `tar' will keep track - of which volume of a multi-volume archive it is working in FILE. - *Note volno-file::. - -`--wildcards' - Use wildcards when matching member names with patterns. *Note - controlling pattern-matching::. - -`--wildcards-match-slash' - Wildcards match `/'. *Note controlling pattern-matching::. - - ---------- Footnotes ---------- - - (1) Earlier versions of GNU `tar' understood `-l' as a synonym for -`--one-file-system'. The current semantics, which complies to UNIX98, -was introduced with version 1.15.91. *Note Changes::, for more -information. - - -File: tar.info, Node: Short Option Summary, Prev: Option Summary, Up: All Options - -3.4.3 Short Options Cross Reference ------------------------------------ - -Here is an alphabetized list of all of the short option forms, matching -them with the equivalent long option. - -Short Option Reference --------------------------------------------------------------------------- --A *note --concatenate::. --B *note --read-full-records::. --C *note --directory::. --F *note --info-script::. --G *note --incremental::. --K *note --starting-file::. --L *note --tape-length::. --M *note --multi-volume::. --N *note --newer::. --O *note --to-stdout::. --P *note --absolute-names::. --R *note --block-number::. --S *note --sparse::. --T *note --files-from::. --U *note --unlink-first::. --V *note --label::. --W *note --verify::. --X *note --exclude-from::. --Z *note --compress::. --b *note --blocking-factor::. --c *note --create::. --d *note --compare::. --f *note --file::. --g *note --listed-incremental::. --h *note --dereference::. --i *note --ignore-zeros::. --j *note --bzip2::. --k *note --keep-old-files::. --l *note --check-links::. --m *note --touch::. --o When creating, *note --no-same-owner::, when extracting -- - *note --portability::. - - The later usage is deprecated. It is retained for - compatibility with the earlier versions of GNU `tar'. In - future releases `-o' will be equivalent to - `--no-same-owner' only. --p *note --preserve-permissions::. --r *note --append::. --s *note --same-order::. --t *note --list::. --u *note --update::. --v *note --verbose::. --w *note --interactive::. --x *note --extract::. --z *note --gzip::. - - -File: tar.info, Node: help, Next: defaults, Prev: All Options, Up: tar invocation - -3.5 GNU `tar' documentation -=========================== - -Being careful, the first thing is really checking that you are using -GNU `tar', indeed. The `--version' option causes `tar' to print -information about its name, version, origin and legal status, all on -standard output, and then exit successfully. For example, -`tar --version' might print: - - tar (GNU tar) 1.20 - Copyright (C) 2008 Free Software Foundation, Inc. - This is free software. You may redistribute copies of it under the terms - of the GNU General Public License . - There is NO WARRANTY, to the extent permitted by law. - - Written by John Gilmore and Jay Fenlason. - -The first occurrence of `tar' in the result above is the program name -in the package (for example, `rmt' is another program), while the -second occurrence of `tar' is the name of the package itself, -containing possibly many programs. The package is currently named -`tar', after the name of the main program it contains(1). - - Another thing you might want to do is checking the spelling or -meaning of some particular `tar' option, without resorting to this -manual, for once you have carefully read it. GNU `tar' has a short -help feature, triggerable through the `--help' option. By using this -option, `tar' will print a usage message listing all available options -on standard output, then exit successfully, without doing anything else -and ignoring all other options. Even if this is only a brief summary, -it may be several screens long. So, if you are not using some kind of -scrollable window, you might prefer to use something like: - - $ tar --help | less - -presuming, here, that you like using `less' for a pager. Other popular -pagers are `more' and `pg'. If you know about some KEYWORD which -interests you and do not want to read all the `--help' output, another -common idiom is doing: - - tar --help | grep KEYWORD - -for getting only the pertinent lines. Notice, however, that some `tar' -options have long description lines and the above command will list -only the first of them. - - The exact look of the option summary displayed by `tar --help' is -configurable. *Note Configuring Help Summary::, for a detailed -description. - - If you only wish to check the spelling of an option, running `tar ---usage' may be a better choice. This will display a terse list of -`tar' option without accompanying explanations. - - The short help output is quite succinct, and you might have to get -back to the full documentation for precise points. If you are reading -this paragraph, you already have the `tar' manual in some form. This -manual is available in a variety of forms from -`http://www.gnu.org/software/tar/manual'. It may be printed out of the -GNU `tar' distribution, provided you have TeX already installed -somewhere, and a laser printer around. Just configure the -distribution, execute the command `make dvi', then print `doc/tar.dvi' -the usual way (contact your local guru to know how). If GNU `tar' has -been conveniently installed at your place, this manual is also -available in interactive, hypertextual form as an Info file. Just call -`info tar' or, if you do not have the `info' program handy, use the -Info reader provided within GNU Emacs, calling `tar' from the main Info -menu. - - There is currently no `man' page for GNU `tar'. If you observe such -a `man' page on the system you are running, either it does not belong -to GNU `tar', or it has not been produced by GNU. Some package -maintainers convert `tar --help' output to a man page, using -`help2man'. In any case, please bear in mind that the authoritative -source of information about GNU `tar' is this Texinfo documentation. - - ---------- Footnotes ---------- - - (1) There are plans to merge the `cpio' and `tar' packages into a -single one which would be called `paxutils'. So, who knows if, one of -this days, the `--version' would not output `tar (GNU paxutils) 3.2' - - -File: tar.info, Node: defaults, Next: verbose, Prev: help, Up: tar invocation - -3.6 Obtaining GNU `tar' default values -====================================== - -GNU `tar' has some predefined defaults that are used when you do not -explicitly specify another values. To obtain a list of such defaults, -use `--show-defaults' option. This will output the values in the form -of `tar' command line options: - - tar --show-defaults - --format=gnu -f- -b20 --quoting-style=escape - --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh - -Notice, that this option outputs only one line. The example output -above has been split to fit page boundaries. - -The above output shows that this version of GNU `tar' defaults to using -`gnu' archive format (*note Formats::), it uses standard output as the -archive, if no `--file' option has been given (*note file tutorial::), -the default blocking factor is 20 (*note Blocking Factor::). It also -shows the default locations where `tar' will look for `rmt' and `rsh' -binaries. - - -File: tar.info, Node: verbose, Next: checkpoints, Prev: defaults, Up: tar invocation - -3.7 Checking `tar' progress -=========================== - -Typically, `tar' performs most operations without reporting any -information to the user except error messages. When using `tar' with -many options, particularly ones with complicated or -difficult-to-predict behavior, it is possible to make serious mistakes. -`tar' provides several options that make observing `tar' easier. These -options cause `tar' to print information as it progresses in its job, -and you might want to use them just for being more careful about what -is going on, or merely for entertaining yourself. If you have -encountered a problem when operating on an archive, however, you may -need more information than just an error message in order to solve the -problem. The following options can be helpful diagnostic tools. - - Normally, the `--list' (`-t') command to list an archive prints just -the file names (one per line) and the other commands are silent. When -used with most operations, the `--verbose' (`-v') option causes `tar' -to print the name of each file or archive member as it is processed. -This and the other options which make `tar' print status information -can be useful in monitoring `tar'. - - With `--create' or `--extract', `--verbose' used once just prints -the names of the files or members as they are processed. Using it -twice causes `tar' to print a longer listing (*Note verbose member -listing::, for the description) for each member. Since `--list' -already prints the names of the members, `--verbose' used once with -`--list' causes `tar' to print an `ls -l' type listing of the files in -the archive. The following examples both extract members with long -list output: - - $ tar --extract --file=archive.tar --verbose --verbose - $ tar xvvf archive.tar - - Verbose output appears on the standard output except when an archive -is being written to the standard output, as with `tar --create --file=- ---verbose' (`tar cfv -', or even `tar cv'--if the installer let -standard output be the default archive). In that case `tar' writes -verbose output to the standard error stream. - - If `--index-file=FILE' is specified, `tar' sends verbose output to -FILE rather than to standard output or standard error. - - The `--totals' option causes `tar' to print on the standard error -the total amount of bytes transferred when processing an archive. When -creating or appending to an archive, this option prints the number of -bytes written to the archive and the average speed at which they have -been written, e.g.: - - $ tar -c -f archive.tar --totals /home - Total bytes written: 7924664320 (7.4GiB, 85MiB/s) - - When reading an archive, this option displays the number of bytes -read: - - $ tar -x -f archive.tar --totals - Total bytes read: 7924664320 (7.4GiB, 95MiB/s) - - Finally, when deleting from an archive, the `--totals' option -displays both numbers plus number of bytes removed from the archive: - - $ tar --delete -f foo.tar --totals --wildcards '*~' - Total bytes read: 9543680 (9.2MiB, 201MiB/s) - Total bytes written: 3829760 (3.7MiB, 81MiB/s) - Total bytes deleted: 1474048 - - You can also obtain this information on request. When `--totals' is -used with an argument, this argument is interpreted as a symbolic name -of a signal, upon delivery of which the statistics is to be printed: - -`--totals=SIGNO' - Print statistics upon delivery of signal SIGNO. Valid arguments - are: `SIGHUP', `SIGQUIT', `SIGINT', `SIGUSR1' and `SIGUSR2'. - Shortened names without `SIG' prefix are also accepted. - - Both forms of `--totals' option can be used simultaneously. Thus, -`tar -x --totals --totals=USR1' instructs `tar' to extract all members -from its default archive and print statistics after finishing the -extraction, as well as when receiving signal `SIGUSR1'. - - The `--checkpoint' option prints an occasional message as `tar' -reads or writes the archive. It is designed for those who don't need -the more detailed (and voluminous) output of `--block-number' (`-R'), -but do want visual confirmation that `tar' is actually making forward -progress. By default it prints a message each 10 records read or -written. This can be changed by giving it a numeric argument after an -equal sign: - - $ tar -c --checkpoint=1000 /var - tar: Write checkpoint 1000 - tar: Write checkpoint 2000 - tar: Write checkpoint 3000 - - This example shows the default checkpoint message used by `tar'. If -you place a dot immediately after the equal sign, it will print a `.' -at each checkpoint(1). For example: - - $ tar -c --checkpoint=.1000 /var - ... - - The `--checkpoint' option provides a flexible mechanism for -executing arbitrary actions upon hitting checkpoints, see the next -section (*note checkpoints::), for more information on it. - - The `--show-omitted-dirs' option, when reading an archive--with -`--list' or `--extract', for example--causes a message to be printed -for each directory in the archive which is skipped. This happens -regardless of the reason for skipping: the directory might not have -been named on the command line (implicitly or explicitly), it might be -excluded by the use of the `--exclude=PATTERN' option, or some other -reason. - - If `--block-number' (`-R') is used, `tar' prints, along with every -message it would normally produce, the block number within the archive -where the message was triggered. Also, supplementary messages are -triggered when reading blocks full of NULs, or when hitting end of file -on the archive. As of now, if the archive if properly terminated with -a NUL block, the reading of the file may stop before end of file is -met, so the position of end of file will not usually show when -`--block-number' (`-R') is used. Note that GNU `tar' drains the -archive before exiting when reading the archive from a pipe. - - This option is especially useful when reading damaged archives, since -it helps pinpoint the damaged sections. It can also be used with -`--list' (`-t') when listing a file-system backup tape, allowing you to -choose among several backup tapes when retrieving a file later, in -favor of the tape where the file appears earliest (closest to the front -of the tape). *Note backup::. - - ---------- Footnotes ---------- - - (1) This is actually a shortcut for `--checkpoint=N ---checkpoint-action=dot'. *Note dot: checkpoints. - - -File: tar.info, Node: checkpoints, Next: interactive, Prev: verbose, Up: tar invocation - -3.8 Checkpoints -=============== - -A "checkpoint" is a moment of time before writing Nth record to the -archive (a "write checkpoint"), or before reading Nth record from the -archive (a "read checkpoint"). Checkpoints allow to periodically -execute arbitrary actions. - - The checkpoint facility is enabled using the following option: - -`--checkpoint[=N]' - Schedule checkpoints before writing or reading each Nth record. - The default value for N is 10. - - A list of arbitrary "actions" can be executed at each checkpoint. -These actions include: pausing, displaying textual messages, and -executing arbitrary external programs. Actions are defined using the -`--checkpoint-action' option. - -`--checkpoint-action=ACTION' - Execute an ACTION at each checkpoint. - - The simplest value of ACTION is `echo'. It instructs `tar' to -display the default message on the standard error stream upon arriving -at each checkpoint. The default message is (in POSIX locale) `Write -checkpoint N', for write checkpoints, and `Read checkpoint N', for read -checkpoints. Here, N represents ordinal number of the checkpoint. - - In another locales, translated versions of this message are used. - - This is the default action, so running: - - $ tar -c --checkpoint=1000 --checkpoint-action=echo /var - -is equivalent to: - - $ tar -c --checkpoint=1000 /var - - The `echo' action also allows to supply a customized message. You -do so by placing an equals sign and the message right after it, e.g.: - - --checkpoint-action="echo=Hit %s checkpoint #%u" - - The `%s' and `%u' in the above example are "meta-characters". The -`%s' meta-character is replaced with the "type" of the checkpoint: -`write' or `read' (or a corresponding translated version in locales -other than POSIX). The `%u' meta-character is replaced with the -ordinal number of the checkpoint. Thus, the above example could -produce the following output when used with the `--create' option: - - tar: Hit write checkpoint #10 - tar: Hit write checkpoint #20 - tar: Hit write checkpoint #30 - - Aside from meta-character expansion, the message string is subject to -"unquoting", during which the backslash "escape sequences" are replaced -with their corresponding ASCII characters (*note escape sequences::). -E.g. the following action will produce an audible bell and the message -described above at each checkpoint: - - --checkpoint-action='echo=\aHit %s checkpoint #%u' - - There is also a special action which produces an audible signal: -`bell'. It is not equivalent to `echo='\a'', because `bell' sends the -bell directly to the console (`/dev/tty'), whereas `echo='\a'' sends it -to the standard error. - - The `ttyout=STRING' action outputs STRING to `/dev/tty', so it can -be used even if the standard output is redirected elsewhere. The -STRING is subject to the same modifications as with `echo' action. In -contrast to the latter, `ttyout' does not prepend `tar' executable name -to the string, nor does it output a newline after it. For example, the -following action will print the checkpoint message at the same screen -line, overwriting any previous message: - - --checkpoint-action="ttyout=\rHit %s checkpoint #%u" - - Another available checkpoint action is `dot' (or `.'). It instructs -`tar' to print a single dot on the standard listing stream, e.g.: - - $ tar -c --checkpoint=1000 --checkpoint-action=dot /var - ... - - For compatibility with previous GNU `tar' versions, this action can -be abbreviated by placing a dot in front of the checkpoint frequency, -as shown in the previous section. - - Yet another action, `sleep', pauses `tar' for a specified amount of -seconds. The following example will stop for 30 seconds at each -checkpoint: - - $ tar -c --checkpoint=1000 --checkpoint-action=sleep=30 - - Finally, the `exec' action executes a given external program. For -example: - - $ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint - - This program is executed using `/bin/sh -c', with no additional -arguments. Its exit code is ignored. It gets a copy of `tar''s -environment plus the following variables: - -`TAR_VERSION' - GNU `tar' version number. - -`TAR_ARCHIVE' - The name of the archive `tar' is processing. - -`TAR_BLOCKING_FACTOR' - Current blocking factor (*note Blocking::. - -`TAR_CHECKPOINT' - The checkpoint number. - -`TAR_SUBCOMMAND' - A short option describing the operation `tar' is executing *Note - Operations::, for a complete list of subcommand options. - -`TAR_FORMAT' - Format of the archive being processed. *Note Formats::, for a - complete list of archive format names. - - Any number of actions can be defined, by supplying several -`--checkpoint-action' options in the command line. For example, the -command below displays two messages, pauses execution for 30 seconds -and executes the `/sbin/cpoint' script: - - $ tar -c -f arc.tar \ - --checkpoint-action='\aecho=Hit %s checkpoint #%u' \ - --checkpoint-action='echo=Sleeping for 30 seconds' \ - --checkpoint-action='sleep=30' \ - --checkpoint-action='exec=/sbin/cpoint' - - This example also illustrates the fact that `--checkpoint-action' -can be used without `--checkpoint'. In this case, the default -checkpoint frequency (at each 10th record) is assumed. - - -File: tar.info, Node: interactive, Prev: checkpoints, Up: tar invocation - -3.9 Asking for Confirmation During Operations -============================================= - -Typically, `tar' carries out a command without stopping for further -instructions. In some situations however, you may want to exclude some -files and archive members from the operation (for instance if disk or -storage space is tight). You can do this by excluding certain files -automatically (*note Choosing::), or by performing an operation -interactively, using the `--interactive' (`-w') option. `tar' also -accepts `--confirmation' for this option. - - When the `--interactive' (`-w') option is specified, before reading, -writing, or deleting files, `tar' first prints a message for each such -file, telling what operation it intends to take, then asks for -confirmation on the terminal. The actions which require confirmation -include adding a file to the archive, extracting a file from the -archive, deleting a file from the archive, and deleting a file from -disk. To confirm the action, you must type a line of input beginning -with `y'. If your input line begins with anything other than `y', -`tar' skips that file. - - If `tar' is reading the archive from the standard input, `tar' opens -the file `/dev/tty' to support the interactive communications. - - Verbose output is normally sent to standard output, separate from -other error messages. However, if the archive is produced directly on -standard output, then verbose output is mixed with errors on `stderr'. -Producing the archive on standard output may be used as a way to avoid -using disk space, when the archive is soon to be consumed by another -process reading it, say. Some people felt the need of producing an -archive on stdout, still willing to segregate between verbose output -and error output. A possible approach would be using a named pipe to -receive the archive, and having the consumer process to read from that -named pipe. This has the advantage of letting standard output free to -receive verbose output, all separate from errors. - - -File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top - -4 GNU `tar' Operations -********************** - -* Menu: - -* Basic tar:: -* Advanced tar:: -* create options:: -* extract options:: -* backup:: -* Applications:: -* looking ahead:: - - -File: tar.info, Node: Basic tar, Next: Advanced tar, Up: operations - -4.1 Basic GNU `tar' Operations -============================== - -The basic `tar' operations, `--create' (`-c'), `--list' (`-t') and -`--extract' (`--get', `-x'), are currently presented and described in -the tutorial chapter of this manual. This section provides some -complementary notes for these operations. - -`--create' -`-c' - Creating an empty archive would have some kind of elegance. One - can initialize an empty archive and later use `--append' (`-r') - for adding all members. Some applications would not welcome - making an exception in the way of adding the first archive member. - On the other hand, many people reported that it is dangerously - too easy for `tar' to destroy a magnetic tape with an empty - archive(1). The two most common errors are: - - 1. Mistakingly using `create' instead of `extract', when the - intent was to extract the full contents of an archive. This - error is likely: keys `c' and `x' are right next to each - other on the QWERTY keyboard. Instead of being unpacked, the - archive then gets wholly destroyed. When users speak about - "exploding" an archive, they usually mean something else :-). - - 2. Forgetting the argument to `file', when the intent was to - create an archive with a single file in it. This error is - likely because a tired user can easily add the `f' key to the - cluster of option letters, by the mere force of habit, - without realizing the full consequence of doing so. The - usual consequence is that the single file, which was meant to - be saved, is rather destroyed. - - So, recognizing the likelihood and the catastrophic nature of these - errors, GNU `tar' now takes some distance from elegance, and - cowardly refuses to create an archive when `--create' option is - given, there are no arguments besides options, and `--files-from' - (`-T') option is _not_ used. To get around the cautiousness of - GNU `tar' and nevertheless create an archive with nothing in it, - one may still use, as the value for the `--files-from' option, a - file with no names in it, as shown in the following commands: - - tar --create --file=empty-archive.tar --files-from=/dev/null - tar cfT empty-archive.tar /dev/null - -`--extract' -`--get' -`-x' - A socket is stored, within a GNU `tar' archive, as a pipe. - -``--list' (`-t')' - GNU `tar' now shows dates as `1996-08-30', while it used to show - them as `Aug 30 1996'. Preferably, people should get used to ISO - 8601 dates. Local American dates should be made available again - with full date localization support, once ready. In the meantime, - programs not being localizable for dates should prefer - international dates, that's really the way to go. - - Look up `http://www.cl.cam.ac.uk/~mgk25/iso-time.html' if you are - curious, it contains a detailed explanation of the ISO 8601 - standard. - - - ---------- Footnotes ---------- - - (1) This is well described in `Unix-haters Handbook', by Simson -Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN -1-56884-203-1. - - -File: tar.info, Node: Advanced tar, Next: create options, Prev: Basic tar, Up: operations - -4.2 Advanced GNU `tar' Operations -================================= - -Now that you have learned the basics of using GNU `tar', you may want -to learn about further ways in which `tar' can help you. - - This chapter presents five, more advanced operations which you -probably won't use on a daily basis, but which serve more specialized -functions. We also explain the different styles of options and why you -might want to use one or another, or a combination of them in your `tar' -commands. Additionally, this chapter includes options which allow you -to define the output from `tar' more carefully, and provide help and -error correction in special circumstances. - -* Menu: - -* Operations:: -* append:: -* update:: -* concatenate:: -* delete:: -* compare:: - - -File: tar.info, Node: Operations, Next: append, Up: Advanced tar - -4.2.1 The Five Advanced `tar' Operations ----------------------------------------- - - _(This message will disappear, once this node revised.)_ - -In the last chapter, you learned about the first three operations to -`tar'. This chapter presents the remaining five operations to `tar': -`--append', `--update', `--concatenate', `--delete', and `--compare'. - - You are not likely to use these operations as frequently as those -covered in the last chapter; however, since they perform specialized -functions, they are quite useful when you do need to use them. We will -give examples using the same directory and files that you created in -the last chapter. As you may recall, the directory is called -`practice', the files are `jazz', `blues', `folk', `rock', and the two -archive files you created are `collection.tar' and `music.tar'. - - We will also use the archive files `afiles.tar' and `bfiles.tar'. -The archive `afiles.tar' contains the members `apple', `angst', and -`aspic'; `bfiles.tar' contains the members `./birds', `baboon', and -`./box'. - - Unless we state otherwise, all practicing you do and examples you -follow in this chapter will take place in the `practice' directory that -you created in the previous chapter; see *note prepare for examples::. -(Below in this section, we will remind you of the state of the examples -where the last chapter left them.) - - The five operations that we will cover in this chapter are: - -`--append' -`-r' - Add new entries to an archive that already exists. - -`--update' -`-r' - Add more recent copies of archive members to the end of an - archive, if they exist. - -`--concatenate' -`--catenate' -`-A' - Add one or more pre-existing archives to the end of another - archive. - -`--delete' - Delete items from an archive (does not work on tapes). - -`--compare' -`--diff' -`-d' - Compare archive members to their counterparts in the file system. - - -File: tar.info, Node: append, Next: update, Prev: Operations, Up: Advanced tar - -4.2.2 How to Add Files to Existing Archives: `--append' -------------------------------------------------------- - - _(This message will disappear, once this node revised.)_ - -If you want to add files to an existing archive, you don't need to -create a new archive; you can use `--append' (`-r'). The archive must -already exist in order to use `--append'. (A related operation is the -`--update' operation; you can use this to add newer versions of archive -members to an existing archive. To learn how to do this with -`--update', *note update::.) - - If you use `--append' to add a file that has the same name as an -archive member to an archive containing that archive member, then the -old member is not deleted. What does happen, however, is somewhat -complex. `tar' _allows_ you to have infinite number of files with the -same name. Some operations treat these same-named members no -differently than any other set of archive members: for example, if you -view an archive with `--list' (`-t'), you will see all of those members -listed, with their data modification times, owners, etc. - - Other operations don't deal with these members as perfectly as you -might prefer; if you were to use `--extract' to extract the archive, -only the most recently added copy of a member with the same name as four -other members would end up in the working directory. This is because -`--extract' extracts an archive in the order the members appeared in -the archive; the most recently archived members will be extracted last. -Additionally, an extracted member will _replace_ a file of the same -name which existed in the directory already, and `tar' will not prompt -you about this(1). Thus, only the most recently archived member will -end up being extracted, as it will replace the one extracted before it, -and so on. - - There exists a special option that allows you to get around this -behavior and extract (or list) only a particular copy of the file. -This is `--occurrence' option. If you run `tar' with this option, it -will extract only the first copy of the file. You may also give this -option an argument specifying the number of copy to be extracted. -Thus, for example if the archive `archive.tar' contained three copies -of file `myfile', then the command - - tar --extract --file archive.tar --occurrence=2 myfile - -would extract only the second copy. *Note --occurrence: Option -Summary, for the description of `--occurrence' option. - - If you want to replace an archive member, use `--delete' to delete -the member you want to remove from the archive, , and then use -`--append' to add the member you want to be in the archive. Note that -you can not change the order of the archive; the most recently added -member will still appear last. In this sense, you cannot truly -"replace" one member with another. (Replacing one member with another -will not work on certain types of media, such as tapes; see *note -delete:: and *note Media::, for more information.) - -* Menu: - -* appending files:: Appending Files to an Archive -* multiple:: - - ---------- Footnotes ---------- - - (1) Unless you give it `--keep-old-files' option, or the disk copy -is newer than the the one in the archive and you invoke `tar' with -`--keep-newer-files' option - - -File: tar.info, Node: appending files, Next: multiple, Up: append - -4.2.2.1 Appending Files to an Archive -..................................... - - _(This message will disappear, once this node revised.)_ - -The simplest way to add a file to an already existing archive is the -`--append' (`-r') operation, which writes specified files into the -archive whether or not they are already among the archived files. - - When you use `--append', you _must_ specify file name arguments, as -there is no default. If you specify a file that already exists in the -archive, another copy of the file will be added to the end of the -archive. As with other operations, the member names of the newly added -files will be exactly the same as their names given on the command -line. The `--verbose' (`-v') option will print out the names of the -files as they are written into the archive. - - `--append' cannot be performed on some tape drives, unfortunately, -due to deficiencies in the formats those tape drives use. The archive -must be a valid `tar' archive, or else the results of using this -operation will be unpredictable. *Note Media::. - - To demonstrate using `--append' to add a file to an archive, create -a file called `rock' in the `practice' directory. Make sure you are in -the `practice' directory. Then, run the following `tar' command to add -`rock' to `collection.tar': - - $ tar --append --file=collection.tar rock - -If you now use the `--list' (`-t') operation, you will see that `rock' -has been added to the archive: - - $ tar --list --file=collection.tar - -rw-r--r-- me user 28 1996-10-18 16:31 jazz - -rw-r--r-- me user 21 1996-09-23 16:44 blues - -rw-r--r-- me user 20 1996-09-23 16:44 folk - -rw-r--r-- me user 20 1996-09-23 16:44 rock - - -File: tar.info, Node: multiple, Prev: appending files, Up: append - -4.2.2.2 Multiple Members with the Same Name -........................................... - -You can use `--append' (`-r') to add copies of files which have been -updated since the archive was created. (However, we do not recommend -doing this since there is another `tar' option called `--update'; *Note -update::, for more information. We describe this use of `--append' -here for the sake of completeness.) When you extract the archive, the -older version will be effectively lost. This works because files are -extracted from an archive in the order in which they were archived. -Thus, when the archive is extracted, a file archived later in time will -replace a file of the same name which was archived earlier, even though -the older version of the file will remain in the archive unless you -delete all versions of the file. - - Supposing you change the file `blues' and then append the changed -version to `collection.tar'. As you saw above, the original `blues' is -in the archive `collection.tar'. If you change the file and append the -new version of the file to the archive, there will be two copies in the -archive. When you extract the archive, the older version of the file -will be extracted first, and then replaced by the newer version when it -is extracted. - - You can append the new, changed copy of the file `blues' to the -archive in this way: - - $ tar --append --verbose --file=collection.tar blues - blues - -Because you specified the `--verbose' option, `tar' has printed the -name of the file being appended as it was acted on. Now list the -contents of the archive: - - $ tar --list --verbose --file=collection.tar - -rw-r--r-- me user 28 1996-10-18 16:31 jazz - -rw-r--r-- me user 21 1996-09-23 16:44 blues - -rw-r--r-- me user 20 1996-09-23 16:44 folk - -rw-r--r-- me user 20 1996-09-23 16:44 rock - -rw-r--r-- me user 58 1996-10-24 18:30 blues - -The newest version of `blues' is now at the end of the archive (note -the different creation dates and file sizes). If you extract the -archive, the older version of the file `blues' will be replaced by the -newer version. You can confirm this by extracting the archive and -running `ls' on the directory. - - If you wish to extract the first occurrence of the file `blues' from -the archive, use `--occurrence' option, as shown in the following -example: - - $ tar --extract -vv --occurrence --file=collection.tar blues - -rw-r--r-- me user 21 1996-09-23 16:44 blues - - *Note Writing::, for more information on `--extract' and *Note --occurrence: Option Summary, for the description of `--occurrence' -option. - - -File: tar.info, Node: update, Next: concatenate, Prev: append, Up: Advanced tar - -4.2.3 Updating an Archive -------------------------- - - _(This message will disappear, once this node revised.)_ - -In the previous section, you learned how to use `--append' to add a -file to an existing archive. A related operation is `--update' (`-u'). -The `--update' operation updates a `tar' archive by comparing the date -of the specified archive members against the date of the file with the -same name. If the file has been modified more recently than the -archive member, then the newer version of the file is added to the -archive (as with `--append'). - - Unfortunately, you cannot use `--update' with magnetic tape drives. -The operation will fail. - - Both `--update' and `--append' work by adding to the end of the -archive. When you extract a file from the archive, only the version -stored last will wind up in the file system, unless you use the -`--backup' option. *Note multiple::, for a detailed discussion. - -* Menu: - -* how to update:: - - -File: tar.info, Node: how to update, Up: update - -4.2.3.1 How to Update an Archive Using `--update' -................................................. - -You must use file name arguments with the `--update' (`-u') operation. -If you don't specify any files, `tar' won't act on any files and won't -tell you that it didn't do anything (which may end up confusing you). - - To see the `--update' option at work, create a new file, -`classical', in your practice directory, and some extra text to the -file `blues', using any text editor. Then invoke `tar' with the -`update' operation and the `--verbose' (`-v') option specified, using -the names of all the files in the practice directory as file name -arguments: - - $ tar --update -v -f collection.tar blues folk rock classical - blues - classical - $ - -Because we have specified verbose mode, `tar' prints out the names of -the files it is working on, which in this case are the names of the -files that needed to be updated. If you run `tar --list' and look at -the archive, you will see `blues' and `classical' at its end. There -will be a total of two versions of the member `blues'; the one at the -end will be newer and larger, since you added text before updating it. - - (The reason `tar' does not overwrite the older file when updating it -is because writing to the middle of a section of tape is a difficult -process. Tapes are not designed to go backward. *Note Media::, for -more information about tapes. - - `--update' (`-u') is not suitable for performing backups for two -reasons: it does not change directory content entries, and it lengthens -the archive every time it is used. The GNU `tar' options intended -specifically for backups are more efficient. If you need to run -backups, please consult *note Backups::. - - -File: tar.info, Node: concatenate, Next: delete, Prev: update, Up: Advanced tar - -4.2.4 Combining Archives with `--concatenate' ---------------------------------------------- - -Sometimes it may be convenient to add a second archive onto the end of -an archive rather than adding individual files to the archive. To add -one or more archives to the end of another archive, you should use the -`--concatenate' (`--catenate', `-A') operation. - - To use `--concatenate', give the first archive with `--file' option -and name the rest of archives to be concatenated on the command line. -The members, and their member names, will be copied verbatim from those -archives to the first one. (1) The new, concatenated archive will be -called by the same name as the one given with the `--file' option. As -usual, if you omit `--file', `tar' will use the value of the environment -variable `TAPE', or, if this has not been set, the default archive name. - - To demonstrate how `--concatenate' works, create two small archives -called `bluesrock.tar' and `folkjazz.tar', using the relevant files -from `practice': - - $ tar -cvf bluesrock.tar blues rock - blues - rock - $ tar -cvf folkjazz.tar folk jazz - folk - jazz - -If you like, You can run `tar --list' to make sure the archives contain -what they are supposed to: - - $ tar -tvf bluesrock.tar - -rw-r--r-- melissa user 105 1997-01-21 19:42 blues - -rw-r--r-- melissa user 33 1997-01-20 15:34 rock - $ tar -tvf jazzfolk.tar - -rw-r--r-- melissa user 20 1996-09-23 16:44 folk - -rw-r--r-- melissa user 65 1997-01-30 14:15 jazz - - We can concatenate these two archives with `tar': - - $ cd .. - $ tar --concatenate --file=bluesrock.tar jazzfolk.tar - - If you now list the contents of the `bluesrock.tar', you will see -that now it also contains the archive members of `jazzfolk.tar': - - $ tar --list --file=bluesrock.tar - blues - rock - folk - jazz - - When you use `--concatenate', the source and target archives must -already exist and must have been created using compatible format -parameters. Notice, that `tar' does not check whether the archives it -concatenates have compatible formats, it does not even check if the -files are really tar archives. - - Like `--append' (`-r'), this operation cannot be performed on some -tape drives, due to deficiencies in the formats those tape drives use. - - It may seem more intuitive to you to want or try to use `cat' to -concatenate two archives instead of using the `--concatenate' -operation; after all, `cat' is the utility for combining files. - - However, `tar' archives incorporate an end-of-file marker which must -be removed if the concatenated archives are to be read properly as one -archive. `--concatenate' removes the end-of-archive marker from the -target archive before each new archive is appended. If you use `cat' -to combine the archives, the result will not be a valid `tar' format -archive. If you need to retrieve files from an archive that was added -to using the `cat' utility, use the `--ignore-zeros' (`-i') option. -*Note Ignore Zeros::, for further information on dealing with archives -improperly combined using the `cat' shell utility. - - ---------- Footnotes ---------- - - (1) This can cause multiple members to have the same name, for -information on how this affects reading the archive, *note multiple::. - - -File: tar.info, Node: delete, Next: compare, Prev: concatenate, Up: Advanced tar - -4.2.5 Removing Archive Members Using `--delete' ------------------------------------------------ - - _(This message will disappear, once this node revised.)_ - -You can remove members from an archive by using the `--delete' option. -Specify the name of the archive with `--file' (`-f') and then specify -the names of the members to be deleted; if you list no member names, -nothing will be deleted. The `--verbose' option will cause `tar' to -print the names of the members as they are deleted. As with -`--extract', you must give the exact member names when using `tar ---delete'. `--delete' will remove all versions of the named file from -the archive. The `--delete' operation can run very slowly. - - Unlike other operations, `--delete' has no short form. - - This operation will rewrite the archive. You can only use -`--delete' on an archive if the archive device allows you to write to -any point on the media, such as a disk; because of this, it does not -work on magnetic tapes. Do not try to delete an archive member from a -magnetic tape; the action will not succeed, and you will be likely to -scramble the archive and damage your tape. There is no safe way -(except by completely re-writing the archive) to delete files from most -kinds of magnetic tape. *Note Media::. - - To delete all versions of the file `blues' from the archive -`collection.tar' in the `practice' directory, make sure you are in that -directory, and then, - - $ tar --list --file=collection.tar - blues - folk - jazz - rock - $ tar --delete --file=collection.tar blues - $ tar --list --file=collection.tar - folk - jazz - rock - $ - - The `--delete' option has been reported to work properly when `tar' -acts as a filter from `stdin' to `stdout'. - - -File: tar.info, Node: compare, Prev: delete, Up: Advanced tar - -4.2.6 Comparing Archive Members with the File System ----------------------------------------------------- - - _(This message will disappear, once this node revised.)_ - -The `--compare' (`-d'), or `--diff' operation compares specified -archive members against files with the same names, and then reports -differences in file size, mode, owner, modification date and contents. -You should _only_ specify archive member names, not file names. If you -do not name any members, then `tar' will compare the entire archive. -If a file is represented in the archive but does not exist in the file -system, `tar' reports a difference. - - You have to specify the record size of the archive when modifying an -archive with a non-default record size. - - `tar' ignores files in the file system that do not have -corresponding members in the archive. - - The following example compares the archive members `rock', `blues' -and `funk' in the archive `bluesrock.tar' with files of the same name -in the file system. (Note that there is no file, `funk'; `tar' will -report an error message.) - - $ tar --compare --file=bluesrock.tar rock blues funk - rock - blues - tar: funk not found in archive - - The spirit behind the `--compare' (`--diff', `-d') option is to -check whether the archive represents the current state of files on -disk, more than validating the integrity of the archive media. For -this later goal, *Note verify::. - - -File: tar.info, Node: create options, Next: extract options, Prev: Advanced tar, Up: operations - -4.3 Options Used by `--create' -============================== - -The previous chapter described the basics of how to use `--create' -(`-c') to create an archive from a set of files. *Note create::. This -section described advanced options to be used with `--create'. - -* Menu: - -* override:: Overriding File Metadata. -* Ignore Failed Read:: - - -File: tar.info, Node: override, Next: Ignore Failed Read, Up: create options - -4.3.1 Overriding File Metadata ------------------------------- - -As described above, a `tar' archive keeps, for each member it contains, -its "metadata", such as modification time, mode and ownership of the -file. GNU `tar' allows to replace these data with other values when -adding files to the archive. The options described in this section -affect creation of archives of any type. For POSIX archives, see also -*note PAX keywords::, for additional ways of controlling metadata, -stored in the archive. - -`--mode=PERMISSIONS' - When adding files to an archive, `tar' will use PERMISSIONS for - the archive members, rather than the permissions from the files. - PERMISSIONS can be specified either as an octal number or as - symbolic permissions, like with `chmod' (*Note Permissions: - (fileutils)File permissions. This reference also has useful - information for those not being overly familiar with the UNIX - permission system). Using latter syntax allows for more - flexibility. For example, the value `a+rw' adds read and write - permissions for everybody, while retaining executable bits on - directories or on any other file already marked as executable: - - $ tar -c -f archive.tar --mode='a+rw' . - -`--mtime=DATE' - When adding files to an archive, `tar' will use DATE as the - modification time of members when creating archives, instead of - their actual modification times. The argument DATE can be either - a textual date representation in almost arbitrary format (*note - Date input formats::) or a name of the existing file, starting - with `/' or `.'. In the latter case, the modification time of - that file will be used. - - The following example will set the modification date to 00:00:00 - UTC, January 1, 1970: - - $ tar -c -f archive.tar --mtime='1970-01-01' . - - When used with `--verbose' (*note verbose tutorial::) GNU `tar' - will try to convert the specified date back to its textual - representation and compare it with the one given with `--mtime' - options. If the two dates differ, `tar' will print a warning - saying what date it will use. This is to help user ensure he is - using the right date. - - For example: - - $ tar -c -f archive.tar -v --mtime=yesterday . - tar: Option --mtime: Treating date `yesterday' as 2006-06-20 - 13:06:29.152478 - ... - -`--owner=USER' - Specifies that `tar' should use USER as the owner of members when - creating archives, instead of the user associated with the source - file. The argument USER can be either an existing user symbolic - name, or a decimal numeric user ID. - - There is no value indicating a missing number, and `0' usually - means `root'. Some people like to force `0' as the value to offer - in their distributions for the owner of files, because the `root' - user is anonymous anyway, so that might as well be the owner of - anonymous archives. For example: - - $ tar -c -f archive.tar --owner=0 . - # Or: - $ tar -c -f archive.tar --owner=root . - -`--group=GROUP' - Files added to the `tar' archive will have a group ID of GROUP, - rather than the group from the source file. The argument GROUP - can be either an existing group symbolic name, or a decimal - numeric group ID. - - -File: tar.info, Node: Ignore Failed Read, Prev: override, Up: create options - -4.3.2 Ignore Fail Read ----------------------- - -`--ignore-failed-read' - Do not exit with nonzero on unreadable files or directories. - - -File: tar.info, Node: extract options, Next: backup, Prev: create options, Up: operations - -4.4 Options Used by `--extract' -=============================== - - _(This message will disappear, once this node revised.)_ - -The previous chapter showed how to use `--extract' to extract an -archive into the file system. Various options cause `tar' to extract -more information than just file contents, such as the owner, the -permissions, the modification date, and so forth. This section -presents options to be used with `--extract' when certain special -considerations arise. You may review the information presented in -*note extract:: for more basic information about the `--extract' -operation. - -* Menu: - -* Reading:: Options to Help Read Archives -* Writing:: Changing How `tar' Writes Files -* Scarce:: Coping with Scarce Resources - - -File: tar.info, Node: Reading, Next: Writing, Up: extract options - -4.4.1 Options to Help Read Archives ------------------------------------ - - _(This message will disappear, once this node revised.)_ - -Normally, `tar' will request data in full record increments from an -archive storage device. If the device cannot return a full record, -`tar' will report an error. However, some devices do not always return -full records, or do not require the last record of an archive to be -padded out to the next record boundary. To keep reading until you -obtain a full record, or to accept an incomplete record if it contains -an end-of-archive marker, specify the `--read-full-records' (`-B') -option in conjunction with the `--extract' or `--list' operations. -*Note Blocking::. - - The `--read-full-records' (`-B') option is turned on by default when -`tar' reads an archive from standard input, or from a remote machine. -This is because on BSD Unix systems, attempting to read a pipe returns -however much happens to be in the pipe, even if it is less than was -requested. If this option were not enabled, `tar' would fail as soon -as it read an incomplete record from the pipe. - - If you're not sure of the blocking factor of an archive, you can -read the archive by specifying `--read-full-records' (`-B') and -`--blocking-factor=512-SIZE' (`-b 512-SIZE'), using a blocking factor -larger than what the archive uses. This lets you avoid having to -determine the blocking factor of an archive. *Note Blocking Factor::. - -* Menu: - -* read full records:: -* Ignore Zeros:: - - -File: tar.info, Node: read full records, Next: Ignore Zeros, Up: Reading - -Reading Full Records -.................... - -`--read-full-records' - -`-B' - Use in conjunction with `--extract' (`--get', `-x') to read an - archive which contains incomplete records, or one which has a - blocking factor less than the one specified. - - -File: tar.info, Node: Ignore Zeros, Prev: read full records, Up: Reading - -Ignoring Blocks of Zeros -........................ - -Normally, `tar' stops reading when it encounters a block of zeros -between file entries (which usually indicates the end of the archive). -`--ignore-zeros' (`-i') allows `tar' to completely read an archive -which contains a block of zeros before the end (i.e., a damaged -archive, or one that was created by concatenating several archives -together). - - The `--ignore-zeros' (`-i') option is turned off by default because -many versions of `tar' write garbage after the end-of-archive entry, -since that part of the media is never supposed to be read. GNU `tar' -does not write after the end of an archive, but seeks to maintain -compatibility among archiving utilities. - -`--ignore-zeros' -`-i' - To ignore blocks of zeros (i.e., end-of-archive entries) which may - be encountered while reading an archive. Use in conjunction with - `--extract' or `--list'. - - -File: tar.info, Node: Writing, Next: Scarce, Prev: Reading, Up: extract options - -4.4.2 Changing How `tar' Writes Files -------------------------------------- - - _(This message will disappear, once this node revised.)_ - -* Menu: - -* Dealing with Old Files:: -* Overwrite Old Files:: -* Keep Old Files:: -* Keep Newer Files:: -* Unlink First:: -* Recursive Unlink:: -* Data Modification Times:: -* Setting Access Permissions:: -* Directory Modification Times and Permissions:: -* Writing to Standard Output:: -* Writing to an External Program:: -* remove files:: - - -File: tar.info, Node: Dealing with Old Files, Next: Overwrite Old Files, Up: Writing - -Options Controlling the Overwriting of Existing Files -..................................................... - -When extracting files, if `tar' discovers that the extracted file -already exists, it normally replaces the file by removing it before -extracting it, to prevent confusion in the presence of hard or symbolic -links. (If the existing file is a symbolic link, it is removed, not -followed.) However, if a directory cannot be removed because it is -nonempty, `tar' normally overwrites its metadata (ownership, -permission, etc.). The `--overwrite-dir' option enables this default -behavior. To be more cautious and preserve the metadata of such a -directory, use the `--no-overwrite-dir' option. - - To be even more cautious and prevent existing files from being -replaced, use the `--keep-old-files' (`-k') option. It causes `tar' to -refuse to replace or update a file that already exists, i.e., a file -with the same name as an archive member prevents extraction of that -archive member. Instead, it reports an error. - - To be more aggressive about altering existing files, use the -`--overwrite' option. It causes `tar' to overwrite existing files and -to follow existing symbolic links when extracting. - - Some people argue that GNU `tar' should not hesitate to overwrite -files with other files when extracting. When extracting a `tar' -archive, they expect to see a faithful copy of the state of the file -system when the archive was created. It is debatable that this would -always be a proper behavior. For example, suppose one has an archive -in which `usr/local' is a link to `usr/local2'. Since then, maybe the -site removed the link and renamed the whole hierarchy from -`/usr/local2' to `/usr/local'. Such things happen all the time. I -guess it would not be welcome at all that GNU `tar' removes the whole -hierarchy just to make room for the link to be reinstated (unless it -_also_ simultaneously restores the full `/usr/local2', of course!) GNU -`tar' is indeed able to remove a whole hierarchy to reestablish a -symbolic link, for example, but _only if_ `--recursive-unlink' is -specified to allow this behavior. In any case, single files are -silently removed. - - Finally, the `--unlink-first' (`-U') option can improve performance -in some cases by causing `tar' to remove files unconditionally before -extracting them. - - -File: tar.info, Node: Overwrite Old Files, Next: Keep Old Files, Prev: Dealing with Old Files, Up: Writing - -Overwrite Old Files -................... - -`--overwrite' - Overwrite existing files and directory metadata when extracting - files from an archive. - - This causes `tar' to write extracted files into the file system - without regard to the files already on the system; i.e., files - with the same names as archive members are overwritten when the - archive is extracted. It also causes `tar' to extract the - ownership, permissions, and time stamps onto any preexisting files - or directories. If the name of a corresponding file name is a - symbolic link, the file pointed to by the symbolic link will be - overwritten instead of the symbolic link itself (if this is - possible). Moreover, special devices, empty directories and even - symbolic links are automatically removed if they are in the way of - extraction. - - Be careful when using the `--overwrite' option, particularly when - combined with the `--absolute-names' (`-P') option, as this - combination can change the contents, ownership or permissions of - any file on your system. Also, many systems do not take kindly to - overwriting files that are currently being executed. - -`--overwrite-dir' - Overwrite the metadata of directories when extracting files from an - archive, but remove other files before extracting. - - -File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing - -Keep Old Files -.............. - -`--keep-old-files' -`-k' - Do not replace existing files from archive. The - `--keep-old-files' (`-k') option prevents `tar' from replacing - existing files with files with the same name from the archive. The - `--keep-old-files' option is meaningless with `--list' (`-t'). - Prevents `tar' from replacing files in the file system during - extraction. - - -File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing - -Keep Newer Files -................ - -`--keep-newer-files' - Do not replace existing files that are newer than their archive - copies. This option is meaningless with `--list' (`-t'). - - -File: tar.info, Node: Unlink First, Next: Recursive Unlink, Prev: Keep Newer Files, Up: Writing - -Unlink First -............ - -`--unlink-first' -`-U' - Remove files before extracting over them. This can make `tar' run - a bit faster if you know in advance that the extracted files all - need to be removed. Normally this option slows `tar' down - slightly, so it is disabled by default. - - -File: tar.info, Node: Recursive Unlink, Next: Data Modification Times, Prev: Unlink First, Up: Writing - -Recursive Unlink -................ - -`--recursive-unlink' - When this option is specified, try removing files and directory - hierarchies before extracting over them. _This is a dangerous - option!_ - - If you specify the `--recursive-unlink' option, `tar' removes -_anything_ that keeps you from extracting a file as far as current -permissions will allow it. This could include removal of the contents -of a full directory hierarchy. - - -File: tar.info, Node: Data Modification Times, Next: Setting Access Permissions, Prev: Recursive Unlink, Up: Writing - -Setting Data Modification Times -............................... - -Normally, `tar' sets the data modification times of extracted files to -the corresponding times recorded for the files in the archive, but -limits the permissions of extracted files by the current `umask' -setting. - - To set the data modification times of extracted files to the time -when the files were extracted, use the `--touch' (`-m') option in -conjunction with `--extract' (`--get', `-x'). - -`--touch' -`-m' - Sets the data modification time of extracted archive members to - the time they were extracted, not the time recorded for them in - the archive. Use in conjunction with `--extract' (`--get', `-x'). - - -File: tar.info, Node: Setting Access Permissions, Next: Directory Modification Times and Permissions, Prev: Data Modification Times, Up: Writing - -Setting Access Permissions -.......................... - -To set the modes (access permissions) of extracted files to those -recorded for those files in the archive, use `--same-permissions' in -conjunction with the `--extract' (`--get', `-x') operation. - -`--preserve-permissions' -`--same-permissions' -`-p' - Set modes of extracted archive members to those recorded in the - archive, instead of current umask settings. Use in conjunction - with `--extract' (`--get', `-x'). - - -File: tar.info, Node: Directory Modification Times and Permissions, Next: Writing to Standard Output, Prev: Setting Access Permissions, Up: Writing - -Directory Modification Times and Permissions -............................................ - -After successfully extracting a file member, GNU `tar' normally -restores its permissions and modification times, as described in the -previous sections. This cannot be done for directories, because after -extracting a directory `tar' will almost certainly extract files into -that directory and this will cause the directory modification time to -be updated. Moreover, restoring that directory permissions may not -permit file creation within it. Thus, restoring directory permissions -and modification times must be delayed at least until all files have -been extracted into that directory. GNU `tar' restores directories -using the following approach. - - The extracted directories are created with the mode specified in the -archive, as modified by the umask of the user, which gives sufficient -permissions to allow file creation. The meta-information about the -directory is recorded in the temporary list of directories. When -preparing to extract next archive member, GNU `tar' checks if the -directory prefix of this file contains the remembered directory. If it -does not, the program assumes that all files have been extracted into -that directory, restores its modification time and permissions and -removes its entry from the internal list. This approach allows to -correctly restore directory meta-information in the majority of cases, -while keeping memory requirements sufficiently small. It is based on -the fact, that most `tar' archives use the predefined order of members: -first the directory, then all the files and subdirectories in that -directory. - - However, this is not always true. The most important exception are -incremental archives (*note Incremental Dumps::). The member order in -an incremental archive is reversed: first all directory members are -stored, followed by other (non-directory) members. So, when extracting -from incremental archives, GNU `tar' alters the above procedure. It -remembers all restored directories, and restores their meta-data only -after the entire archive has been processed. Notice, that you do not -need to specify any special options for that, as GNU `tar' -automatically detects archives in incremental format. - - There may be cases, when such processing is required for normal -archives too. Consider the following example: - - $ tar --no-recursion -cvf archive \ - foo foo/file1 bar bar/file foo/file2 - foo/ - foo/file1 - bar/ - bar/file - foo/file2 - - During the normal operation, after encountering `bar' GNU `tar' will -assume that all files from the directory `foo' were already extracted -and will therefore restore its timestamp and permission bits. However, -after extracting `foo/file2' the directory timestamp will be offset -again. - - To correctly restore directory meta-information in such cases, use -`delay-directory-restore' command line option: - -`--delay-directory-restore' - Delays restoring of the modification times and permissions of - extracted directories until the end of extraction. This way, - correct meta-information is restored even if the archive has - unusual member ordering. - -`--no-delay-directory-restore' - Cancel the effect of the previous `--delay-directory-restore'. - Use this option if you have used `--delay-directory-restore' in - `TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to - temporarily disable it. - - -File: tar.info, Node: Writing to Standard Output, Next: Writing to an External Program, Prev: Directory Modification Times and Permissions, Up: Writing - -Writing to Standard Output -.......................... - -To write the extracted files to the standard output, instead of -creating the files on the file system, use `--to-stdout' (`-O') in -conjunction with `--extract' (`--get', `-x'). This option is useful if -you are extracting files to send them through a pipe, and do not need to -preserve them in the file system. If you extract multiple members, -they appear on standard output concatenated, in the order they are -found in the archive. - -`--to-stdout' -`-O' - Writes files to the standard output. Use only in conjunction with - `--extract' (`--get', `-x'). When this option is used, instead of - creating the files specified, `tar' writes the contents of the - files extracted to its standard output. This may be useful if you - are only extracting the files in order to send them through a - pipe. This option is meaningless with `--list' (`-t'). - - This can be useful, for example, if you have a tar archive containing -a big file and don't want to store the file on disk before processing -it. You can use a command like this: - - tar -xOzf foo.tgz bigfile | process - - or even like this if you want to process the concatenation of the -files: - - tar -xOzf foo.tgz bigfile1 bigfile2 | process - - However, `--to-command' may be more convenient for use with multiple -files. See the next section. - - -File: tar.info, Node: Writing to an External Program, Next: remove files, Prev: Writing to Standard Output, Up: Writing - -Writing to an External Program -.............................. - -You can instruct `tar' to send the contents of each extracted file to -the standard input of an external program: - -`--to-command=COMMAND' - Extract files and pipe their contents to the standard input of - COMMAND. When this option is used, instead of creating the files - specified, `tar' invokes COMMAND and pipes the contents of the - files to its standard output. COMMAND may contain command line - arguments. The program is executed via `sh -c'. Notice, that - COMMAND is executed once for each regular file extracted. - Non-regular files (directories, etc.) are ignored when this option - is used. - - The command can obtain the information about the file it processes -from the following environment variables: - -`TAR_FILETYPE' - Type of the file. It is a single letter with the following meaning: - - f Regular file - d Directory - l Symbolic link - h Hard link - b Block device - c Character device - - Currently only regular files are supported. - -`TAR_MODE' - File mode, an octal number. - -`TAR_FILENAME' - The name of the file. - -`TAR_REALNAME' - Name of the file as stored in the archive. - -`TAR_UNAME' - Name of the file owner. - -`TAR_GNAME' - Name of the file owner group. - -`TAR_ATIME' - Time of last access. It is a decimal number, representing seconds - since the epoch. If the archive provides times with nanosecond - precision, the nanoseconds are appended to the timestamp after a - decimal point. - -`TAR_MTIME' - Time of last modification. - -`TAR_CTIME' - Time of last status change. - -`TAR_SIZE' - Size of the file. - -`TAR_UID' - UID of the file owner. - -`TAR_GID' - GID of the file owner. - - In addition to these variables, `TAR_VERSION' contains the GNU `tar' -version number. - - If COMMAND exits with a non-0 status, `tar' will print an error -message similar to the following: - - tar: 2345: Child returned status 1 - - Here, `2345' is the PID of the finished process. - - If this behavior is not wanted, use `--ignore-command-error': - -`--ignore-command-error' - Ignore exit codes of subprocesses. Notice that if the program - exits on signal or otherwise terminates abnormally, the error - message will be printed even if this option is used. - -`--no-ignore-command-error' - Cancel the effect of any previous `--ignore-command-error' option. - This option is useful if you have set `--ignore-command-error' in - `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to temporarily cancel - it. - - -File: tar.info, Node: remove files, Prev: Writing to an External Program, Up: Writing - -Removing Files -.............. - -`--remove-files' - Remove files after adding them to the archive. - - -File: tar.info, Node: Scarce, Prev: Writing, Up: extract options - -4.4.3 Coping with Scarce Resources ----------------------------------- - - _(This message will disappear, once this node revised.)_ - -* Menu: - -* Starting File:: -* Same Order:: - - -File: tar.info, Node: Starting File, Next: Same Order, Up: Scarce - -Starting File -............. - -`--starting-file=NAME' -`-K NAME' - Starts an operation in the middle of an archive. Use in - conjunction with `--extract' (`--get', `-x') or `--list' (`-t'). - - If a previous attempt to extract files failed due to lack of disk -space, you can use `--starting-file=NAME' (`-K NAME') to start -extracting only after member NAME of the archive. This assumes, of -course, that there is now free space, or that you are now extracting -into a different file system. (You could also choose to suspend `tar', -remove unnecessary files from the file system, and then restart the -same `tar' operation. In this case, `--starting-file' is not necessary. -*Note Incremental Dumps::, *Note interactive::, and *note exclude::.) - - -File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce - -Same Order -.......... - -`--same-order' -`--preserve-order' -`-s' - To process large lists of file names on machines with small - amounts of memory. Use in conjunction with `--compare' (`--diff', - `-d'), `--list' (`-t') or `--extract' (`--get', `-x'). - - The `--same-order' (`--preserve-order', `-s') option tells `tar' -that the list of file names to be listed or extracted is sorted in the -same order as the files in the archive. This allows a large list of -names to be used, even on a small machine that would not otherwise be -able to hold all the names in memory at the same time. Such a sorted -list can easily be created by running `tar -t' on the archive and -editing its output. - - This option is probably never needed on modern computer systems. - - -File: tar.info, Node: backup, Next: Applications, Prev: extract options, Up: operations - -4.5 Backup options -================== - -GNU `tar' offers options for making backups of files before writing new -versions. These options control the details of these backups. They -may apply to the archive itself before it is created or rewritten, as -well as individual extracted members. Other GNU programs (`cp', -`install', `ln', and `mv', for example) offer similar options. - - Backup options may prove unexpectedly useful when extracting archives -containing many members having identical name, or when extracting -archives on systems having file name limitations, making different -members appear has having similar names through the side-effect of name -truncation. (This is true only if we have a good scheme for truncated -backup names, which I'm not sure at all: I suspect work is needed in -this area.) When any existing file is backed up before being -overwritten by extraction, then clashing files are automatically be -renamed to be unique, and the true name is kept for only the last file -of a series of clashing files. By using verbose mode, users may track -exactly what happens. - - At the detail level, some decisions are still experimental, and may -change in the future, we are waiting comments from our users. So, -please do not learn to depend blindly on the details of the backup -features. For example, currently, directories themselves are never -renamed through using these options, so, extracting a file over a -directory still has good chances to fail. Also, backup options apply -to created archives, not only to extracted members. For created -archives, backups will not be attempted when the archive is a block or -character device, or when it refers to a remote file. - - For the sake of simplicity and efficiency, backups are made by -renaming old files prior to creation or extraction, and not by copying. -The original name is restored if the file creation fails. If a -failure occurs after a partial extraction of a file, both the backup -and the partially extracted file are kept. - -`--backup[=METHOD]' - Back up files that are about to be overwritten or removed. - Without this option, the original versions are destroyed. - - Use METHOD to determine the type of backups made. If METHOD is - not specified, use the value of the `VERSION_CONTROL' environment - variable. And if `VERSION_CONTROL' is not set, use the `existing' - method. - - This option corresponds to the Emacs variable `version-control'; - the same values for METHOD are accepted as in Emacs. This option - also allows more descriptive names. The valid METHODs are: - - `t' - `numbered' - Always make numbered backups. - - `nil' - `existing' - Make numbered backups of files that already have them, simple - backups of the others. - - `never' - `simple' - Always make simple backups. - - -`--suffix=SUFFIX' - Append SUFFIX to each backup file made with `--backup'. If this - option is not specified, the value of the `SIMPLE_BACKUP_SUFFIX' - environment variable is used. And if `SIMPLE_BACKUP_SUFFIX' is not - set, the default is `~', just as in Emacs. - - - -File: tar.info, Node: Applications, Next: looking ahead, Prev: backup, Up: operations - -4.6 Notable `tar' Usages -======================== - - _(This message will disappear, once this node revised.)_ - -You can easily use archive files to transport a group of files from one -system to another: put all relevant files into an archive on one -computer system, transfer the archive to another system, and extract -the contents there. The basic transfer medium might be magnetic tape, -Internet FTP, or even electronic mail (though you must encode the -archive with `uuencode' in order to transport it properly by mail). -Both machines do not have to use the same operating system, as long as -they both support the `tar' program. - - For example, here is how you might copy a directory's contents from -one disk to another, while preserving the dates, modes, owners and -link-structure of all the files therein. In this case, the transfer -medium is a "pipe", which is one a Unix redirection mechanism: - - $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -) - -You can avoid subshells by using `-C' option: - - $ tar -C sourcedir -cf - . | tar -C targetdir -xf - - -The command also works using short option forms: - - $ (cd sourcedir; tar --create --file=- . ) \ - | (cd targetdir; tar --extract --file=-) - # Or: - $ tar --directory sourcedir --create --file=- . ) \ - | tar --directory targetdir --extract --file=- - -This is one of the easiest methods to transfer a `tar' archive. - - -File: tar.info, Node: looking ahead, Prev: Applications, Up: operations - -4.7 Looking Ahead: The Rest of this Manual -========================================== - -You have now seen how to use all eight of the operations available to -`tar', and a number of the possible options. The next chapter explains -how to choose and change file and archive names, how to use files to -store names of other files which you can then call as arguments to -`tar' (this can help you save time if you expect to archive the same -list of files a number of times), and so forth. - - If there are too many files to conveniently list on the command line, -you can list the names in a file, and `tar' will read that file. *Note -files::. - - There are various ways of causing `tar' to skip over some files, and -not archive them. *Note Choosing::. - - -File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top - -5 Performing Backups and Restoring Files -**************************************** - - _(This message will disappear, once this node revised.)_ - -GNU `tar' is distributed along with the scripts which the Free Software -Foundation uses for performing backups. There is no corresponding -scripts available yet for doing restoration of files. Even if there is -a good chance those scripts may be satisfying to you, they are not the -only scripts or methods available for doing backups and restore. You -may well create your own, or use more sophisticated packages dedicated -to that purpose. - - Some users are enthusiastic about `Amanda' (The Advanced Maryland -Automatic Network Disk Archiver), a backup system developed by James da -Silva `jds@cs.umd.edu' and available on many Unix systems. This is -free software, and it is available at these places: - - http://www.cs.umd.edu/projects/amanda/amanda.html - ftp://ftp.cs.umd.edu/pub/amanda - - This chapter documents both the provided shell scripts and `tar' -options which are more specific to usage as a backup tool. - - To "back up" a file system means to create archives that contain all -the files in that file system. Those archives can then be used to -restore any or all of those files (for instance if a disk crashes or a -file is accidentally deleted). File system "backups" are also called -"dumps". - -* Menu: - -* Full Dumps:: Using `tar' to Perform Full Dumps -* Incremental Dumps:: Using `tar' to Perform Incremental Dumps -* Backup Levels:: Levels of Backups -* Backup Parameters:: Setting Parameters for Backups and Restoration -* Scripted Backups:: Using the Backup Scripts -* Scripted Restoration:: Using the Restore Script - - -File: tar.info, Node: Full Dumps, Next: Incremental Dumps, Up: Backups - -5.1 Using `tar' to Perform Full Dumps -===================================== - - _(This message will disappear, once this node revised.)_ - -Full dumps should only be made when no other people or programs are -modifying files in the file system. If files are modified while `tar' -is making the backup, they may not be stored properly in the archive, -in which case you won't be able to restore them if you have to. (Files -not being modified are written with no trouble, and do not corrupt the -entire archive.) - - You will want to use the `--label=ARCHIVE-LABEL' (`-V -ARCHIVE-LABEL') option to give the archive a volume label, so you can -tell what this archive is even if the label falls off the tape, or -anything like that. - - Unless the file system you are dumping is guaranteed to fit on one -volume, you will need to use the `--multi-volume' (`-M') option. Make -sure you have enough tapes on hand to complete the backup. - - If you want to dump each file system separately you will need to use -the `--one-file-system' option to prevent `tar' from crossing file -system boundaries when storing (sub)directories. - - The `--incremental' (`-G') (*note Incremental Dumps::) option is not -needed, since this is a complete copy of everything in the file system, -and a full restore from this backup would only be done onto a completely -empty disk. - - Unless you are in a hurry, and trust the `tar' program (and your -tapes), it is a good idea to use the `--verify' (`-W') option, to make -sure your files really made it onto the dump properly. This will also -detect cases where the file was modified while (or just after) it was -being archived. Not all media (notably cartridge tapes) are capable of -being verified, unfortunately. - - -File: tar.info, Node: Incremental Dumps, Next: Backup Levels, Prev: Full Dumps, Up: Backups - -5.2 Using `tar' to Perform Incremental Dumps -============================================ - -"Incremental backup" is a special form of GNU `tar' archive that stores -additional metadata so that exact state of the file system can be -restored when extracting the archive. - - GNU `tar' currently offers two options for handling incremental -backups: `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') and -`--incremental' (`-G'). - - The option `--listed-incremental' instructs tar to operate on an -incremental archive with additional metadata stored in a standalone -file, called a "snapshot file". The purpose of this file is to help -determine which files have been changed, added or deleted since the -last backup, so that the next incremental backup will contain only -modified files. The name of the snapshot file is given as an argument -to the option: - -`--listed-incremental=FILE' -`-g FILE' - Handle incremental backups with snapshot data in FILE. - - To create an incremental backup, you would use -`--listed-incremental' together with `--create' (*note create::). For -example: - - $ tar --create \ - --file=archive.1.tar \ - --listed-incremental=/var/log/usr.snar \ - /usr - - This will create in `archive.1.tar' an incremental backup of the -`/usr' file system, storing additional metadata in the file -`/var/log/usr.snar'. If this file does not exist, it will be created. -The created archive will then be a "level 0 backup"; please see the -next section for more on backup levels. - - Otherwise, if the file `/var/log/usr.snar' exists, it determines -which files are modified. In this case only these files will be stored -in the archive. Suppose, for example, that after running the above -command, you delete file `/usr/doc/old' and create directory -`/usr/local/db' with the following contents: - - $ ls /usr/local/db - /usr/local/db/data - /usr/local/db/index - - Some time later you create another incremental backup. You will -then see: - - $ tar --create \ - --file=archive.2.tar \ - --listed-incremental=/var/log/usr.snar \ - /usr - tar: usr/local/db: Directory is new - usr/local/db/ - usr/local/db/data - usr/local/db/index - -The created archive `archive.2.tar' will contain only these three -members. This archive is called a "level 1 backup". Notice that -`/var/log/usr.snar' will be updated with the new data, so if you plan -to create more `level 1' backups, it is necessary to create a working -copy of the snapshot file before running `tar'. The above example will -then be modified as follows: - - $ cp /var/log/usr.snar /var/log/usr.snar-1 - $ tar --create \ - --file=archive.2.tar \ - --listed-incremental=/var/log/usr.snar-1 \ - /usr - - Incremental dumps depend crucially on time stamps, so the results are -unreliable if you modify a file's time stamps during dumping (e.g., -with the `--atime-preserve=replace' option), or if you set the clock -backwards. - - Metadata stored in snapshot files include device numbers, which, -obviously are supposed to be a non-volatile values. However, it turns -out that NFS devices have undependable values when an automounter gets -in the picture. This can lead to a great deal of spurious redumping in -incremental dumps, so it is somewhat useless to compare two NFS devices -numbers over time. The solution implemented currently is to considers -all NFS devices as being equal when it comes to comparing directories; -this is fairly gross, but there does not seem to be a better way to go. - - Apart from using NFS, there are a number of cases where relying on -device numbers can cause spurious redumping of unmodified files. For -example, this occurs when archiving LVM snapshot volumes. To avoid -this, use `--no-check-device' option: - -`--no-check-device' - Do not rely on device numbers when preparing a list of changed - files for an incremental dump. - -`--check-device' - Use device numbers when preparing a list of changed files for an - incremental dump. This is the default behavior. The purpose of - this option is to undo the effect of the `--no-check-device' if it - was given in `TAR_OPTIONS' environment variable (*note - TAR_OPTIONS::). - - There is also another way to cope with changing device numbers. It -is described in detail in *note Fixing Snapshot Files::. - - Note that incremental archives use `tar' extensions and may not be -readable by non-GNU versions of the `tar' program. - - To extract from the incremental dumps, use `--listed-incremental' -together with `--extract' option (*note extracting files::). In this -case, `tar' does not need to access snapshot file, since all the data -necessary for extraction are stored in the archive itself. So, when -extracting, you can give whatever argument to `--listed-incremental', -the usual practice is to use `--listed-incremental=/dev/null'. -Alternatively, you can use `--incremental', which needs no arguments. -In general, `--incremental' (`-G') can be used as a shortcut for -`--listed-incremental' when listing or extracting incremental backups -(for more information, regarding this option, *note incremental-op::). - - When extracting from the incremental backup GNU `tar' attempts to -restore the exact state the file system had when the archive was -created. In particular, it will _delete_ those files in the file -system that did not exist in their directories when the archive was -created. If you have created several levels of incremental files, then -in order to restore the exact contents the file system had when the -last level was created, you will need to restore from all backups in -turn. Continuing our example, to restore the state of `/usr' file -system, one would do(1): - - $ tar --extract \ - --listed-incremental=/dev/null \ - --file archive.1.tar - $ tar --extract \ - --listed-incremental=/dev/null \ - --file archive.2.tar - - To list the contents of an incremental archive, use `--list' (*note -list::), as usual. To obtain more information about the archive, use -`--listed-incremental' or `--incremental' combined with two `--verbose' -options(2): - - tar --list --incremental --verbose --verbose archive.tar - - This command will print, for each directory in the archive, the list -of files in that directory at the time the archive was created. This -information is put out in a format which is both human-readable and -unambiguous for a program: each file name is printed as - - X FILE - -where X is a letter describing the status of the file: `Y' if the file -is present in the archive, `N' if the file is not included in the -archive, or a `D' if the file is a directory (and is included in the -archive). *Note Dumpdir::, for the detailed description of dumpdirs -and status codes. Each such line is terminated by a newline character. -The last line is followed by an additional newline to indicate the end -of the data. - - The option `--incremental' (`-G') gives the same behavior as -`--listed-incremental' when used with `--list' and `--extract' options. -When used with `--create' option, it creates an incremental archive -without creating snapshot file. Thus, it is impossible to create -several levels of incremental backups with `--incremental' option. - - ---------- Footnotes ---------- - - (1) Notice, that since both archives were created without `-P' -option (*note absolute::), these commands should be run from the root -file system. - - (2) Two `--verbose' options were selected to avoid breaking usual -verbose listing output (`--list --verbose') when using in scripts. - - Versions of GNU `tar' up to 1.15.1 used to dump verbatim binary -contents of the DUMPDIR header (with terminating nulls) when -`--incremental' or `--listed-incremental' option was given, no matter -what the verbosity level. This behavior, and, especially, the binary -output it produced were considered inconvenient and were changed in -version 1.16 - - -File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups - -5.3 Levels of Backups -===================== - -An archive containing all the files in the file system is called a -"full backup" or "full dump". You could insure your data by creating a -full dump every day. This strategy, however, would waste a substantial -amount of archive media and user time, as unchanged files are daily -re-archived. - - It is more efficient to do a full dump only occasionally. To back up -files between full dumps, you can use "incremental dumps". A "level -one" dump archives all the files that have changed since the last full -dump. - - A typical dump strategy would be to perform a full dump once a week, -and a level one dump once a day. This means some versions of files -will in fact be archived more than once, but this dump strategy makes -it possible to restore a file system to within one day of accuracy by -only extracting two archives--the last weekly (full) dump and the last -daily (level one) dump. The only information lost would be in files -changed or created since the last daily backup. (Doing dumps more than -once a day is usually not worth the trouble). - - GNU `tar' comes with scripts you can use to do full and level-one -(actually, even level-two and so on) dumps. Using scripts (shell -programs) to perform backups and restoration is a convenient and -reliable alternative to typing out file name lists and `tar' commands -by hand. - - Before you use these scripts, you need to edit the file -`backup-specs', which specifies parameters used by the backup scripts -and by the restore script. This file is usually located in -`/etc/backup' directory. *Note Backup Parameters::, for its detailed -description. Once the backup parameters are set, you can perform -backups or restoration by running the appropriate script. - - The name of the backup script is `backup'. The name of the restore -script is `restore'. The following sections describe their use in -detail. - - _Please Note:_ The backup and restoration scripts are designed to be -used together. While it is possible to restore files by hand from an -archive which was created using a backup script, and to create an -archive by hand which could then be extracted using the restore script, -it is easier to use the scripts. *Note Incremental Dumps::, before -making such an attempt. - - -File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups - -5.4 Setting Parameters for Backups and Restoration -================================================== - -The file `backup-specs' specifies backup parameters for the backup and -restoration scripts provided with `tar'. You must edit `backup-specs' -to fit your system configuration and schedule before using these -scripts. - - Syntactically, `backup-specs' is a shell script, containing mainly -variable assignments. However, any valid shell construct is allowed in -this file. Particularly, you may wish to define functions within that -script (e.g., see `RESTORE_BEGIN' below). For more information about -shell script syntax, please refer to the definition of the Shell -Command Language -(http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta -g_02). See also *note Bash Features: (bashref)Top. - - The shell variables controlling behavior of `backup' and `restore' -are described in the following subsections. - -* Menu: - -* General-Purpose Variables:: -* Magnetic Tape Control:: -* User Hooks:: -* backup-specs example:: An Example Text of `Backup-specs' - - -File: tar.info, Node: General-Purpose Variables, Next: Magnetic Tape Control, Up: Backup Parameters - -5.4.1 General-Purpose Variables -------------------------------- - - -- Backup variable: ADMINISTRATOR - The user name of the backup administrator. `Backup' scripts sends - a backup report to this address. - - -- Backup variable: BACKUP_HOUR - The hour at which the backups are done. This can be a number from - 0 to 23, or the time specification in form HOURS:MINUTES, or the - string `now'. - - This variable is used by `backup'. Its value may be overridden - using `--time' option (*note Scripted Backups::). - - -- Backup variable: TAPE_FILE - The device `tar' writes the archive to. If TAPE_FILE is a remote - archive (*note remote-dev::), backup script will suppose that your - `mt' is able to access remote devices. If RSH (*note RSH::) is - set, `--rsh-command' option will be added to invocations of `mt'. - - -- Backup variable: BLOCKING - The blocking factor `tar' will use when writing the dump archive. - *Note Blocking Factor::. - - -- Backup variable: BACKUP_DIRS - A list of file systems to be dumped (for `backup'), or restored - (for `restore'). You can include any directory name in the list - -- subdirectories on that file system will be included, regardless - of how they may look to other networked machines. Subdirectories - on other file systems will be ignored. - - The host name specifies which host to run `tar' on, and should - normally be the host that actually contains the file system. - However, the host machine must have GNU `tar' installed, and must - be able to access the directory containing the backup scripts and - their support files using the same file name that is used on the - machine where the scripts are run (i.e., what `pwd' will print - when in that directory on that machine). If the host that contains - the file system does not have this capability, you can specify - another host as long as it can access the file system through NFS. - - If the list of file systems is very long you may wish to put it in - a separate file. This file is usually named `/etc/backup/dirs', - but this name may be overridden in `backup-specs' using `DIRLIST' - variable. - - -- Backup variable: DIRLIST - The name of the file that contains a list of file systems to backup - or restore. By default it is `/etc/backup/dirs'. - - -- Backup variable: BACKUP_FILES - A list of individual files to be dumped (for `backup'), or restored - (for `restore'). These should be accessible from the machine on - which the backup script is run. - - If the list of file systems is very long you may wish to store it - in a separate file. This file is usually named - `/etc/backup/files', but this name may be overridden in - `backup-specs' using `FILELIST' variable. - - -- Backup variable: FILELIST - The name of the file that contains a list of individual files to - backup or restore. By default it is `/etc/backup/files'. - - -- Backup variable: MT - Full file name of `mt' binary. - - -- Backup variable: RSH - Full file name of `rsh' binary or its equivalent. You may wish to - set it to `ssh', to improve security. In this case you will have - to use public key authentication. - - -- Backup variable: RSH_COMMAND - Full file name of `rsh' binary on remote machines. This will be - passed via `--rsh-command' option to the remote invocation of GNU - `tar'. - - -- Backup variable: VOLNO_FILE - Name of temporary file to hold volume numbers. This needs to be - accessible by all the machines which have file systems to be - dumped. - - -- Backup variable: XLIST - Name of "exclude file list". An "exclude file list" is a file - located on the remote machine and containing the list of files to - be excluded from the backup. Exclude file lists are searched in - /etc/tar-backup directory. A common use for exclude file lists is - to exclude files containing security-sensitive information (e.g., - `/etc/shadow' from backups). - - This variable affects only `backup'. - - -- Backup variable: SLEEP_TIME - Time to sleep between dumps of any two successive file systems - - This variable affects only `backup'. - - -- Backup variable: DUMP_REMIND_SCRIPT - Script to be run when it's time to insert a new tape in for the - next volume. Administrators may want to tailor this script for - their site. If this variable isn't set, GNU `tar' will display - its built-in prompt, and will expect confirmation from the - console. For the description of the default prompt, see *note - change volume prompt::. - - - -- Backup variable: SLEEP_MESSAGE - Message to display on the terminal while waiting for dump time. - Usually this will just be some literal text. - - -- Backup variable: TAR - Full file name of the GNU `tar' executable. If this is not set, - backup scripts will search `tar' in the current shell path. - - -File: tar.info, Node: Magnetic Tape Control, Next: User Hooks, Prev: General-Purpose Variables, Up: Backup Parameters - -5.4.2 Magnetic Tape Control ---------------------------- - -Backup scripts access tape device using special "hook functions". -These functions take a single argument - the name of the tape device. -Their names are kept in the following variables: - - -- Backup variable: MT_BEGIN - The name of "begin" function. This function is called before - accessing the drive. By default it retensions the tape: - - MT_BEGIN=mt_begin - - mt_begin() { - mt -f "$1" retension - } - - -- Backup variable: MT_REWIND - The name of "rewind" function. The default definition is as - follows: - - MT_REWIND=mt_rewind - - mt_rewind() { - mt -f "$1" rewind - } - - - -- Backup variable: MT_OFFLINE - The name of the function switching the tape off line. By default - it is defined as follows: - - MT_OFFLINE=mt_offline - - mt_offline() { - mt -f "$1" offl - } - - -- Backup variable: MT_STATUS - The name of the function used to obtain the status of the archive - device, including error count. Default definition: - - MT_STATUS=mt_status - - mt_status() { - mt -f "$1" status - } - - -File: tar.info, Node: User Hooks, Next: backup-specs example, Prev: Magnetic Tape Control, Up: Backup Parameters - -5.4.3 User Hooks ----------------- - -"User hooks" are shell functions executed before and after each `tar' -invocation. Thus, there are "backup hooks", which are executed before -and after dumping each file system, and "restore hooks", executed -before and after restoring a file system. Each user hook is a shell -function taking four arguments: - - -- User Hook Function: hook LEVEL HOST FS FSNAME - Its arguments are: - - LEVEL - Current backup or restore level. - - HOST - Name or IP address of the host machine being dumped or - restored. - - FS - Full file name of the file system being dumped or restored. - - FSNAME - File system name with directory separators replaced with - colons. This is useful, e.g., for creating unique files. - - Following variables keep the names of user hook functions - - -- Backup variable: DUMP_BEGIN - Dump begin function. It is executed before dumping the file - system. - - -- Backup variable: DUMP_END - Executed after dumping the file system. - - -- Backup variable: RESTORE_BEGIN - Executed before restoring the file system. - - -- Backup variable: RESTORE_END - Executed after restoring the file system. - - -File: tar.info, Node: backup-specs example, Prev: User Hooks, Up: Backup Parameters - -5.4.4 An Example Text of `Backup-specs' ---------------------------------------- - -The following is an example of `backup-specs': - - # site-specific parameters for file system backup. - - ADMINISTRATOR=friedman - BACKUP_HOUR=1 - TAPE_FILE=/dev/nrsmt0 - - # Use `ssh' instead of the less secure `rsh' - RSH=/usr/bin/ssh - RSH_COMMAND=/usr/bin/ssh - - # Override MT_STATUS function: - my_status() { - mts -t $TAPE_FILE - } - MT_STATUS=my_status - - # Disable MT_OFFLINE function - MT_OFFLINE=: - - BLOCKING=124 - BACKUP_DIRS=" - albert:/fs/fsf - apple-gunkies:/gd - albert:/fs/gd2 - albert:/fs/gp - geech:/usr/jla - churchy:/usr/roland - albert:/ - albert:/usr - apple-gunkies:/ - apple-gunkies:/usr - gnu:/hack - gnu:/u - apple-gunkies:/com/mailer/gnu - apple-gunkies:/com/archive/gnu" - - BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]" - - -File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups - -5.5 Using the Backup Scripts -============================ - -The syntax for running a backup script is: - - backup --level=LEVEL --time=TIME - - The `level' option requests the dump level. Thus, to produce a full -dump, specify `--level=0' (this is the default, so `--level' may be -omitted if its value is `0'). (1) - - The `--time' option determines when should the backup be run. TIME -may take three forms: - -HH:MM - The dump must be run at HH hours MM minutes. - -HH - The dump must be run at HH hours - -now - The dump must be run immediately. - - You should start a script with a tape or disk mounted. Once you -start a script, it prompts you for new tapes or disks as it needs them. -Media volumes don't have to correspond to archive files -- a -multi-volume archive can be started in the middle of a tape that -already contains the end of another multi-volume archive. The -`restore' script prompts for media by its archive volume, so to avoid -an error message you should keep track of which tape (or disk) contains -which volume of the archive (*note Scripted Restoration::). - - The backup scripts write two files on the file system. The first is -a record file in `/etc/tar-backup/', which is used by the scripts to -store and retrieve information about which files were dumped. This -file is not meant to be read by humans, and should not be deleted by -them. *Note Snapshot Files::, for a more detailed explanation of this -file. - - The second file is a log file containing the names of the file -systems and files dumped, what time the backup was made, and any error -messages that were generated, as well as how much space was left in the -media volume after the last volume of the archive was written. You -should check this log file after every backup. The file name is -`log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and -N represents current dump level number. - - The script also prints the name of each system being dumped to the -standard output. - - Following is the full list of options accepted by `backup' script: - -`-l LEVEL' -`--level=LEVEL' - Do backup level LEVEL (default 0). - -`-f' -`--force' - Force backup even if today's log file already exists. - -`-v[LEVEL]' -`--verbose[=LEVEL]' - Set verbosity level. The higher the level is, the more debugging - information will be output during execution. Default LEVEL is - 100, which means the highest debugging level. - -`-t START-TIME' -`--time=START-TIME' - Wait till TIME, then do backup. - -`-h' -`--help' - Display short help message and exit. - -`-V' -`--version' - Display information about the program's name, version, origin and - legal status, all on standard output, and then exit successfully. - - ---------- Footnotes ---------- - - (1) For backward compatibility, the `backup' will also try to deduce -the requested dump level from the name of the script itself. If the -name consists of a string `level-' followed by a single decimal digit, -that digit is taken as the dump level number. Thus, you may create a -link from `backup' to `level-1' and then run `level-1' whenever you -need to create a level one dump. - - -File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups - -5.6 Using the Restore Script -============================ - -To restore files that were archived using a scripted backup, use the -`restore' script. Its usage is quite straightforward. In the simplest -form, invoke `restore --all', it will then restore all the file systems -and files specified in `backup-specs' (*note BACKUP_DIRS: -General-Purpose Variables.). - - You may select the file systems (and/or files) to restore by giving -`restore' list of "patterns" in its command line. For example, running - - restore 'albert:*' - -will restore all file systems on the machine `albert'. A more -complicated example: - - restore 'albert:*' '*:/var' - -This command will restore all file systems on the machine `albert' as -well as `/var' file system on all machines. - - By default `restore' will start restoring files from the lowest -available dump level (usually zero) and will continue through all -available dump levels. There may be situations where such a thorough -restore is not necessary. For example, you may wish to restore only -files from the recent level one backup. To do so, use `--level' -option, as shown in the example below: - - restore --level=1 - - The full list of options accepted by `restore' follows: - -`-a' -`--all' - Restore all file systems and files specified in `backup-specs' - -`-l LEVEL' -`--level=LEVEL' - Start restoring from the given backup level, instead of the - default 0. - -`-v[LEVEL]' -`--verbose[=LEVEL]' - Set verbosity level. The higher the level is, the more debugging - information will be output during execution. Default LEVEL is - 100, which means the highest debugging level. - -`-h' -`--help' - Display short help message and exit. - -`-V' -`--version' - Display information about the program's name, version, origin and - legal status, all on standard output, and then exit successfully. - - You should start the restore script with the media containing the -first volume of the archive mounted. The script will prompt for other -volumes as they are needed. If the archive is on tape, you don't need -to rewind the tape to to its beginning--if the tape head is positioned -past the beginning of the archive, the script will rewind the tape as -needed. *Note Tape Positioning::, for a discussion of tape positioning. - - *Warning:* The script will delete files from the active file - system if they were not in the file system when the archive was - made. - - *Note Incremental Dumps::, for an explanation of how the script makes -that determination. - - -File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top - -6 Choosing Files and Names for `tar' -************************************ - - _(This message will disappear, once this node revised.)_ - -Certain options to `tar' enable you to specify a name for your archive. -Other options let you decide which files to include or exclude from -the archive, based on when or whether files were modified, whether the -file names do or don't match specified patterns, or whether files are -in specified directories. - - This chapter discusses these options in detail. - -* Menu: - -* file:: Choosing the Archive's Name -* Selecting Archive Members:: -* files:: Reading Names from a File -* exclude:: Excluding Some Files -* wildcards:: Wildcards Patterns and Matching -* quoting styles:: Ways of Quoting Special Characters in Names -* transform:: Modifying File and Member Names -* after:: Operating Only on New Files -* recurse:: Descending into Directories -* one:: Crossing File System Boundaries - - -File: tar.info, Node: file, Next: Selecting Archive Members, Up: Choosing - -6.1 Choosing and Naming Archive Files -===================================== - - _(This message will disappear, once this node revised.)_ - -By default, `tar' uses an archive file name that was compiled when it -was built on the system; usually this name refers to some physical tape -drive on the machine. However, the person who installed `tar' on the -system may not have set the default to a meaningful value as far as -most users are concerned. As a result, you will usually want to tell -`tar' where to find (or create) the archive. The `--file=ARCHIVE-NAME' -(`-f ARCHIVE-NAME') option allows you to either specify or name a file -to use as the archive instead of the default archive file location. - -`--file=ARCHIVE-NAME' -`-f ARCHIVE-NAME' - Name the archive to create or operate on. Use in conjunction with - any operation. - - For example, in this `tar' command, - - $ tar -cvf collection.tar blues folk jazz - -`collection.tar' is the name of the archive. It must directly follow -the `-f' option, since whatever directly follows `-f' _will_ end up -naming the archive. If you neglect to specify an archive name, you may -end up overwriting a file in the working directory with the archive you -create since `tar' will use this file's name for the archive name. - - An archive can be saved as a file in the file system, sent through a -pipe or over a network, or written to an I/O device such as a tape, -floppy disk, or CD write drive. - - If you do not name the archive, `tar' uses the value of the -environment variable `TAPE' as the file name for the archive. If that -is not available, `tar' uses a default, compiled-in archive name, -usually that for tape unit zero (i.e., `/dev/tu00'). - - If you use `-' as an ARCHIVE-NAME, `tar' reads the archive from -standard input (when listing or extracting files), or writes it to -standard output (when creating an archive). If you use `-' as an -ARCHIVE-NAME when modifying an archive, `tar' reads the original -archive from its standard input and writes the entire new archive to -its standard output. - - The following example is a convenient way of copying directory -hierarchy from `sourcedir' to `targetdir'. - - $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -) - - The `-C' option allows to avoid using subshells: - - $ tar -C sourcedir -cf - . | tar -C targetdir -xpf - - - In both examples above, the leftmost `tar' invocation archives the -contents of `sourcedir' to the standard output, while the rightmost one -reads this archive from its standard input and extracts it. The `-p' -option tells it to restore permissions of the extracted files. - - To specify an archive file on a device attached to a remote machine, -use the following: - - --file=HOSTNAME:/DEV/FILE-NAME - -`tar' will complete the remote connection, if possible, and prompt you -for a username and password. If you use -`--file=@HOSTNAME:/DEV/FILE-NAME', `tar' will complete the remote -connection, if possible, using your username as the username on the -remote machine. - - If the archive file name includes a colon (`:'), then it is assumed -to be a file on another machine. If the archive file is -`USER@HOST:FILE', then FILE is used on the host HOST. The remote host -is accessed using the `rsh' program, with a username of USER. If the -username is omitted (along with the `@' sign), then your user name will -be used. (This is the normal `rsh' behavior.) It is necessary for the -remote machine, in addition to permitting your `rsh' access, to have -the `rmt' program installed (This command is included in the GNU `tar' -distribution and by default is installed under `PREFIX/libexec/rmt', -were PREFIX means your installation prefix). If you need to use a file -whose name includes a colon, then the remote tape drive behavior can be -inhibited by using the `--force-local' option. - - When the archive is being created to `/dev/null', GNU `tar' tries to -minimize input and output operations. The Amanda backup system, when -used with GNU `tar', has an initial sizing pass which uses this feature. - - -File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing - -6.2 Selecting Archive Members -============================= - -"File Name arguments" specify which files in the file system `tar' -operates on, when creating or adding to an archive, or which archive -members `tar' operates on, when reading or deleting from an archive. -*Note Operations::. - - To specify file names, you can include them as the last arguments on -the command line, as follows: - tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...] - - If a file name begins with dash (`-'), precede it with `--add-file' -option to prevent it from being treated as an option. - - By default GNU `tar' attempts to "unquote" each file or member name, -replacing "escape sequences" according to the following table: - -Escape Replaced with ------------------------------------------------------------ -\a Audible bell (ASCII 7) -\b Backspace (ASCII 8) -\f Form feed (ASCII 12) -\n New line (ASCII 10) -\r Carriage return (ASCII 13) -\t Horizontal tabulation (ASCII 9) -\v Vertical tabulation (ASCII 11) -\? ASCII 127 -\N ASCII N (N should be an octal number - of up to 3 digits) - - A backslash followed by any other symbol is retained. - - This default behavior is controlled by the following command line -option: - -`--unquote' - Enable unquoting input file or member names (default). - -`--no-unquote' - Disable unquoting input file or member names. - - If you specify a directory name as a file name argument, all the -files in that directory are operated on by `tar'. - - If you do not specify files, `tar' behavior differs depending on the -operation mode as described below: - - When `tar' is invoked with `--create' (`-c'), `tar' will stop -immediately, reporting the following: - - $ tar cf a.tar - tar: Cowardly refusing to create an empty archive - Try `tar --help' or `tar --usage' for more information. - - If you specify either `--list' (`-t') or `--extract' (`--get', -`-x'), `tar' operates on all the archive members in the archive. - - If run with `--diff' option, tar will compare the archive with the -contents of the current working directory. - - If you specify any other operation, `tar' does nothing. - - By default, `tar' takes file names from the command line. However, -there are other ways to specify file or member names, or to modify the -manner in which `tar' selects the files or members upon which to -operate. In general, these methods work both for specifying the names -of files and archive members. - - -File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing - -6.3 Reading Names from a File -============================= - -Instead of giving the names of files or archive members on the command -line, you can put the names into a file, and then use the -`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'. -Give the name of the file which contains the list of files to include -as the argument to `--files-from'. In the list, the file names should -be separated by newlines. You will frequently use this option when you -have generated the list of files to archive with the `find' utility. - -`--files-from=FILE-NAME' -`-T FILE-NAME' - Get names to extract or create from file FILE-NAME. - - If you give a single dash as a file name for `--files-from', (i.e., -you specify either `--files-from=-' or `-T -'), then the file names are -read from standard input. - - Unless you are running `tar' with `--create', you can not use both -`--files-from=-' and `--file=-' (`-f -') in the same command. - - Any number of `-T' options can be given in the command line. - - The following example shows how to use `find' to generate a list of -files smaller than 400K in length and put that list into a file called -`small-files'. You can then use the `-T' option to `tar' to specify -the files from that file, `small-files', to create the archive -`little.tgz'. (The `-z' option to `tar' compresses the archive with -`gzip'; *note gzip:: for more information.) - - $ find . -size -400 -print > small-files - $ tar -c -v -z -T small-files -f little.tgz - -In the file list given by `-T' option, any file name beginning with `-' -character is considered a `tar' option and is processed accordingly.(1) -For example, the common use of this feature is to change to another -directory by specifying `-C' option: - - $ cat list - -C/etc - passwd - hosts - -C/lib - libc.a - $ tar -c -f foo.tar --files-from list - -In this example, `tar' will first switch to `/etc' directory and add -files `passwd' and `hosts' to the archive. Then it will change to -`/lib' directory and will archive the file `libc.a'. Thus, the -resulting archive `foo.tar' will contain: - - $ tar tf foo.tar - passwd - hosts - libc.a - - - Notice that the option parsing algorithm used with `-T' is stricter -than the one used by shell. Namely, when specifying option arguments, -you should observe the following rules: - - * When using short (single-letter) option form, its argument must - immediately follow the option letter, without any intervening - whitespace. For example: `-Cdir'. - - * When using long option form, the option argument must be separated - from the option by a single equal sign. No whitespace is allowed - on any side of the equal sign. For example: `--directory=dir'. - - * For both short and long option forms, the option argument can be - given on the next line after the option name, e.g.: - - --directory - dir - - and - - -C - dir - - If you happen to have a file whose name starts with `-', precede it -with `--add-file' option to prevent it from being recognized as an -option. For example: `--add-file=--my-file'. - -* Menu: - -* nul:: - - ---------- Footnotes ---------- - - (1) Versions of GNU `tar' up to 1.15.1 recognized only `-C' option -in file lists, and only if the option and its argument occupied two -consecutive lines. - - -File: tar.info, Node: nul, Up: files - -6.3.1 `NUL' Terminated File Names ---------------------------------- - -The `--null' option causes `--files-from=FILE-OF-NAMES' (`-T -FILE-OF-NAMES') to read file names terminated by a `NUL' instead of a -newline, so files whose names contain newlines can be archived using -`--files-from'. - -`--null' - Only consider `NUL' terminated file names, instead of files that - terminate in a newline. - - The `--null' option is just like the one in GNU `xargs' and `cpio', -and is useful with the `-print0' predicate of GNU `find'. In `tar', -`--null' also disables special handling for file names that begin with -dash. - - This example shows how to use `find' to generate a list of files -larger than 800K in length and put that list into a file called -`long-files'. The `-print0' option to `find' is just like `-print', -except that it separates files with a `NUL' rather than with a newline. -You can then run `tar' with both the `--null' and `-T' options to -specify that `tar' get the files from that file, `long-files', to -create the archive `big.tgz'. The `--null' option to `tar' will cause -`tar' to recognize the `NUL' separator between files. - - $ find . -size +800 -print0 > long-files - $ tar -c -v --null --files-from=long-files --file=big.tar - - -File: tar.info, Node: exclude, Next: wildcards, Prev: files, Up: Choosing - -6.4 Excluding Some Files -======================== - - _(This message will disappear, once this node revised.)_ - -To avoid operating on files whose names match a particular pattern, use -the `--exclude' or `--exclude-from' options. - -`--exclude=PATTERN' - Causes `tar' to ignore files that match the PATTERN. - - The `--exclude=PATTERN' option prevents any file or member whose -name matches the shell wildcard (PATTERN) from being operated on. For -example, to create an archive with all the contents of the directory -`src' except for files whose names end in `.o', use the command `tar --cf src.tar --exclude='*.o' src'. - - You may give multiple `--exclude' options. - -`--exclude-from=FILE' -`-X FILE' - Causes `tar' to ignore files that match the patterns listed in - FILE. - - Use the `--exclude-from' option to read a list of patterns, one per -line, from FILE; `tar' will ignore files matching those patterns. Thus -if `tar' is called as `tar -c -X foo .' and the file `foo' contains a -single line `*.o', no files whose names end in `.o' will be added to -the archive. - - Notice, that lines from FILE are read verbatim. One of the frequent -errors is leaving some extra whitespace after a file name, which is -difficult to catch using text editors. - - However, empty lines are OK. - -`--exclude-vcs' - Exclude files and directories used by some version control systems. - - As of version 1.20, the following files are excluded: - - * `CVS/', and everything under it - - * `RCS/', and everything under it - - * `SCCS/', and everything under it - - * `.git/', and everything under it - - * `.gitignore' - - * `.cvsignore' - - * `.svn/', and everything under it - - * `.arch-ids/', and everything under it - - * `{arch}/', and everything under it - - * `=RELEASE-ID' - - * `=meta-update' - - * `=update' - - When creating an archive, the `--exclude-caches' option family -causes `tar' to exclude all directories that contain a "cache directory -tag". A cache directory tag is a short file with the well-known name -`CACHEDIR.TAG' and having a standard header specified in -`http://www.brynosaurus.com/cachedir/spec.html'. Various applications -write cache directory tags into directories they use to hold -regenerable, non-precious data, so that such data can be more easily -excluded from backups. - - There are three `exclude-caches' options, each providing a different -exclusion semantics: - -`--exclude-caches' - Do not archive the contents of the directory, but archive the - directory itself and the `CACHEDIR.TAG' file. - -`--exclude-caches-under' - Do not archive the contents of the directory, nor the - `CACHEDIR.TAG' file, archive only the directory itself. - -`--exclude-caches-all' - Omit directories containing `CACHEDIR.TAG' file entirely. - - Another option family, `--exclude-tag', provides a generalization of -this concept. It takes a single argument, a file name to look for. -Any directory that contains this file will be excluded from the dump. -Similarly to `exclude-caches', there are three options in this option -family: - -`--exclude-tag=FILE' - Do not dump the contents of the directory, but dump the directory - itself and the FILE. - -`--exclude-tag-under=FILE' - Do not dump the contents of the directory, nor the FILE, archive - only the directory itself. - -`--exclude-tag-all=FILE' - Omit directories containing FILE file entirely. - - Multiple `--exclude-tag*' options can be given. - - For example, given this directory: - - $ find dir - dir - dir/blues - dir/jazz - dir/folk - dir/folk/tagfile - dir/folk/sanjuan - dir/folk/trote - - The `--exclude-tag' will produce the following: - - $ tar -cf archive.tar --exclude-tag=tagfile -v dir - dir/ - dir/blues - dir/jazz - dir/folk/ - tar: dir/folk/: contains a cache directory tag tagfile; - contents not dumped - dir/folk/tagfile - - Both the `dir/folk' directory and its tagfile are preserved in the -archive, however the rest of files in this directory are not. - - Now, using the `--exclude-tag-under' option will exclude `tagfile' -from the dump, while still preserving the directory itself, as shown in -this example: - - $ tar -cf archive.tar --exclude-tag-under=tagfile -v dir - dir/ - dir/blues - dir/jazz - dir/folk/ - ./tar: dir/folk/: contains a cache directory tag tagfile; - contents not dumped - - Finally, using `--exclude-tag-all' omits the `dir/folk' directory -entirely: - - $ tar -cf archive.tar --exclude-tag-all=tagfile -v dir - dir/ - dir/blues - dir/jazz - ./tar: dir/folk/: contains a cache directory tag tagfile; - directory not dumped - -* Menu: - -* problems with exclude:: - - -File: tar.info, Node: problems with exclude, Up: exclude - -Problems with Using the `exclude' Options ------------------------------------------ - -Some users find `exclude' options confusing. Here are some common -pitfalls: - - * The main operating mode of `tar' does not act on a file name - explicitly listed on the command line, if one of its file name - components is excluded. In the example above, if you create an - archive and exclude files that end with `*.o', but explicitly name - the file `dir.o/foo' after all the options have been listed, - `dir.o/foo' will be excluded from the archive. - - * You can sometimes confuse the meanings of `--exclude' and - `--exclude-from'. Be careful: use `--exclude' when files to be - excluded are given as a pattern on the command line. Use - `--exclude-from' to introduce the name of a file which contains a - list of patterns, one per line; each of these patterns can exclude - zero, one, or many files. - - * When you use `--exclude=PATTERN', be sure to quote the PATTERN - parameter, so GNU `tar' sees wildcard characters like `*'. If you - do not do this, the shell might expand the `*' itself using files - at hand, so `tar' might receive a list of files instead of one - pattern, or none at all, making the command somewhat illegal. - This might not correspond to what you want. - - For example, write: - - $ tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY - - rather than: - - # _Wrong!_ - $ tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY - - * You must use use shell syntax, or globbing, rather than `regexp' - syntax, when using exclude options in `tar'. If you try to use - `regexp' syntax to describe files to be excluded, your command - might fail. - - * In earlier versions of `tar', what is now the `--exclude-from' - option was called `--exclude' instead. Now, `--exclude' applies - to patterns listed on the command line and `--exclude-from' - applies to patterns listed in a file. - - - -File: tar.info, Node: wildcards, Next: quoting styles, Prev: exclude, Up: Choosing - -6.5 Wildcards Patterns and Matching -=================================== - -"Globbing" is the operation by which "wildcard" characters, `*' or `?' -for example, are replaced and expanded into all existing files matching -the given pattern. GNU `tar' can use wildcard patterns for matching -(or globbing) archive members when extracting from or listing an -archive. Wildcard patterns are also used for verifying volume labels -of `tar' archives. This section has the purpose of explaining wildcard -syntax for `tar'. - - A PATTERN should be written according to shell syntax, using wildcard -characters to effect globbing. Most characters in the pattern stand -for themselves in the matched string, and case is significant: `a' will -match only `a', and not `A'. The character `?' in the pattern matches -any single character in the matched string. The character `*' in the -pattern matches zero, one, or more single characters in the matched -string. The character `\' says to take the following character of the -pattern _literally_; it is useful when one needs to match the `?', `*', -`[' or `\' characters, themselves. - - The character `[', up to the matching `]', introduces a character -class. A "character class" is a list of acceptable characters for the -next single character of the matched string. For example, `[abcde]' -would match any of the first five letters of the alphabet. Note that -within a character class, all of the "special characters" listed above -other than `\' lose their special meaning; for example, `[-\\[*?]]' -would match any of the characters, `-', `\', `[', `*', `?', or `]'. -(Due to parsing constraints, the characters `-' and `]' must either -come _first_ or _last_ in a character class.) - - If the first character of the class after the opening `[' is `!' or -`^', then the meaning of the class is reversed. Rather than listing -character to match, it lists those characters which are _forbidden_ as -the next single character of the matched string. - - Other characters of the class stand for themselves. The special -construction `[A-E]', using an hyphen between two letters, is meant to -represent all characters between A and E, inclusive. - - Periods (`.') or forward slashes (`/') are not considered special -for wildcard matches. However, if a pattern completely matches a -directory prefix of a matched string, then it matches the full matched -string: thus, excluding a directory also excludes all the files beneath -it. - -* Menu: - -* controlling pattern-matching:: - - -File: tar.info, Node: controlling pattern-matching, Up: wildcards - -Controlling Pattern-Matching ----------------------------- - -For the purposes of this section, we call "exclusion members" all -member names obtained while processing `--exclude' and `--exclude-from' -options, and "inclusion members" those member names that were given in -the command line or read from the file specified with `--files-from' -option. - - These two pairs of member lists are used in the following operations: -`--diff', `--extract', `--list', `--update'. - - There are no inclusion members in create mode (`--create' and -`--append'), since in this mode the names obtained from the command -line refer to _files_, not archive members. - - By default, inclusion members are compared with archive members -literally (1) and exclusion members are treated as globbing patterns. -For example: - - $ tar tf foo.tar - a.c - b.c - a.txt - [remarks] - # Member names are used verbatim: - $ tar -xf foo.tar -v '[remarks]' - [remarks] - # Exclude member names are globbed: - $ tar -xf foo.tar -v --exclude '*.c' - a.txt - [remarks] - - This behavior can be altered by using the following options: - -`--wildcards' - Treat all member names as wildcards. - -`--no-wildcards' - Treat all member names as literal strings. - - Thus, to extract files whose names end in `.c', you can use: - - $ tar -xf foo.tar -v --wildcards '*.c' - a.c - b.c - -Notice quoting of the pattern to prevent the shell from interpreting it. - - The effect of `--wildcards' option is canceled by `--no-wildcards'. -This can be used to pass part of the command line arguments verbatim -and other part as globbing patterns. For example, the following -invocation: - - $ tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]' - -instructs `tar' to extract from `foo.tar' all files whose names end in -`.txt' and the file named `[remarks]'. - - Normally, a pattern matches a name if an initial subsequence of the -name's components matches the pattern, where `*', `?', and `[...]' are -the usual shell wildcards, `\' escapes wildcards, and wildcards can -match `/'. - - Other than optionally stripping leading `/' from names (*note -absolute::), patterns and names are used as-is. For example, trailing -`/' is not trimmed from a user-specified name before deciding whether -to exclude it. - - However, this matching procedure can be altered by the options listed -below. These options accumulate. For example: - - --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme' - -ignores case when excluding `makefile', but not when excluding `readme'. - -`--anchored' -`--no-anchored' - If anchored, a pattern must match an initial subsequence of the - name's components. Otherwise, the pattern can match any - subsequence. Default is `--no-anchored' for exclusion members and - `--anchored' inclusion members. - -`--ignore-case' -`--no-ignore-case' - When ignoring case, upper-case patterns match lower-case names and - vice versa. When not ignoring case (the default), matching is - case-sensitive. - -`--wildcards-match-slash' -`--no-wildcards-match-slash' - When wildcards match slash (the default for exclusion members), a - wildcard like `*' in the pattern can match a `/' in the name. - Otherwise, `/' is matched only by `/'. - - - The `--recursion' and `--no-recursion' options (*note recurse::) -also affect how member patterns are interpreted. If recursion is in -effect, a pattern matches a name if it matches any of the name's parent -directories. - - The following table summarizes pattern-matching default values: - -Members Default settings --------------------------------------------------------------------------- -Inclusion `--no-wildcards --anchored - --no-wildcards-match-slash' -Exclusion `--wildcards --no-anchored - --wildcards-match-slash' - - ---------- Footnotes ---------- - - (1) Notice that earlier GNU `tar' versions used globbing for -inclusion members, which contradicted to UNIX98 specification and was -not documented. *Note Changes::, for more information on this and other -changes. - - -File: tar.info, Node: quoting styles, Next: transform, Prev: wildcards, Up: Choosing - -6.6 Quoting Member Names -======================== - -When displaying member names, `tar' takes care to avoid ambiguities -caused by certain characters. This is called "name quoting". The -characters in question are: - - * Non-printable control characters: - - Character ASCII Character name - --------------------------------------------------------------- - \a 7 Audible bell - \b 8 Backspace - \f 12 Form feed - \n 10 New line - \r 13 Carriage return - \t 9 Horizontal tabulation - \v 11 Vertical tabulation - - * Space (ASCII 32) - - * Single and double quotes (`'' and `"') - - * Backslash (`\') - - The exact way `tar' uses to quote these characters depends on the -"quoting style". The default quoting style, called "escape" (see -below), uses backslash notation to represent control characters, space -and backslash. Using this quoting style, control characters are -represented as listed in column `Character' in the above table, a space -is printed as `\ ' and a backslash as `\\'. - - GNU `tar' offers seven distinct quoting styles, which can be selected -using `--quoting-style' option: - -`--quoting-style=STYLE' - Sets quoting style. Valid values for STYLE argument are: literal, - shell, shell-always, c, escape, locale, clocale. - - These styles are described in detail below. To illustrate their -effect, we will use an imaginary tar archive `arch.tar' containing the -following members: - - # 1. Contains horizontal tabulation character. - a tab - # 2. Contains newline character - a - newline - # 3. Contains a space - a space - # 4. Contains double quotes - a"double"quote - # 5. Contains single quotes - a'single'quote - # 6. Contains a backslash character: - a\backslash - - Here is how usual `ls' command would have listed them, if they had -existed in the current working directory: - - $ ls - a\ttab - a\nnewline - a\ space - a"double"quote - a'single'quote - a\\backslash - - Quoting styles: - -`literal' - No quoting, display each character as is: - - $ tar tf arch.tar --quoting-style=literal - ./ - ./a space - ./a'single'quote - ./a"double"quote - ./a\backslash - ./a tab - ./a - newline - -`shell' - Display characters the same way Bourne shell does: control - characters, except `\t' and `\n', are printed using backslash - escapes, `\t' and `\n' are printed as is, and a single quote is - printed as `\''. If a name contains any quoted characters, it is - enclosed in single quotes. In particular, if a name contains - single quotes, it is printed as several single-quoted strings: - - $ tar tf arch.tar --quoting-style=shell - ./ - './a space' - './a'\''single'\''quote' - './a"double"quote' - './a\backslash' - './a tab' - './a - newline' - -`shell-always' - Same as `shell', but the names are always enclosed in single - quotes: - - $ tar tf arch.tar --quoting-style=shell-always - './' - './a space' - './a'\''single'\''quote' - './a"double"quote' - './a\backslash' - './a tab' - './a - newline' - -`c' - Use the notation of the C programming language. All names are - enclosed in double quotes. Control characters are quoted using - backslash notations, double quotes are represented as `\"', - backslash characters are represented as `\\'. Single quotes and - spaces are not quoted: - - $ tar tf arch.tar --quoting-style=c - "./" - "./a space" - "./a'single'quote" - "./a\"double\"quote" - "./a\\backslash" - "./a\ttab" - "./a\nnewline" - -`escape' - Control characters are printed using backslash notation, a space is - printed as `\ ' and a backslash as `\\'. This is the default - quoting style, unless it was changed when configured the package. - - $ tar tf arch.tar --quoting-style=escape - ./ - ./a space - ./a'single'quote - ./a"double"quote - ./a\\backslash - ./a\ttab - ./a\nnewline - -`locale' - Control characters, single quote and backslash are printed using - backslash notation. All names are quoted using left and right - quotation marks, appropriate to the current locale. If it does not - define quotation marks, use ``' as left and `'' as right quotation - marks. Any occurrences of the right quotation mark in a name are - escaped with `\', for example: - - For example: - - $ tar tf arch.tar --quoting-style=locale - `./' - `./a space' - `./a\'single\'quote' - `./a"double"quote' - `./a\\backslash' - `./a\ttab' - `./a\nnewline' - -`clocale' - Same as `locale', but `"' is used for both left and right - quotation marks, if not provided by the currently selected locale: - - $ tar tf arch.tar --quoting-style=clocale - "./" - "./a space" - "./a'single'quote" - "./a\"double\"quote" - "./a\\backslash" - "./a\ttab" - "./a\nnewline" - - You can specify which characters should be quoted in addition to -those implied by the current quoting style: - -`--quote-chars=STRING' - Always quote characters from STRING, even if the selected quoting - style would not quote them. - - For example, using `escape' quoting (compare with the usual escape -listing above): - - $ tar tf arch.tar --quoting-style=escape --quote-chars=' "' - ./ - ./a\ space - ./a'single'quote - ./a\"double\"quote - ./a\\backslash - ./a\ttab - ./a\nnewline - - To disable quoting of such additional characters, use the following -option: - -`--no-quote-chars=STRING' - Remove characters listed in STRING from the list of quoted - characters set by the previous `--quote-chars' option. - - This option is particularly useful if you have added `--quote-chars' -to your `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for -the current invocation. - - Note, that `--no-quote-chars' does _not_ disable those characters -that are quoted by default in the selected quoting style. - - -File: tar.info, Node: transform, Next: after, Prev: quoting styles, Up: Choosing - -6.7 Modifying File and Member Names -=================================== - -`Tar' archives contain detailed information about files stored in them -and full file names are part of that information. When storing file to -an archive, its file name is recorded in the archive along with the -actual file contents. When restoring from an archive, a file is -created on disk with exactly the same name as that stored in the -archive. In the majority of cases this is the desired behavior of a -file archiver. However, there are some cases when it is not. - - First of all, it is often unsafe to extract archive members with -absolute file names or those that begin with a `../'. GNU `tar' takes -special precautions when extracting such names and provides a special -option for handling them, which is described in *note absolute::. - - Secondly, you may wish to extract file names without some leading -directory components, or with otherwise modified names. In other cases -it is desirable to store files under differing names in the archive. - - GNU `tar' provides two options for these needs. - -`--strip-components=NUMBER' - Strip given NUMBER of leading components from file names before - extraction. - - For example, suppose you have archived whole `/usr' hierarchy to a -tar archive named `usr.tar'. Among other files, this archive contains -`usr/include/stdlib.h', which you wish to extract to the current -working directory. To do so, you type: - - $ tar -xf usr.tar --strip=2 usr/include/stdlib.h - - The option `--strip=2' instructs `tar' to strip the two leading -components (`usr/' and `include/') off the file name. - - If you add to the above invocation `--verbose' (`-v') option, you -will note that the verbose listing still contains the full file name, -with the two removed components still in place. This can be -inconvenient, so `tar' provides a special option for altering this -behavior: - -`--show-transformed-names' - Display file or member names with all requested transformations - applied. - -For example: - - $ tar -xf usr.tar -v --strip=2 usr/include/stdlib.h - usr/include/stdlib.h - $ tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h - stdlib.h - - Notice that in both cases the file is `stdlib.h' extracted to the -current working directory, `--show-transformed-names' affects only the -way its name is displayed. - - This option is especially useful for verifying whether the invocation -will have the desired effect. Thus, before running - - $ tar -x --strip=N - -it is often advisable to run - - $ tar -t -v --show-transformed --strip=N - -to make sure the command will produce the intended results. - - In case you need to apply more complex modifications to the file -name, GNU `tar' provides a general-purpose transformation option: - -`--transform=EXPRESSION' - Modify file names using supplied EXPRESSION. - -The EXPRESSION is a `sed'-like replace expression of the form: - - s/REGEXP/REPLACE/[FLAGS] - -where REGEXP is a "regular expression", REPLACE is a replacement for -each file name part that matches REGEXP. Both REGEXP and REPLACE are -described in detail in *note The "s" Command: (sed)The "s" Command. - - As in `sed', you can give several replace expressions, separated by -a semicolon. - - Supported FLAGS are: - -`g' - Apply the replacement to _all_ matches to the REGEXP, not just the - first. - -`i' - Use case-insensitive matching - -`x' - REGEXP is an "extended regular expression" (*note Extended regular - expressions: (sed)Extended regexps.). - -`NUMBER' - Only replace the NUMBERth match of the REGEXP. - - Note: the POSIX standard does not specify what should happen when - you mix the `g' and NUMBER modifiers. GNU `tar' follows the GNU - `sed' implementation in this regard, so the interaction is defined - to be: ignore matches before the NUMBERth, and then match and - replace all matches from the NUMBERth on. - - - Any delimiter can be used in lieue of `/', the only requirement being -that it be used consistently throughout the expression. For example, -the following two expressions are equivalent: - - s/one/two/ - s,one,two, - - Changing delimiters is often useful when the REGEX contains slashes. -For example, it is more convenient to write `s,/,-,' than `s/\//-/'. - - Here are several examples of `--transform' usage: - - 1. Extract `usr/' hierarchy into `usr/local/': - - $ tar --transform='s,usr/,usr/local/,' -x -f arch.tar - - 2. Strip two leading directory components (equivalent to - `--strip-components=2'): - - $ tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar - - 3. Prepend `/prefix/' to each file name: - - $ tar --transform 's,^,/prefix/,' -x -f arch.tar - - 4. Convert each file name to lower case: - - $ tar --transform 's/.*/\L&/' -x -f arch.tar - - - Unlike `--strip-components', `--transform' can be used in any GNU -`tar' operation mode. For example, the following command adds files to -the archive while replacing the leading `usr/' component with `var/': - - $ tar -cf arch.tar --transform='s,^usr/,var/,' / - - To test `--transform' effect we suggest using -`--show-transformed-names' option: - - $ tar -cf arch.tar --transform='s,^usr/,var/,' \ - --verbose --show-transformed-names / - - If both `--strip-components' and `--transform' are used together, -then `--transform' is applied first, and the required number of -components is then stripped from its result. - - You can use as many `--transform' options in a single command line -as you want. The specified expressions will then be applied in order -of their appearance. For example, the following two invocations are -equivalent: - - $ tar -cf arch.tar --transform='s,/usr/var,/var/' \ - --transform='s,/usr/local,/usr/,' - $ tar -cf arch.tar \ - --transform='s,/usr/var,/var/;s,/usr/local,/usr/,' - - -File: tar.info, Node: after, Next: recurse, Prev: transform, Up: Choosing - -6.8 Operating Only on New Files -=============================== - - _(This message will disappear, once this node revised.)_ - -The `--after-date=DATE' (`--newer=DATE', `-N DATE') option causes `tar' -to only work on files whose data modification or status change times -are newer than the DATE given. If DATE starts with `/' or `.', it is -taken to be a file name; the data modification time of that file is -used as the date. If you use this option when creating or appending to -an archive, the archive will only include new files. If you use -`--after-date' when extracting an archive, `tar' will only extract -files newer than the DATE you specify. - - If you only want `tar' to make the date comparison based on -modification of the file's data (rather than status changes), then use -the `--newer-mtime=DATE' option. - - You may use these options with any operation. Note that these -options differ from the `--update' (`-u') operation in that they allow -you to specify a particular date against which `tar' can compare when -deciding whether or not to archive the files. - -`--after-date=DATE' -`--newer=DATE' -`-N DATE' - Only store files newer than DATE. - - Acts on files only if their data modification or status change - times are later than DATE. Use in conjunction with any operation. - - If DATE starts with `/' or `.', it is taken to be a file name; the - data modification time of that file is used as the date. - -`--newer-mtime=DATE' - Acts like `--after-date', but only looks at data modification - times. - - These options limit `tar' to operate only on files which have been -modified after the date specified. A file's status is considered to -have changed if its contents have been modified, or if its owner, -permissions, and so forth, have been changed. (For more information on -how to specify a date, see *note Date input formats::; remember that the -entire date argument must be quoted if it contains any spaces.) - - Gurus would say that `--after-date' tests both the data modification -time (`mtime', the time the contents of the file were last modified) -and the status change time (`ctime', the time the file's status was -last changed: owner, permissions, etc.) fields, while `--newer-mtime' -tests only the `mtime' field. - - To be precise, `--after-date' checks _both_ `mtime' and `ctime' and -processes the file if either one is more recent than DATE, while -`--newer-mtime' only checks `mtime' and disregards `ctime'. Neither -does it use `atime' (the last time the contents of the file were looked -at). - - Date specifiers can have embedded spaces. Because of this, you may -need to quote date arguments to keep the shell from parsing them as -separate arguments. For example, the following command will add to the -archive all the files modified less than two days ago: - - $ tar -cf foo.tar --newer-mtime '2 days ago' - - When any of these options is used with the option `--verbose' (*note -verbose tutorial::) GNU `tar' will try to convert the specified date -back to its textual representation and compare that with the one given -with the option. If the two dates differ, `tar' will print a warning -saying what date it will use. This is to help user ensure he is using -the right date. For example: - - $ tar -c -f archive.tar --after-date='10 days ago' . - tar: Option --after-date: Treating date `10 days ago' as 2006-06-11 - 13:19:37.232434 - - *Please Note:* `--after-date' and `--newer-mtime' should not be - used for incremental backups. *Note Incremental Dumps::, for - proper way of creating incremental backups. - - -File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing - -6.9 Descending into Directories -=============================== - - _(This message will disappear, once this node revised.)_ - -Usually, `tar' will recursively explore all directories (either those -given on the command line or through the `--files-from' option) for the -various files they contain. However, you may not always want `tar' to -act this way. - - The `--no-recursion' option inhibits `tar''s recursive descent into -specified directories. If you specify `--no-recursion', you can use -the `find' utility for hunting through levels of directories to -construct a list of file names which you could then pass to `tar'. -`find' allows you to be more selective when choosing which files to -archive; see *note files::, for more information on using `find' with -`tar', or look. - -`--no-recursion' - Prevents `tar' from recursively descending directories. - -`--recursion' - Requires `tar' to recursively descend directories. This is the - default. - - When you use `--no-recursion', GNU `tar' grabs directory entries -themselves, but does not descend on them recursively. Many people use -`find' for locating files they want to back up, and since `tar' -_usually_ recursively descends on directories, they have to use the -`-not -type d' test in their `find' invocation (*note Type: -(find)Type.), as they usually do not want all the files in a directory. -They then use the `--files-from' option to archive the files located -via `find'. - - The problem when restoring files archived in this manner is that the -directories themselves are not in the archive; so the -`--same-permissions' (`--preserve-permissions', `-p') option does not -affect them--while users might really like it to. Specifying -`--no-recursion' is a way to tell `tar' to grab only the directory -entries given to it, adding no new files on its own. To summarize, if -you use `find' to create a list of files to be stored in an archive, -use it as follows: - - $ find DIR TESTS | \ - tar -cf ARCHIVE -T - --no-recursion - - The `--no-recursion' option also applies when extracting: it causes -`tar' to extract only the matched directory entries, not the files -under those directories. - - The `--no-recursion' option also affects how globbing patterns are -interpreted (*note controlling pattern-matching::). - - The `--no-recursion' and `--recursion' options apply to later -options and operands, and can be overridden by later occurrences of -`--no-recursion' and `--recursion'. For example: - - $ tar -cf jams.tar --no-recursion grape --recursion grape/concord - -creates an archive with one entry for `grape', and the recursive -contents of `grape/concord', but no entries under `grape' other than -`grape/concord'. - - -File: tar.info, Node: one, Prev: recurse, Up: Choosing - -6.10 Crossing File System Boundaries -==================================== - - _(This message will disappear, once this node revised.)_ - -`tar' will normally automatically cross file system boundaries in order -to archive files which are part of a directory tree. You can change -this behavior by running `tar' and specifying `--one-file-system'. -This option only affects files that are archived because they are in a -directory that is being archived; `tar' will still archive files -explicitly named on the command line or through `--files-from', -regardless of where they reside. - -`--one-file-system' - Prevents `tar' from crossing file system boundaries when - archiving. Use in conjunction with any write operation. - - The `--one-file-system' option causes `tar' to modify its normal -behavior in archiving the contents of directories. If a file in a -directory is not on the same file system as the directory itself, then -`tar' will not archive that file. If the file is a directory itself, -`tar' will not archive anything beneath it; in other words, `tar' will -not cross mount points. - - This option is useful for making full or incremental archival -backups of a file system. If this option is used in conjunction with -`--verbose' (`-v'), files that are excluded are mentioned by name on -the standard error. - -* Menu: - -* directory:: Changing Directory -* absolute:: Absolute File Names - - -File: tar.info, Node: directory, Next: absolute, Up: one - -6.10.1 Changing the Working Directory -------------------------------------- - -To change the working directory in the middle of a list of file names, -either on the command line or in a file specified using `--files-from' -(`-T'), use `--directory' (`-C'). This will change the working -directory to the specified directory after that point in the list. - -`--directory=DIRECTORY' -`-C DIRECTORY' - Changes the working directory in the middle of a command line. - - For example, - - $ tar -c -f jams.tar grape prune -C food cherry - -will place the files `grape' and `prune' from the current directory -into the archive `jams.tar', followed by the file `cherry' from the -directory `food'. This option is especially useful when you have -several widely separated files that you want to store in the same -archive. - - Note that the file `cherry' is recorded in the archive under the -precise name `cherry', _not_ `food/cherry'. Thus, the archive will -contain three files that all appear to have come from the same -directory; if the archive is extracted with plain `tar --extract', all -three files will be written in the current directory. - - Contrast this with the command, - - $ tar -c -f jams.tar grape prune -C food red/cherry - -which records the third file in the archive under the name `red/cherry' -so that, if the archive is extracted using `tar --extract', the third -file will be written in a subdirectory named `orange-colored'. - - You can use the `--directory' option to make the archive independent -of the original name of the directory holding the files. The following -command places the files `/etc/passwd', `/etc/hosts', and `/lib/libc.a' -into the archive `foo.tar': - - $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a - -However, the names of the archive members will be exactly what they were -on the command line: `passwd', `hosts', and `libc.a'. They will not -appear to be related by file name to the original directories where -those files were located. - - Note that `--directory' options are interpreted consecutively. If -`--directory' specifies a relative file name, it is interpreted -relative to the then current directory, which might not be the same as -the original current working directory of `tar', due to a previous -`--directory' option. - - When using `--files-from' (*note files::), you can put various `tar' -options (including `-C') in the file list. Notice, however, that in -this case the option and its argument may not be separated by -whitespace. If you use short option, its argument must either follow -the option letter immediately, without any intervening whitespace, or -occupy the next line. Otherwise, if you use long option, separate its -argument by an equal sign. - - For instance, the file list for the above example will be: - - -C/etc - passwd - hosts - --directory=/lib - libc.a - -To use it, you would invoke `tar' as follows: - - $ tar -c -f foo.tar --files-from list - - The interpretation of `--directory' is disabled by `--null' option. - - -File: tar.info, Node: absolute, Prev: directory, Up: one - -6.10.2 Absolute File Names --------------------------- - - _(This message will disappear, once this node revised.)_ - -`--absolute-names' -`-P' - Do not strip leading slashes from file names, and permit file names - containing a `..' file name component. - - By default, GNU `tar' drops a leading `/' on input or output, and -complains about file names containing a `..' component. This option -turns off this behavior. - - When `tar' extracts archive members from an archive, it strips any -leading slashes (`/') from the member name. This causes absolute -member names in the archive to be treated as relative file names. This -allows you to have such members extracted wherever you want, instead of -being restricted to extracting the member in the exact directory named -in the archive. For example, if the archive member has the name -`/etc/passwd', `tar' will extract it as if the name were really -`etc/passwd'. - - File names containing `..' can cause problems when extracting, so -`tar' normally warns you about such files when creating an archive, and -rejects attempts to extracts such files. - - Other `tar' programs do not do this. As a result, if you create an -archive whose member names start with a slash, they will be difficult -for other people with a non-GNU `tar' program to use. Therefore, GNU -`tar' also strips leading slashes from member names when putting -members into the archive. For example, if you ask `tar' to add the file -`/bin/ls' to an archive, it will do so, but the member name will be -`bin/ls'.(1) - - If you use the `--absolute-names' (`-P') option, `tar' will do none -of these transformations. - - To archive or extract files relative to the root directory, specify -the `--absolute-names' (`-P') option. - - Normally, `tar' acts on files relative to the working -directory--ignoring superior directory names when archiving, and -ignoring leading slashes when extracting. - - When you specify `--absolute-names' (`-P'), `tar' stores file names -including all superior directory names, and preserves leading slashes. -If you only invoked `tar' from the root directory you would never need -the `--absolute-names' option, but using this option may be more -convenient than switching to root. - -`--absolute-names' - Preserves full file names (including superior directory names) when - archiving files. Preserves leading slash when extracting files. - - - `tar' prints out a message about removing the `/' from file names. -This message appears once per GNU `tar' invocation. It represents -something which ought to be told; ignoring what it means can cause very -serious surprises, later. - - Some people, nevertheless, do not want to see this message. Wanting -to play really dangerously, one may of course redirect `tar' standard -error to the sink. For example, under `sh': - - $ tar -c -f archive.tar /home 2> /dev/null - -Another solution, both nicer and simpler, would be to change to the `/' -directory first, and then avoid absolute notation. For example: - - $ (cd / && tar -c -f archive.tar home) - # or: - $ tar -c -f archive.tar -C / home - - ---------- Footnotes ---------- - - (1) A side effect of this is that when `--create' is used with -`--verbose' the resulting output is not, generally speaking, the same -as the one you'd get running `tar --list' command. This may be -important if you use some scripts for comparing both outputs. *Note -listing member and file names::, for the information on how to handle -this case. - - -File: tar.info, Node: Date input formats, Next: Formats, Prev: Choosing, Up: Top - -7 Date input formats -******************** - -First, a quote: - - Our units of temporal measurement, from seconds on up to months, - are so complicated, asymmetrical and disjunctive so as to make - coherent mental reckoning in time all but impossible. Indeed, had - some tyrannical god contrived to enslave our minds to time, to - make it all but impossible for us to escape subjection to sodden - routines and unpleasant surprises, he could hardly have done - better than handing down our present system. It is like a set of - trapezoidal building blocks, with no vertical or horizontal - surfaces, like a language in which the simplest thought demands - ornate constructions, useless particles and lengthy - circumlocutions. Unlike the more successful patterns of language - and science, which enable us to face experience boldly or at least - level-headedly, our system of temporal calculation silently and - persistently encourages our terror of time. - - ... It is as though architects had to measure length in feet, - width in meters and height in ells; as though basic instruction - manuals demanded a knowledge of five different languages. It is - no wonder then that we often look into our own immediate past or - future, last Tuesday or a week from Sunday, with feelings of - helpless confusion. ... - - -- Robert Grudin, `Time and the Art of Living'. - - This section describes the textual date representations that GNU -programs accept. These are the strings you, as a user, can supply as -arguments to the various programs. The C interface (via the `get_date' -function) is not described here. - -* Menu: - -* General date syntax:: Common rules. -* Calendar date items:: 19 Dec 1994. -* Time of day items:: 9:20pm. -* Time zone items:: EST, PDT, GMT. -* Day of week items:: Monday and others. -* Relative items in date strings:: next tuesday, 2 years ago. -* Pure numbers in date strings:: 19931219, 1440. -* Seconds since the Epoch:: @1078100502. -* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". -* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al. - - -File: tar.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats - -7.1 General date syntax -======================= - -A "date" is a string, possibly empty, containing many items separated -by whitespace. The whitespace may be omitted when no ambiguity arises. -The empty string means the beginning of today (i.e., midnight). Order -of the items is immaterial. A date string may contain many flavors of -items: - - * calendar date items - - * time of day items - - * time zone items - - * day of the week items - - * relative items - - * pure numbers. - -We describe each of these item types in turn, below. - - A few ordinal numbers may be written out in words in some contexts. -This is most useful for specifying day of the week items or relative -items (see below). Among the most commonly used ordinal numbers, the -word `last' stands for -1, `this' stands for 0, and `first' and `next' -both stand for 1. Because the word `second' stands for the unit of -time there is no way to write the ordinal number 2, but for convenience -`third' stands for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6, -`seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10, -`eleventh' for 11 and `twelfth' for 12. - - When a month is written this way, it is still considered to be -written numerically, instead of being "spelled in full"; this changes -the allowed strings. - - In the current implementation, only English is supported for words -and abbreviations like `AM', `DST', `EST', `first', `January', -`Sunday', `tomorrow', and `year'. - - The output of the `date' command is not always acceptable as a date -string, not only because of the language problem, but also because -there is no standard meaning for time zone items like `IST'. When using -`date' to generate a date string intended to be parsed later, specify a -date format that is independent of language and that does not use time -zone items other than `UTC' and `Z'. Here are some ways to do this: - - $ LC_ALL=C TZ=UTC0 date - Mon Mar 1 00:21:42 UTC 2004 - $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' - 2004-03-01 00:21:42Z - $ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. - 2004-02-29 16:21:42,692722128-0800 - $ date --rfc-2822 # a GNU extension - Sun, 29 Feb 2004 16:21:42 -0800 - $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. - 2004-02-29 16:21:42 -0800 - $ date +'@%s.%N' # %s and %N are GNU extensions. - @1078100502.692722128 - - Alphabetic case is completely ignored in dates. Comments may be -introduced between round parentheses, as long as included parentheses -are properly nested. Hyphens not followed by a digit are currently -ignored. Leading zeros on numbers are ignored. - - Invalid dates like `2005-02-29' or times like `24:00' are rejected. -In the typical case of a host that does not support leap seconds, a -time like `23:59:60' is rejected even if it corresponds to a valid leap -second. - - -File: tar.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats - -7.2 Calendar date items -======================= - -A "calendar date item" specifies a day of the year. It is specified -differently, depending on whether the month is specified numerically or -literally. All these strings specify the same calendar date: - - 1972-09-24 # ISO 8601. - 72-9-24 # Assume 19xx for 69 through 99, - # 20xx for 00 through 68. - 72-09-24 # Leading zeros are ignored. - 9/24/72 # Common U.S. writing. - 24 September 1972 - 24 Sept 72 # September has a special abbreviation. - 24 Sep 72 # Three-letter abbreviations always allowed. - Sep 24, 1972 - 24-sep-72 - 24sep72 - - The year can also be omitted. In this case, the last specified year -is used, or the current year if none. For example: - - 9/24 - sep 24 - - Here are the rules. - - For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed, -where YEAR is any positive number, MONTH is a number between 01 and 12, -and DAY is a number between 01 and 31. A leading zero must be present -if a number is less than ten. If YEAR is 68 or smaller, then 2000 is -added to it; otherwise, if YEAR is less than 100, then 1900 is added to -it. The construct `MONTH/DAY/YEAR', popular in the United States, is -accepted. Also `MONTH/DAY', omitting the year. - - Literal months may be spelled out in full: `January', `February', -`March', `April', `May', `June', `July', `August', `September', -`October', `November' or `December'. Literal months may be abbreviated -to their first three letters, possibly followed by an abbreviating dot. -It is also permitted to write `Sept' instead of `September'. - - When months are written literally, the calendar date may be given as -any of the following: - - DAY MONTH YEAR - DAY MONTH - MONTH DAY YEAR - DAY-MONTH-YEAR - - Or, omitting the year: - - MONTH DAY - - -File: tar.info, Node: Time of day items, Next: Time zone items, Prev: Calendar date items, Up: Date input formats - -7.3 Time of day items -===================== - -A "time of day item" in date strings specifies the time on a given day. -Here are some examples, all of which represent the same time: - - 20:02:00.000000 - 20:02 - 8:02pm - 20:02-0500 # In EST (U.S. Eastern Standard Time). - - More generally, the time of day may be given as -`HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE -is a number between 0 and 59, and SECOND is a number between 0 and 59 -possibly followed by `.' or `,' and a fraction containing one or more -digits. Alternatively, `:SECOND' can be omitted, in which case it is -taken to be zero. On the rare hosts that support leap seconds, SECOND -may be 60. - - If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR -is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken -to be zero). `am' indicates the first half of the day, `pm' indicates -the second half of the day. In this notation, 12 is the predecessor of -1: midnight is `12am' while noon is `12pm'. (This is the zero-oriented -interpretation of `12am' and `12pm', as opposed to the old tradition -derived from Latin which uses `12m' for noon and `12pm' for midnight.) - - The time may alternatively be followed by a time zone correction, -expressed as `SHHMM', where S is `+' or `-', HH is a number of zone -hours and MM is a number of zone minutes. You can also separate HH -from MM with a colon. When a time zone correction is given this way, it -forces interpretation of the time relative to Coordinated Universal -Time (UTC), overriding any previous specification for the time zone or -the local time zone. For example, `+0530' and `+05:30' both stand for -the time zone 5.5 hours ahead of UTC (e.g., India). The MINUTE part of -the time of day may not be elided when a time zone correction is used. -This is the best way to specify a time zone correction by fractional -parts of an hour. - - Either `am'/`pm' or a time zone correction may be specified, but not -both. - - -File: tar.info, Node: Time zone items, Next: Day of week items, Prev: Time of day items, Up: Date input formats - -7.4 Time zone items -=================== - -A "time zone item" specifies an international time zone, indicated by a -small set of letters, e.g., `UTC' or `Z' for Coordinated Universal -Time. Any included periods are ignored. By following a -non-daylight-saving time zone by the string `DST' in a separate word -(that is, separated by some white space), the corresponding daylight -saving time zone may be specified. Alternatively, a -non-daylight-saving time zone can be followed by a time zone -correction, to add the two values. This is normally done only for -`UTC'; for example, `UTC+05:30' is equivalent to `+05:30'. - - Time zone items other than `UTC' and `Z' are obsolescent and are not -recommended, because they are ambiguous; for example, `EST' has a -different meaning in Australia than in the United States. Instead, -it's better to use unambiguous numeric time zone corrections like -`-0500', as described in the previous section. - - If neither a time zone item nor a time zone correction is supplied, -time stamps are interpreted using the rules of the default time zone -(*note Specifying time zone rules::). - - -File: tar.info, Node: Day of week items, Next: Relative items in date strings, Prev: Time zone items, Up: Date input formats - -7.5 Day of week items -===================== - -The explicit mention of a day of the week will forward the date (only -if necessary) to reach that day of the week in the future. - - Days of the week may be spelled out in full: `Sunday', `Monday', -`Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may -be abbreviated to their first three letters, optionally followed by a -period. The special abbreviations `Tues' for `Tuesday', `Wednes' for -`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed. - - A number may precede a day of the week item to move forward -supplementary weeks. It is best used in expression like `third -monday'. In this context, `last DAY' or `next DAY' is also acceptable; -they move one week before or after the day that DAY by itself would -represent. - - A comma following a day of the week item is ignored. - - -File: tar.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats - -7.6 Relative items in date strings -================================== - -"Relative items" adjust a date (or the current date if none) forward or -backward. The effects of relative items accumulate. Here are some -examples: - - 1 year - 1 year ago - 3 years - 2 days - - The unit of time displacement may be selected by the string `year' -or `month' for moving by whole years or months. These are fuzzy units, -as years and months are not all of equal duration. More precise units -are `fortnight' which is worth 14 days, `week' worth 7 days, `day' -worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60 -seconds, and `second' or `sec' worth one second. An `s' suffix on -these units is accepted and ignored. - - The unit of time may be preceded by a multiplier, given as an -optionally signed number. Unsigned numbers are taken as positively -signed. No number at all implies 1 for a multiplier. Following a -relative item by the string `ago' is equivalent to preceding the unit -by a multiplier with value -1. - - The string `tomorrow' is worth one day in the future (equivalent to -`day'), the string `yesterday' is worth one day in the past (equivalent -to `day ago'). - - The strings `now' or `today' are relative items corresponding to -zero-valued time displacement, these strings come from the fact a -zero-valued time displacement represents the current time when not -otherwise changed by previous items. They may be used to stress other -items, like in `12:00 today'. The string `this' also has the meaning -of a zero-valued time displacement, but is preferred in date strings -like `this thursday'. - - When a relative item causes the resulting date to cross a boundary -where the clocks were adjusted, typically for daylight saving time, the -resulting date and time are adjusted accordingly. - - The fuzz in units can cause problems with relative items. For -example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because -2003-06-31 is an invalid date. To determine the previous month more -reliably, you can ask for the month before the 15th of the current -month. For example: - - $ date -R - Thu, 31 Jul 2003 13:02:39 -0700 - $ date --date='-1 month' +'Last month was %B?' - Last month was July? - $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' - Last month was June! - - Also, take care when manipulating dates around clock changes such as -daylight saving leaps. In a few cases these have added or subtracted -as much as 24 hours from the clock, so it is often wise to adopt -universal time by setting the `TZ' environment variable to `UTC0' -before embarking on calendrical calculations. - - -File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats - -7.7 Pure numbers in date strings -================================ - -The precise interpretation of a pure decimal number depends on the -context in the date string. - - If the decimal number is of the form YYYYMMDD and no other calendar -date item (*note Calendar date items::) appears before it in the date -string, then YYYY is read as the year, MM as the month number and DD as -the day of the month, for the specified calendar date. - - If the decimal number is of the form HHMM and no other time of day -item appears before it in the date string, then HH is read as the hour -of the day and MM as the minute of the hour, for the specified time of -day. MM can also be omitted. - - If both a calendar date and a time of day appear to the left of a -number in the date string, but no relative item, then the number -overrides the year. - - -File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats - -7.8 Seconds since the Epoch -=========================== - -If you precede a number with `@', it represents an internal time stamp -as a count of seconds. The number can contain an internal decimal -point (either `.' or `,'); any excess precision not supported by the -internal representation is truncated toward minus infinity. Such a -number cannot be combined with any other date item, as it specifies a -complete time stamp. - - Internally, computer times are represented as a count of seconds -since an epoch--a well-defined point of time. On GNU and POSIX -systems, the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this -time, `@1' represents 1970-01-01 00:00:01 UTC, and so forth. GNU and -most other POSIX-compliant systems support such times as an extension -to POSIX, using negative counts, so that `@-1' represents 1969-12-31 -23:59:59 UTC. - - Traditional Unix systems count seconds with 32-bit two's-complement -integers and can represent times from 1901-12-13 20:45:52 through -2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of -seconds with nanosecond subcounts, and can represent all the times in -the known lifetime of the universe to a resolution of 1 nanosecond. - - On most hosts, these counts ignore the presence of leap seconds. -For example, on most hosts `@915148799' represents 1998-12-31 23:59:59 -UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no -way to represent the intervening leap second 1998-12-31 23:59:60 UTC. - - -File: tar.info, Node: Specifying time zone rules, Next: Authors of get_date, Prev: Seconds since the Epoch, Up: Date input formats - -7.9 Specifying time zone rules -============================== - -Normally, dates are interpreted using the rules of the current time -zone, which in turn are specified by the `TZ' environment variable, or -by a system default if `TZ' is not set. To specify a different set of -default time zone rules that apply just to one date, start the date -with a string of the form `TZ="RULE"'. The two quote characters (`"') -must be present in the date, and any quotes or backslashes within RULE -must be escaped by a backslash. - - For example, with the GNU `date' command you can answer the question -"What time is it in New York when a Paris clock shows 6:30am on October -31, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown -in the following shell transcript: - - $ export TZ="America/New_York" - $ date --date='TZ="Europe/Paris" 2004-10-31 06:30' - Sun Oct 31 01:30:00 EDT 2004 - - In this example, the `--date' operand begins with its own `TZ' -setting, so the rest of that operand is processed according to -`Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it -were in Paris. However, since the output of the `date' command is -processed according to the overall time zone rules, it uses New York -time. (Paris was normally six hours ahead of New York in 2004, but -this example refers to a brief Halloween period when the gap was five -hours.) - - A `TZ' value is a rule that typically names a location in the `tz' -database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of -location names appears in the TWiki Date and Time Gateway -(http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a -colon before a location name in a `TZ' setting, e.g., -`TZ=":America/New_York"'. - - The `tz' database includes a wide variety of locations ranging from -`Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea -and have your own private time zone, or if you are using a non-GNU host -that does not support the `tz' database, you may need to use a POSIX -rule instead. Simple POSIX rules like `UTC0' specify a time zone -without daylight saving time; other rules can specify simple daylight -saving regimes. *Note Specifying the Time Zone with `TZ': (libc)TZ -Variable. - - -File: tar.info, Node: Authors of get_date, Prev: Specifying time zone rules, Up: Date input formats - -7.10 Authors of `get_date' -========================== - -`get_date' was originally implemented by Steven M. Bellovin -() while at the University of North Carolina at -Chapel Hill. The code was later tweaked by a couple of people on -Usenet, then completely overhauled by Rich $alz () and -Jim Berets () in August, 1990. Various revisions for -the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert -and others. - - This chapter was originally produced by Franc,ois Pinard -() from the `getdate.y' source code, and then -edited by K. Berry (). - - -File: tar.info, Node: Formats, Next: Media, Prev: Date input formats, Up: Top - -8 Controlling the Archive Format -******************************** - -Due to historical reasons, there are several formats of tar archives. -All of them are based on the same principles, but have some subtle -differences that often make them incompatible with each other. - - GNU tar is able to create and handle archives in a variety of -formats. The most frequently used formats are (in alphabetical order): - -gnu - Format used by GNU `tar' versions up to 1.13.25. This format - derived from an early POSIX standard, adding some improvements - such as sparse file handling and incremental archives. - Unfortunately these features were implemented in a way - incompatible with other archive formats. - - Archives in `gnu' format are able to hold file names of unlimited - length. - -oldgnu - Format used by GNU `tar' of versions prior to 1.12. - -v7 - Archive format, compatible with the V7 implementation of tar. This - format imposes a number of limitations. The most important of them - are: - - 1. The maximum length of a file name is limited to 99 characters. - - 2. The maximum length of a symbolic link is limited to 99 - characters. - - 3. It is impossible to store special files (block and character - devices, fifos etc.) - - 4. Maximum value of user or group ID is limited to 2097151 - (7777777 octal) - - 5. V7 archives do not contain symbolic ownership information - (user and group name of the file owner). - - This format has traditionally been used by Automake when producing - Makefiles. This practice will change in the future, in the - meantime, however this means that projects containing file names - more than 99 characters long will not be able to use GNU `tar' - 1.20 and Automake prior to 1.9. - -ustar - Archive format defined by POSIX.1-1988 specification. It stores - symbolic ownership information. It is also able to store special - files. However, it imposes several restrictions as well: - - 1. The maximum length of a file name is limited to 256 - characters, provided that the file name can be split at a - directory separator in two parts, first of them being at most - 155 bytes long. So, in most cases the maximum file name - length will be shorter than 256 characters. - - 2. The maximum length of a symbolic link name is limited to 100 - characters. - - 3. Maximum size of a file the archive is able to accommodate is - 8GB - - 4. Maximum value of UID/GID is 2097151. - - 5. Maximum number of bits in device major and minor numbers is - 21. - -star - Format used by Jo"rg Schilling `star' implementation. GNU `tar' - is able to read `star' archives but currently does not produce - them. - -posix - Archive format defined by POSIX.1-2001 specification. This is the - most flexible and feature-rich format. It does not impose any - restrictions on file sizes or file name lengths. This format is - quite recent, so not all tar implementations are able to handle it - properly. However, this format is designed in such a way that any - tar implementation able to read `ustar' archives will be able to - read most `posix' archives as well, with the only exception that - any additional information (such as long file names etc.) will in - such case be extracted as plain text files along with the files it - refers to. - - This archive format will be the default format for future versions - of GNU `tar'. - - - The following table summarizes the limitations of each of these -formats: - -Format UID File Size File Name Devn --------------------------------------------------------------------- -gnu 1.8e19 Unlimited Unlimited 63 -oldgnu 1.8e19 Unlimited Unlimited 63 -v7 2097151 8GB 99 n/a -ustar 2097151 8GB 256 21 -posix Unlimited Unlimited Unlimited Unlimited - - The default format for GNU `tar' is defined at compilation time. -You may check it by running `tar --help', and examining the last lines -of its output. Usually, GNU `tar' is configured to create archives in -`gnu' format, however, future version will switch to `posix'. - -* Menu: - -* Compression:: Using Less Space through Compression -* Attributes:: Handling File Attributes -* Portability:: Making `tar' Archives More Portable -* cpio:: Comparison of `tar' and `cpio' - - -File: tar.info, Node: Compression, Next: Attributes, Up: Formats - -8.1 Using Less Space through Compression -======================================== - -* Menu: - -* gzip:: Creating and Reading Compressed Archives -* sparse:: Archiving Sparse Files - - -File: tar.info, Node: gzip, Next: sparse, Up: Compression - -8.1.1 Creating and Reading Compressed Archives ----------------------------------------------- - -GNU `tar' is able to create and read compressed archives. It supports -`gzip', `bzip2' and `lzma' compression programs. For backward -compatibility, it also supports `compress' command, although we -strongly recommend against using it, because it is by far less -effective than other compression programs(1). - - Creating a compressed archive is simple: you just specify a -"compression option" along with the usual archive creation commands. -The compression option is `-z' (`--gzip') to create a `gzip' compressed -archive, `-j' (`--bzip2') to create a `bzip2' compressed archive, -`--lzma' to create an LZMA compressed archive and `-Z' (`--compress') -to use `compress' program. For example: - - $ tar cfz archive.tar.gz . - - You can also let GNU `tar' select the compression program basing on -the suffix of the archive file name. This is done using -`--auto-compress' (`-a') command line option. For example, the -following invocation will use `bzip2' for compression: - - $ tar cfa archive.tar.bz2 . - -whereas the following one will use `lzma': - - $ tar cfa archive.tar.lzma . - - For a complete list of file name suffixes recognized by GNU `tar', -*note auto-compress::. - - Reading compressed archive is even simpler: you don't need to specify -any additional options as GNU `tar' recognizes its format -automatically. Thus, the following commands will list and extract the -archive created in previous example: - - # List the compressed archive - $ tar tf archive.tar.gz - # Extract the compressed archive - $ tar xf archive.tar.gz - - The only case when you have to specify a decompression option while -reading the archive is when reading from a pipe or from a tape drive -that does not support random access. However, in this case GNU `tar' -will indicate which option you should use. For example: - - $ cat archive.tar.gz | tar tf - - tar: Archive is compressed. Use -z option - tar: Error is not recoverable: exiting now - - If you see such diagnostics, just add the suggested option to the -invocation of GNU `tar': - - $ cat archive.tar.gz | tar tfz - - - Notice also, that there are several restrictions on operations on -compressed archives. First of all, compressed archives cannot be -modified, i.e., you cannot update (`--update' (`-u')) them or delete -(`--delete') members from them or add (`--append' (`-r')) members to -them. Likewise, you cannot append another `tar' archive to a -compressed archive using `--concatenate' (`-A')). Secondly, -multi-volume archives cannot be compressed. - - The following table summarizes compression options used by GNU `tar'. - -`--auto-compress' -`-a' - Select a compression program to use by the archive file name - suffix. The following suffixes are recognized: - - Suffix Compression program - -------------------------------------------------------------- - `.gz' `gzip' - `.tgz' `gzip' - `.taz' `gzip' - `.Z' `compress' - `.taZ' `compress' - `.bz2' `bzip2' - `.tz2' `bzip2' - `.tbz2' `bzip2' - `.tbz' `bzip2' - `.lzma' `lzma' - `.tlz' `lzma' - -`-z' -`--gzip' -`--ungzip' - Filter the archive through `gzip'. - - You can use `--gzip' and `--gunzip' on physical devices (tape - drives, etc.) and remote files as well as on normal files; data to - or from such devices or remote files is reblocked by another copy - of the `tar' program to enforce the specified (or default) record - size. The default compression parameters are used; if you need to - override them, set `GZIP' environment variable, e.g.: - - $ GZIP=--best tar cfz archive.tar.gz subdir - - Another way would be to avoid the `--gzip' (`--gunzip', - `--ungzip', `-z') option and run `gzip' explicitly: - - $ tar cf - subdir | gzip --best -c - > archive.tar.gz - - About corrupted compressed archives: `gzip''ed files have no - redundancy, for maximum compression. The adaptive nature of the - compression scheme means that the compression tables are implicitly - spread all over the archive. If you lose a few blocks, the dynamic - construction of the compression tables becomes unsynchronized, and - there is little chance that you could recover later in the archive. - - There are pending suggestions for having a per-volume or per-file - compression in GNU `tar'. This would allow for viewing the - contents without decompression, and for resynchronizing - decompression at every volume or file, in case of corrupted - archives. Doing so, we might lose some compressibility. But this - would have make recovering easier. So, there are pros and cons. - We'll see! - -`-j' -`--bzip2' - Filter the archive through `bzip2'. Otherwise like `--gzip'. - -`--lzma' - Filter the archive through `lzma'. Otherwise like `--gzip'. - -`-Z' -`--compress' -`--uncompress' - Filter the archive through `compress'. Otherwise like `--gzip'. - -`--use-compress-program=PROG' - Use external compression program PROG. Use this option if you - have a compression program that GNU `tar' does not support. There - are two requirements to which PROG should comply: - - First, when called without options, it should read data from - standard input, compress it and output it on standard output. - - Secondly, if called with `-d' argument, it should do exactly the - opposite, i.e., read the compressed data from the standard input - and produce uncompressed data on the standard output. - - The `--use-compress-program' option, in particular, lets you -implement your own filters, not necessarily dealing with -compression/decompression. For example, suppose you wish to implement -PGP encryption on top of compression, using `gpg' (*note gpg: -(gpg)Top.). The following script does that: - - #! /bin/sh - case $1 in - -d) gpg --decrypt - | gzip -d -c;; - '') gzip -c | gpg -s ;; - *) echo "Unknown option $1">&2; exit 1;; - esac - - Suppose you name it `gpgz' and save it somewhere in your `PATH'. -Then the following command will create a compressed archive signed with -your private key: - - $ tar -cf foo.tar.gpgz --use-compress=gpgz . - -Likewise, the following command will list its contents: - - $ tar -tf foo.tar.gpgz --use-compress=gpgz . - - ---------- Footnotes ---------- - - (1) It also had patent problems in the past. -